ESP32 Transceiver IEEE 802.15.4 Library
Loading...
Searching...
No Matches
Public Member Functions | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Friends | List of all members
ieee802154::ESP32TransceiverIEEE802_15_4 Class Reference

Class to manage an IEEE 802.15.4 transceiver using the ESP-IDF API. On the sending side we support broadcast and direct addressing. On the receiving side we support promiscuous mode, and reveiving only frames that are destinated to the device or broadcast frames. More...

#include <ESP32TransceiverIEEE802_15_4.h>

Collaboration diagram for ieee802154::ESP32TransceiverIEEE802_15_4:
Collaboration graph
[legend]

Public Member Functions

bool begin ()
 Initialize the IEEE 802.15.4 transceiver with a specified channel.
 
bool begin (FrameControlField fcf)
 Initialize the IEEE 802.15.4 transceiver with a specified channel.
 
bool end (void)
 Deinitialize the IEEE 802.15.4 transceiver.
 
 ESP32TransceiverIEEE802_15_4 (channel_t channel, int16_t panID, Address localAddress)
 Construct a new ESP32TransceiverIEEE802_15_4 object.
 
uint32_t getAckTimeoutUs () const
 Get the current acknowledgment timeout in microseconds.
 
channel_t getChannel () const
 Get the current channel of the transceiver.
 
FramegetFrame ()
 
FrameControlFieldgetFrameControlField ()
 Get a reference to the Frame Control Field (FCF) for outgoing frames.
 
StreamBufferHandle_t getMessageBuffer () const
 Get the FreeRTOS message buffer handle for received frames.
 
esp_ieee802154_pending_mode_t getPendingMode ()
 Get the current pending mode of the transceiver.
 
int8_t getTxPower ()
 Get the current transmit power of the transceiver.
 
void incrementSequenceNumber (int n=1)
 Increment the sequence number in the current frame by a specified value.
 
bool isCCAActive () const
 Check if CCA (Clear Channel Assessment) is enabled.
 
bool isCoordinatorActive () const
 Check if the transceiver is currently set as coordinator.
 
bool isPromiscuousModeActive () const
 Check if promiscuous mode is active.
 
bool isRxWhenIdleActive () const
 Check if RX when idle mode is active.
 
bool send (Frame &frame)
 Transmit an IEEE 802.15.4 frame. You need to setup up all values in the frame object before calling this method. The channel and destination address will be used from the frame object.
 
bool send (uint8_t *data, size_t len)
 Transmit an IEEE 802.15.4 frame on the current channel.
 
void setAckTimeoutUs (uint32_t timeout_us)
 Set the time in us to wait for the ack frame.
 
void setAutoIncrementSequenceNumber (bool auto_increment)
 Enable or disable automatic incrementing of the sequence number after each successful transmission.
 
void setBroadcast ()
 Set the destination address to the broadcast address (0xFFFF).
 
void setCCAActive (bool cca_enabled)
 Enable or disable CCA (Clear Channel Assessment).
 
bool setChannel (channel_t channel)
 Change the IEEE 802.15.4 channel.
 
bool setCoordinatorActive (bool coordinator)
 Set the coordinator mode for the transceiver.
 
void setDestinationAddress (const Address &address)
 Set the destination address for outgoing frames.
 
void setFrameControlField (const FrameControlField &fcf)
 Set the Frame Control Field (FCF) for outgoing frames.
 
bool setPromiscuousModeActive (bool promiscuous)
 Set promiscuous mode for the transceiver.
 
void setReceiveBufferSize (int size)
 
void setReceiveTask (void(*task)(void *pvParameters))
 Set a custom FreeRTOS task function for processing received packets.
 
bool setRxCallback (ieee802154_transceiver_rx_callback_t callback, void *user_data)
 Set the callback function for received frames.
 
bool setRxWhenIdleActive (bool rx_when_idle)
 Set RX when idle mode for the transceiver.
 
bool setSfdCallback (ieee802154_transceiver_sfd_callback_t callback, void *user_data)
 Set the callback function for SFD (Start Frame Delimiter) received event.
 
