domo/doc/protocol.md

> **Version:** `1`  
> **Authored by:** `Raine <raine@ixvd.net>`  

# Table of contents
- [Table of contents](#table-of-contents)
- [Prelude](#prelude)
  - [Interpretation of types](#interpretation-of-types)
    - [Booleans](#booleans)
  - [Reserved fields](#reserved-fields)
- [Structure](#structure)
- [Data types](#data-types)
  - [Dynamic data (`dynamic_data`)](#dynamic-data-dynamic_data)
- [Commands](#commands)
  - [`0x0*` - Node management](#0x0---node-management)
    - [`0x00` - Ping](#0x00---ping)
      - [Command data](#command-data)
    - [`0x01` - Register node](#0x01---register-node)
      - [Command data](#command-data-1)
    - [`0x02` - Remove node](#0x02---remove-node)
      - [Command data](#command-data-2)
    - [`0x0A` - Acknowledge packets](#0x0a---acknowledge-packets)
    - [`0x0E` - Error](#0x0e---error)
      - [Command data](#command-data-3)
      - [Error codes](#error-codes)
  - [`0x1*` - Properties control](#0x1---properties-control)
    - [`0x10` - Register property](#0x10---register-property)
      - [Command data](#command-data-4)
    - [`0x11` - Remove property](#0x11---remove-property)
      - [Command data](#command-data-5)
    - [`0x12` - Get property](#0x12---get-property)
      - [Command data](#command-data-6)
    - [`0x13` - Set property](#0x13---set-property)
      - [Command data](#command-data-7)
    - [`0x14` - Reset property](#0x14---reset-property)
      - [Command data](#command-data-8)
    - [`0x1A` - Subscribe to property](#0x1a---subscribe-to-property)
    - [`0x1B` - Unsubscribe to property](#0x1b---unsubscribe-to-property)
    - [`0x1F` - All properties](#0x1f---all-properties)
      - [Command data](#command-data-9)
  - [`0xF*` - Raw data transmission](#0xf---raw-data-transmission)
    - [`0xF0` - Setup transfer](#0xf0---setup-transfer)
      - [Command data](#command-data-10)
    - [`0xF1` - Data](#0xf1---data)
      - [Command data](#command-data-11)


# Prelude

This document only describes what the protocol looks like.
The specification can be found at `./specification.md`.

## Interpretation of types

### Booleans

If in the description of a property it's marked as a boolean the exact logic that should be executed is:  
`value != 0`

## Reserved fields

The "reserved" column (if present) will state what should be filled in by each side.

- "no": this should be filled in by both sides. (default)
- "request": this should only be filled in the request.
- "response": this should only be filled in the response.


# Structure

Packets are sent in big endian.

| offset                           | size                      | name          | description                                                                        | example      |
| -------------------------------- | ------------------------- | ------------- | ---------------------------------------------------------------------------------- | ------------ |
| `0x00`                           | 1 byte                    | `version`     | This describes the version of the packet                                           | `0x01`       |
| `0x01`                           | 4 bytes                   | `dest`        | This describes who the packet is for a.k.a. destination device id                  | `0xAABBCCDD` |
| `0x05`                           | 4 bytes                   | `src`         | This describes who sent the packet a.k.a. source device id                         | `0xAABBCCDD` |
| `0x09`                           | 4 bytes                   | `packet_id`   | This is the unique identifier of the packet                                        | `0xFAB1B39D` |
| `0x0D`                           | 4 bytes                   | `reply_to`    | This describes what this packet is replying to, if initial message, value is `0x0` | `0x00000000` |
| `0x11`                           | 1 byte                    | `command`     | This describes what kind of command is sent                                        | `0x00`       |
| `0x12`                           | 2 bytes                   | `data_length` | This describes the length of the data in bytes                                     | `0x0001`     |
| `0x14`                           | `<0x11-0x12:data_length>` | `data`        | This is the data of the command                                                    | `0x0000`     |
| `0x14 + <0x11-0x12:data_length>` | 4 bytes                   | `checksum`    | This is the CRC32 checksum of the packet without the checksum.                     | `0x00000000` |

# Data types

Domo has a data framework reliant on data types.
These define what kind of data the property holds.

| `data_type` | size      | type       | description                                                            |
| ----------- | --------- | ---------- | ---------------------------------------------------------------------- |
| `0x0*`      |           |            | **Meta**                                                               |
| `0x00`      | 0 bytes   | Nothing    | Nothing                                                                |
| `0x01`      | 2+ bytes  | Array      | An array of DataTypes. first two bytes is the length in u16 BE         |
| `0x1*`      |           |            | **Basic**                                                              |
| `0x10`      | 1 byte    | Boolean    | `0x00` = false, `0x01` = true, `0x02` = toggle item (reserved for set) |
| `0x11`      | 8 bytes   | Number     | A number.                                                              |
| `0x12`      | 256 bytes | Text       | A simple bit of text.                                                  |
| `0x13`      | 4 bytes   | Identifier | An identifier.                                                         |
| `0x2*`      |           |            | **Color**                                                              |
| `0x20`      | 3 bytes   | RGB        | An RGB value.                                                          |

## Dynamic data (`dynamic_data`)

Dynamic data is a data snippet with a `prop_data_type` byte and the data next to it.

> **Note**: this section uses relative offset

| offset | size                        | name             | description             | example |
| ------ | --------------------------- | ---------------- | ----------------------- | ------- |
| `0x00` | 1 byte                      | `prop_data_type` | Describes the data type | `0x00`  |
| `0x01` | depends on `prop_data_type` | `data`           | The data                |         |

# Commands

These are the default commands. All Domo nodes should support these.

> **Note:** all offsets are *absolute*.

## `0x0*` - Node management

These are commands specifically for management of the nodes.

### `0x00` - Ping

Check to see if a node is up.

#### Command data

there is no command data.

### `0x01` - Register node

This command will register a node.

You can try to register as a node with a specific device_id but this might result in an error `0x03`.  
Leave `0` to get a random id.

#### Command data

| offset | size    | name        | description                                                | reserved | example      |
| ------ | ------- | ----------- | ---------------------------------------------------------- | -------- | ------------ |
| `0x14` | 4 bytes | `device_id` | the device identifier. leave `0x00000000` to get random id | no       | `0x00000000` |

### `0x02` - Remove node

Remove node from network

#### Command data

there is no extra data required.

### `0x0A` - Acknowledge packets

Acknowledge received packets.

| offset | size          | name        | description                        | reserved    | example |
| ------ | ------------- | ----------- | ---------------------------------- | ----------- | ------- |
| `0x14` | 4 bytes * `n` | `packet_id` | list of packet_id's to acknowledge | origin node |         |

### `0x0E` - Error

Send a packet to state an error occurred.

#### Command data

| offset | size          | name         | description                     | example |
| ------ | ------------- | ------------ | ------------------------------- | ------- |
| `0x14` | 1 byte        | `error_code` | error code; check 'Error codes' | `0x00`  |
| `0x15` | `data_length` | `metadata`   | metadata                        |         |

#### Error codes

| `status_code` | name                    | description                                                           | recoverable                       |
| ------------- | ----------------------- | --------------------------------------------------------------------- | --------------------------------- |
| `0x0*`        | `net_*`                 | **Network errors**                                                    |                                   |
| `0x00`        | `net_broken_packet`     | recent packet was broken; this packet's data did not arrive properly. | resend packet                     |
| `0x01`        | `net_invalid_packet`    | the packet sent is not valid; this packet's data does not make sense. | send packet with proper values    |
| `0x02`        | `net_dest_unreachable`  | the destination could not be reached                                  | no                                |
| `0x1*`        | `mgmt_*`                | **Management errors**                                                 |                                   |
| `0x10`        | `mgmt_duplicate_packet` | `packet_id` was used recently.                                        | resend with different `packet_id` |
| `0x11`        | `mgmt_addr_in_use`      | the addr requested is in use already                                  | register with another id or `0`   |
| `0x12`        | `mgmt_not_registered`   | the src addr is not registered with the master node                   | register with another id or `0`   |
| `0x13`        | `mgmt_not_delivered`    | the sent packet could not be delivered                                | register with another id or `0`   |
| `0x2*`        | `node_*`                | **Node errors**                                                       |                                   |
| `0x20`        | `node_invalid_property` | the property specified is invalid                                     | no                                |
| `0x21`        | `node_failed_request`   | the request could not be completed.                                   | consult metadata                  |


## `0x1*` - Properties control

### `0x10` - Register property

#### Command data

| offset | size     | name            | description                                    | reserved | example |
| ------ | -------- | --------------- | ---------------------------------------------- | -------- | ------- |
| `0x14` | 32 bytes | `property_name` | The name of the property as a UTF-8 string.    | no       | "Power" |
| `0x34` | 1 byte   | `data_type`     | The type of data; see "Data types".            | no       | `0x01`  |
| `0x35` | 1 byte   | `read_only`     | Whether the property is readonly. (boolean)    | no       | `0x00`  |
| `0x36` | 1 byte   | `descriptive`   | Whether the property is descriptive. (boolean) | no       | `0x00`  |

### `0x11` - Remove property

#### Command data

| offset | size     | name            | description                                 | reserved | example |
| ------ | -------- | --------------- | ------------------------------------------- | -------- | ------- |
| `0x14` | 32 bytes | `property_name` | The name of the property as a UTF-8 string. | no       | "Power" |

### `0x12` - Get property

Get a properties value

#### Command data

| offset | size     | name            | description                                 | reserved         | example  |
| ------ | -------- | --------------- | ------------------------------------------- | ---------------- | -------- |
| `0x14` | 32 bytes | `property_name` | The name of the property as a UTF-8 string. | no               | "Power"  |
| `0x34` | dynamic  | `dynamic_data`  | Dynamic data snippet                        | destination node | `0x0100` |

### `0x13` - Set property

#### Command data

| offset | size     | name            | description                                 | reserved | example  |
| ------ | -------- | --------------- | ------------------------------------------- | -------- | -------- |
| `0x14` | 32 bytes | `property_name` | The name of the property as a UTF-8 string. | no       | "Power"  |
| `0x34` | dynamic  | `dynamic_data`  | Dynamic data snippet                        | no       | `0x0100` |

### `0x14` - Reset property

#### Command data

| offset | size     | name            | description                                 | reserved | example |
| ------ | -------- | --------------- | ------------------------------------------- | -------- | ------- |
| `0x14` | 32 bytes | `property_name` | The name of the property as a UTF-8 string. | no       | "Power" |

### `0x1A` - Subscribe to property

| offset | size     | name            | description                                 | reserved | example      |
| ------ | -------- | --------------- | ------------------------------------------- | -------- | ------------ |
| `0x14` | 4 bytes  | `device_id`     | Who's property?                             | no       | `0x00000000` |
| `0x18` | 32 bytes | `property_name` | The name of the property as a UTF-8 string. | no       | "Power"      |

### `0x1B` - Unsubscribe to property

| offset | size     | name            | description                                 | reserved | example      |
| ------ | -------- | --------------- | ------------------------------------------- | -------- | ------------ |
| `0x14` | 4 bytes  | `device_id`     | Who's property?                             | no       | `0x00000000` |
| `0x18` | 32 bytes | `property_name` | The name of the property as a UTF-8 string. | no       | "Power"      |

### `0x1F` - All properties

Return all properties.

#### Command data

| offset | size   | name   | description               | reserved | example |
| ------ | ------ | ------ | ------------------------- | -------- | ------- |
| `0x14` | 1 byte | `type` |                           | no       | `0x00`  |
|        |        |        | `0x00` - all              |          |         |
|        |        |        | `0x01` - descriptive only |          |         |
|        |        |        | `0x02` - m only           |          |         |

## `0xF*` - Raw data transmission

This is useful for things like OTA updates.  

### `0xF0` - Setup transfer

Since this procedure is quite expensive (network wise), the sides must shake hands.

#### Command data

| offset | size      | name   | description          | reserved    | example |
| ------ | --------- | ------ | -------------------- | ----------- | ------- |
| `0x14` | 8 bytes   | `size` | u64 size of the data | origin node | `0x00`  |
| `0x1c` | 128 bytes | `mime` | media type of data   | origin node | `0x00`  |

### `0xF1` - Data

This is raw data.
This may be sent without the initial transfer setup for custom implementations.

#### Command data

The `sequence_number` is added for redundancy, all data sent will always reply to it's previous data segment.

| offset | size          | name              | description                     | example      |
| ------ | ------------- | ----------------- | ------------------------------- | ------------ |
| `0x14` | 4 bytes       | `sequence_number` | the sequence number of the data | `0x00000000` |
| `0x18` | `data_length` | `data`            | the data                        |              |