Contiki-NG
radio_driver Struct Reference

The structure of a Contiki-NG radio device driver. More...

#include <os/dev/radio.h>

Data Fields

int(* init )(void)
 Initialise the radio hardware. More...
 
int(* prepare )(const void *payload, unsigned short payload_len)
 Prepare the radio with a packet to be sent. More...
 
int(* transmit )(unsigned short transmit_len)
 Send the packet that has previously been prepared. More...
 
int(* send )(const void *payload, unsigned short payload_len)
 Prepare & transmit a packet. More...
 
int(* read )(void *buf, unsigned short buf_len)
 Read a received packet into a buffer. More...
 
int(* channel_clear )(void)
 Perform a Clear-Channel Assessment (CCA) to find out if there is a packet in the air or not. More...
 
int(* receiving_packet )(void)
 Check if the radio driver is currently receiving a packet. More...
 
int(* pending_packet )(void)
 Check if a packet has been received and is available in the radio driver's buffers. More...
 
int(* on )(void)
 Turn the radio on. More...
 
int(* off )(void)
 Turn the radio off. More...
 
radio_result_t(* get_value )(radio_param_t param, radio_value_t *value)
 Get a radio parameter value. More...
 
radio_result_t(* set_value )(radio_param_t param, radio_value_t value)
 Set a radio parameter value. More...
 
radio_result_t(* get_object )(radio_param_t param, void *dest, size_t size)
 Get a radio parameter object. More...
 
radio_result_t(* set_object )(radio_param_t param, const void *src, size_t size)
 Set a radio parameter object. More...
 

Detailed Description

The structure of a Contiki-NG radio device driver.

Typically this data structure will represent the driver of an IEEE 802.15.4-compliant radio hardware.

This data structure is the only required interface between the radio driver and the Contiki-NG network stack. All functions implemented in the radio driver, including those pointed to by the fields of this structure can be static.

Definition at line 534 of file radio.h.

Field Documentation

◆ channel_clear

int(* radio_driver::channel_clear) (void)

Perform a Clear-Channel Assessment (CCA) to find out if there is a packet in the air or not.

Return values
0The channel is busy
1The channel is clear

It is up to the radio driver's developer to decide how the CCA will be performed. Some radios have built-in, .15.4-compliant CCA operation; for those radios, it is up to the developer to decide which CCA mode to use.

This function should not be called while the radio is not in RX mode. If this happens, this function shall return 0 and it will not try to power-on the radio in order to perform a CCA.

Definition at line 672 of file radio.h.

◆ get_object

radio_result_t(* radio_driver::get_object) (radio_param_t param, void *dest, size_t size)

Get a radio parameter object.

Parameters
paramThe parameter to retrieve: An enumerator of radio_param_e
destA pointer to a buffer where the value of param shall be stored
sizeThe size of the dest buffer
Returns
An enumerator of radio_result_t

The argument dest must point to a memory area of at least size bytes, and this memory area will contain the parameter object if the function succeeds. dest shall be allocated by the caller.

Definition at line 770 of file radio.h.

◆ get_value

radio_result_t(* radio_driver::get_value) (radio_param_t param, radio_value_t *value)

Get a radio parameter value.

Parameters
paramThe parameter to retrieve: An enumerator of radio_param_e
valueA pointer to store the value of param
Returns
An enumerator of radio_result_t

This function shall copy the current value of parameter param to the location pointed to by value. The caller shall allocate value.

Definition at line 741 of file radio.h.

◆ init

int(* radio_driver::init) (void)

Initialise the radio hardware.

Return values
1Initialisation successful
0Initialisation failed

This function will be called once during boot. It shall perform one-off initialisation of the radio driver and hardware. Typical operations to implement as part of this function are initialisation of driver internal data structures and initial configuration of the radio hardware.

This function is expected to apply configuration that persists across radio on/off cycles. Non-persistent changes should be implemented as part of on() instead.

This function may, but is not strictly expected to put the radio in RX mode. The Contiki-NG boot sequence will put the radio in RX mode explicitly by a subsequent call to on().

Definition at line 555 of file radio.h.

◆ off

int(* radio_driver::off) (void)

Turn the radio off.

Return values
1Success
0Error

This function shall put the radio to its lowest power consumption state.

This function may be called immediately after the reception of a packet, but before this packet gets copied to the upper layers through a call to read(). If powering down the radio would result in the received packet getting lost, due to e.g. non-retention of the radio's hardware FIFO, then the radio driver shall make sure any received packets get copied to RAM first. This function shall not intentionally discard any previously received packets.

Definition at line 729 of file radio.h.

◆ on

int(* radio_driver::on) (void)

Turn the radio on.

Return values
1The call was successful and the radio is now in RX mode
0The call failed

This function will put the radio in a state ready to receive packets. The function will power-on and configure the radio if necessary.

This function shall not intentionally discard any previously received packets.

Definition at line 711 of file radio.h.

◆ pending_packet

int(* radio_driver::pending_packet) (void)

Check if a packet has been received and is available in the radio driver's buffers.

Return values
1One (or more) packet(s) is (are) available
0No packets available