bool setSfdTxCallback (ieee802154_transceiver_sfd_tx_callback_t callback, void *user_data)
 Set the callback function for SFD transmitted event.
 
bool setTxDoneCallback (ieee802154_transceiver_tx_done_callback_t callback, void *user_data)
 Set the callback function for successful frame transmission.
 
bool setTxFailedCallback (ieee802154_transceiver_tx_failed_callback_t callback, void *user_data)
 Set the callback function for failed frame transmission.
 
bool setTxPower (int power)
 Set the transmit power of the transceiver.
 

Protected Member Functions

void onRxDone (uint8_t *frame, esp_ieee802154_frame_info_t *frame_info)
 
void onStartFrameDelimiterReceived ()
 
void onStartFrameDelimiterTransmitDone (uint8_t *frame)
 
void onTransmitDone (const uint8_t *frame, const uint8_t *ack, esp_ieee802154_frame_info_t *ack_frame_info)
 
void onTransmitFailed (const uint8_t *frame, esp_ieee802154_tx_error_t error)
 
esp_err_t transmit_frame (Frame *frame)
 

Static Protected Member Functions

static void default_receive_packet_task (void *pvParameters)
 

Protected Attributes

uint32_t ack_timeout_us = (2016 * 16)
 
bool auto_increment_sequence_number = true
 
bool cca_enabled = false
 
channel_t channel = channel_t::UNDEFINED
 
Address destination_address = BROADCAST_ADDRESS
 
Frame frame
 
FrameControlField frame_control_field {}
 
bool is_active = false
 
bool is_coordinator = false
 
bool is_promiscuous_mode = false
 
bool is_rx_when_idle = true
 
Address local_address
 
StreamBufferHandle_t message_buffer = nullptr
 
int16_t panID
 
bool radio_enabled = false
 
int receive_msg_buffer_size = sizeof(frame_data_t) + 4
 
void(* receive_packet_task )(void *pvParameters)=default_receive_packet_task
 
ieee802154_transceiver_rx_callback_t rx_callback_ = nullptr
 
void * rx_callback_user_data_ = nullptr
 
TaskHandle_t rx_task_handle = nullptr
 
ieee802154_transceiver_sfd_callback_t sfd_callback_ = nullptr
 
void * sfd_callback_user_data_ = nullptr
 
ieee802154_transceiver_sfd_tx_callback_t sfd_tx_callback_ = nullptr
 
void * sfd_tx_callback_user_data_ = nullptr
 
uint8_t transmit_buffer [MAX_FRAME_LEN] = {0}
 
ieee802154_transceiver_tx_done_callback_t tx_done_callback_ = nullptr
 
void * tx_done_callback_user_data_ = nullptr
 
ieee802154_transceiver_tx_failed_callback_t tx_failed_callback_ = nullptr
 
void * tx_failed_callback_user_data_ = nullptr
 

Friends

void receive_packet_task (void *)
 Forward declarations.
 

Detailed Description

Class to manage an IEEE 802.15.4 transceiver using the ESP-IDF API. On the sending side we support broadcast and direct addressing. On the receiving side we support promiscuous mode, and reveiving only frames that are destinated to the device or broadcast frames.

Warning
Only one instance of this class should be created, as the ESP-IDF callbacks are global and will reference the single instance through a global pointer. Creating multiple instances may lead to undefined behavior.

Constructor & Destructor Documentation

◆ ESP32TransceiverIEEE802_15_4()

ieee802154::ESP32TransceiverIEEE802_15_4::ESP32TransceiverIEEE802_15_4 ( channel_t  channel,
int16_t  panID,
Address  localAddress 
)
inline

Construct a new ESP32TransceiverIEEE802_15_4 object.

Parameters
panIDThe Personal Area Network Identifier to use for the transceiver.
localAddressThe local address for the device.

Member Function Documentation

◆ begin() [1/2]

bool ieee802154::ESP32TransceiverIEEE802_15_4::begin ( )

Initialize the IEEE 802.15.4 transceiver with a specified channel.

Returns
ESP_OK on success, or an error code on failure.

