µracoli Manual Version foo

- µracoli
- User Guide
- Reference Guide

Data Structures
Radio API

The high level interface to the radio chip.
More...

## 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...

## Detailed Description

### Overview

Radio API in liburacoli_<board>.a

Usage

#include "board.h"
#include "radio.h"
void main()
{
radio_init(rxbuf, MAX_FRAME_SIZE);
...
}

Examples

- xmpl_linbuf_rx.c
- xmpl_linbuf_tx.c
- xmpl_radio_range.c
- xmpl_radio_stream.c

## Functions

radio_cca_t radio_do_cca | ( | void |  | ) |

Returns
  cca status (see radio_cca_t)

void radio_force_state | ( | radio_state_t | state | ) |

Parameters

  state | requested radio state

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

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

Examples:
  xmpl_linbuf_rx.c, xmpl_linbuf_tx.c, xmpl_radio_range.c, and xmpl_radio_stream.c.

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

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)

Examples:
  xmpl_linbuf_tx.c, xmpl_radio_range.c, and xmpl_radio_stream.c.

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

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)

Examples:

1 radio_set_param(RP_IDLESTATE(STATE_RX));
1 #define CHANNEL (17)
2
3 radio_set_param(RP_CHANNEL(CHANNEL));

Examples:
  xmpl_linbuf_rx.c, xmpl_linbuf_tx.c, xmpl_radio_range.c, and xmpl_radio_stream.c.

void radio_set_state | ( | radio_state_t | state | ) |

Parameters

  state | requested radio state

Examples:
  xmpl_linbuf_rx.c, xmpl_linbuf_tx.c, xmpl_radio_range.c, and xmpl_radio_stream.c.

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,
|  | int8_t | ed,
|  | uint8_t | crc_fail
| ) |  |

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

Examples:
  xmpl_linbuf_rx.c, xmpl_radio_range.c, and xmpl_radio_stream.c.

void usr_radio_tx_done | ( | radio_tx_done_t | status | ) |

Transmit done callback function.

Parameters

  status | completion status, radio_tx_done_t

Examples:
  xmpl_radio_range.c.

## Data Structure Documentation

union radio_param_t

Note
  The elements in this union should have max. a size of 2 byte, all other parameters should be configured with the void pointer.

Definition at line 165 of file radio.h.

Data Fields
ccamode_t | cca_mode | Value for cca mode.
channel_t | channel | Value for current radio channel. (MIN_CHANNEL ... MAX_CHANNEL)
uint8_t | data_rate | data rate type
radio_state_t | idle_state | after TX go to idle state
uint64_t * | long_addr | Pointer to long (64-bit) address
uint16_t | pan_id | Value for PANID
uint8_t | rx_lna | RX LNA type
uint16_t | short_addr | Value for short address
uint8_t | tx_pa | TX power amp type
txpwr_t | tx_pwr | Value for transmit power in dB.

struct radio_status_t

Definition at line 219 of file radio.h.

Data Fields
uint8_t | cca_mode | Current cca mode.
uint8_t | channel | Current radio channel. (MIN_CHANNEL ... MAX_CHANNEL)
radio_state_t | idle_state | after TX go to idle state
uint8_t | rx_lna |
uint8_t * | rxframe | Pointer for frame data storage.
uint8_t | rxframesz | Length of the buffer rxframesz
radio_state_t | state | Current transceiver state.
uint8_t | tx_pa |
uint8_t | tx_pwr | Current transmit power.

## Typedefs

typedef uint8_t radio_state_t

Radio state type, supported values are

- STATE_OFF,
- STATE_TX,
- STATE_TXAUTO,
- STATE_RX,
- STATE_RXAUTO,
- STATE_SLEEP.

Definition at line 78 of file radio.h.

## Defines

#define MOD_BPSK_20 (0)

PHY modulation BPSK, 20 kbit/s

Definition at line 197 of file const.h.

#define MOD_BPSK_40 (1)

PHY modulation BPSK, 40 kbit/s

Definition at line 198 of file const.h.

#define MOD_OQPSK_100 (2)

PHY modulation O-QPSK, 100 kbit/s

Definition at line 199 of file const.h.

#define MOD_OQPSK_1000 (7)

PHY modulation O-QPSK, 1000 kbit/s

Definition at line 204 of file const.h.

#define MOD_OQPSK_200 (3)

PHY modulation O-QPSK, 200 kbit/s

Definition at line 200 of file const.h.

#define MOD_OQPSK_2000 (8)

PHY modulation O-QPSK, 2000 kbit/s

Definition at line 205 of file const.h.

#define MOD_OQPSK_250 (4)

PHY modulation O-QPSK, 250 kbit/s

Definition at line 201 of file const.h.

#define MOD_OQPSK_400 (5)

PHY modulation O-QPSK, 400 kbit/s

Definition at line 202 of file const.h.

#define MOD_OQPSK_500 (6)

PHY modulation O-QPSK, 500 kbit/s

Definition at line 203 of file const.h.

#define RADIO_AT86RF212 (4)

Identifier for radio AT86RF212

Definition at line 181 of file const.h.

#define RADIO_AT86RF230 (1)

