Coriandolo Radio: Software and Design Support
64seconds can make a difference and help you get your product developed with Coriandolo Radio. Contact us for more information.
Download the CR Software
Coriandolo Radio embedded software is open-source, license-free, and eminently hackable. Take a look on Github →
Coriandolo Radio Design Guide in Brief
The embedded software developer has full control over how the application uses the CR protocol in an architecture of point (base) to multi-point (1+ sensors).
CR is a connection-less protocol:
- Sensor Announcement: The sensor starts a message exchange by sending an Announcement Message at any time.
- Base Reply: Always listening, the base receives the message from the sensor in its RX bank then replies with either: (A) the oldest message, with that sensor ID, in its TX bank, or (B) an Acknowledgement Message.
- Message Exchange: On receiving a base reply, the sensor will send the oldest message in its TX bank, if present. Then the base will reply again (Base Reply step).
- Completion: The sensor ends the exchange when its TX bank is empty, its RX bank is full, the base did not reply, or the programmed exchange limit has been reached.
The application can read the RX bank and write to the TX bank at any time, including during a message exchange.
All messages have the same simple format: [ length, id24, payload ].
- Length byte: 1 byte long, value = 3 - 253
- ID24: 3 bytes long, value = 0x1 - 0xFFFFFE
- Payload: 0 - 250 bytes long, value = any
- The value of the length byte is the total number of proceeding bytes, i.e. 3 + the number of payload bytes.
- The device ID24 value is set by the application. By convention, a sensor transmits its own permanently assigned 24-bit ID24 and a base transmits the ID24 of the target sensor.
- The application is free to define the payload without restriction.
In addition to 24-bit sensor IDs, the application also sets a 16-bit Connection ID, which is a private network number.
Announcement and Acknowledgement Messages
These messages have a zero-byte payload.
TX and RX Message Banks
Each CR device has two First In, First Out (FIFO) Message Banks:
- TX Bank holds messages to be transmitted that have been written to the bank by the application
- RX Bank holds received messages that will be read by the application
The TX and RX banks used in CR are software objects that do not contain the messages themselves, rather they contain metadata about the messages. The banks reference message buffers located elsewhere in RAM, declared by the application. A message bank is represented programmatically by an array of metadata structures, referred to as Slots; one slot for each message buffer.
The CR source code documentation is the authoritative reference, but an examination of the contents of the slot structure gives insight into how Coriandolo Radio works.
Buffer byte pointer: The slot structure holds meta data about the message; it does not contain any message data itself. Instead it has a pointer to a byte buffer that has been declared by the application.
Buffer byte length: The number of bytes in the message (not the allocated byte length of the buffer).
Status: Instantaneous state of the buffer, for example, "currently receiving data".
Exchange status: Identifies whether a transmitted message has a delivery receipt.
Device ID24: The ID24 in the message (not the ID of the device that owns the message bank).
Flags: Tells CR whether to retry sending messages and whether to add SYNC info (CR can sync devices).
Timestamp: A ticks value (typically 32K ticks) set when the message is transmitted or received. Ticks are read from a timer that the application starts and dedicates to CR.
Sequence Number: Identifies the order in which messages were put into the message bank.
A slot has at all times a precisely defined status:
- TX Slot: (A) Unused (no buffer assigned), (B) Message Unsent, (C) Sending (busy), (D) Message Sent, (E) Message Exchanged
- RX Slot: (A) Unused (no buffer assigned), (B) Available, (C) Receiving (busy), (D) Message Received