◆ begin() [2/2]

bool ieee802154::ESP32TransceiverIEEE802_15_4::begin ( FrameControlField  fcf)
inline

Initialize the IEEE 802.15.4 transceiver with a specified channel.

Parameters
fcfThe Frame Control Field to use for the transceiver. transceiver.
Returns
ESP_OK on success, or an error code on failure.

◆ default_receive_packet_task()

void ieee802154::ESP32TransceiverIEEE802_15_4::default_receive_packet_task ( void *  pvParameters)
staticprotected

◆ end()

bool ieee802154::ESP32TransceiverIEEE802_15_4::end ( void  )

Deinitialize the IEEE 802.15.4 transceiver.

Returns
ESP_OK on success, or an error code on failure.

◆ getAckTimeoutUs()

uint32_t ieee802154::ESP32TransceiverIEEE802_15_4::getAckTimeoutUs ( ) const
inline

Get the current acknowledgment timeout in microseconds.

Returns
The acknowledgment timeout in microseconds.

◆ getChannel()

channel_t ieee802154::ESP32TransceiverIEEE802_15_4::getChannel ( ) const
inline

Get the current channel of the transceiver.

Returns
The current channel number (11-26).

◆ getFrame()

Frame & ieee802154::ESP32TransceiverIEEE802_15_4::getFrame ( )
inline

◆ getFrameControlField()

FrameControlField & ieee802154::ESP32TransceiverIEEE802_15_4::getFrameControlField ( )
inline

Get a reference to the Frame Control Field (FCF) for outgoing frames.

Returns
Reference to the current Frame Control Field structure.

◆ getMessageBuffer()

StreamBufferHandle_t ieee802154::ESP32TransceiverIEEE802_15_4::getMessageBuffer ( ) const
inline

Get the FreeRTOS message buffer handle for received frames.

Returns
StreamBufferHandle_t for the RX message buffer.

◆ getPendingMode()

esp_ieee802154_pending_mode_t ieee802154::ESP32TransceiverIEEE802_15_4::getPendingMode ( )
inline

Get the current pending mode of the transceiver.

Returns
The pending mode value from the ESP-IDF driver.

◆ getTxPower()

int8_t ieee802154::ESP32TransceiverIEEE802_15_4::getTxPower ( )
inline

Get the current transmit power of the transceiver.

Returns
The transmit power value from the ESP-IDF driver.

◆ incrementSequenceNumber()

void ieee802154::ESP32TransceiverIEEE802_15_4::incrementSequenceNumber ( int  n = 1)
inline

Increment the sequence number in the current frame by a specified value.

Parameters
nThe value to add to the current sequence number.
Note
this is automatically called after each successful transmission, but you can call it

◆ isCCAActive()

bool ieee802154::ESP32TransceiverIEEE802_15_4::isCCAActive ( ) const
inline

Check if CCA (Clear Channel Assessment) is enabled.

Returns
True if CCA is enabled, false otherwise.

◆ isCoordinatorActive()

bool ieee802154::ESP32TransceiverIEEE802_15_4::isCoordinatorActive ( ) const
inline

Check if the transceiver is currently set as coordinator.

Returns
True if coordinator mode is active, false otherwise.

◆ isPromiscuousModeActive()

bool ieee802154::ESP32TransceiverIEEE802_15_4::isPromiscuousModeActive ( ) const
inline

Check if promiscuous mode is active.

Returns
True if promiscuous mode is enabled, false otherwise.

◆ isRxWhenIdleActive()

bool ieee802154::ESP32TransceiverIEEE802_15_4::isRxWhenIdleActive ( ) const
inline

Check if RX when idle mode is active.

Returns
True if RX when idle is enabled, false otherwise.

◆ onRxDone()

void ieee802154::ESP32TransceiverIEEE802_15_4::onRxDone ( uint8_t *  frame,
esp_ieee802154_frame_info_t *  frame_info 
)
protected

◆ onStartFrameDelimiterReceived()

void ieee802154::ESP32TransceiverIEEE802_15_4::onStartFrameDelimiterReceived ( )
protected

