207 lines
13 KiB
Markdown
207 lines
13 KiB
Markdown
> **Version:** `1`
|
|
> **Authored by:** `Raine <raine@ixvd.net>`
|
|
> **Status**: `planning`
|
|
|
|
# Prelude
|
|
|
|
Version 1 has zero security on itself.
|
|
This can be changed with something like TLS but that's up to the implementer.
|
|
|
|
# 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` |
|
|
|
|
# Packets in practice
|
|
|
|
## Statuses
|
|
|
|
When an error occurs the response should be a `0x0E` (error command).
|
|
This can contain error data.
|
|
|
|
To mark a success, you should just send back the expected response.
|
|
|
|
## 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.
|
|
|
|
# Error checking
|
|
|
|
If the CRC32 doesn't match up the receiver will send a `0x0E` (error) packet to the probable source.
|
|
The error code `0x01`/`net_broken_packet` should be used. The metadata may contain some textual info on what went
|
|
wrong.
|
|
The master will not track the broken packet's `packet_id`, so the slave can send it again.
|
|
|
|
# Data types
|
|
|
|
Domo has a data framework reliant on data types.
|
|
These define what kind of data the property holds.
|
|
|
|
| `data_type` | physical type (rust types) | size | virtual type | description |
|
|
|-------------|----------------------------|-----------|---------------------|-----------------------------------------------------------------------------|
|
|
| `0x0*` | | | | **Meta** |
|
|
| `0x00` | `None` | 0 bytes | Nothing | Nothing, mostly used internally or as example. |
|
|
| `0x01` | `Vec<DataType>` | 2+ bytes | Array | An array of DataTypes. first two bytes is the u16 length |
|
|
| `0x1*` | | | | **Simple** |
|
|
| `0x10` | `bool` | 1 byte | Switch | A simple switch with two states. `0x00` = off, `0x01` = on, `0x02` = toggle |
|
|
| `0x11` | `u8` | 1 byte | Slider | A simple slider with u8 precision. |
|
|
| `0x12` | `[u8; 256]` | 256 bytes | Text | A simple bit of text. |
|
|
| `0x2*` | | | | **Cosmetic** |
|
|
| `0x20` | `[u8; 3]` | 3 bytes | Color | An RGB value. |
|
|
| `0x9*` | | | | **Time & Space** |
|
|
| `0x90` | `u64` | 8 bytes | Seconds | A simple value that is in seconds. |
|
|
| `0xF*` | | | | **Domo types** |
|
|
| `0xF0` | `[u8; 4]` | 4 bytes | Domo node reference | A reference to a node. |
|
|
|
|
## 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` | depending 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.
|
|
|
|
### `0x03` - 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. <br/>(`0x00` = no, `0x01` = yes) | no | `0x00` |
|
|
|
|
### `0x04` - 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" |
|
|
|
|
### `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` | 2 bytes | `metadata_length` | metadata length | `0x0000` |
|
|
| `0x17` | `<0x14-0x15:metadata_length>` | `metadata` | metadata | |
|
|
|
|
#### Error codes
|
|
|
|
| `status_code` | name | description | recoverable |
|
|
|---------------|------------------------|----------------------------------------------------------------------------------------------|-----------------------------------|
|
|
| `0x1*` | `net_*` | **Network errors** | |
|
|
| `0x00` | `net_duplicate_packet` | `reply_to` packet is invalid because another packet was sent recently with same `packet_id`. | resend with different `packet_id` |
|
|
| `0x01` | `net_broken_packet` | recent packet was broken. | resend packet |
|
|
| `0x02` | `net_invalid_packet` | the packet sent is not valid | send packet with proper values |
|
|
| `0x03` | `net_addr_in_use` | the addr requested is in use already | register with another id or `0` |
|
|
| `0x1*` | `errc_*` | **Client errors** | |
|
|
| `0x10` | `errc_not_registered` | client is not registered | register client |
|
|
| `0x2*` | `errs_*` | **Server errors** | |
|
|
| `0x20` | `errs_not_delivered` | server could not deliver packet. | depends on situation |
|
|
|
|
## `0x1*` - Properties control
|
|
|
|
### `0x10` - 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` | 1 byte | `dynamic_data` | Dynamic data snippet | response | `0x0100` |
|
|
|
|
### `0x11` - 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` | 1 byte | `dynamic_data` | Dynamic data snippet | no | `0x0100` |
|
|
|
|
### `0x12` - 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" |
|
|
|
|
### `0x1A` - 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" |
|