Identifier for radio AT86RF230

Definition at line 177 of file const.h.

#define RADIO_AT86RF230A (RADIO_AT86RF230)

Identifier for radio AT86RF230 Rev A

Definition at line 178 of file const.h.

#define RADIO_AT86RF230B (2)

Identifier for radio AT86RF230 Rev B

Definition at line 179 of file const.h.

#define RADIO_AT86RF231 (3)

Identifier for radio AT86RF231

Definition at line 180 of file const.h.

#define RADIO_AT86RF232 (9)

Identifier for radio AT86RF232

Definition at line 186 of file const.h.

#define RADIO_AT86RF233 (10)

Identifier for radio AT86RF233

Definition at line 187 of file const.h.

#define RADIO_ATMEGA128RFA1_A (5)

Identifier for radio ATmega128RFA1 Rev. A

Definition at line 182 of file const.h.

#define RADIO_ATMEGA128RFA1_B (6)

Identifier for radio ATmega128RFA1 Rev. B

Definition at line 183 of file const.h.

#define RADIO_ATMEGA128RFA1_C (7)

Identifier for radio ATmega128RFA1 Rev. C

Definition at line 184 of file const.h.

#define RADIO_ATMEGA128RFA1_D (8)

Identifier for radio ATmega128RFA1 Rev. D

Definition at line 185 of file const.h.

#define RADIO_ATMEGA2564RFR2 (12)

Identifier for radio ATmega128RFR2

Definition at line 189 of file const.h.

#define RADIO_ATMEGA256RFR2 (11)

Identifier for radio ATmega128RFR2

Definition at line 188 of file const.h.

#define RADIO_BAND_2400 (4)

2.4GHz frequency band (international)

Definition at line 194 of file const.h.

#define RADIO_BAND_700 (1)

700MHz frequency band (china)

Definition at line 191 of file const.h.

#define RADIO_BAND_800 (2)

868MHz frequency band (europe)

Definition at line 192 of file const.h.

#define RADIO_BAND_900 (3)

900MHz frequency band (north america)

Definition at line 193 of file const.h.

#define RADIO_CFG_DATA {chan: 16, txp: 0, cca: 1, edt: 11, clkm: 0, crc: 0xab12}

a default radio configuration data structure

Definition at line 370 of file radio.h.

#define RADIO_CFG_EEOFFSET (8)

offset of radio config data in EEPROM

Definition at line 365 of file radio.h.

#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 281 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`.

Helper macro to construct the arguments for radio_set_param in order to set the TX power amplifier enable number to `x`.

Examples:
  xmpl_linbuf_rx.c, xmpl_linbuf_tx.c, xmpl_radio_range.c, and xmpl_radio_stream.c.

Definition at line 342 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`.

Helper macro to construct the arguments for radio_set_param in order to set the TX power amplifier enable number to `x`.

Definition at line 342 of file radio.h.

#define RP_DATARATE | ( |  | x | ) |

Helper macro to construct the arguments for radio_set_param in order to set the data rate to `x`.

Examples:
  xmpl_radio_range.c.

Definition at line 330 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`.

Examples:
  xmpl_radio_range.c, and xmpl_radio_stream.c.

Definition at line 269 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 317 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`.

Examples:
  xmpl_radio_range.c.

Definition at line 293 of file radio.h.

#define RP_RX_LNA | ( |  | x | ) |

Helper macro to construct the arguments for radio_set_param in order to set the TX power amplifier enable number to `x`.

Definition at line 354 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`.

Examples:
  xmpl_radio_range.c.

Definition at line 305 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 257 of file radio.h.

#define STATE_OFF (0)

Radio state enumerationTRX in OFF state.

Examples:
  HelloRadio.ino, IoRadio.ino, xmpl_radio_range.c, and xmpl_radio_stream.c.

Definition at line 58 of file radio.h.

#define STATE_RX (2)

Basic mode RX state.

Examples:
  xmpl_linbuf_rx.c, xmpl_radio_stream.c, and xmpl_trx_echo.c.

Definition at line 62 of file radio.h.

#define STATE_RXAUTO (4)

Extended mode RX state (RX_AACK).

Examples:
  xmpl_radio_range.c.

Definition at line 66 of file radio.h.

#define STATE_SLEEP (5)

Sleep state (lowest power consumption).

Examples:
  Remote.ino.

Definition at line 68 of file radio.h.

#define STATE_TX (1)

Basic mode TX state.

Examples:
  xmpl_linbuf_tx.c, xmpl_radio_stream.c, and xmpl_trx_echo.c.

Definition at line 60 of file radio.h.

#define STATE_TXAUTO (3)

Extended mode TX state (TX_ARET).

Examples:
  xmpl_radio_range.c.

Definition at line 64 of file radio.h.

#define VOID_RSSI (0xff)

Code for invalid RSSI value.

Definition at line 238 of file radio.h.

## Enums

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
phyDataRate | Datarate
phyTxPa | PA enable
phyRxLna | LNA enable

Definition at line 119 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 95 of file radio.h.

enum radio_error_t

Enumerator
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 203 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 83 of file radio.h.