◆ onStartFrameDelimiterTransmitDone()

void ieee802154::ESP32TransceiverIEEE802_15_4::onStartFrameDelimiterTransmitDone ( uint8_t *  frame)
protected

◆ onTransmitDone()

void ieee802154::ESP32TransceiverIEEE802_15_4::onTransmitDone ( const uint8_t *  frame,
const uint8_t *  ack,
esp_ieee802154_frame_info_t *  ack_frame_info 
)
protected

◆ onTransmitFailed()

void ieee802154::ESP32TransceiverIEEE802_15_4::onTransmitFailed ( const uint8_t *  frame,
esp_ieee802154_tx_error_t  error 
)
protected

◆ send() [1/2]

bool ieee802154::ESP32TransceiverIEEE802_15_4::send ( Frame frame)

Transmit an IEEE 802.15.4 frame. You need to setup up all values in the frame object before calling this method. The channel and destination address will be used from the frame object.

Parameters
framePointer to the frame to transmit.
Returns
True on success, false on failure.
Note
if the the frame frame does not have a PAN, source or destination address, we will use the information defined in the transceiver object.

◆ send() [2/2]

bool ieee802154::ESP32TransceiverIEEE802_15_4::send ( uint8_t *  data,
size_t  len 
)

Transmit an IEEE 802.15.4 frame on the current channel.

Parameters
datapayload data to tramsit.
lenlength of the payload data.
Returns
ESP_OK on success, or an error code on failure.

◆ setAckTimeoutUs()

void ieee802154::ESP32TransceiverIEEE802_15_4::setAckTimeoutUs ( uint32_t  timeout_us)
inline

Set the time in us to wait for the ack frame.

Parameters
[in]timeoutThe time to wait for the ack frame, in us. It Should be a multiple of 16.

◆ setAutoIncrementSequenceNumber()

void ieee802154::ESP32TransceiverIEEE802_15_4::setAutoIncrementSequenceNumber ( bool  auto_increment)
inline

Enable or disable automatic incrementing of the sequence number after each successful transmission.

Parameters
auto_incrementTrue to enable automatic incrementing, false to

◆ setBroadcast()

void ieee802154::ESP32TransceiverIEEE802_15_4::setBroadcast ( )
inline

Set the destination address to the broadcast address (0xFFFF).

◆ setCCAActive()

void ieee802154::ESP32TransceiverIEEE802_15_4::setCCAActive ( bool  cca_enabled)
inline

Enable or disable CCA (Clear Channel Assessment).

Parameters
cca_enabledTrue to enable CCA (Clear Channel Assessment), false to disable.

◆ setChannel()

bool ieee802154::ESP32TransceiverIEEE802_15_4::setChannel ( channel_t  channel)

Change the IEEE 802.15.4 channel.

Parameters
channelChannel number (11-26).
Returns
ESP_OK on success, or an error code on failure.
Note
This method can be called at any time to change the channel of the transceiver.

◆ setCoordinatorActive()

bool ieee802154::ESP32TransceiverIEEE802_15_4::setCoordinatorActive ( bool  coordinator)

Set the coordinator mode for the transceiver.

Parameters
coordinatorTrue to enable coordinator mode, false to disable.
Returns
True if the mode was set successfully, false otherwise.
Note
This method must be called before begin() to take effect!

◆ setDestinationAddress()

void ieee802154::ESP32TransceiverIEEE802_15_4::setDestinationAddress ( const Address address)
inline

Set the destination address for outgoing frames.

Parameters
addressDestination address to use for outgoing frames.

◆ setFrameControlField()

void ieee802154::ESP32TransceiverIEEE802_15_4::setFrameControlField ( const FrameControlField fcf)
inline

Set the Frame Control Field (FCF) for outgoing frames.

Parameters
fcfThe frame control field structure to use.
Note
This method must be called before begin() to take effect!

◆ setPromiscuousModeActive()

bool ieee802154::ESP32TransceiverIEEE802_15_4::setPromiscuousModeActive ( bool  promiscuous)

Set promiscuous mode for the transceiver.

