Contiki Radio Driver

Contiki uses a set structure for all of its radio drivers. This is defined by the radio_driver struct in core/dev/radio.h and every radio driver must provide the specified functions. Existing documentation on radio driver structures is limited so this page summarises the requirements of each function.

 1 struct radio_driver {
 2   int (* init)(void);
 3   int (* prepare)(const void *payload, unsigned short payload_len);	/** Prepare the radio with a packet to be sent. */
 4   int (* transmit)(unsigned short transmit_len);				/** Send the packet that has previously been prepared. */
 5   int (* send)(const void *payload, unsigned short payload_len);		/** Prepare & transmit a packet. */
 6   int (* read)(void *buf, unsigned short buf_len);			/** Read a received packet into a buffer. */
 7   int (* channel_clear)(void);						/** Perform a Clear-Channel Assessment (CCA) to find out if there is a packet in the air or not. */
 8   int (* receiving_packet)(void);					/** Check if the radio driver is currently receiving a packet */
 9   int (* pending_packet)(void);						/** Check if the radio driver has just received a packet */
10   int (* on)(void);							/** Turn the radio on. */
11   int (* off)(void);							/** Turn the radio off. */
12 };

Init:

Init initialises the radio and any dependant hardware. It should be called during the platform-specific main() function as "NETSTACK_RADIO.init()". Most drivers follow a scheme where architecture specific functions (such as SPI writing) are hived off to their own c-file so that the bulk of the driver can be shared between multiple platforms.

Prepare:

This prepares the radio with a packet. The intention seems to be that this function should load a TX buffer/FIFO with the data to be sent however the Contikimac layer will try to issue multiple Transmits from a single prepare. This can cause issues where data is not left in the FIFO and can be dealt with in two ways:

1. Copy the data to be prepared to an buffer internal to the driver and then copy this to any FIFO that the radio may have during the Transmit operation.
2. Load the data into the FIFO and, during transmit, store the first and last FIFO pointers and, if the FIFO is empty when Transmit() is called, write them back so that the same data is transmitted.

Prepare takes a pointer to the payload and an unsigned short int that indicates the number of bytes to be prepared. This function returns an int however this is ignored by both contikimac and nullrdc so the value does not matter. This function is also called by Send, which is used in all of the other MAC layers, so some return is beneficial however none is defined within Contiki.

Transmit:

Transmit sends an already prepared packet. It takes an unsigned short int that indicates the number of bytes to be transmitted and returns an int that indicates whether the transmission was successful or not. The return codes are defined in core/dev/radio.h and comprise of:

• • RADIO_TX_OK: Indicates that the transmission succeeded.
  • RADIO_TX_ERR: Indicates that an error of some description has occurred. Most drivers use this to indicate that the packet is too large.
  • RADIO_TX_COLLISION: Indicates that a collision has occurred. This is only used by contikimac (for radios that block in TX and do hardware ACK detection) and nullrdc.
  • RADIO_TX_NOACK: Indicates that no acknowledgement has been received.

Send:

Send prepares and transmits a packet. This takes a pointer to the payload and an unsigned short int that indicates the number of bytes. This function returns an int and should use the same return codes as Transmit. This should probably call the Prepare and Transmit functions.

Read:

Reads a pending packet from the radio. This function returns an int that indicates the length of the read packet.

Channel_clear:

Channel Clear performs a Channel Clear Assesment to see if there is other RF activity on the channel to avoid collisions. This function takes no arguments and returns an int that indicates whether there is radio activity. core/net/mac/contikimac.c contains a warning that a channel clear assessment may disrupt receive on some radios so this should be taken into account when writing a driver. Return codes are:

• • "0" indicates that the channel is busy.
  • "1" indicates that the channel is clear.

It should be noted that the Contikimac layer will not transmit during periods where Channel_clear returns a "0".

Receiving_packet:

This function checks whether we are currently receiving a packet. This is used by several MAC layers to detect and indicate a collision before a TX. Return codes are:

• • "0" indicates that we are not receiving a packet.
  • "1" indicates that we are receiving a packet.

Pending_packet:

Checks to see if we have a pending packet. Some drivers check a flag set by an interrupt routine. Return codes are:

• • "0" indicates that there is no pending packet.
  • "1" indicates that there is a pending packet.

On:

Turns "on" the radio. This function should put the radio into Receive mode and is called very frequently as the MAC layer turns on and off the radio rapidly. This function takes no arguments and returns an int that indicates whether the turn on succeeded. Nothing seems to use the value of return so not essential? return Return codes are:

• • "0" indicates that the radio did not turn on.
  • "1" indicates that the radio did turn on.

Off:

Turns "off" the radio. This should put the radio into Idle or a low-power state. This function takes no arguments and returns an int that indicates whether the turn off succeeded. Nothing seems to use the value of return so not essential? return Return codes are:

• • "0" indicates that the radio did not turn off.
  • "1" indicates that the radio did turn off.