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 do not use NRF ACK mechanism.

We use nrf24l01 buffers only. Send packages instantly on receive via uart. 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. MAC address is being assigned to a device during installation sequence.

Internal structure

Every device consists of a number of units. Every unit represents one isolated functional, like one sensor, one actuator, etc. Units always number from 0 consecutively without any gaps. Units contain readable-writable nodes and functions to read or write data.

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

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

Every unit should have predefined by a protocol nodes enlisted in a table below. Node numbers 0 .. 0x0F and function numbers 0x80 .. 0x8F are standard and required.

Custom device nodes to control the hardware should start from 0x10. Custom device functions to control the hardware should start from 0x90.

Data abstractions

Every data abstraction has 1-byte id from a common mapping 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 an 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

Request

1{transaction id}{unit id}{function id}{data}

• 1 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.

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

2{transaction id}{code}{response data}

• 2 is response protocol version (only to distinguish from the request)

• 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

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.