# ICDs

> Learn what an ICD is, what it is for, and how a task uses one.

An interface control document (ICD) describes the messages that a device sends: the layout of each message, and the meaning of each value in it. A read task uses an ICD to turn each message into samples on [channels](https://docs.synnaxlabs.com/reference/channels).

An ICD is almost the same as a DBC file for a CAN bus, or an Avro schema for a Kafka topic. One ICD can hold many messages, and many tasks can use one ICD.

## What ICDs are for

### Read JSON from an MQTT topic

An [MQTT read task](https://docs.synnaxlabs.com/reference/hardware/mqtt/read-task) reads each JSON document on a topic with one ICD message. Each field of the message finds one value with a JSON pointer, such as `/temperature`. When you first add data to a task, the Console creates an ICD with the name of the task, and a message for each topic.

### Read many kinds of message from one topic

A topic can carry more than one kind of document, such as sensor readings and status reports. Give each message a [match rule](https://docs.synnaxlabs.com/reference/hardware/icds/reference#match-rules): a JSON pointer and the value that it must hold, such as `/type` equal to `status`. The task reads each document with the message whose rule the document meets.

### Fill a missing value

A device can leave a value out of some documents. Give the field a [default](https://docs.synnaxlabs.com/reference/hardware/icds/reference#defaults), and the task writes the default when the document has no value. Without a default, the task skips the document.

### Record text labels as numbers

A device can send a state as text, such as `ON` or `OFF`. The [enum values](https://docs.synnaxlabs.com/reference/hardware/icds/reference#enum-values) of a field map each label to a number, such as `ON` to 1, so that a line plot can show the state.

### Bring in a CAN database or a spreadsheet

[Import](https://docs.synnaxlabs.com/reference/hardware/icds/import) a DBC file, or a CSV or XLSX file with one line for each field, into an ICD. The messages that the file describes replace the messages of the ICD.

## Messages and fields

An ICD holds messages. A message is the layout of one kind of payload, and its fields are the values in the payload. Each message has one of three formats:

| Format | One message is                              | A field is found by                                                        | Example                                        |
| ------ | ------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------- |
| JSON   | One JSON document                           | A JSON pointer                                                             | `/temperature`                                 |
| Text   | One line of text                            | Its position after a split on a delimiter, or the tag that comes before it | Position 1 in `oven,21.4`, or `T=` in `T=21.4` |
| Binary | The bytes of one frame, such as a CAN frame | A start bit and a length in bits                                           | Start bit 16, length 12                        |

A message can also select the payloads that belong to it. A JSON message has a match rule, a text message has a prefix that each line starts with, and a binary message has an identifier, such as a CAN ID.

Each field has a name, a scale, an offset, and units. The task multiplies the raw value by the scale, then adds the offset. JSON and binary fields also have a kind, such as `float` or `integer`. A JSON field can also have enum values and a default. The [ICD reference](https://docs.synnaxlabs.com/reference/hardware/icds/reference) gives each property.

An MQTT read task reads JSON messages.

## How tasks use an ICD

The ICD says what a message is. The task says where to get the message, and where its values go.

A task names an ICD and the messages that it reads. For each message, the task binds fields to channels, and it records only the fields that it binds. You cannot delete an ICD that a task uses.

An edit to an ICD saves at once. When you change a message that a running task reads, the task keeps the old layout until you deploy it again, and it shows **Redeploy**. A new name for the ICD or for a message does not need a redeploy, because tasks refer to them by key.
