10 KiB
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 | src |
This describes who sent the packet a.k.a. source device id | 0xAABBCCDD |
0x05 |
4 bytes | dest |
This describes who the packet is for a.k.a. destination device id | 0xAABBCCDD |
0x09 |
4 bytes | checksum |
This is the CRC32 checksum of the whole packet. | 0x00000000 |
0x0D |
4 bytes | packet_id |
This is the unique identifier of the packet | 0xFAB1B39D |
0x11 |
4 bytes | reply_to |
This describes what this packet is replying to, if initial message, value is 0x0 |
0x00000000 |
0x12 |
1 byte | command |
This describes what kind of command is sent | 0x00 |
0x13 |
2 bytes | data_length |
This describes the length of the data in bytes | 0x0001 |
0x15 |
<0x11-0x12:data_length> |
data |
This is the data of the command | 0x00 |
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* |
Basic | |||
0x00 |
None |
0 bytes | Nothing | Nothing, mostly used internally or as example. |
0x01 |
bool |
1 bit | Switch | A simple switch with two states. |
0x02 |
u8 |
1 byte | Slider | A simple slider with u8 precision. |
0x03 |
[u8; 256] |
256 bytes | Text | A simple bit of text. |
0x1* |
Cosmetic | |||
0x10 |
[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. |
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.
Command data
| offset | size | name | description | example |
|---|---|---|---|---|
0x15 |
4 bytes | device_id |
the device identifier. (reserved for response) | 0x00000000 |
Example request
source should be
0xFFFFFFFFor MASTER's device id
0x00000000
Example response
0x0A001001
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 |
|---|---|---|---|---|---|
0x15 |
32 bytes | property_name |
The name of the property as a UTF-8 string. | no | "Power" |
0x35 |
1 byte | data_type |
The type of data; see "Data types". | no | 0x01 |
0x36 |
1 bit | read_only |
Whether the property is readonly. | no | 0b0 |
0x04 - Remove property
Command data
| offset | size | name | description | reserved | example |
|---|---|---|---|---|---|
0x15 |
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 |
|---|---|---|---|---|
0x15 |
1 byte | error_code |
error code; check 'Error codes' | 0x00 |
0x16 |
2 bytes | metadata_length |
metadata length | 0x0000 |
0x18 |
<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 |
0x1* |
errc_* |
Client errors | |
0x10 |
errc_not_registered |
client is not registered | register client |
0x2* |
errs_* |
Server errors |
0x1* - Properties control
0x10 - Get property
Get a properties value
Command data
| offset | size | name | description | reserved | example |
|---|---|---|---|---|---|
0x15 |
32 bytes | property_name |
The name of the property as a UTF-8 string. | no | "Power" |
0x35 |
1 byte | data_type |
The type of the data. | response | 0x00 |
0x36 |
determined by data type | data |
The actual data. | response |
0x11 - Set property
Command data
| offset | size | name | description | reserved | example |
|---|---|---|---|---|---|
0x15 |
32 bytes | property_name |
The name of the property as a UTF-8 string. | no | "Power" |
0x35 |
1 byte | data_type |
The type of the data. | no | 0x00 |
0x36 |
determined by data type | data |
The actual data. | no |
0x12 - Reset property
Command data
| offset | size | name | description | reserved | example |
|---|---|---|---|---|---|
0x15 |
32 bytes | property_name |
The name of the property as a UTF-8 string. | no | "Power" |