Comm Protocol v0 - HerbiHub/power-box GitHub Wiki
Version 0.1.0
WORK IN PROGRESS! Much of this page is currently invalid.
What if we embedded a version of commands into each string?
eg: 1,<DEST>,<SOURCE>,... would mean version 1 of the command spec. Devices could ignore command version they do not understand, and fall-back to older versions.
If a slave goes more than 10 seconds without a command, it shall return to Reset Mode and wait communication from the master.
Most basic communication mode. Slow baud rate, wait for orders from Master.
Wait a psudo-random amount of time, and echo it's own address on it's current baud (generally minimum).
Increase Baud to setting given by host (or closest it can reach).
This is a work in progress!
4 characters representing the address of a given device. Letters and numbers are valid in the address. Special characters may be used in some circumstances.
Good Examples:
- 1234
- A43F
- ZZZZ
Bad Examples:
- 12345 (5 Characters long)
- AF&A (& is not a valid character)
There are a few special case addresses.
Master Host: 0000
While a host may also have a valid address, 0000 is always the host on a given network.
All Devices: ****
All devices on the network will listen to and follow this command. Often no response is given (lest chaos begin!)
No Device: ----
No device should listen to this command. Used as a NOOP or a test.
* Factory Reset
* Get/Say Firmware Version
* Get/Say Profile (Give add settings)
* Get/Set/Say/Clear Address
* Get/Set/Say/Clear Baud Rate
* Get/Set/Say/Clear Config Value
* Get/Set/Say/Clear Dimmer Value
* Get/Set/Say/Clear Ident Channel (Channel switches from 0-100 every 1 second)
* Get/Set/Say/Clear RTC Value
* Get/Set/Say/Clear Sensor Setting
* Get/Set/Say/Clear Switch Setting
* Ident (Blink to find)
* Keep Alive (Do nothing, respond)
* NOOP (Do nothing, do not respond)
* Reset
* Status Code (ACK,NACK,ERROR,etc)
* Factory Reset
* Get/Say Firmware Version
* Get/Say Profile (Give add settings)
* Get/Set/Say/Clear Address
* Get/Set/Say/Clear Config Value
* Get/Set/Say/Clear Ident Channel (Channel switches from 0-100 every 1 second)
* Ident (Blink to find)
* Keep Alive (Do nothing, respond)
* NOOP (Do nothing, do not respond)
* Reset
Each command (from Master>Slave, or Slave>Master) will follow a basic overall structure.
<VERSION>,<DEST>,<SOURCE>,<COMMAND>,<VERB>,<ARGUMENTS...>,<CRC>\n
: Version of command defition in use (Hex number).
: The destination address on the bus. Slaves not matching this will ignore the command.
: String indicating what command is being issued.
: (Optional) Subcommand (eg: SET, CLEAR, GET, SAY...).
<ARGUMENTS...>: (Optional) Series of comma seperated arguments defined by each command.
: ASCII hex of the CRC checksum of the preceding string (Including , characters!). If incorrect, the command is ignored.
\n: All commands are terminated by a \n. A timeout can occur if a command is missing this \n
Used to acknowledge a command as recieved. Will embed the status of the response.
This command is only used when a logical "SAY" verb, or other response. Some commands do not result in any response.
1,<DEST>,<SOURCE>,STATUS,<STATUS_CODE>,<CRC_OLD>,<CRC>\n
1: Version 1 of command protocol.
: The destination address on the bus. Slaves not matching this will ignore the command.
STATUS: Status noun, this message is a response to a previous command.
<STATUS_CODE>: Status code of the response. Can be varried. In general, these follow the http status code spec.
* 100: Continue. Ready for mode data.
* 200: OK (Generic response of success.
* 400: Bad Request.
* 401: Not Authorized.
* 402: Payment required.
* 404: Not Found.
* 405: Not Allowed.
* 418: I'm a Teapot.
* 429: Too Many Requests.
* 500: Internal Server Error.
<CRC_OLD>: CRC of the command this is a response to.
: Hex digit CRC of all preceding ASCII chars. Not listed in this example.
\n: Termination character.
1,MMMM,SSSS,STATUS,418,0x12345678,0xc1b92f5c\n
None (This is alread a response!)
Host may respond with other commands based on this success.
1,<DEST>,<SOURCE>,BAUD,SET,<SETTING>,<CRC>\n
1: Version 1 of command protocol.
: The destination address on the bus. Slaves not matching this will ignore the command.
BAUD: Command noun, Baud Rate.
SET: Command verb, set the Baud Rate.
: Baud rate setting (Given in whole numbered bps).
: Hex digit CRC of all preceding ASCII chars. Not listed in this example.
\n: Termination character.
1,SSSS,MMMM,BAUD,SET,9600,0xd2c518e2\n
Status message with result of command.
Device changes in UART connection to match the Baud rate after responding with status message.
1,<DEST>,<SOURCE>,BAUD,GET,<CRC>\n
: The destination address on the bus. Slaves not matching this will ignore the command.
BAUD: Command noun, Baud Rate.
SET: Command verb, get the Baud Rate.
: Hex digit CRC of all preceding ASCII chars. Not listed in this example.
\n: Termination character.
TBD
Baud Say
1,<DEST>,<SOURCE>,BAUD,SAY,<BAUD>,<CRC>\n
None.
1,<DEST>,<SOURCE>,DIMMER,SET,<CHAN>,<SETTING>,<CRC>\n
: The destination address on the bus. Slaves not matching this will ignore the command.
DIMMER: Command noun, Dimmer channel settings.
SET: Command verb, get the Baud Rate.
: Channel selection to apply dimmer value to.
: Single int (0-255) setting to set. Device will, in general, attempt to map 0-255 between settings available to it. Due to limitations of the end device, any given single increase/decrease to a setting may not result in behavior changes in the output.
<>: Hex digit CRC of all preceding ASCII chars. Not listed in this example.
\n: Termination character.
None
Device changes given dimmer value immediately.
1,<DEST>,<SOURCE>,DIMMER,GET,<CHAN>,<CRC>\n
: The destination address on the bus. Slaves not matching this will ignore the command.
DIMMER: Command to retrieve dimmer value from device channel.
GET: Command verb, get the dimmer setting.
: Single digit (0-9) channel selection to retrieve dimmer value from.
: Hex digit CRC of all preceding ASCII chars. Not listed in this example.
\n: Termination character.
1,<DEST>,<SOURCE>,SWITCH,SET,<CHAN>,<SETTING>,<CRC>\n
: The destination address on the bus. Slaves not matching this will ignore the command.
SWITCH: Command to set switch value on device channel.
SET: Command verb, set the swtich setting.
: Single digit (0-9) channel selection to apply switch value to.
: Single int (0,1) setting to set. 0 for off, 1 for on.
<>: Hex digit CRC of all preceding ASCII chars. Not listed in this example.
\n: Termination character.
1,<DEST>,<SOURCE>,SWITCH,GET,<CHAN>,<CRC>\n
: The destination address on the bus. Slaves not matching this will ignore the command.
SWITCH?: Command to retrieve switch value from device channel.
: Single digit (0-9) channel selection to retrieve switch value from.
: Hex digit CRC of all preceding ASCII chars. Not listed in this example.
\n: Termination character.
1,<DEST>,<SOURCE>,RTC,SET,<YEAR>,<MONTH>,<DAY>,<HOUR>,<MINUTE>,<SECOND>,<MILLISECONDS>,<CRC>\n
: The destination address on the bus. Slaves not matching this will ignore the command.
RTC: Command to set real time clock value.
: Current year (4 digits)
: Current month (2 digits)
: Current day (2 digits)
: Current hour, in 24 hour time (2 digits)
: Current minute (2 digits)
: Current second (2 digits)
: Current milliseconds (3 digits)
: Single int (0,1) setting to set. 0 for off, 1 for on.
<>: Hex digit CRC of all preceding ASCII chars. Not listed in this example.
\n: Termination character.
1,<DEST>,<SOURCE>,RTC,GET,<CRC>\n
: The destination address on the bus. Slaves not matching this will ignore the command.
RTC?: Command to retrieve current RTC values from device. Note Due to timing limitations, RTC values may not be very accurate. Expect milliseconds in particular to be useless.
: Hex digit CRC of all preceding ASCII chars. Not listed in this example.
\n: Termination character.
1,<DEST>,<SOURCE>,,<CRC>\n
1: Version 1 of command protocol.
: The destination address on the bus. Slaves not matching this will ignore the command.
: Hex digit CRC of all preceding ASCII chars. Not listed in this example.
\n: Termination character.