From 4dd61dd200bdd73869c3a9ea59c829b357483031 Mon Sep 17 00:00:00 2001 From: Raine Date: Sun, 15 Oct 2023 18:06:18 +0200 Subject: [PATCH] init: initial commit --- README.md | 11 +++ doc/proto.md | 181 +++++++++++++++++++++++++++++++++++++++++++++++ domo.master.toml | 3 + 3 files changed, 195 insertions(+) create mode 100644 README.md create mode 100644 doc/proto.md create mode 100644 domo.master.toml diff --git a/README.md b/README.md new file mode 100644 index 0000000..61d5425 --- /dev/null +++ b/README.md @@ -0,0 +1,11 @@ +Domo is a domotica system for me. + +# Nodes + +Domo has 2 types of nodes: + +- Master node; the control node. +- Slave nodes; the other nodes. + +## Master node +The difference between a master node and a slave node is that everything connects to it. \ No newline at end of file diff --git a/doc/proto.md b/doc/proto.md new file mode 100644 index 0000000..ee37761 --- /dev/null +++ b/doc/proto.md @@ -0,0 +1,181 @@ +> **Version:** `1` +> **Authored by:** `Raine ` +> **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 | `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` | +| `0x09` | 1 byte | `command` | This describes what kind of command is sent | `0x00` | +| `0x11` | 2 bytes | `data_length` | This describes the length of the data in bytes | `0x0001` | +| `0x13` | `<0x11-0x12:data_length>` | `data` | This is the data of the command | `0x00` | + +# Request / Response + +## 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. + +# 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 | +|--------|---------|-------------|------------------------------------------------|--------------| +| `0x13` | 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 | +|--------|-----------|-----------------|---------------------------------------------|----------|---------| +| `0x13` | 32 bytes | `property_name` | The name of the property as a UTF-8 string. | no | "Power" | +| `0x33` | 1 byte | `data_type` | The type of data; see "Data types". | no | `0x01` | +| `0x34` | **1 bit** | `read_only` | Whether the property is readonly. | no | `0b0` | + +### `0x04` - Remove property + +#### Command data + +| offset | size | name | description | reserved | example | +|--------|----------|-----------------|---------------------------------------------|----------|---------| +| `0x13` | 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 | +|--------|-------------------------------|-------------------|---------------------------------|----------| +| `0x13` | 1 byte | `error_code` | error code; check 'Error codes' | `0x00` | +| `0x14` | 2 bytes | `metadata_length` | metadata length | `0x0000` | +| `0x16` | `<0x14-0x15:metadata_length>` | `metadata` | metadata | | + +#### Error codes + +| `status_code` | name | description | +|---------------|------------------------|----------------------------------------------------------------------------------------------| +| `0x00` | `net_duplicate_packet` | `reply_to` packet is invalid because another packet was sent recently with same `packet_id`. | +| `0x01` | `net_broken_packet` | recent packet was broken. | +| `0x1*` | `errc_*` | **Client errors** | +| `0x10` | `errc_not_registered` | client is not registered | +| `0x2*` | `errs_*` | **Server errors** | + +## `0x1*` - Properties control + +### `0x10` - Get property + +Get a properties value + +#### Command data + +| offset | size | name | description | reserved | example | +|--------|-------------------------|-----------------|---------------------------------------------|----------|---------| +| `0x13` | 32 bytes | `property_name` | The name of the property as a UTF-8 string. | no | "Power" | +| `0x33` | 1 byte | `data_type` | The type of the data. | response | `0x00` | +| `0x34` | determined by data type | `data` | The actual data. | response | | + +### `0x11` - Set property + +#### Command data + +| offset | size | name | description | reserved | example | +|--------|-------------------------|-----------------|---------------------------------------------|----------|---------| +| `0x13` | 32 bytes | `property_name` | The name of the property as a UTF-8 string. | no | "Power" | +| `0x33` | 1 byte | `data_type` | The type of the data. | no | `0x00` | +| `0x34` | determined by data type | `data` | The actual data. | no | | + +### `0x12` - Reset property + +#### Command data + +| offset | size | name | description | reserved | example | +|--------|----------|-----------------|---------------------------------------------|----------|---------| +| `0x13` | 32 bytes | `property_name` | The name of the property as a UTF-8 string. | no | "Power" | \ No newline at end of file diff --git a/domo.master.toml b/domo.master.toml new file mode 100644 index 0000000..4d3bf84 --- /dev/null +++ b/domo.master.toml @@ -0,0 +1,3 @@ +[node] +name = "domo-main" +role = "master" \ No newline at end of file