General

Since NRF24 protocol does not resolve packet collision, we won’t implement that ourselves, but will implement a pulling mechanism of transmission. Thus, we do not have a requirement that all the devices have to hear each other.

We use nrf24l01 buffers only. Send packages instantly on receive via uart. Received packages are being sent back to uart instantly as well. Packages with modem mac address considered command requests and are being parsed generating package-response. Received packages are being stored in the internal buffer (up to 8) and shall be read by a command.

Every client device has to have a unique MAC address. We could either pre-program them during flashing firmware, or obtain them dynamically on every installation.

Internal structure

Every device consists of a number of units. Every unit represents one isolated functional, like one sensor, one actuator, etc. It contains channels that could be read, write or both. Units always number from 0 consecutively without any gaps. Units contain functions to read or write data.

Unit 0 always corresponds to the controller itself and contains slave info and rf control functions.

Unit types

Channels

In RF write channel packet number of channels limited to 64 (6 bits) given data type field is 2 bit long.

Data types

Integer data types are divided by 7-bit bytes. MSB of every byte is 1 if it is not the last byte in a sequence and a 0 if it is the last one. Bytes are going from least significant (little endian). Negative numbers are represented only by sign (MSB of data). Higher 0 bits may be omitted.

In RF write channel packet number of channels limited to 64 (6 bits) given data type field is 2 bit long.

Obtaining MAC address at installation process

Device enters installation mode on button press. At this point it constantly sends (every 500ms) device info packet to its address (from eeprom) — todo: determine single address. In this state it still replies to all the commands. After that, the concentrator decides which address should be given to it and sends the package “change MAC address”, “change RF channel” and finally “change mode to normal slave”.

Constants

• Modem address: 00:00:00:00:01 A5:42:42:42:XX

• Broadcast address for endpoint devices: 00:00:00:00:00

RF package structure

Let’s try modified modbus TCP protocol for our network since we have only 32 byte maximum package size.

Functions from 0 to 0x0F are predefined by protocol and are standard and required. Custom device functions to control the hardware should start from 0x10.

TBD: For the custom functions the least significant bit is data direction: 0 for read functions, 1 for write functions.

Data abstractions

Every data abstraction has 1-byte id from a common namespace (unique per unit). If MSB of id is 0, then it is node, if it is 1, then it is a method.

1. Method — the most primitive data abstraction. Input and output data types may be different.
   1. Input data type
   2. Output data type
2. Node — it is basically two methods in one entity, one for read, one for write. Read method should not have any side effects and can not be the trigger for any action. Write might be the trigger for action.
   In the package, if there is no payload to the function given, it means it is node read, node write otherwise. Therefore node can not have no data type (0xF)
   1. Data type
   2. Access permissions

Package format for protocol version 0

Request

0{transaction id}{unit id}{function id}{data}

• 0 is protocol version

• Transaction id, 1 byte, for synchronization between messages of server and client. Slave does not keep track of it.

• Unit id, 1 byte, id of unit behind that transceiver, basically enhansion of the address

• Function id, 1 byte, data abstraction id, see the table below

• Data, up to 28 bytes payload, arguments to a function. Functions with variable length of the data will specify the format of that length.

Besides the NRF ACK, a slave unit shall send a response to a master for every request. If a request can not be parsed, the slave shall send an error response to the master. List of error responses is below.

Response

0{transaction id}{code}{response data}

• 0 is response protocol version

• Transaction id should be equal to transaction id of the request regardless of whether it is valid or not.

• Response code, see table Slave error responses below

• Response data is for code 0 (up to 29 bytes)

For the advertisement packet it is a response to a function GetProperties of unit 0 with transaction id 0xAA.

Function table for protocol version 0 (todo: double-check if function numbers are correct and not from protocol version 1)

Slave error responses

There are two kinds of status codes: critical error, when the message was not passed to a given function, and when the function was run. First group error codes have MSB set. Second group errors depend on the function called.

Data types of function input/output

RF model

Has 3 modes, idle by default:

1. rmIdle — do nothing, just put received packets (data and ack) into a buffer, also ack timeout is possible as it is a hardware feature.

2. rmSlave — always in a listen mode, process received packets using RF protocol module and responses back.

3. rmMaster — utilizes timeout feature. For every sent packet it listens to the same address and expects the response in a specified period of time, otherwise it puts eptResponseTimeout packet into a buffer. It should stop listening to the timeouted address.