This function may be called while the radio is powered down by a previous call to off(). If that happens, the function shall not power on the radio.

Definition at line 697 of file radio.h.

◆ prepare

int(* radio_driver::prepare) (const void *payload, unsigned short payload_len)

Prepare the radio with a packet to be sent.

Parameters
payloadA pointer to the location of the packet
payload_lenThe length of the packet to be sent
Return values
0Packet copied successfully
1The packet could not be copied

This function is expected to copy payload_len bytes from the location pointed to by payload to a location internal to the radio driver. In a typical scenario this will be a separate buffer in RAM, or the radio hardware's FIFO.

payload will contain the MAC header (MHR) and MAC payload, but it will not contain the physical header or the MAC footer (MFR).

payload_len must be lower than or equal to the value retrieved when calling NETSTACK_RADIO.get_value(RADIO_CONST_MAX_PAYLOAD_LEN, ...)

This function will return an error if the radio driver could not copy the packet to a location internal to the driver. Commonly this may happen if the latter is occupied by a previous packet which has yet to be sent.

Definition at line 580 of file radio.h.

◆ read

int(* radio_driver::read) (void *buf, unsigned short buf_len)

Read a received packet into a buffer.

Parameters
bufA pointer the the buffer where the packet is to be copied
buf_lenThe length of buf
Returns
The number of bytes copied to buf

If the radio has no correctly-received packets then this function will return 0.

The buffer buf will be allocated by the caller.

The radio driver is not expected to remember the packet after this call returns.

This function is expected to be able to deliver a packet to the MAC layer even if the radio is powered down by a call to off().

When this function returns, buf will contain the MAC header (MHR) and MAC payload, but it will not contain the physical header or the MAC footer (MFR).

Definition at line 655 of file radio.h.

◆ receiving_packet

int(* radio_driver::receiving_packet) (void)

Check if the radio driver is currently receiving a packet.

Return values
1Reception of a packet is in progress
0No reception in progress

If at the point of calling this function the radio is not in RX mode, for example as a result of a previous call to off(), this function will immediately return 0.

Definition at line 684 of file radio.h.

◆ send

int(* radio_driver::send) (const void *payload, unsigned short payload_len)

Prepare & transmit a packet.

Parameters
payloadA pointer to the location of the packet
payload_lenThe length of the packet to be sent
Returns
This function will return one of the radio_tx_e enumerators

This function shall behave exactly as a call to prepare(), immediately followed by a call to transmit().

Definition at line 631 of file radio.h.

◆ set_object

radio_result_t(* radio_driver::set_object) (radio_param_t param, const void *src, size_t size)

Set a radio parameter object.

Parameters
paramThe parameter to set: An enumerator of radio_param_e
srcA pointer to a buffer where the new value is stored
sizeThe size of the src buffer
Returns
An enumerator of radio_result_t

The memory area referred to by the argument src will not be accessed after the function returns.

If this function is called while the radio is powered on, the requested change shall take effect immediately. If the radio is powered-off, the change shall take effect in the next power-on cycle.

Definition at line 787 of file radio.h.

◆ set_value

radio_result_t(* radio_driver::set_value) (radio_param_t param, radio_value_t value)

Set a radio parameter value.

Parameters
paramThe parameter to set: An enumerator of radio_param_e
valueThe new value for param
Returns
An enumerator of radio_result_t

This function shall set the value of a radio parameter.

If this function is called while the radio is powered on, the requested change shall take effect immediately. If the radio is powered-off, the change shall take effect in the next power-on cycle.

Definition at line 756 of file radio.h.

◆ transmit

int(* radio_driver::transmit) (unsigned short transmit_len)

Send the packet that has previously been prepared.

Parameters
transmit_lenThe number of bytes to transmit
Returns
This function will return one of the radio_tx_e enumerators

The radio driver is not expected to remember the packet even if TX fails.

transmit_len is equal the length of a previously prepared packet. Semantically it is identical to the payload_len argument of the prepare() function.

A previously prepared packet shall contain the MAC header (MHR) and MAC payload, but it shall not contain the physical header or the MAC footer (MFR). This function shall make sure that all necessary physical layer symbols are transmitted before the packet. In the case of .15.4 radios this includes the synch header (SHR), preamble and physical header (PHR). This function shall also make sure that the MFR is transmitted.

Unless an error occurs, this function will wait until the packet has been fully transmitted.

If RADIO_PARAM_TX_MODE & RADIO_TX_MODE_SEND_ON_CCA then this function should perform a CCA before transmission. If this CCA fails the function shall return RADIO_TX_COLLISION.

This function may be called while the radio is powered-off, or while the radio is in RX mode. In the former case, it shall power on the radio and enter TX mode, ideally bypassing RX mode to reduce off->TX turnaround time. In the latter case, the function shall perform an RX-TX transition.

This function may leave the radio in RX mode after transmission, but this is not necessary since the caller will explicitly request the correct radio state after this function returns: This will either be a request to revert to RX mode by a call to on(), or a request to power the radio down by a call to off().

Definition at line 619 of file radio.h.