> ## Documentation Index
> Fetch the complete documentation index at: https://docs.directenergypartners.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CANbus

Each entry in the JSON-formatted address map corresponds to a data field within a CAN frame on the actual device. Every entry in the address map must contain several required and optional parameters, which are described below. The final address map should cover all relevant CAN data fields for the device.

### Understanding CAN Frames

CAN (Controller Area Network) communication uses frames to transmit data. Each frame is identified by a CAN ID and contains up to 8 bytes of data. Data fields within a frame are defined by their byte position, bit position, and bit length, allowing for precise extraction of values from the CAN frame payload.

### Naming Conventions

While not mandatory, it is recommended to adopt the following naming conventions for clarity and usability:

* **Write Operations:** Prefix names with `control.` to indicate that the field is used for controlling the device.
* **Read Operations:** Prefix names with `measure.` to signify that the field is used for measurement purposes.
* **Fault and Warning Fields:** Use the prefixes `fault.` or `warning.` for fields that monitor faults or warnings. This helps in generating appropriate Telegram notifications and alerts for the system.

See the example CANbus address map below for naming conventions.

### Required Parameters

Each register in the address map must include the following parameters:

<ParamField path="canId" type="int | string" required>
  The CAN identifier for the frame containing this data field. The canId can be specified as a decimal integer or as a hexadecimal string (prefixed with `0x`).

  **Example:** `100` or `"0x64"`
</ParamField>

<ParamField path="startByte" type="int" required>
  The starting byte position within the CAN frame data payload (0-7).

  **Options:** `0 - 7`
</ParamField>

<ParamField path="startBit" type="int" required>
  The starting bit position within the start byte (0-7).

  **Options:** `0 - 7`
</ParamField>

<ParamField path="bitLength" type="int" required>
  The total number of bits for this data field (1-64).

  **Options:** `1 - 64`
</ParamField>

<ParamField path="name" type="string" required>
  A unique name for the data field, representing the measurement point read from or written to the CAN device.

  **Example:** `measure.ports.port1.voltage`
</ParamField>

<ParamField path="datatype" type="string" required>
  The data type of the value.

  **Options:** `int8 | uint8 | int16 | uint16 | int32 | uint32 | float32 | string32 | int64 | uint64 | float64`
</ParamField>

### Optional Parameters

These parameters are not necessary for every entry but can be included as needed:

<ParamField path="scaling" type="int | float | string">
  The scaling factor to apply to the CAN data field's return value or the value being written.

  **Example:** `0.1`
</ParamField>

<ParamField path="offset" type="int | float">
  The offset to apply to the CAN data field's return value or the value being written.

  **Example:** `10`
</ParamField>

<ParamField path="direction" type="string">
  The direction of the power or current flow on a port of the device. When the direction is set to `output`,
  the register value will be inverted.

  **Options:** `input | output`
</ParamField>

<ParamField path="minimum" type="int | float">
  The minimum value of the register. For write register, setting the minimum value prevents you from
  writing a value lower than the minimum value. The control command will be blocked by the Power Platform.

  **Example:** `0`
</ParamField>

<ParamField path="maximum" type="int, float">
  The maximum value of the register. For write register, setting the maximum value prevents you from
  writing a value higher than the maximum value. The control command will be blocked by the Power Platform.

  **Example:** `10`
</ParamField>

<ParamField path="map" type="object">
  Indicates if mapping should be applied to the return value or the value being written.

  <Expandable title="properties">
    <ParamField path="type" type="string">
      Indicates the type of mapping to be applied.

      **Options:** `bitwise | value`
    </ParamField>

    * **bitwise:** Each bit in a number corresponds to a specific state (e.g., fault or status).
    * **value:** The entire return value corresponds to a state.
  </Expandable>

  **Example:**

  ```json icon="code" theme={null}
  {
    "map": {
      "type": "bitwise"
    }
  }
  ```
</ParamField>

<ParamField path="byteOrder" type="string">
  Specifies the byte order notation.

  **Options:** `little | big`
</ParamField>

### Expression Registers

In addition to standard CAN data fields, you can define **optional** expression registers. An expression register computes a value from other registers in the address map using a specified operator and operands, rather than reading directly from the device.

Each expression register requires the following parameters:

<ParamField path="name" type="string" required>
  A unique name for the expression register.

  **Example:** `measure.ports.port2.power`
</ParamField>

<ParamField path="operator" type="string" required>
  The operator used to evaluate the expression.

  **Options:** `+ | - | * | / | > | < | >= | <= | == | != | contains`
</ParamField>

<ParamField path="operands" type="string" required>
  A pipe-separated (`|`) list of register names to use as operands. All referenced registers must exist in the address map itself.

  **Example:** `measure.ports.port2.voltage|measure.ports.port2.current`
</ParamField>

<Note>
  All registers referenced in the operands must exist in the address map itself.
</Note>

```json icon="code" theme={null}
{
    "name": "measure.ports.port2.power",
    "operator": "*",
    "operands": "measure.ports.port2.voltage|measure.ports.port2.current"
}
```

### Saving the Address Map

By following the naming conventions and adding all the required and optional parameters to each CAN data field, you have created a complete address map for the controller
to communicate and interact with the device. The final JSON file should be saved with a unique name and a `.json` extension. For example, `canbus_address_map.json`.

### Example

```json canbus_address_map.json icon="code" theme={null}
[
  {
    "canId": 100,
    "startByte": 0,
    "startBit": 0,
    "bitLength": 16,
    "name": "measure.ports.port1.voltage",
    "datatype": "uint16"
  },
  {
    "canId": 100,
    "startByte": 2,
    "startBit": 0,
    "bitLength": 16,
    "name": "measure.ports.port1.current",
    "datatype": "int16",
    "scaling": 0.1,
    "offset": 0
  },
  {
    "canId": "0xC8",
    "startByte": 0,
    "startBit": 0,
    "bitLength": 8,
    "name": "control.ports.port1.method",
    "datatype": "uint8",
    "map": {
      "type": "value",
      "0": "idle",
      "1": "net",
      "2": "GPWR",
      "3": "FPWR"
    }
  },
  {
    "canId": 300,
    "startByte": 0,
    "startBit": 0,
    "bitLength": 16,
    "name": "fault.active",
    "datatype": "uint16",
    "map": {
      "type": "bitwise",
      "0": "Overvoltage",
      "1": "Undervoltage",
      "2": "Overcurrent",
      "3": "Overtemperature",
      "4": "Communication error",
      "5": "Internal fault"
    }
  }
]
```