at86rf2xx.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2015 Freie Universität Berlin
3  *
4  * This file is subject to the terms and conditions of the GNU Lesser General
5  * Public License v2.1. See the file LICENSE in the top level directory for more
6  * details.
7  */
8 
29 #ifndef AT86RF2XX_H
30 #define AT86RF2XX_H
31 
32 #include <stdint.h>
33 #include <stdbool.h>
34 
35 #include "board.h"
36 #include "kernel_defines.h"
37 #include "net/netdev.h"
38 #include "net/netdev/ieee802154.h"
39 #include "net/gnrc/nettype.h"
40 
41 /* we need no peripherals for memory mapped radios */
42 #if !defined(MODULE_AT86RFA1) && !defined(MODULE_AT86RFR2)
43 #include "periph/spi.h"
44 #include "periph/gpio.h"
45 #endif
46 
47 #ifdef __cplusplus
48 extern "C" {
49 #endif
50 
54 #define AT86RF2XX_MAX_PKT_LENGTH (IEEE802154_FRAME_LEN_MAX)
55 
60 #ifdef MODULE_AT86RF212B
61 /* the AT86RF212B has a sub-1GHz radio */
62 #define AT86RF2XX_MIN_CHANNEL (IEEE802154_CHANNEL_MIN_SUBGHZ)
63 #define AT86RF2XX_MAX_CHANNEL (IEEE802154_CHANNEL_MAX_SUBGHZ)
64 #define AT86RF2XX_DEFAULT_CHANNEL (CONFIG_IEEE802154_DEFAULT_SUBGHZ_CHANNEL)
65 /* Page 2 is O-QPSK 100 kbit/s (channel 0), or 250 kbit/s (channels 1-10) */
66 #define AT86RF2XX_DEFAULT_PAGE (CONFIG_IEEE802154_DEFAULT_SUBGHZ_PAGE)
67 #else
68 #define AT86RF2XX_MIN_CHANNEL (IEEE802154_CHANNEL_MIN)
69 #define AT86RF2XX_MAX_CHANNEL (IEEE802154_CHANNEL_MAX)
70 #define AT86RF2XX_DEFAULT_CHANNEL (CONFIG_IEEE802154_DEFAULT_CHANNEL)
71 /* Only page 0 is supported in the 2.4 GHz band */
72 #endif
73 
78 #define AT86RF2XX_DEFAULT_TXPOWER (CONFIG_IEEE802154_DEFAULT_TXPOWER)
79 
83 #if MODULE_AT86RF233
84 # define RSSI_BASE_VAL (-94)
85 #elif MODULE_AT86RF212B
86 
90 # define RSSI_BASE_VAL (-98)
91 #elif MODULE_AT86RFA1 || MODULE_AT86RFR2
92 # define RSSI_BASE_VAL (-90)
93 #else
94 # define RSSI_BASE_VAL (-91)
95 #endif
96 
100 #if MODULE_AT86RF233
101 # define MIN_RX_SENSITIVITY (-101)
102 #elif MODULE_AT86RF212B
103 # define MIN_RX_SENSITIVITY (-110)
104 #elif MODULE_AT86RFA1 || MODULE_AT86RFR2
105 # define MIN_RX_SENSITIVITY (-100)
106 #else
107 # define MIN_RX_SENSITIVITY (-101)
108 #endif
109 
110 #if defined(DOXYGEN) || defined(MODULE_AT86RF232) || defined(MODULE_AT86RF233) || defined(MODULE_AT86RFR2)
111 
119 #define AT86RF2XX_HAVE_RETRIES (1)
120 #else
121 #define AT86RF2XX_HAVE_RETRIES (0)
122 #endif
123 
131 #if defined(MODULE_AT86RF233) || defined(MODULE_AT86RF231) || defined(MODULE_AT86RFA1) || defined(MODULE_AT86RFR2)
132 #ifndef AT86RF2XX_RANDOM_NUMBER_GENERATOR
133 #define AT86RF2XX_RANDOM_NUMBER_GENERATOR (1)
134 #endif
135 #else
136 #ifndef AT86RF2XX_RANDOM_NUMBER_GENERATOR
137 #define AT86RF2XX_RANDOM_NUMBER_GENERATOR (0)
138 #endif
139 #endif
140 
149 #if defined(MODULE_AT86RF233) || defined(MODULE_AT86RFR2)
150 #ifndef AT86RF2XX_SMART_IDLE_LISTENING
151 #define AT86RF2XX_SMART_IDLE_LISTENING (1)
152 #endif
153 #else
154 #define AT86RF2XX_SMART_IDLE_LISTENING (0)
155 #endif
156 
161 #define AT86RF2XX_STATE_P_ON (0x00)
162 #define AT86RF2XX_STATE_BUSY_RX (0x01)
163 #define AT86RF2XX_STATE_BUSY_TX (0x02)
164 #define AT86RF2XX_STATE_FORCE_TRX_OFF (0x03)
165 #define AT86RF2XX_STATE_RX_ON (0x06)
166 #define AT86RF2XX_STATE_TRX_OFF (0x08)
167 #define AT86RF2XX_STATE_PLL_ON (0x09)
168 #define AT86RF2XX_STATE_SLEEP (0x0f)
169 #define AT86RF2XX_STATE_BUSY_RX_AACK (0x11)
170 #define AT86RF2XX_STATE_BUSY_TX_ARET (0x12)
171 #define AT86RF2XX_STATE_RX_AACK_ON (0x16)
172 #define AT86RF2XX_STATE_TX_ARET_ON (0x19)
173 #define AT86RF2XX_STATE_IN_PROGRESS (0x1f)
180 #define AT86RF2XX_OPT_TELL_TX_START (0x0001)
182 #define AT86RF2XX_OPT_TELL_TX_END (0x0002)
184 #define AT86RF2XX_OPT_TELL_RX_START (0x0004)
186 #define AT86RF2XX_OPT_TELL_RX_END (0x0008)
188 #define AT86RF2XX_OPT_CSMA (0x0010)
189 #define AT86RF2XX_OPT_PROMISCUOUS (0x0020)
191 #define AT86RF2XX_OPT_PRELOADING (0x0040)
192 #define AT86RF2XX_OPT_AUTOACK (0x0080)
193 #define AT86RF2XX_OPT_ACK_PENDING (0x0100)
198 #if IS_ACTIVE(AT86RF2XX_BASIC_MODE) || defined(DOXYGEN)
199 
202 #define AT86RF2XX_PHY_STATE_RX AT86RF2XX_STATE_RX_ON
203 
206 #define AT86RF2XX_PHY_STATE_RX_BUSY AT86RF2XX_STATE_BUSY_RX
207 
210 #define AT86RF2XX_PHY_STATE_TX AT86RF2XX_STATE_PLL_ON
211 
214 #define AT86RF2XX_PHY_STATE_TX_BUSY AT86RF2XX_STATE_BUSY_TX
215 #else
216 #define AT86RF2XX_PHY_STATE_RX AT86RF2XX_STATE_RX_AACK_ON
217 #define AT86RF2XX_PHY_STATE_RX_BUSY AT86RF2XX_STATE_BUSY_RX_AACK
218 #define AT86RF2XX_PHY_STATE_TX AT86RF2XX_STATE_TX_ARET_ON
219 #define AT86RF2XX_PHY_STATE_TX_BUSY AT86RF2XX_STATE_BUSY_TX_ARET
220 #endif /* IS_ACTIVE(AT86RF2XX_BASIC_MODE) */
221 
222 #if defined(MODULE_AT86RFA1) || defined(MODULE_AT86RFR2)
223 
226 typedef void at86rf2xx_params_t;
227 #else
228 
231 typedef struct at86rf2xx_params {
232  spi_t spi;
233  spi_clk_t spi_clk;
234  spi_cs_t cs_pin;
235  gpio_t int_pin;
236  gpio_t sleep_pin;
237  gpio_t reset_pin;
238 } at86rf2xx_params_t;
239 #endif
240 
246 typedef struct {
247  netdev_ieee802154_t netdev;
248 #if defined(MODULE_AT86RFA1) || defined(MODULE_AT86RFR2)
249  /* ATmega256rfr2 signals transceiver events with different interrupts
250  * they have to be stored to mimic the same flow as external transceiver
251  * Use irq_status to map saved interrupts of SOC transceiver,
252  * as they clear after IRQ callback.
253  *
254  * irq_status = IRQ_STATUS
255  */
256  uint8_t irq_status;
257 #else
258  /* device specific fields */
259  at86rf2xx_params_t params;
260 #endif
261  uint16_t flags;
262  uint8_t state;
263  uint8_t tx_frame_len;
264 #ifdef MODULE_AT86RF212B
265  /* Only AT86RF212B supports multiple pages (PHY modes) */
266  uint8_t page;
267 #endif
268  uint8_t idle_state;
269  uint8_t pending_tx;
272 #if AT86RF2XX_HAVE_RETRIES
273  /* Only radios with the XAH_CTRL_2 register support frame retry reporting */
274  int8_t tx_retries;
275 #endif
276 
277 } at86rf2xx_t;
278 
287 void at86rf2xx_setup(at86rf2xx_t *dev, const at86rf2xx_params_t *params, uint8_t index);
288 
294 void at86rf2xx_reset(at86rf2xx_t *dev);
295 
304 void at86rf2xx_get_addr_short(const at86rf2xx_t *dev, network_uint16_t *addr);
305 
312 void at86rf2xx_set_addr_short(at86rf2xx_t *dev, const network_uint16_t *addr);
313 
322 void at86rf2xx_get_addr_long(const at86rf2xx_t *dev, eui64_t *addr);
323 
330 void at86rf2xx_set_addr_long(at86rf2xx_t *dev, const eui64_t *addr);
331 
339 uint8_t at86rf2xx_get_chan(const at86rf2xx_t *dev);
340 
347 void at86rf2xx_set_chan(at86rf2xx_t *dev, uint8_t chan);
348 
356 uint8_t at86rf2xx_get_page(const at86rf2xx_t *dev);
357 
364 void at86rf2xx_set_page(at86rf2xx_t *dev, uint8_t page);
365 
372 uint8_t at86rf2xx_get_phy_mode(at86rf2xx_t *dev);
373 
381 uint8_t at86rf2xx_get_rate(at86rf2xx_t *dev);
382 
397 int at86rf2xx_set_rate(at86rf2xx_t *dev, uint8_t rate);
398 
406 uint16_t at86rf2xx_get_pan(const at86rf2xx_t *dev);
407 
414 void at86rf2xx_set_pan(at86rf2xx_t *dev, uint16_t pan);
415 
423 int16_t at86rf2xx_get_txpower(const at86rf2xx_t *dev);
424 
436 void at86rf2xx_set_txpower(const at86rf2xx_t *dev, int16_t txpower);
437 
445 int8_t at86rf2xx_get_rxsensitivity(const at86rf2xx_t *dev);
446 
458 void at86rf2xx_set_rxsensitivity(const at86rf2xx_t *dev, int8_t rxsens);
459 
467 uint8_t at86rf2xx_get_max_retries(const at86rf2xx_t *dev);
468 
479 void at86rf2xx_set_max_retries(const at86rf2xx_t *dev, uint8_t max);
480 
488 uint8_t at86rf2xx_get_csma_max_retries(const at86rf2xx_t *dev);
489 
501 void at86rf2xx_set_csma_max_retries(const at86rf2xx_t *dev, int8_t retries);
502 
513 void at86rf2xx_set_csma_backoff_exp(const at86rf2xx_t *dev,
514  uint8_t min, uint8_t max);
515 
522 void at86rf2xx_set_csma_seed(const at86rf2xx_t *dev, const uint8_t entropy[2]);
523 
531 int8_t at86rf2xx_get_cca_threshold(const at86rf2xx_t *dev);
532 
539 void at86rf2xx_set_cca_threshold(const at86rf2xx_t *dev, int8_t value);
540 
548 int8_t at86rf2xx_get_ed_level(at86rf2xx_t *dev);
549 
557 void at86rf2xx_set_option(at86rf2xx_t *dev, uint16_t option, bool state);
558 
567 uint8_t at86rf2xx_set_state(at86rf2xx_t *dev, uint8_t state);
568 
581 size_t at86rf2xx_send(at86rf2xx_t *dev, const uint8_t *data, size_t len);
582 
591 void at86rf2xx_tx_prepare(at86rf2xx_t *dev);
592 
603 size_t at86rf2xx_tx_load(at86rf2xx_t *dev, const uint8_t *data,
604  size_t len, size_t offset);
605 
611 void at86rf2xx_tx_exec(at86rf2xx_t *dev);
612 
623 bool at86rf2xx_cca(at86rf2xx_t *dev);
624 
625 #ifdef __cplusplus
626 }
627 #endif
628 
629 #endif /* AT86RF2XX_H */
630 
at86rf2xx_t::idle_state
uint8_t idle_state
state to return to after sending
Definition: at86rf2xx.h:268
at86rf2xx_set_option
void at86rf2xx_set_option(at86rf2xx_t *dev, uint16_t option, bool state)
Enable or disable driver specific options.
at86rf2xx_set_cca_threshold
void at86rf2xx_set_cca_threshold(const at86rf2xx_t *dev, int8_t value)
Set the CCA threshold value.
at86rf2xx_t::params
at86rf2xx_params_t params
parameters for initialization
Definition: at86rf2xx.h:259
at86rf2xx_tx_exec
void at86rf2xx_tx_exec(at86rf2xx_t *dev)
Trigger sending of data previously loaded into transmit buffer.
kernel_defines.h
Common macros and compiler attributes/pragmas configuration.
ieee802154.h
Definitions for netdev common IEEE 802.15.4 code.
be_uint16_t
A 16 bit integer in big endian aka network byte order.
Definition: byteorder.h:77
spi.h
Low-level SPI peripheral driver interface definition.
at86rf2xx_params::cs_pin
spi_cs_t cs_pin
GPIO pin connected to chip select.
Definition: at86rf2xx.h:234
at86rf2xx_set_txpower
void at86rf2xx_set_txpower(const at86rf2xx_t *dev, int16_t txpower)
Set the transmission power of the given device [in dBm].
at86rf2xx_params::spi
spi_t spi
SPI bus the device is connected to.
Definition: at86rf2xx.h:232
at86rf2xx_t::pending_tx
uint8_t pending_tx
keep track of pending TX calls this is required to know when to return to at86rf2xx_t::idle_state
Definition: at86rf2xx.h:269
at86rf2xx_t::flags
uint16_t flags
Device specific flags.
Definition: at86rf2xx.h:261
at86rf2xx_get_addr_long
void at86rf2xx_get_addr_long(const at86rf2xx_t *dev, eui64_t *addr)
Get the configured long address of the given device.
at86rf2xx_cca
bool at86rf2xx_cca(at86rf2xx_t *dev)
Perform one manual channel clear assessment (CCA)
at86rf2xx_get_cca_threshold
int8_t at86rf2xx_get_cca_threshold(const at86rf2xx_t *dev)
Get the CCA threshold value.
at86rf2xx_params_t
struct at86rf2xx_params at86rf2xx_params_t
struct holding all params needed for device initialization
at86rf2xx_set_addr_short
void at86rf2xx_set_addr_short(at86rf2xx_t *dev, const network_uint16_t *addr)
Set the short address of the given device.
at86rf2xx_params::spi_clk
spi_clk_t spi_clk
SPI clock speed to use.
Definition: at86rf2xx.h:233
at86rf2xx_get_addr_short
void at86rf2xx_get_addr_short(const at86rf2xx_t *dev, network_uint16_t *addr)
Get the short address of the given device.
spi_cs_t
gpio_t spi_cs_t
Chip select pin type overlaps with gpio_t so it can be casted to this.
Definition: spi.h:126
at86rf2xx_get_max_retries
uint8_t at86rf2xx_get_max_retries(const at86rf2xx_t *dev)
Get the maximum number of retransmissions.
at86rf2xx_get_rxsensitivity
int8_t at86rf2xx_get_rxsensitivity(const at86rf2xx_t *dev)
Get the configured receiver sensitivity of the given device [in dBm].
at86rf2xx_send
size_t at86rf2xx_send(at86rf2xx_t *dev, const uint8_t *data, size_t len)
Convenience function for simply sending data.
at86rf2xx_get_csma_max_retries
uint8_t at86rf2xx_get_csma_max_retries(const at86rf2xx_t *dev)
Get the maximum number of channel access attempts per frame (CSMA)
spi_clk_t
spi_clk_t
Available SPI clock speeds.
Definition: spi.h:173
at86rf2xx_set_csma_max_retries
void at86rf2xx_set_csma_max_retries(const at86rf2xx_t *dev, int8_t retries)
Set the maximum number of channel access attempts per frame (CSMA)
netdev.h
Definitions low-level network driver interface.
at86rf2xx_set_addr_long
void at86rf2xx_set_addr_long(at86rf2xx_t *dev, const eui64_t *addr)
Set the long address of the given device.
at86rf2xx_set_csma_backoff_exp
void at86rf2xx_set_csma_backoff_exp(const at86rf2xx_t *dev, uint8_t min, uint8_t max)
Set the min and max backoff exponent for CSMA/CA.
nettype.h
Protocol type definitions.
at86rf2xx_tx_load
size_t at86rf2xx_tx_load(at86rf2xx_t *dev, const uint8_t *data, size_t len, size_t offset)
Load chunks of data into the transmit buffer of the given device.
at86rf2xx_t::tx_frame_len
uint8_t tx_frame_len
length of the current TX frame
Definition: at86rf2xx.h:263
at86rf2xx_get_rate
uint8_t at86rf2xx_get_rate(at86rf2xx_t *dev)
Get the current O-QPSK rate mode of the PHY.
at86rf2xx_tx_prepare
void at86rf2xx_tx_prepare(at86rf2xx_t *dev)
Prepare for sending of data.
at86rf2xx_params::sleep_pin
gpio_t sleep_pin
GPIO pin connected to the sleep pin.
Definition: at86rf2xx.h:236
at86rf2xx_get_pan
uint16_t at86rf2xx_get_pan(const at86rf2xx_t *dev)
Get the configured PAN ID of the given device.
at86rf2xx_setup
void at86rf2xx_setup(at86rf2xx_t *dev, const at86rf2xx_params_t *params, uint8_t index)
Setup an AT86RF2xx based device state.
at86rf2xx_get_phy_mode
uint8_t at86rf2xx_get_phy_mode(at86rf2xx_t *dev)
Get the PHY mode of the given device.
netdev_ieee802154_t
Extended structure to hold IEEE 802.15.4 driver state.
Definition: ieee802154.h:90
at86rf2xx_params::reset_pin
gpio_t reset_pin
GPIO pin connected to the reset pin.
Definition: at86rf2xx.h:237
at86rf2xx_get_txpower
int16_t at86rf2xx_get_txpower(const at86rf2xx_t *dev)
Get the configured transmission power of the given device [in dBm].
gpio.h
Low-level GPIO peripheral driver interface definitions.
at86rf2xx_reset
void at86rf2xx_reset(at86rf2xx_t *dev)
Trigger a hardware reset and configure radio with default values.
at86rf2xx_t::tx_retries
int8_t tx_retries
Number of NOACK retransmissions.
Definition: at86rf2xx.h:274
at86rf2xx_t::netdev
netdev_ieee802154_t netdev
netdev parent struct
Definition: at86rf2xx.h:247
at86rf2xx_get_ed_level
int8_t at86rf2xx_get_ed_level(at86rf2xx_t *dev)
Get the latest ED level measurement.
at86rf2xx_set_state
uint8_t at86rf2xx_set_state(at86rf2xx_t *dev, uint8_t state)
Set the state of the given device (trigger a state change)
eui64_t
Data type to represent an EUI-64.
Definition: eui64.h:55
at86rf2xx_set_rate
int at86rf2xx_set_rate(at86rf2xx_t *dev, uint8_t rate)
Set the current O-QPSK rate mode of the PHY rate modes > 0 are proprietary.
at86rf2xx_set_max_retries
void at86rf2xx_set_max_retries(const at86rf2xx_t *dev, uint8_t max)
Set the maximum number of retransmissions.
at86rf2xx_set_rxsensitivity
void at86rf2xx_set_rxsensitivity(const at86rf2xx_t *dev, int8_t rxsens)
Set the receiver sensitivity of the given device [in dBm].
at86rf2xx_set_csma_seed
void at86rf2xx_set_csma_seed(const at86rf2xx_t *dev, const uint8_t entropy[2])
Set seed for CSMA random backoff.
at86rf2xx_t::state
uint8_t state
current state of the radio
Definition: at86rf2xx.h:262
at86rf2xx_set_pan
void at86rf2xx_set_pan(at86rf2xx_t *dev, uint16_t pan)
Set the PAN ID of the given device.
at86rf2xx_params::int_pin
gpio_t int_pin
GPIO pin connected to the interrupt pin.
Definition: at86rf2xx.h:235
at86rf2xx_t
Device descriptor for AT86RF2XX radio devices.
Definition: at86rf2xx.h:246
at86rf2xx_set_page
void at86rf2xx_set_page(at86rf2xx_t *dev, uint8_t page)
Set the channel page of the given device.
at86rf2xx_set_chan
void at86rf2xx_set_chan(at86rf2xx_t *dev, uint8_t chan)
Set the channel number of the given device.
at86rf2xx_params
struct holding all params needed for device initialization
Definition: at86rf2xx.h:231
spi_t
unsigned int spi_t
Default type for SPI devices.
Definition: spi.h:118
at86rf2xx_get_page
uint8_t at86rf2xx_get_page(const at86rf2xx_t *dev)
Get the configured channel page of the given device.
at86rf2xx_get_chan
uint8_t at86rf2xx_get_chan(const at86rf2xx_t *dev)
Get the configured channel number of the given device.