Parameters
promiscuousTrue to enable promiscuous mode, false to disable.
Returns
True if the mode was set successfully, false otherwise.
Note
This method must be called before begin() to take effect!

◆ setReceiveBufferSize()

void ieee802154::ESP32TransceiverIEEE802_15_4::setReceiveBufferSize ( int  size)

◆ setReceiveTask()

void ieee802154::ESP32TransceiverIEEE802_15_4::setReceiveTask ( void(*)(void *pvParameters)  task)
inline

Set a custom FreeRTOS task function for processing received packets.

Parameters
taskPointer to the task function to use for processing received

◆ setRxCallback()

bool ieee802154::ESP32TransceiverIEEE802_15_4::setRxCallback ( ieee802154_transceiver_rx_callback_t  callback,
void *  user_data 
)

Set the callback function for received frames.

Parameters
callbackCallback function to invoke on frame reception.
user_dataUser-defined data to pass to the callback.
Returns
ESP_OK on success, or an error code on failure.

◆ setRxWhenIdleActive()

bool ieee802154::ESP32TransceiverIEEE802_15_4::setRxWhenIdleActive ( bool  rx_when_idle)

Set RX when idle mode for the transceiver.

Parameters
rx_when_idleTrue to enable RX when idle, false to disable.
Returns
True if the mode was set successfully, false otherwise.

◆ setSfdCallback()

bool ieee802154::ESP32TransceiverIEEE802_15_4::setSfdCallback ( ieee802154_transceiver_sfd_callback_t  callback,
void *  user_data 
)

Set the callback function for SFD (Start Frame Delimiter) received event.

Parameters
callbackCallback function to invoke when SFD is received.
user_dataUser-defined data to pass to the callback.
Returns
ESP_OK on success, or an error code on failure.

◆ setSfdTxCallback()

bool ieee802154::ESP32TransceiverIEEE802_15_4::setSfdTxCallback ( ieee802154_transceiver_sfd_tx_callback_t  callback,
void *  user_data 
)

Set the callback function for SFD transmitted event.

Parameters
callbackCallback function to invoke when SFD is transmitted.
user_dataUser-defined data to pass to the callback.
Returns
ESP_OK on success, or an error code on failure.

◆ setTxDoneCallback()

bool ieee802154::ESP32TransceiverIEEE802_15_4::setTxDoneCallback ( ieee802154_transceiver_tx_done_callback_t  callback,
void *  user_data 
)

Set the callback function for successful frame transmission.

Parameters
callbackCallback function to invoke when a frame is successfully transmitted.
user_dataUser-defined data to pass to the callback.
Returns
ESP_OK on success, or an error code on failure.

◆ setTxFailedCallback()

bool ieee802154::ESP32TransceiverIEEE802_15_4::setTxFailedCallback ( ieee802154_transceiver_tx_failed_callback_t  callback,
void *  user_data 
)

Set the callback function for failed frame transmission.

Parameters
callbackCallback function to invoke when a frame transmission fails.
user_dataUser-defined data to pass to the callback.
Returns
ESP_OK on success, or an error code on failure.

◆ setTxPower()

bool ieee802154::ESP32TransceiverIEEE802_15_4::setTxPower ( int  power)

Set the transmit power of the transceiver.

Parameters
powerTransmit power value to set (in dBm). -24 dBm to +20 dBm
Returns
True if the power was set successfully, false otherwise.

◆ transmit_frame()

esp_err_t ieee802154::ESP32TransceiverIEEE802_15_4::transmit_frame ( Frame frame)
protected

Friends And Related Symbol Documentation

◆ receive_packet_task

void receive_packet_task ( void *  )
friend

Forward declarations.

Member Data Documentation

◆ ack_timeout_us

uint32_t ieee802154::ESP32TransceiverIEEE802_15_4::ack_timeout_us = (2016 * 16)
protected

◆ auto_increment_sequence_number

bool ieee802154::ESP32TransceiverIEEE802_15_4::auto_increment_sequence_number = true
protected

◆ cca_enabled

