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
0xFFFFFFFF
or 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 |
---|---|---|---|
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" |