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.
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 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: 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, 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 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 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:
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 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.