Ref::Radio

Radio interface allows for transmitting and receiving data over a wireless channel. This is a low level interface, on the top of which various MAC and other communications protocols can be built.

Location

• mos/include/radio.h
• mos/arch/radio_hal.h

Functions

// The receive function defined by the user should look like this
typedef void (*RadioRecvFunction)(void);

// Initialize the radio
void radioInit(void);

// (Re)initialize radio communications (serial/SPI) interface
void radioReinit(void);

// Send two data buffers to radio.
// Either of the pointers is allowed to be NULL (except both at once)
// in case the respective length parameters are 0.
// @return zero on success, a negative number on error (a negated error code)
int8_t radioSendHeader(const void *header, uint16_t headerLength,
                                     const void *data, uint16_t dataLength);

// Convenience function for sending just one buffer to radio
// @return zero on success, a negative number on error (a negated error code)
int8_t radioSend(const void *data, uint16_t dataLength);

// Convenience function for sending one byte to radio
// @return zero on success, a negative number on error (a negated error code)
int8_t radioSendByte(uint8_t data);

// Receive data
// Should be called on after the radio driver has signalled the availability of a received packet
int16_t radioRecv(void *buffer, uint16_t bufferLength);

// Similar as radioRecv(), but does not keep the result, just clears the receive buffer
void radioDiscard(void);

// Set a new radio callback function.
// The callback function is called when a packet becomes available.
// In general, the callback function should call either radioRecv() to read the packet,
// or radioDiscard() to ignore it.
// @return  old callback function, if any
RadioRecvFunction radioSetReceiveHandle(RadioRecvFunction functionHandle);

// Turn radio listening on
// Note: listening is not required to be turned on to send data!
void radioOn(void);

// Turn radio listening off
void radioOff(void);

// Get RSSI (Received Signal Strength Indication) of the last received packet
int8_t radioGetLastRSSI(void);

// Get LQI (Link Quality Indication) of the last received packet
uint8_t radioGetLastLQI(void);

// Measure the current RSSI on the air
int radioGetRSSI(void);

// Radio channel control
// The exact behaviour of this function is platform- and chip-dependent.
// For IEEE 802.15.4 compatible radios (such as the CC2420)
// there are 16 channels available in the 2.4 GHz band
// in 5 MHz steps, numbered 11 through 26.
// They have 2MHz channel bandwidth, and channel separation of 5 MHz.
// Center frequency Fc in MHz is calculated as:
//    Fc = 2405 + 5 * (k – 11),
// where k is channel number.
// For example, channel 11 is 2405 MHz, channel 20: 2450 MHz, channel 26: 2480 MHz.
void radioSetChannel(int channel);

// Transmit power control
// The exact behaviour of this function is platform- and chip-dependent.
// For CC2420, a value in range [0 .. 31] is expected,
// where 0 corresponds to the minimal transmit power and 31 - to the maximum
// On CC2420, the default value is 31. Possible other values:
//   31      0 dBm    (1 mW)
//   27     -1 dBm    (0.8 mW)
//   23     -3 dBm    (0.5 mW)
//   19     -5 dBm    (0.3 mW)
//   15     -7 dBm    (0.2 mW)
//   11    -10 dBm    (0.1 mW)
//    7    -15 dBm    (0.03 mW)
//    3    -25 dBm    (0.003 mW)
void radioSetTxPower(uint8_t power);

// Returns true if CCA detects that transmission medium is free
// Always returns true if the chip doesn't have hardware CCA support
bool radioIsChannelClear(void);

Chip specific constants

The following are defined in the radio_hal.h for each radio chip or platform

#define RADIO_MAX_PACKET        0
#define RADIO_TX_POWER_MIN      0
#define RADIO_TX_POWER_MAX      0

// Chip-specific default radio channel number
#define RADIO_CHANNEL 26

// Chip-specific default radio transmission power (in chip-specific units)
#ifndef RADIO_TX_POWER 31

Example

The following example uses radio and serial port interfaces to forward data packets: apps/demo/PrintRadio