bool ieee802154::ESP32TransceiverIEEE802_15_4::cca_enabled = false
protected

◆ channel

channel_t ieee802154::ESP32TransceiverIEEE802_15_4::channel = channel_t::UNDEFINED
protected

◆ destination_address

Address ieee802154::ESP32TransceiverIEEE802_15_4::destination_address = BROADCAST_ADDRESS
protected

◆ frame

Frame ieee802154::ESP32TransceiverIEEE802_15_4::frame
protected

◆ frame_control_field

FrameControlField ieee802154::ESP32TransceiverIEEE802_15_4::frame_control_field {}
protected

◆ is_active

bool ieee802154::ESP32TransceiverIEEE802_15_4::is_active = false
protected

◆ is_coordinator

bool ieee802154::ESP32TransceiverIEEE802_15_4::is_coordinator = false
protected

◆ is_promiscuous_mode

bool ieee802154::ESP32TransceiverIEEE802_15_4::is_promiscuous_mode = false
protected

◆ is_rx_when_idle

bool ieee802154::ESP32TransceiverIEEE802_15_4::is_rx_when_idle = true
protected

◆ local_address

Address ieee802154::ESP32TransceiverIEEE802_15_4::local_address
protected

◆ message_buffer

StreamBufferHandle_t ieee802154::ESP32TransceiverIEEE802_15_4::message_buffer = nullptr
protected

◆ panID

int16_t ieee802154::ESP32TransceiverIEEE802_15_4::panID
protected

◆ radio_enabled

bool ieee802154::ESP32TransceiverIEEE802_15_4::radio_enabled = false
protected

◆ receive_msg_buffer_size

int ieee802154::ESP32TransceiverIEEE802_15_4::receive_msg_buffer_size = sizeof(frame_data_t) + 4
protected

◆ receive_packet_task

void(* ieee802154::ESP32TransceiverIEEE802_15_4::receive_packet_task) (void *pvParameters)=default_receive_packet_task
protecteddefault

◆ rx_callback_

ieee802154_transceiver_rx_callback_t ieee802154::ESP32TransceiverIEEE802_15_4::rx_callback_ = nullptr
protected

◆ rx_callback_user_data_

void* ieee802154::ESP32TransceiverIEEE802_15_4::rx_callback_user_data_ = nullptr
protected

◆ rx_task_handle

TaskHandle_t ieee802154::ESP32TransceiverIEEE802_15_4::rx_task_handle = nullptr
protected

◆ sfd_callback_

ieee802154_transceiver_sfd_callback_t ieee802154::ESP32TransceiverIEEE802_15_4::sfd_callback_ = nullptr
protected

◆ sfd_callback_user_data_

void* ieee802154::ESP32TransceiverIEEE802_15_4::sfd_callback_user_data_ = nullptr
protected

◆ sfd_tx_callback_

ieee802154_transceiver_sfd_tx_callback_t ieee802154::ESP32TransceiverIEEE802_15_4::sfd_tx_callback_ = nullptr
protected

◆ sfd_tx_callback_user_data_

void* ieee802154::ESP32TransceiverIEEE802_15_4::sfd_tx_callback_user_data_ = nullptr
protected

◆ transmit_buffer

uint8_t ieee802154::ESP32TransceiverIEEE802_15_4::transmit_buffer[MAX_FRAME_LEN] = {0}
protected

◆ tx_done_callback_

ieee802154_transceiver_tx_done_callback_t ieee802154::ESP32TransceiverIEEE802_15_4::tx_done_callback_ = nullptr
protected

◆ tx_done_callback_user_data_

void* ieee802154::ESP32TransceiverIEEE802_15_4::tx_done_callback_user_data_ = nullptr
protected

◆ tx_failed_callback_

ieee802154_transceiver_tx_failed_callback_t ieee802154::ESP32TransceiverIEEE802_15_4::tx_failed_callback_ = nullptr
protected

◆ tx_failed_callback_user_data_

void* ieee802154::ESP32TransceiverIEEE802_15_4::tx_failed_callback_user_data_ = nullptr
protected

The documentation for this class was generated from the following files: