# Radio Access Functions
[Radio Library libradio_<board>.a]

## Detailed Description

The high level interface to the radio chip.

This group of functions combines various register accesses (see Transceiver Access Functions) to higher primitives.

Various examples on how to use this module can be found here.

## Data Structures
union | radio_param_t
| Container for handover of radio parameter values. More...
struct | radio_status_t
| Structure for storage of radio parameters. More...
## Defines
#define | RP_CCAMODE(x)
#define | RP_CHANNEL(x)
#define | RP_IDLESTATE(x)
#define | RP_LONGADDR(x)
#define | RP_PANID(x)
#define | RP_SHORTADDR(x)
#define | RP_TXPWR(x)
#define | VOID_RSSI (0xff)
## Enumerations
enum | radio_attribute_t { phyCurrentChannel, phyChannelsSupported, phyTransmitPower, phyIdleState, phyCCAMode, phyPanId, phyShortAddr, phyLongAddr }
enum | radio_cca_t { RADIO_CCA_FREE = 0, RADIO_CCA_BUSY, RADIO_CCA_FAIL }
enum | radio_error_t { SUCCESS = 0, STATE_SET_FAILED = 1, SET_PARM_FAILED, GET_PARM_FAILED, GENERAL_ERROR }
| Error codes. More...
enum | radio_state_t { STATE_OFF = 0, STATE_TX, STATE_RX, STATE_TXAUTO, STATE_RXAUTO, STATE_SLEEP }
enum | radio_tx_done_t { TX_OK, TX_CCA_FAIL, TX_NO_ACK, TX_FAIL }
## Functions
radio_cca_t | radio_do_cca (void)
| Perform CCA Measure.
void | radio_force_state (radio_state_t state)
| Force the radio to the requested state. (using CMD_FORCE_TRX_OFF).
void | radio_init (uint8_t *rxbuf, uint8_t rxbufsz)
| Radio related ressource initialization.
void | radio_send_frame (uint8_t len, uint8_t *frm, uint8_t compcrc)
| Frame transmission.
void | radio_set_param (radio_attribute_t attr, radio_param_t parm)
| Set a radio parameter.
void | radio_set_state (radio_state_t state)
| Bring the the radio in the requested state.
void | usr_radio_error (radio_error_t err)
void | usr_radio_irq (uint8_t cause)
uint8_t * | usr_radio_receive_frame (uint8_t len, uint8_t *frm, uint8_t lqi, uint8_t rssi, uint8_t crc_fail)
| Frame reception callback function.
void | usr_radio_tx_done (radio_tx_done_t status)

## Define Documentation

#define RP_CCAMODE | ( | x |  | ) |

Helper macro to construct the arguments for radio_set_param in order to set the CCA mode to `x`.

Definition at line 261 of file radio.h.

#define RP_CHANNEL | ( | x |  | ) |

Helper macro to construct the arguments for radio_set_param in order to set the channel number to `x`.

Definition at line 222 of file radio.h.

#define RP_IDLESTATE | ( | x |  | ) |

Helper macro to construct the arguments for radio_set_param in order to set the transceiver's idle state to `x`.

Definition at line 248 of file radio.h.

#define RP_LONGADDR | ( | x |  | ) |

Helper macro to construct the arguments for radio_set_param in order to set the long address pointer to `x`.

Definition at line 300 of file radio.h.

#define RP_PANID | ( | x |  | ) |

Helper macro to construct the arguments for radio_set_param in order to set the PAN ID to `x`.

Definition at line 274 of file radio.h.

#define RP_SHORTADDR | ( | x |  | ) |

Helper macro to construct the arguments for radio_set_param in order to set the short address to `x`.

Definition at line 287 of file radio.h.

#define RP_TXPWR | ( | x |  | ) |

Helper macro to construct the arguments for radio_set_param in order to set the tx power value to `x`.

Definition at line 235 of file radio.h.

#define VOID_RSSI (0xff)

Code for invalid RSSI value.

Definition at line 214 of file radio.h.

## Enumeration Type Documentation

enum radio_attribute_t

Enumeration to identify radio attributes.

Enumerator:

  phyCurrentChannel | Set the current channel
  phyChannelsSupported | Currently unused
  phyTransmitPower | Set the Tx power
  phyIdleState | Transceiver state to return to after transmission
  phyCCAMode | CCA mode to use in CSMA-CA:
  value | CCA mode
  --- | ---
  0 | carrier sense OR energy above threshold
  1 | energy above threshold (default)
  2 | carrier sense
  3 | carrier sense AND energy above threshold
  phyPanId | PAN ID to use in STATE_RXAUTO frame filter
  phyShortAddr | Short (16-bit) address to use in STATE_RXAUTO frame filter
  phyLongAddr | Pointer to long (EUI-64) address to use in STATE_RXAUTO frame filter

Definition at line 107 of file radio.h.

enum radio_cca_t

codes for CCA

Enumerator:

  RADIO_CCA_FREE | The CCA measurement estimates, that the channel is free.
  RADIO_CCA_BUSY | The CCA measurement estimates, that the channel is busy.
  RADIO_CCA_FAIL | The CCA measurement was not finished.

Definition at line 82 of file radio.h.

enum radio_error_t

Error codes.

Enumerator:

  SUCCESS | Todo: same like CCA_FREE, include/avr/iom128rfa1.h:3687:define SUCCESS OK Code
  STATE_SET_FAILED | function radio_set_state failed
  SET_PARM_FAILED | function radio_set_param failed
  GET_PARM_FAILED | function radio_get_param failed
  GENERAL_ERROR | something unexpected happened

Definition at line 177 of file radio.h.

enum radio_state_t

Radio state enumeration

Enumerator:

  STATE_OFF | TRX is in off state
  STATE_TX | TRX is in transmit state (a call to radio_send_frame transmits a frame)
  STATE_RX | TRX is in receive state (incoming frames are signalled by the usr_radio_receive_frame callback)
  STATE_TXAUTO | TX_ARET state
  STATE_RXAUTO | RX_AACK state
  STATE_SLEEP | TRX is in sleep state (lowest power consumption)

Definition at line 52 of file radio.h.

enum radio_tx_done_t

error codes for tx done event

Enumerator:

  TX_OK | transmission completed successfully
  TX_CCA_FAIL | channel was busy (TX_AUTO only)
  TX_NO_ACK | no ACK received (TX_AUTO only)
  TX_FAIL | unexpected error

Definition at line 69 of file radio.h.

## Function Documentation

radio_cca_t radio_do_cca | ( | void |  | ) |

Perform CCA Measure.

Returns:
  cca status (see radio_cca_t)

void radio_force_state | ( | radio_state_t | state | ) |

Force the radio to the requested state. (using CMD_FORCE_TRX_OFF).

Parameters:

  | state | requested radio state

void radio_init | ( | uint8_t * | rxbuf,
|  | uint8_t | rxbufsz |
| ) |  |  |

Radio related ressource initialization.

The function initializes all IO ressources, needed for the usage of the radio and performs a reset.

Parameters:

  | rxbuf | A buffer for the receive frames. This buffer needs to be static, and of size MAX_FRAME_SIZE (see also function usr_radio_receive_frame).
  | rxbufsz | maximum size of the rx buffer, frames longer then rxbufsz will be ignored

void radio_send_frame | ( | uint8_t | len,
|  | uint8_t * | frm,
|  | uint8_t | compcrc |
| ) |  |  |

Frame transmission.

Initiates a frame transmission procedure, and then downloads the frame passed as `frm`. The function returns immediately once the frame download procedure completed; the end of transmission is signalled by the usr_radio_tx_done callback. If the radio is in STATE_TXAUTO, a full unslotted CSMA-CA is procedure is performed by the transceiver hardware, including frame retransmissions in case the transmitted frame has requested an acknowledgement by the recipient. If the transceiver is in STATE_TX, an immediate frame transmission is initiated, without CSMA-CA or frame retransmissions.

Parameters:

  | len | length of frame to transmit
  | frm | pointer to frame to transmit
  | compcrc | compute CRC-16 if != 0 (currently ignored)

void radio_set_param | ( | radio_attribute_t | attr,
|  | radio_param_t | parm |
| ) |  |  |

Set a radio parameter.

Note that the radio must not be in STATE_SLEEP when setting parameters. Preferrably, it should be kept in STATE_OFF (in which it is immediately after a call to radio_init) in order to set parameters.

Parameters:

  | attr | attribute parameter (enumeration value radio_attribute_t)
  | parm | pointer to parameter value (union type radio_param_t)

void radio_set_state | ( | radio_state_t | state | ) |

Bring the the radio in the requested state.

Parameters:

  | state | requested radio state

void usr_radio_error | ( | radio_error_t | err | ) |

Error callback function which has to be implemented in the application.

This function is called, when a fatal error occurs. see also radio_error_t.

Parameters:

  | err | error code being reported

void usr_radio_irq | ( | uint8_t | cause | ) |

Interrupt callback function.

Parameters:

  | cause | value of the transceiver's IRQ status register

uint8_t* usr_radio_receive_frame | ( | uint8_t | len,
|  | uint8_t * | frm,
|  | uint8_t | lqi,
|  | uint8_t | rssi,
|  | uint8_t | crc_fail |
| ) |  |  |

Frame reception callback function.

This function is called within an interrupt context for every received frame, according to the current receive mode used (which involves address filtering in case the transceiver is in state RX_AUTO). The frame has been internally stored into the receive buffer that has been configured before, either by radio_init, or as the result of a previous call to usr_radio_receive_frame. The function must return a valid pointer to a receive buffer to be used for receiving the next frame; this can be the same value as the parameter `frm`, or a different one in case the application wants to maintain multiple buffers.

The `rssi` parameter is obtained at the frame's RX_START interrupt. If there was no RX_START interrupt to read an RSSI value at, the value VOID_RSSI is passed instead.

Parameters:

  | len | length of frame received
  | frm | pointer to frame received
  | lqi | LQI value reported by transceiver
  | rssi | RSSI value obtained from transceiver
  | crc_fail | boolean indicating whether the received frame failed FCS verification

Returns:
  address of new receive buffer

void usr_radio_tx_done | ( | radio_tx_done_t | status | ) |

Transmit done callback function.

Parameters:

  | status | completion status, radio_tx_done_t