Nano-RK WiDom API

  • int8_t wd_init(RF_RX_INFO *pRRI, uint8_t channel)
    • Initializes the radio and protocol. Initializes CC2420 for radio communication via the basic RF library functions. Turns on the voltage regulator, resets the CC2420 and turns on the crystal oscillator. Note that the crystal oscillator will remain on (forever). The pointer (pRRI) to RF_RX_INFO data structure is to be used during the first packet reception. The structure can be switched upon packet reception. The channel defines the RF channel to be used (11 = 2405 MHz to 26 = 2480 MHz). This function must be called from inside a task, and never before nrk_start().
  • uint8_t wd_tx_packet(RF_TX_INFO *pRTI, uint16_t priority)
    • This passes a packet to be sent. WiDom will not queue packets, so calling this function from multiple tasks concurrently will return an error code. A value of 1 is returned if the packet was accepted. -1 is returned upon failure. This call will return immediately, but the packet will eventually be later. The argument priority indicates the priority of the message.
  • uint8_t wd_wait_tx_packet(RF_TX_INFO *pRTI, uint16_t priority)
    • This passes a packet to be sent and waits until the end transmission. WiDom will not queue packets, so calling this function from multiple tasks concurrently will return an error code. A value of 1 is returned if the packet was transmitted. -1 is returned upon failure. This call will return after the packet was transmitted or a failure occurs. The argument priority indicates the priority of the message.
  • int8_t wd_check_rx_status()
    • This function checks if a packet was received. Returns a value >=0 if there is a packet received and buffered.
  • RF_RX_INFO *wd_get_rx_packet()
    • This function returns pointer to received packet info. Returns a value !=NULL if there is a packet received and buffered.
  • int8_t wd_release_rx_packet()
    • Releases the reception buffer. It is necessary to call this function whenever a new packet is received. Otherwise, WiDom will not enqeue newly received packets.
  • int8_t wd_wait_until_tx_packet()
    • Blocks until next packet transmission.
  • int8_t wd_wait_until_rx_packet()
    • Blocks until next packet reception.

Using WiDom

You must start by including widom and define transmit and receive buffers.

1#include <widom.h>
2#include <widom_rf.h>
3RF_TX_INFO rfTxInfo;
4RF_RX_INFO rfRxInfo;
5uint8_t tx_buf[RF_MAX_PAYLOAD_SIZE];
6uint8_t rx_buf[RF_MAX_PAYLOAD_SIZE];

Initialization

Function wd_init() initializes the radio and protocol. This function must be called from inside a task, and never before nrk_start().

1rfRxInfo.pPayload = rx_buf;
2rfRxInfo.max_length = RF_MAX_PAYLOAD_SIZE;
3wd_init (&rfRxInfo, WD_CHANNEL);

Sending a Packet

Sending a packet is done by either either function wd_tx_packet() or* wd_tx_wait_packet()*. While function
wd_tx_packet() just signals to the protocol that a new packet was enqued, wd_wait_tx_packet() signals
the new packet and blocks until it is sent. These two functions accept as arguments a RF_TX_INFO data
structure and the priority of the message.

1// fill packet buffer with data ...
2for (i=0; i<DATA_LENGHT; i++) tx_buf[i]=data[
3rfTxInfo.pPayload=tx_buf;
4wd_wait_tx_packet(&rfTxInfo, MY_MSG_PRIO);

or

1// fill packet buffer with data ...
2for (i=0; i<DATA_LENGHT; i++) tx_buf[i]=data[i];
3rfTxInfo.pPayload=tx_buf;
4wd_tx_packet(&rfTxInfo, MY_PRIO);
5wd_wait_until_tx_packet();

One does not need to wait until the packet transmission is finished, and thus the call to wd_wait_until_tx_packet() is not mandatory;

Receiving a Packet

To receive a packet, call wd_wait_until_rx_packet(). And do not forget to release the reception buffer with wd_release_rx_packet().

1wd_wait_until_rx_packet();
2// get data from packet ...
3for (i=0; i<rfRxInfo.length; i++) putchar (rfRxInfo.pPayload[i]);
4// release buffer
5wd_release_rx_packet();

Advanced issues

Choosing Protocol Version

There are three diferent versions of WiDom implemented in nano-RK:

  • Widom Single Broadcast Domain (SBD) using the CC2420 to send priority bits and data messages (WD_SBD_CC2420 - This version works in both the FireFly and MicaZ platforms);
  • Widom Single Broadcast Domain (SBD) using the CC2420 to send and receive data messages and the RFLINX OOK add-on board, a.k.a. wings board for bit arbitration (WD_SBD_RFLNX - This version works only in the FireFly platform);
  • Widom Multiple Broadcast Domains (MBD) that relies on an external synchronization device (WD_MBD_EXT_SYNC - This version works only in the FireFly platform).

    The version that is compiled is chosen in widom.h.

1// define mode/version of the protocol (WD_SBD_CC2420, WD_SBD_RFLNX, WD_MBD_EXT_SYNC)
2#define WD_VERSION WD_SBD_CC2420

Protocol Parameters

The protocol parameters can be set in widom.h. Usually, there is no need to change this.
The number of priority bits used is defined by NPRIOBITS.
The time out parameters (E, G, ETG) can be set in micro-seconds units. We also can define the maximum
packet duration allowed.
The default parameters are based on the the following parameters: ε = 10−5, CLK = 1/8 × 10−6,
L = 5us, α = 1us, TFCS = 256us and SYNC_ERROR = 50us. This gives the timeouts F = 320us,
G = 58us and ETG = 59us.

1// num of priorities
2#define NPRIOBITS 3 // number of priority bits
3// timeouts interval constants (in us)
4#define H_us 320 // duration of a pulse of a carrier
5#define G_us 58 // "guarding" time between bits
6#define ETG_us 59 // "guarding" time after the tournament
7#define CMSG_us WD_MAX_MSG_LEN_us // max time to tx our messages

The parameters related to the synchronization are the the following. The amount of time before
receiving the synchronization packet the node must start polling for it is defined by three parameters
(WD_MAX_BLOCKING_TIME, _WD_SYNC_PULSE_RX_SWX and WD_SYNC_WITH_MASTER_MAX_ERROR).
The synchronization period is automatically defined by WD_SYNC_PERIOD as a function of the duration of
the tournament and message transmission.

1// these three parameters define how long we wake up before the synchronization
2#define WD_MAX_BLOCKING_TIME_us 150 // maximum blocking widom may experience
3#define WD_SYNC_PULSE_RX_SWX_us 256 // time to switch to rx and lock on to the preamble
4#define WD_SYNC_WITH_MASTER_MAX_ERROR 400 // maximum difference with synch master