radio.h
1 /*
2  * Copyright (C) 2020 HAW Hamburg
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 
22 #ifndef NET_IEEE802154_RADIO_H
23 #define NET_IEEE802154_RADIO_H
24 
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28 
29 #include <stdbool.h>
30 #include "iolist.h"
31 #include "sys/uio.h"
32 #include "byteorder.h"
33 #include "net/eui64.h"
34 
39 
45 typedef enum {
122 
126 typedef enum {
160 
164 typedef enum {
178 
185 typedef enum {
192 
201 
220 
237 
241 typedef struct {
242  uint8_t min;
243  uint8_t max;
245 
249 typedef struct {
256  uint8_t rssi;
257  uint8_t lqi;
259 
263 typedef struct {
264  ieee802154_tx_status_t status;
265  int8_t retrans;
267 
272 
279 typedef void (*ieee802154_cb_t)(ieee802154_dev_t *dev,
280  ieee802154_trx_ev_t status);
281 
293  void *ctx;
298 };
299 
303 typedef enum {
321 
325 typedef enum {
355 
359 typedef struct {
360  uint16_t channel;
361  uint8_t page;
362  int8_t pow;
364 
381  int (*write)(ieee802154_dev_t *dev, const iolist_t *psdu);
382 
398 
424 
438  int (*len)(ieee802154_dev_t *dev);
439 
459  int (*read)(ieee802154_dev_t *dev, void *buf, size_t size, ieee802154_rx_info_t *info);
473  int (*off)(ieee802154_dev_t *dev);
474 
489 
516 
534  ieee802154_trx_state_t state);
535 
550 
568 
586 
596  bool (*get_cap)(ieee802154_dev_t *dev, ieee802154_rf_caps_t cap);
597 
609  int (*set_cca_threshold)(ieee802154_dev_t *dev, int8_t threshold);
610 
625  int (*set_cca_mode)(ieee802154_dev_t *dev, ieee802154_cca_mode_t mode);
626 
646 
663  const network_uint16_t *short_addr,
664  const eui64_t *ext_addr,
665  const uint16_t *pan_id);
666 
681  int (*set_frame_retrans)(ieee802154_dev_t *dev, uint8_t retrans);
682 
702  int8_t retries);
703 
713  int (*set_rx_mode)(ieee802154_dev_t *dev, ieee802154_rx_mode_t mode);
714 };
715 
724 static inline int ieee802154_radio_write(ieee802154_dev_t *dev, const iolist_t *psdu)
725 {
726  return dev->driver->write(dev, psdu);
727 }
728 
737 {
738  return dev->driver->request_transmit(dev);
739 }
740 
750  ieee802154_tx_info_t *info)
751 {
752  return dev->driver->confirm_transmit(dev, info);
753 }
754 
762 static inline int ieee802154_radio_len(ieee802154_dev_t *dev)
763 {
764  return dev->driver->len(dev);
765 }
766 
779  void *buf,
780  size_t size,
781  ieee802154_rx_info_t *info)
782 {
783  return dev->driver->read(dev, buf, size, info);
784 }
785 
795  int8_t threshold)
796 {
797  return dev->driver->set_cca_threshold(dev, threshold);
798 }
799 
809  ieee802154_cca_mode_t mode)
810 {
811  return dev->driver->set_cca_mode(dev, mode);
812 }
813 
823  const ieee802154_phy_conf_t *conf)
824 {
825  return dev->driver->config_phy(dev, conf);
826 }
827 
837 static inline int ieee802154_radio_off(ieee802154_dev_t *dev)
838 {
839  return dev->driver->off(dev);
840 }
841 
857  const network_uint16_t *short_addr,
858  const eui64_t *ext_addr,
859  const uint16_t *pan_id)
860 {
861  return dev->driver->set_hw_addr_filter(dev, short_addr, ext_addr, pan_id);
862 }
863 
877  uint8_t retrans)
878 {
879  return dev->driver->set_frame_retrans(dev, retrans);
880 }
881 
897  const ieee802154_csma_be_t *bd,
898  int8_t retries)
899 {
900  return dev->driver->set_csma_params(dev, bd, retries);
901 }
902 
911 {
912  return dev->driver->request_on(dev);
913 }
914 
923 {
924  return dev->driver->confirm_on(dev);
925 }
926 
936  ieee802154_trx_state_t state)
937 {
938  return dev->driver->request_set_trx_state(dev, state);
939 }
940 
949 {
950  return dev->driver->confirm_set_trx_state(dev);
951 }
952 
961 {
962  return dev->driver->request_cca(dev);
963 }
964 
973 {
974  return dev->driver->confirm_cca(dev);
975 }
976 
989 {
990  return dev->driver->get_cap(dev, IEEE802154_CAP_IRQ_ACK_TIMEOUT);
991 }
992 
1005 {
1006  return dev->driver->get_cap(dev, IEEE802154_CAP_FRAME_RETRANS);
1007 }
1008 
1021 {
1022  return dev->driver->get_cap(dev, IEEE802154_CAP_AUTO_CSMA);
1023 }
1024 
1037 {
1038  return dev->driver->get_cap(dev, IEEE802154_CAP_SUB_GHZ);
1039 }
1040 
1053 {
1054  return dev->driver->get_cap(dev, IEEE802154_CAP_24_GHZ);
1055 }
1056 
1069 {
1070  return dev->driver->get_cap(dev, IEEE802154_CAP_IRQ_TX_DONE);
1071 }
1072 
1085 {
1086  return dev->driver->get_cap(dev, IEEE802154_CAP_IRQ_RX_START);
1087 }
1088 
1101 {
1102  return dev->driver->get_cap(dev, IEEE802154_CAP_IRQ_TX_START);
1103 }
1104 
1117 {
1118  return dev->driver->get_cap(dev, IEEE802154_CAP_IRQ_CCA_DONE);
1119 }
1120 
1134  ieee802154_dev_t *dev)
1135 {
1137 }
1138 
1148  ieee802154_rx_mode_t mode)
1149 {
1150  return dev->driver->set_rx_mode(dev, mode);
1151 }
1152 
1153 #ifdef __cplusplus
1154 }
1155 #endif
1156 
1157 #endif /* NET_IEEE802154_RADIO_H */
1158 
ieee802154_trx_ev_t
IEEE802.15.4 Radio HAL events.
Definition: radio.h:185
EUI-64 data type definition.
int(* set_cca_mode)(ieee802154_dev_t *dev, ieee802154_cca_mode_t mode)
Set CCA mode.
Definition: radio.h:625
the transceiver is ready to receive/receiving frames
Definition: radio.h:172
int(* set_cca_threshold)(ieee802154_dev_t *dev, int8_t threshold)
Set the threshold for the Energy Detection (first mode of CCA)
Definition: radio.h:609
ieee802154_rx_mode_t
RX mode configuration.
Definition: radio.h:325
static int ieee802154_radio_set_hw_addr_filter(ieee802154_dev_t *dev, const network_uint16_t *short_addr, const eui64_t *ext_addr, const uint16_t *pan_id)
Shortcut to ieee802154_radio_ops::set_hw_addr_filter.
Definition: radio.h:856
Radio is in promiscuous mode.
Definition: radio.h:341
the device reports the end of the CCA procedure
Definition: radio.h:110
static int ieee802154_radio_request_cca(ieee802154_dev_t *dev)
Shortcut to ieee802154_radio_ops::request_cca.
Definition: radio.h:960
Radio ops struct declaration.
Definition: radio.h:368
int(* confirm_cca)(ieee802154_dev_t *dev)
Confirmation function for ieee802154_radio_ops::request_cca.
Definition: radio.h:585
Auto ACK is disabled.
Definition: radio.h:329
static bool ieee802154_radio_has_irq_cca_done(ieee802154_dev_t *dev)
Check if the device supports CCA done interrupt.
Definition: radio.h:1116
iolist scatter / gather IO
int(* off)(ieee802154_dev_t *dev)
Turn off the device.
Definition: radio.h:473
CCA using second mode (carrier sensing)
Definition: radio.h:311
ieee802154_rf_caps_t
IEEE802.15.4 Radio capabilities.
Definition: radio.h:45
static int ieee802154_radio_confirm_on(ieee802154_dev_t *dev)
Shortcut to ieee802154_radio_ops::confirm_on.
Definition: radio.h:922
the CSMA-CA algorithm or CCA failed to measure a clear channel
Definition: radio.h:158
the device retains all register values when off.
Definition: radio.h:120
static bool ieee802154_radio_has_auto_csma(ieee802154_dev_t *dev)
Check if the device supports Auto CSMA-CA for transmissions.
Definition: radio.h:1020
static int ieee802154_radio_set_csma_params(ieee802154_dev_t *dev, const ieee802154_csma_be_t *bd, int8_t retries)
Shortcut to ieee802154_radio_ops::set_csma_params.
Definition: radio.h:896
A 16 bit integer in big endian aka network byte order.
Definition: byteorder.h:77
CCA using third mode (energy detection AND carrier sensing)
Definition: radio.h:315
ieee802154_tx_status_t status
status of the last transmission
Definition: radio.h:264
ieee802154_tx_status_t
Transmission status.
Definition: radio.h:126
static int ieee802154_radio_request_set_trx_state(ieee802154_dev_t *dev, ieee802154_trx_state_t state)
Shortcut to ieee802154_radio_ops::request_set_trx_state.
Definition: radio.h:935
int8_t retrans
number of frame retransmissions of the last TX
Definition: radio.h:265
the transceiver successfully sent a frame.
Definition: radio.h:140
int(* request_on)(ieee802154_dev_t *dev)
Request to turn on the device.
Definition: radio.h:488
the transceiver is ready to transmit/transmitting a frame
Definition: radio.h:176
int(* confirm_transmit)(ieee802154_dev_t *dev, ieee802154_tx_info_t *info)
Confirmation function for ieee802154_radio_ops::request_transmit.
Definition: radio.h:423
static bool ieee802154_radio_has_24_ghz(ieee802154_dev_t *dev)
Check if the device supports the IEEE802.15.4 2.4 GHz band.
Definition: radio.h:1052
the device reports when the transmission is done
Definition: radio.h:98
Auto ACK is enabled.
Definition: radio.h:333
CCA using third mode (energy detection OR carrier sensing)
Definition: radio.h:319
static int ieee802154_radio_set_cca_threshold(ieee802154_dev_t *dev, int8_t threshold)
Shortcut to ieee802154_radio_ops::set_cca_threshold.
Definition: radio.h:794
the transceiver detected a valid SFD
Definition: radio.h:191
static bool ieee802154_radio_has_frame_retrans_info(ieee802154_dev_t *dev)
Check if the device reports the number of retransmissions of the last TX procedure.
Definition: radio.h:1133
static int ieee802154_radio_request_transmit(ieee802154_dev_t *dev)
Shortcut to ieee802154_radio_ops::request_transmit.
Definition: radio.h:736
RX information associated to a frame.
Definition: radio.h:249
int(* request_set_trx_state)(ieee802154_dev_t *dev, ieee802154_trx_state_t state)
Request a PHY state change.
Definition: radio.h:533
static bool ieee802154_radio_has_sub_ghz(ieee802154_dev_t *dev)
Check if the device supports the IEEE802.15.4 Sub-GHz band.
Definition: radio.h:1036
void(* ieee802154_cb_t)(ieee802154_dev_t *dev, ieee802154_trx_ev_t status)
Prototype of the IEEE802.15.4 device event callback.
Definition: radio.h:279
the device supports the IEEE802.15.4 2.4 GHz band
Definition: radio.h:90
int(* confirm_set_trx_state)(ieee802154_dev_t *dev)
Confirmation function for ieee802154_radio_ops::request_set_trx_state.
Definition: radio.h:549
int(* config_phy)(ieee802154_dev_t *dev, const ieee802154_phy_conf_t *conf)
Set IEEE802.15.4 PHY configuration (channel, TX power)
Definition: radio.h:645
static int ieee802154_radio_len(ieee802154_dev_t *dev)
Shortcut to ieee802154_radio_ops::len.
Definition: radio.h:762
the IEEE802.15.4 device descriptor
Definition: radio.h:285
int(* write)(ieee802154_dev_t *dev, const iolist_t *psdu)
Write a frame into the framebuffer.
Definition: radio.h:381
int8_t pow
TX power in dBm.
Definition: radio.h:362
int(* confirm_on)(ieee802154_dev_t *dev)
Confirmation function for ieee802154_radio_ops::request_on.
Definition: radio.h:515
uint8_t page
IEEE802.15.4 channel page.
Definition: radio.h:361
static int ieee802154_radio_set_frame_retrans(ieee802154_dev_t *dev, uint8_t retrans)
Shortcut to ieee802154_radio_ops::set_frame_retrans.
Definition: radio.h:876
int(* read)(ieee802154_dev_t *dev, void *buf, size_t size, ieee802154_rx_info_t *info)
Read a frame from the internal framebuffer.
Definition: radio.h:459
the device reports the start of a frame (SFD) when received.
Definition: radio.h:102
TX information of the last transmitted frame.
Definition: radio.h:263
the device supports Auto CSMA-CA
Definition: radio.h:72
bool(* get_cap)(ieee802154_dev_t *dev, ieee802154_rf_caps_t cap)
Get a cap from the radio.
Definition: radio.h:596
static bool ieee802154_radio_has_irq_rx_start(ieee802154_dev_t *dev)
Check if the device supports RX start interrupt.
Definition: radio.h:1084
uint8_t min
minimum value of the exponential backoff
Definition: radio.h:242
static bool ieee802154_radio_has_irq_tx_done(ieee802154_dev_t *dev)
Check if the device supports TX done interrupt.
Definition: radio.h:1068
ieee802154_cca_mode_t
IEEE802.15.4 CCA modes.
Definition: radio.h:303
ieee802154_trx_state_t
IEEE802.15.4 transceiver states (not to confuse with device states)
Definition: radio.h:164
int(* request_transmit)(ieee802154_dev_t *dev)
Request the transmission of a preloaded frame.
Definition: radio.h:397
ieee802154_cb_t cb
the event callback of the device
Definition: radio.h:297
the transceiver ran out of retransmission
Definition: radio.h:154
static bool ieee802154_radio_has_irq_tx_start(ieee802154_dev_t *dev)
Check if the device supports TX start interrupt.
Definition: radio.h:1100
static int ieee802154_radio_set_cca_mode(ieee802154_dev_t *dev, ieee802154_cca_mode_t mode)
Shortcut to ieee802154_radio_ops::set_cca_mode.
Definition: radio.h:808
static int ieee802154_radio_confirm_set_trx_state(ieee802154_dev_t *dev)
Shortcut to ieee802154_radio_ops::confirm_set_trx_state.
Definition: radio.h:948
Functions to work with different byte orders.
the transceiver received a frame and lies in the internal framebuffer.
Definition: radio.h:219
the device supports frame retransmissions with CSMA-CA
Definition: radio.h:62
int(* set_csma_params)(ieee802154_dev_t *dev, const ieee802154_csma_be_t *bd, int8_t retries)
Set the CSMA-CA parameters.
Definition: radio.h:701
uint8_t lqi
LQI of the received frame.
Definition: radio.h:257
the transceiver state is off
Definition: radio.h:168
static int ieee802154_radio_request_on(ieee802154_dev_t *dev)
Shortcut to ieee802154_radio_ops::request_on.
Definition: radio.h:910
const ieee802154_radio_ops_t * driver
pointer to the operations of the device
Definition: radio.h:289
static int ieee802154_radio_confirm_transmit(ieee802154_dev_t *dev, ieee802154_tx_info_t *info)
Shortcut to ieee802154_radio_ops::confirm_transmit.
Definition: radio.h:749
uint8_t max
maximum value of the exponential backoff
Definition: radio.h:243
iolist structure definition
Definition: iolist.h:39
CCA using first mode (energy detection)
Definition: radio.h:307
libc header for scatter/gather I/O
int(* set_rx_mode)(ieee802154_dev_t *dev, ieee802154_rx_mode_t mode)
Set the RX mode.
Definition: radio.h:713
CSMA-CA exponential backoff parameters.
Definition: radio.h:241
Data type to represent an EUI-64.
Definition: eui64.h:55
static bool ieee802154_radio_has_irq_ack_timeout(ieee802154_dev_t *dev)
Check if the device supports ACK timeout.
Definition: radio.h:988
void * ctx
pointer to the context of the device
Definition: radio.h:293
the transceiver sent out a valid SFD
Definition: radio.h:200
static int ieee802154_radio_off(ieee802154_dev_t *dev)
Shortcut to ieee802154_radio_ops::off.
Definition: radio.h:837
Holder of the PHY configuration.
Definition: radio.h:359
the device provides the number of retransmissions
Definition: radio.h:116
static int ieee802154_radio_set_rx_mode(ieee802154_dev_t *dev, ieee802154_rx_mode_t mode)
Shortcut to ieee802154_radio_ops::set_rx_mode.
Definition: radio.h:1147
the device support the IEEE802.15.4 Sub GHz band
Definition: radio.h:94
int(* set_hw_addr_filter)(ieee802154_dev_t *dev, const network_uint16_t *short_addr, const eui64_t *ext_addr, const uint16_t *pan_id)
Set IEEE802.15.4 addresses in hardware address filter.
Definition: radio.h:662
uint8_t rssi
RSSI of the received frame.
Definition: radio.h:256
uint16_t channel
IEEE802.15.4 channel number.
Definition: radio.h:360
static bool ieee802154_radio_has_frame_retrans(ieee802154_dev_t *dev)
Check if the device supports frame retransmissions (with CSMA-CA).
Definition: radio.h:1004
Auto ACK is enabled and frame pending bit set in the next ACK frame.
Definition: radio.h:337
static int ieee802154_radio_write(ieee802154_dev_t *dev, const iolist_t *psdu)
Shortcut to ieee802154_radio_ops::write.
Definition: radio.h:724
static int ieee802154_radio_confirm_cca(ieee802154_dev_t *dev)
Shortcut to ieee802154_radio_ops::confirm_cca.
Definition: radio.h:972
int(* set_frame_retrans)(ieee802154_dev_t *dev, uint8_t retrans)
Set number of frame retransmissions.
Definition: radio.h:681
static int ieee802154_radio_config_phy(ieee802154_dev_t *dev, const ieee802154_phy_conf_t *conf)
Shortcut to ieee802154_radio_ops::config_phy.
Definition: radio.h:822
int(* len)(ieee802154_dev_t *dev)
Get the length of the received PSDU frame.
Definition: radio.h:438
int(* request_cca)(ieee802154_dev_t *dev)
Request Stand-Alone Clear Channel Assessment.
Definition: radio.h:567
the transceiver received a valid ACK with the frame pending bit
Definition: radio.h:147
static int ieee802154_radio_read(ieee802154_dev_t *dev, void *buf, size_t size, ieee802154_rx_info_t *info)
Shortcut to ieee802154_radio_ops::read.
Definition: radio.h:778
the transceiver either finished sending a frame, the retransmission procedure or the channel activity...
Definition: radio.h:229
Radio is ready to receive ACK frames.
Definition: radio.h:353
the device reports the start of a frame (SFD) was sent.
Definition: radio.h:106
the device support ACK timeout interrupt
Definition: radio.h:84
the CCA procedure finished
Definition: radio.h:235