Stella protocol

We provide a custom network protocol called Stella that allows Riotee devices to exchange data bi-directionally with a basestation.

The connection-less protocol uses the 2.4GHz radio on the Riotee devices and is based on the BLE 1Mbit phsyical layer. Communication takes place on one channel and is device-initiated: At any time, a device sends a packet to the basestation containing a device ID, a packet ID, an optional acknowledgment of previously received packet and a payload of a maximum of 247 Byte. After transmitting the packet, the device transitions into RX mode and listens for a response from the basestation. The basestation continuously listens for incoming packets. Upon reception of a packet from a device, the basestation responds with an acknowledgment packet containing the device’s ID, the packet ID of the received packet that is being acknowledged, the packet ID of the current packet and a payload with a maximum size of 247 Byte.

Important

Always check the return code of riotee_stella_send(...), riotee_stella_receive(...) and riotee_stella_transceive(...) to distinguish between a power failure (RIOTEE_ERR_RESET) and successful communication (RIOTEE_SUCCESS or number of bytes received).

Each device is identified by a device ID that is sent as part of the packet. By default, this device ID corresponds to the lower 32 bits of the unique device identifier stored in the FICR->DEVICEID[0] of the nRF52833. The device ID can be set to a custom value by the user with riotee_stella_set_id(...).

Riotee Gateway

We provide a reference implementation for a basestation using a Nordic Semiconductor nRF52840-Dongle here. The Gateway forwards messages received from devices to a host application running on a user’s computer via an HTTP API. It also allows sending messages to devices.

Example usage

 1
 2#include "riotee.h"
 3#include "riotee_stella.h"
 4#include "riotee_timing.h"
 5#include "printf.h"
 6
 7static unsigned int counter = 0;
 8
 9/* Buffer for receiving incoming packet. */
10uint8_t rx_buf[RIOTEE_STELLA_MAX_DATA];
11
12void lateinit(void) {
13  riotee_stella_init();
14}
15
16int main() {
17  riotee_rc_t rc;
18  for (;;) {
19    riotee_wait_cap_charged();
20    rc = riotee_stella_transceive(rx_buf, sizeof(rx_buf), &counter, sizeof(counter));
21    if (rc < 0)
22      printf("Error %d\r\n", rc);
23    else if (rc == 0)
24      printf("Successful transmission. No data received.\r\n");
25    else
26      printf("Successful transmission. Received %d bytes from basestation.\r\n");
27
28    counter++;
29  }
30}

API reference

enum [anonymous]

Stella-specific return codes.

Values:

enumerator RIOTEE_ERR_STELLA_NOACK

No acknowledgement received.

enumerator RIOTEE_ERR_STELLA_INVALIDACK

Invalid acknowledgement received

void riotee_stella_init(void)

Initializes radio and protocol. Must be called once after reset before using the module.

riotee_rc_t riotee_stella_send(void *tx_data, size_t tx_size)

Sends data to the basestation in a Stella packet.

Sends a packet with the specified data as payload to the basestation. IMPORTANT: If the basestation sends data in the acknowledgement packet, this data is discarded and the function returns RIOTEE_ERR_OVERFLOW.

Parameters:

  • tx_data – Pointer to data.

  • tx_size – Size of data.

Return values:

  • RIOTEE_SUCCESS – Packet successfully sent and acknowledged.

  • RIOTEE_ERR_OVERFLOW – tx_size exceeds maximum packet size or basestation sent a payload.

  • RIOTEE_ERR_RESET – Reset occured while sending/receiving acknowledgement.

  • RIOTEE_ERR_TEARDOWN – Teardown occured while sending/receiving acknowledgement.

  • RIOTEE_ERR_STELLA_NOACK – Packet sent, but no acknowledgement received.

  • RIOTEE_ERR_STELLA_INVALIDACK – Invalid acknowledgement received.

riotee_rc_t riotee_stella_receive(uint8_t *rx_buf, size_t rx_size)

Receives a packet from the basestation.

Sends an empty packet to the basestation and receives the response packet in the provided destination buffer. The destination buffer should have the size of the payload if known or RIOTEE_STELLA_MAX_DATA otherwise. Returns the number of bytes copied into the destination buffer or an error code.

Parameters:

  • rx_buf – Pointer to destination buffer.

  • rx_size – Size of destination buffer.

Return values:

  • RIOTEE_SUCCESS – Packet successfully sent and acknowledged.

  • RIOTEE_ERR_OVERFLOW – Received payload is bigger than rx_size.

  • RIOTEE_ERR_RESET – Reset occured while sending/receiving response.

  • RIOTEE_ERR_TEARDOWN – Teardown occured while sending/receiving response.

  • RIOTEE_ERR_STELLA_NOACK – Packet sent, but no response received.

  • RIOTEE_ERR_STELLA_INVALIDACK – Invalid response received.

Returns:

Size of received payload in bytes or error code.

riotee_rc_t riotee_stella_transceive(uint8_t *rx_buf, size_t rx_size, void *tx_data, size_t tx_size)

Sends data in a Stella packet and receives response from basestation.

Parameters:

  • rx_buf – Pointer to destination buffer.

  • rx_size – Size of destination buffer.

  • tx_data – Pointer to TX data.

  • tx_size – Size of TX data.

Return values:

  • RIOTEE_SUCCESS – Packet successfully sent and acknowledged.

  • RIOTEE_ERR_OVERFLOW – tx_size exceeds maximum payload or received payload is bigger than rx_size

  • RIOTEE_ERR_RESET – Reset occured while sending/receiving acknowledgement.

  • RIOTEE_ERR_TEARDOWN – Teardown occured while sending/receiving acknowledgement.

  • RIOTEE_ERR_STELLA_NOACK – Packet sent, but no acknowledgement received.

  • RIOTEE_ERR_STELLA_INVALIDACK – Invalid acknowledgement received.

Returns:

Size of received payload in bytes or error code.

void riotee_stella_set_id(uint32_t dev_id)

Sets the ID that is used when sending packets with riotee_stella_send()

Parameters:

dev_id –

uint32_t riotee_stella_get_id(void)

Reads the ID that is used when sending packets with riotee_stella_send()

Returns:

uint32_t Device ID

unsigned int riotee_stella_get_packet_counter(void)

Reads internal counter counting number of sent packets.

Returns:

unsigned int Number of sent packets.

RIOTEE_STELLA_MAX_DATA

Maximum size of payload in stella packet.

struct riotee_stella_pkt_header_t
struct riotee_stella_pkt_t