# Import ICDs

> Import the messages of an ICD from a DBC, CSV, or XLSX file.

Import a DBC file, or a CSV or XLSX file with one line for each field, into an [ICD](https://docs.synnaxlabs.com/reference/hardware/icds). Each message that the file describes becomes a binary message, such as a CAN frame.

## Import a file

**Console**

1. [Create](https://docs.synnaxlabs.com/reference/hardware/icds/create) the ICD, or open one.
2. Click **Import** at the top of the ICD’s tab. You can also right-click the ICD in the **ICDs** toolbar and select **Import**.
3. Select a `.dbc`, `.csv`, or `.xlsx` file. The extension of the file selects its format.

**Python**

```python
from pathlib import Path

oven = client.icds.import_file(oven.key, Path("oven.dbc").read_bytes(), "dbc")
```

The format is `"dbc"`, `"csv"`, or `"xlsx"`.

**TypeScript**

```typescript
import { readFile } from "node:fs/promises";

const imported = await client.icds.import(oven.key, await readFile("oven.dbc"), "dbc");
```

The format is `"dbc"`, `"csv"`, or `"xlsx"`.

### What an import changes

An import replaces all the messages of the ICD with the messages in the file:

* A message in the file with the name of a message in the ICD keeps the key of that message. Each of its fields keeps the key of the field with its name. Tasks that read them continue to work.
* A message or field that the file does not hold is removed from the ICD.

A file that Synnax cannot read stops the import, and the ICD does not change. So does a value that breaks a rule of the ICD’s schema, such as a field with no name. Other problems that a [check](https://docs.synnaxlabs.com/reference/hardware/icds/create#check-an-icd) finds do not stop an import.

## DBC files

Synnax makes one message for each `BO_` definition in the file, with its CAN ID, and one field for each signal of the message. It skips `VECTOR__INDEPENDENT_SIG_MSG`, which holds the signals that no message sends.

| In the DBC file                                             | In the ICD                                                        |
| ----------------------------------------------------------- | ----------------------------------------------------------------- |
| Message name, or its long name when the file gives one      | Message name                                                      |
| Signal name, or its long name when the file gives one       | Field name                                                        |
| Start bit, size, and byte order (`@1` Intel, `@0` Motorola) | Start bit, bit length, and byte order (little endian, big endian) |
| Factor and offset                                           | Scale and offset                                                  |
| Minimum and maximum, unless both are 0                      | Min and max                                                       |
| Unit                                                        | Units                                                             |
| Float value type, or signed (`-`), or unsigned (`+`)        | Type: float, integer, or unsigned                                 |
| Multiplexor signals (`M`, `m<N>`, `SG_MUL_VAL_`)            | Multiplexor and multiplex values                                  |
| `VFrameFormat`, `BusType`, or a message longer than 8 bytes | CAN FD                                                            |
| `CANFD_BRS` of 1                                            | Bitrate switch                                                    |
| J1939 `VFrameFormat` or `ProtocolType`                      | A mask that matches the parameter group                           |

The mask of a J1939 message leaves out the priority and the source address, and for a PDU1 group the destination address. When two messages share a parameter group, the mask keeps the source address. When two PDU1 messages also share a source address, the mask keeps the destination address too.

Synnax skips value tables and value descriptions (`VAL_TABLE_`, `VAL_`).

## CSV and XLSX files

The first line holds the names of the columns, in any order. Each line after it is one field. Lines with the same `message` make one message, with their fields in file order. Synnax reads the first sheet of an XLSX workbook, and skips empty lines.

```csv
message,id,length,field,start_bit,bit_length,kind,scale,units
Status,0x101,8,state,0,8,,,
Status,0x101,8,temperature,8,16,integer,0.1,degC
Engine,0x200,8,rpm,0,16,unsigned,1,rpm
```

### Columns

Column names are not case sensitive. `message`, `field`, `start_bit`, and `bit_length` are required.

| Column       | Value                                                                      | Empty means                     |
| ------------ | -------------------------------------------------------------------------- | ------------------------------- |
| `message`    | The name of the message                                                    | Required                        |
| `id`         | The CAN ID, in decimal or in hex with `0x`                                 | No identifier                   |
| `extended`   | Whether the ID is extended: `true` or `false` (also `yes`, `no`, `1`, `0`) | Extended when the ID is > 0x7FF |
| `length`     | The length of the message in bytes                                         | Variable length                 |
| `field`      | The name of the field                                                      | Required                        |
| `start_bit`  | The first bit of the field                                                 | Required                        |
| `bit_length` | The number of bits, 1 to 64                                                | Required                        |
| `byte_order` | `little_endian` or `intel`, `big_endian` or `motorola`                     | `little_endian`                 |
| `kind`       | `float`, `integer`, or `unsigned`                                          | `unsigned`                      |
| `scale`      | Multiplies the raw value                                                   | 1                               |
| `offset`     | Added after the scale                                                      | 0                               |
| `units`      | The units of the value                                                     | No units                        |
| `min`, `max` | The range of values that a write task accepts                              | No range                        |

`id`, `extended`, and `length` belong to the message. When more than one line of a message gives one of them, the lines must agree.

## Problems

Most errors name the row or line of the file. In the Console, an error shows under “Failed to import ICD”. Fix the file and import it again.

* [row 1: missing required column "\<column>"](https://docs.synnaxlabs.com/reference/hardware/icds/import#row-1-missing-required-column-column)

  * Cause

    The first line does not name a required column.

  * Fix

    Add the column to the first line.

* [row 1: unknown column "\<column>"](https://docs.synnaxlabs.com/reference/hardware/icds/import#row-1-unknown-column-column)[row 1: duplicate column "\<column>"](https://docs.synnaxlabs.com/reference/hardware/icds/import#row-1-unknown-column-column)

  * Cause

    The first line names a column that Synnax does not know, or names a column twice.

  * Fix

    Rename or remove the column.

* [row \<N>, column \<column>: is required](https://docs.synnaxlabs.com/reference/hardware/icds/import#row-n-column-column-is-required)

  * Cause

    A line leaves a required cell empty.

  * Fix

    Fill in the cell.

* [row \<N>, column \<column>: invalid number "\<value>"](https://docs.synnaxlabs.com/reference/hardware/icds/import#row-n-column-column-invalid-number-value)[row \<N>, column \<column>: invalid integer "\<value>"](https://docs.synnaxlabs.com/reference/hardware/icds/import#row-n-column-column-invalid-number-value)[row \<N>, column \<column>: invalid boolean "\<value>"](https://docs.synnaxlabs.com/reference/hardware/icds/import#row-n-column-column-invalid-number-value)[row \<N>, column id: invalid id "\<value>"](https://docs.synnaxlabs.com/reference/hardware/icds/import#row-n-column-column-invalid-number-value)[row \<N>, column length: invalid length "\<value>"](https://docs.synnaxlabs.com/reference/hardware/icds/import#row-n-column-column-invalid-number-value)[row \<N>, column byte_order: invalid byte order "\<value>"](https://docs.synnaxlabs.com/reference/hardware/icds/import#row-n-column-column-invalid-number-value)[row \<N>, column kind: invalid kind "\<value>", not float, integer, or unsigned](https://docs.synnaxlabs.com/reference/hardware/icds/import#row-n-column-column-invalid-number-value)[row \<N>, column bit_length: \<value> is not 1 to 64](https://docs.synnaxlabs.com/reference/hardware/icds/import#row-n-column-column-invalid-number-value)

  * Cause

    A cell holds a value that its column does not accept.

  * Fix

    Change the value to one that the column accepts.

* [row \<N>, column \<column>: conflicts with the value in row \<M>](https://docs.synnaxlabs.com/reference/hardware/icds/import#row-n-column-column-conflicts-with-the-value-in-row-m)

  * Cause

    Two lines of one message give different values for `id`, `extended`, or `length`.

  * Fix

    Give each line of the message the same value, or leave the cell empty.

* [row \<N>, column extended: requires an id](https://docs.synnaxlabs.com/reference/hardware/icds/import#row-n-column-extended-requires-an-id)

  * Cause

    A message has an `extended` value but no `id`.

  * Fix

    Add the `id`, or clear `extended`.

* [line \<N>: signal \<signal> extends past the \<size>-byte message \<message>](https://docs.synnaxlabs.com/reference/hardware/icds/import#line-n-signal-signal-extends-past-the-size-byte-message-message)[line \<N>: signal \<signal> does not fit a message](https://docs.synnaxlabs.com/reference/hardware/icds/import#line-n-signal-signal-extends-past-the-size-byte-message-message)

  * Cause

    A DBC signal ends after the last byte of its message, or its start bit is more than 65535.

  * Fix

    Correct the start bit and size of the signal, or the size of the message.

* [line \<N>: signal \<signal> has \<bits> bits, not 1 to 64](https://docs.synnaxlabs.com/reference/hardware/icds/import#line-n-signal-signal-has-bits-bits-not-1-to-64)[line \<N>: signal \<signal> is a \<B>-bit float but has \<bits> bits](https://docs.synnaxlabs.com/reference/hardware/icds/import#line-n-signal-signal-has-bits-bits-not-1-to-64)

  * Cause

    The size of a DBC signal is 0 or more than 64 bits, or a float signal is not 32 or 64 bits.

  * Fix

    Correct the size of the signal, or the value type of a float signal.
