-
Notifications
You must be signed in to change notification settings - Fork 3
99. Serial API
Every Meshwork layer has its own serial API, which ensures modularity, so that only subset of features can be used both via local code and via serial.
To improve robustness and ensure simplicity of implementation the L3 Serial API is purely request-response based. The node (MCU) side never sends any unsolicited messages. All messages are sent as a response to a command sent by the host. Below is a list of commands and possible responses.
General command format:
LEN | SEQ | MSG
MSG = CODE | SUBCODE | <MSGDATA>
Note: the table below is really a Markdown code, which rendered nice originally, but recently GitHub changed the table renderer, which messes it up entirely. I decided to keep most of the original Markdown code this way as it is still somewhat readable, until I find a way to stylize the Markdown version.
CODE denotes a serial module identifier. Currently, two such modules are available:
NetworkSerial: CODE = 0
ZeroConfSerial: CODE = 1
SUBCODE denotes a concrete module operation.
| SUBCODE | Value | Host | Node | Response | MSGDATA | Description |
| :----------------- | :---: | :--: | :--: | :--------- | :-------- | :---------- |
| OK | 0 | X | X | - | - | Previous message handled OK |
| NOK | 1 | X | X | - | ERRORCODE | Previous message handled with error |
| UNKNOWN | 2 | X | X | - | - | Unsupported or unknown message command |
| SUBCODE | Value | Host | Node | Response | MSGDATA | Description |
| :----------------- | :---: | :--: | :--: | :--------- | :-------- | :---------- |
| INTERNAL | 32 | - | X | - | - | Indicates an internal message |
| CFGBASIC | 41 | X | - | OK, NOK | see below | Configure basic settings |
| CFGNWK | 42 | X | - | OK, NOK | see below | Configure node's network |
| RFINIT | 43 | X | - | OK, NOK | - | Initialize RF chip |
| RFDEINIT | 44 | X | - | OK, NOK | - | Deinitialize RF chip |
| RFRECV | 45 | - | X | RFRECVACK,
RFROUTEFOUND | see below | Returns a received message |
| RFRECVACK | 46 | X | - | OK, NOK | see below | Complete received message with ACK |
| RFSTARTRECV | 47 | X | - | NOK,
RFRECV,
OK_MESSAGE_INTERNAL | see below | Waits for a message to be received |
| RFSEND | 48 | X | - | NOK,
RFROUTEFAILED, RFGETROUTECOUNT,
RFGETROUTE, RFSENDACK | see below | Sends a singlecast message |
| RFSENDACK | 49 | - | X | OK, NOK | see below | Returns an ACK from a signglecast |
| RFBCAST | 50 | X | - | OK, NOK | see below | Sends a broadcast message |
| CFGREQUEST | 51 | - | X | - | - | Notifies the Host that the Node is ready to accept configuration or commands |
| RFROUTEFOUND | 52 | - | X | - | see below | Notifies that a route has been found |
| RFROUTEFAILED | 53 | - | X | - | see below | Notifies that a route has failed |
| RFGETROUTECOUNT | 54 | - | X |
RFGETROUTECOUNTRES | see below | Asks for available route count to node X |
| RFGETROUTECOUNTRES | 55 | X | - | - | see below | Returns available route count to node X |
| RFGETROUTE | 56 | - | X | NOK,
RFGETROUTERES | see below | Gets routes R to node X |
| RFGETROUTERES | 57 | X | - | - | see below | Returns route R to node X |
MSGDATA for MSGCODE:
ERRORCODE = <list of possible errors TBD>
CFGBASIC = NKWCAPS | DELIVERY | RETRY
CFGNWK = CHANNEL ID | NWK ID | NODE ID | NWKKEYLEN | NWKKEY
NWKKEY = <char seq>
RFRECV = SRC | PORT | DATALEN | DATA
RFRECVACK = DATALEN | DATA
RFSTARTRECV = TIMEOUT
RFSEND = DST | PORT | DATALEN | DATA
RFSENDACK = DATALEN | DATA
RFBCAST = PORT | DATALEN | DATA
CFGREQUEST = <none>
RFROUTEFOUND = HOPCOUNT | SRC | <list of HOPs> | DST
RFROUTEFAILED = HOPCOUNT | SRC | <list of HOPs> | DST
RFGETROUTECOUNT = DST
RFGETROUTECOUNTRES = ROUTECOUNT
RFGETROUTE = DST | ROUTEINDEX
RFGETROUTERES = HOPCOUNT | SRC | <list of HOPs> | DST
Work in progress!
The Meshwork ZeroConf Serial API is designed for ad hoc network management via a dedicated, secure medium such as wired UART or close-range IR UART. The controller node and the slave node are physically coupled (depending on the serial medium) and both are set to Adding mode. The controller sets a sequence of commands via the serial, which will configure the slave node to be part of the controller's network, sending it the network ID, network key, and a newly allocated node ID. The removal is done in a similar fashion.
The advantages over an L4 network-level inclusion are:
- Increased security, since the network key is transferred over a close-range or wired medium vs an open RF channel, in which both devices are guaranteed to be operated by the network owner
- Reduced management protocol complexity, since there is no need for network-level broadcasts, discovery, special routing handling, multicontroller synchronization, and so on
Some disadvantages:
- Requires UART usage, which increases the code size slightly
- Possibly requires some extra components; e.g. in case of IR UART we need IR LED + PIN diode, or IR LED + phototransistor
- Assumes that multicontroller synchronization is done elsewhere, which is an oversimplification
This is a module for the L3 Serial API with CODE = 1.
Note: the table below is really a Markdown code, which rendered nice originally, but recently GitHub changed the table renderer, which messes it up entirely. I decided to keep most of the original Markdown code this way as it is still somewhat readable, until I find a way to stylize the Markdown version.
| SUBCODE | Value | Host | Node | Response | MSGDATA | Description |
| :----------- | :---: | :--: | :--------: | :--------------- | :-------- | :---------- |
| ZCINIT | 41 | X | - | OK, NOK | - | Put slave into ZeroConf Initialization state |
| ZCDEINIT | 42 | X | - | OK, NOK | - | Finish ZeroConf Initialization and return to normal mode |
| ZCDEVREQ | 43 | X | - | ZCDEVRES, NOK | - | Request device configuration flags identification |
| ZCDEVRES | 44 | - | X | - | see below | Return device configuration flags |
| ZCDEVCFG | 45 | X | - | - | see below | Configure device configuration flags |
| ZCNWKREQ | 46 | X | - | ZCNWKRES, NOK | - | Request network configuration flags |
| ZCNWKRES | 47 | - | X | - | see below | Return network configuration flags |
| ZCNWKCFG | 48 | X | - | OK, NOK | see below | Configure network configuration flags |
| ZCREPREQ | 48 | X | - | ZCREPRES, NOK | see below | Request reporting parameters |
| ZCREPRES | 50 | - | X | OK, NOK | see below | Return reporting parameters |
| ZCREPCFG | 51 | X | - | OK, NOK | see below | Configure reporting parameters |
| ZCSERIALREQ | 52 | X | - | ZCSERIALRES, NOK | see below | Request serial number |
| ZCSERIALRES | 53 | - | X | OK, NOK | see below | Return serial number |
| ZCSERIALCFG | 54 | X | - | OK, NOK | see below | Configure serial number |
MSGDATA for MSGCODE:
ERRORCODE = <list of possible errors TBD>
ZCDEVRES = NKWCAPS | DELIVERY
ZCNWKRES = CHANNEL | NWK ID | NODE ID | NWKKEYLEN | NWKKEY
ZCREPRES = REPORTING NODE ID | REPFLAGS
ZCSERIALRES = SERNUMLEN | SERNUM
REPFLAGS = <list of reporting flags TBD>
REPFLAGS (8 bit mask):
b0: Report after add/remove to/from the network
b1: Report values upon discrete change
b2: Report values upon threshold change
b3: Reserved
b4: Reserved
b5: Reserved
b6: Reserved
b7: Reserved