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

Arduino Stream interface for IEEE 802.15.4 transceiver. More...

#include <ESP32TransceiverStreamIEEE802_15_4.h>

Inheritance diagram for ieee802154::ESP32TransceiverStreamIEEE802_15_4:
Inheritance graph
[legend]
Collaboration diagram for ieee802154::ESP32TransceiverStreamIEEE802_15_4:
Collaboration graph
[legend]

Public Member Functions

virtual int available () override
 Get the number of bytes available to read.
 
int availableForWrite () override
 Get the number of bytes available for writing.
 
bool begin ()
 Initialize the stream and underlying transceiver.
 
bool begin (FrameControlField fcf)
 Initialize the stream and underlying transceiver.
 
void end ()
 Deinitialize the stream and underlying transceiver.
 
 ESP32TransceiverStreamIEEE802_15_4 (channel_t channel, int16_t panID, Address localAdr)
 Construct a new ESP32TransceiverStream object with transceiver parameters.
 
 ESP32TransceiverStreamIEEE802_15_4 (ESP32TransceiverIEEE802_15_4 &transceiver)
 Construct a new ESP32TransceiverStream object.
 
void flush () override
 Flush the transmit buffer and send its contents as a frame.
 
uint32_t getAckTimeoutUs () const
 Get the current acknowledgment timeout in microseconds.
 
channel_t getChannel () const
 Get the current IEEE 802.15.4 channel.
 
FrameControlFieldgetFrameControlField ()
 Get the current Frame Control Field (FCF) in use.
 
int getMaxMTU () const
 Get the maximum transmission unit (MTU) size for the data content.
 
size_t getRxBufferSize () const
 Get the current receive buffer size in bytes.
 
int getRxMessageBufferSize () const
 Get the current message buffer size for receiving frames.
 
int getSendDelay () const
 Get the delay between send retries in milliseconds.
 
ESP32TransceiverIEEE802_15_4getTransceiver ()
 Get a reference to the underlying transceiver instance.
 
int getTxBufferSize () const
 Get the current transmit buffer size for the stream.
 
int8_t getTxPower () const
 Get the current transmit power in dBm.
 
bool isAckActive () const
 Check if acknowledgment requests are enabled for outgoing frames.
 
bool isCCAActive () const
 Check if CCA (Clear Channel Assessment) is enabled.
 
int peek ()
 Peek at the next byte in the receive buffer (not implemented).
 
int read () override
 Read a single byte from the receive buffer.
 
size_t readBytes (uint8_t *buffer, size_t size)
 Read multiple bytes from the receive buffer.
 
void setAckActive (bool ack_active)
 Enable or disable acknowledgment requests for outgoing frames.
 
void setAckTimeoutUs (uint32_t timeout_us)
 Set the time in us to wait for the ack frame.
 
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)
 Set 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 the stream.
 
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 setRxBufferSize (size_t size)
 Set the size of the receive buffer. This defines how many bytes we can get by calling readBytes();.
 
void setRxMessageBufferSize (int size)
 Set the size of the message buffer used for receiving frames.
 
bool setRxWhenIdleActive (bool rx_when_idle)
 Set RX when idle mode for the transceiver.
 
void setSendDelay (int delay_ms)
 Set the delay between sends or send retries.
 
void setSendRetryCount (int count)
 Defines the retry count for faild send requests.
 
bool setTxBufferSize (int buffer_size)
 Set the transmit buffer size for the stream. This defines how much data can be buffered for sending before it is flushed.
 
bool setTxPower (int power)
 Set the transmit power in dBm.
 
size_t write (const uint8_t *buffer, size_t size) override
 Write a buffer of bytes to the transceiver.
 
size_t write (const uint8_t byte) override
 Write a single byte to the transceiver.
 
 ~ESP32TransceiverStreamIEEE802_15_4 ()
 Destroy the ESP32TransceiverStream object.
 

Protected Types

enum  send_confirmation_state_t { WAITING_FOR_CONFIRMATION , CONFIRMATION_RECEIVED , CONFIRMATION_ERROR }
 

Protected Member Functions

bool isSendConfirmations ()
 
bool isSequenceNumbers ()
 
bool receive ()
 Internal method to receive frames and fill the receive buffer.
 
void sendWithConfirmations ()
 Internal method to send a frame with confirmation handling. Retries sending the frame if confirmation fails, with a delay between attempts.
 
void sendWithoutConfirmations ()
 Internal method to send a frame without waiting for confirmations. Adds a delay after sending to allow the transceiver to process the frame.
 

Static Protected Member Functions

static void ieee802154_transceiver_tx_done_callback (const uint8_t *frame, const uint8_t *ack, esp_ieee802154_frame_info_t *ack_frame_info, void *user_data)
 Callback for successful frame transmission.
 
static void ieee802154_transceiver_tx_failed_callback (const uint8_t *frame, esp_ieee802154_tx_error_t error, void *user_data)
 Callback for failed frame transmission.
 

Protected Attributes

Frame frame
 
bool is_auto_flush = false
 
bool is_open_frame = false
 
bool is_send_confirations_enabled = false
 
int last_seq = -1
 
esp_ieee802154_tx_error_t last_tx_error = ESP_IEEE802154_TX_ERR_NONE
 
bool owns_transceiver = false
 
ESP32TransceiverIEEE802_15_4p_transceiver = nullptr
 
int receive_msg_buffer_size
 
RingBuffer rx_buffer {1024 + MTU}
 
volatile send_confirmation_state_t send_confirmation_state
 
int send_delay_ms = 10
 Delay after sending a frame when confirmations are not used.
 
int send_retry_count = 2
 
RingBuffer tx_buffer {MTU}
 

Static Protected Attributes

static constexpr int MTU = 116
 
static constexpr const char * TAG = "ESP32TransceiverStream"
 

Detailed Description

Arduino Stream interface for IEEE 802.15.4 transceiver.

Allows using ESP32TransceiverIEEE802_15_4 as a Stream for easy integration with Arduino APIs and libraries that expect a Stream object. Provides buffered read/write access to the transceiver.

If you want to control the creation of the individual frame segments, write data smaller than the MTU (127 bytes) and call flush() to send the frame immediately.

When you write data to the stream, that is bigger than the MTU, it is automatically split into multiple frames and sent one after another.

When you enable acknowledgment requests for outgoing frames, the stream will wait for the acknowledgment frame from the receiver before sending the next frame. If the acknowledgment is not received within the configured timeout, the stream will retry sending the frame after a delay. This process will repeat until the frame is acknowledged or a maximum number of retries is reached.

Member Enumeration Documentation

◆ send_confirmation_state_t

Enumerator
WAITING_FOR_CONFIRMATION 
CONFIRMATION_RECEIVED 
CONFIRMATION_ERROR 

Constructor & Destructor Documentation

◆ ESP32TransceiverStreamIEEE802_15_4() [1/2]

ieee802154::ESP32TransceiverStreamIEEE802_15_4::ESP32TransceiverStreamIEEE802_15_4 ( ESP32TransceiverIEEE802_15_4 transceiver)
inline

Construct a new ESP32TransceiverStream object.

Parameters
transceiverReference to the IEEE802.15.4 transceiver instance.

◆ ESP32TransceiverStreamIEEE802_15_4() [2/2]

ieee802154::ESP32TransceiverStreamIEEE802_15_4::ESP32TransceiverStreamIEEE802_15_4 ( channel_t  channel,
int16_t  panID,
Address  localAdr 
)
inline

Construct a new ESP32TransceiverStream object with transceiver parameters.

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

◆ ~ESP32TransceiverStreamIEEE802_15_4()

ieee802154::ESP32TransceiverStreamIEEE802_15_4::~ESP32TransceiverStreamIEEE802_15_4 ( )
inline

Destroy the ESP32TransceiverStream object.

Member Function Documentation

◆ available()

virtual int ieee802154::ESP32TransceiverStreamIEEE802_15_4::available ( )
inlineoverridevirtual

Get the number of bytes available to read.

Returns
Number of bytes available in the receive buffer.

◆ availableForWrite()

int ieee802154::ESP32TransceiverStreamIEEE802_15_4::availableForWrite ( )
inlineoverride

Get the number of bytes available for writing.

Returns
Always returns 1024.

◆ begin() [1/2]

bool ieee802154::ESP32TransceiverStreamIEEE802_15_4::begin ( )
inline

Initialize the stream and underlying transceiver.

Returns
True on success, false otherwise.

◆ begin() [2/2]

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

Initialize the stream and underlying transceiver.

Returns
True on success, false otherwise.

◆ end()

void ieee802154::ESP32TransceiverStreamIEEE802_15_4::end ( )
inline

Deinitialize the stream and underlying transceiver.

◆ flush()

void ieee802154::ESP32TransceiverStreamIEEE802_15_4::flush ( )
inlineoverride

Flush the transmit buffer and send its contents as a frame.

Sends all buffered data via the transceiver and clears the buffer.

◆ getAckTimeoutUs()

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

Get the current acknowledgment timeout in microseconds.

Returns
The acknowledgment timeout in microseconds.

◆ getChannel()

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

Get the current IEEE 802.15.4 channel.

Returns
The current channel.

◆ getFrameControlField()

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

Get the current Frame Control Field (FCF) in use.

Returns
The current FrameControlField structure.

◆ getMaxMTU()

int ieee802154::ESP32TransceiverStreamIEEE802_15_4::getMaxMTU ( ) const
inline

Get the maximum transmission unit (MTU) size for the data content.

Returns
The MTU size in bytes: 116 bytes for data payload (127 bytes total frame size minus 11 bytes for frame overhead).

◆ getRxBufferSize()

size_t ieee802154::ESP32TransceiverStreamIEEE802_15_4::getRxBufferSize ( ) const
inline

Get the current receive buffer size in bytes.

Returns
The size of the receive buffer.

◆ getRxMessageBufferSize()

int ieee802154::ESP32TransceiverStreamIEEE802_15_4::getRxMessageBufferSize ( ) const
inline

Get the current message buffer size for receiving frames.

Returns
The size of the message buffer in bytes.

◆ getSendDelay()

int ieee802154::ESP32TransceiverStreamIEEE802_15_4::getSendDelay ( ) const
inline

Get the delay between send retries in milliseconds.

Returns
The retry delay in ms.

◆ getTransceiver()

ESP32TransceiverIEEE802_15_4 & ieee802154::ESP32TransceiverStreamIEEE802_15_4::getTransceiver ( )
inline

Get a reference to the underlying transceiver instance.

Returns
Reference to the ESP32TransceiverIEEE802_15_4 instance.

◆ getTxBufferSize()

int ieee802154::ESP32TransceiverStreamIEEE802_15_4::getTxBufferSize ( ) const
inline

Get the current transmit buffer size for the stream.

Returns
The size of the transmit buffer in bytes (default 116 bytes).

◆ getTxPower()

int8_t ieee802154::ESP32TransceiverStreamIEEE802_15_4::getTxPower ( ) const
inline

Get the current transmit power in dBm.

Returns
The transmit power.

◆ ieee802154_transceiver_tx_done_callback()

static void ieee802154::ESP32TransceiverStreamIEEE802_15_4::ieee802154_transceiver_tx_done_callback ( const uint8_t *  frame,
const uint8_t *  ack,
esp_ieee802154_frame_info_t *  ack_frame_info,
void *  user_data 
)
inlinestaticprotected

Callback for successful frame transmission.

◆ ieee802154_transceiver_tx_failed_callback()

static void ieee802154::ESP32TransceiverStreamIEEE802_15_4::ieee802154_transceiver_tx_failed_callback ( const uint8_t *  frame,
esp_ieee802154_tx_error_t  error,
void *  user_data 
)
inlinestaticprotected

Callback for failed frame transmission.

◆ isAckActive()

bool ieee802154::ESP32TransceiverStreamIEEE802_15_4::isAckActive ( ) const
inline

Check if acknowledgment requests are enabled for outgoing frames.

Returns
True if acknowledgment requests are enabled, false otherwise.

◆ isCCAActive()

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

Check if CCA (Clear Channel Assessment) is enabled.

Returns
True if CCA is enabled, false otherwise.

◆ isSendConfirmations()

bool ieee802154::ESP32TransceiverStreamIEEE802_15_4::isSendConfirmations ( )
inlineprotected

◆ isSequenceNumbers()

bool ieee802154::ESP32TransceiverStreamIEEE802_15_4::isSequenceNumbers ( )
inlineprotected

◆ peek()

int ieee802154::ESP32TransceiverStreamIEEE802_15_4::peek ( )
inline

Peek at the next byte in the receive buffer (not implemented).

Returns
The next byte, or -1 if no data is available.

◆ read()

int ieee802154::ESP32TransceiverStreamIEEE802_15_4::read ( )
inlineoverride

Read a single byte from the receive buffer.

Returns
The byte read, or -1 if no data is available.

◆ readBytes()

size_t ieee802154::ESP32TransceiverStreamIEEE802_15_4::readBytes ( uint8_t *  buffer,
size_t  size 
)
inline

Read multiple bytes from the receive buffer.

Parameters
bufferPointer to destination buffer.
sizeNumber of bytes to read.
Returns
Number of bytes actually read.

◆ receive()

bool ieee802154::ESP32TransceiverStreamIEEE802_15_4::receive ( )
inlineprotected

Internal method to receive frames and fill the receive buffer.

Returns
True if a frame was received and processed, false otherwise.

◆ sendWithConfirmations()

void ieee802154::ESP32TransceiverStreamIEEE802_15_4::sendWithConfirmations ( )
inlineprotected

Internal method to send a frame with confirmation handling. Retries sending the frame if confirmation fails, with a delay between attempts.

◆ sendWithoutConfirmations()

void ieee802154::ESP32TransceiverStreamIEEE802_15_4::sendWithoutConfirmations ( )
inlineprotected

Internal method to send a frame without waiting for confirmations. Adds a delay after sending to allow the transceiver to process the frame.

◆ setAckActive()

void ieee802154::ESP32TransceiverStreamIEEE802_15_4::setAckActive ( bool  ack_active)
inline

Enable or disable acknowledgment requests for outgoing frames.

Parameters
ack_activeTrue to enable acknowledgment requests, false to disable.
Note
This method must be called before begin() to take effect!

◆ setAckTimeoutUs()

void ieee802154::ESP32TransceiverStreamIEEE802_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.

◆ setBroadcast()

void ieee802154::ESP32TransceiverStreamIEEE802_15_4::setBroadcast ( )
inline

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

◆ setCCAActive()

void ieee802154::ESP32TransceiverStreamIEEE802_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::ESP32TransceiverStreamIEEE802_15_4::setChannel ( channel_t  channel)
inline

Set the IEEE 802.15.4 channel.

Parameters
channelThe channel to set.
Returns
True if the channel was set successfully, false otherwise.

◆ setCoordinatorActive()

bool ieee802154::ESP32TransceiverStreamIEEE802_15_4::setCoordinatorActive ( bool  coordinator)
inline

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.

◆ setDestinationAddress()

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

Set the destination address for the stream.

Parameters
addressThe destination address.

◆ setFrameControlField()

void ieee802154::ESP32TransceiverStreamIEEE802_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::ESP32TransceiverStreamIEEE802_15_4::setPromiscuousModeActive ( bool  promiscuous)
inline

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.

◆ setRxBufferSize()

void ieee802154::ESP32TransceiverStreamIEEE802_15_4::setRxBufferSize ( size_t  size)
inline

Set the size of the receive buffer. This defines how many bytes we can get by calling readBytes();.

Parameters
sizeNew size of the receive buffer.

◆ setRxMessageBufferSize()

void ieee802154::ESP32TransceiverStreamIEEE802_15_4::setRxMessageBufferSize ( int  size)
inline

Set the size of the message buffer used for receiving frames.

Parameters
sizeNew size of the message buffer in bytes.
Note
This method must be called before begin() to take effect.

◆ setRxWhenIdleActive()

bool ieee802154::ESP32TransceiverStreamIEEE802_15_4::setRxWhenIdleActive ( bool  rx_when_idle)
inline

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.

◆ setSendDelay()

void ieee802154::ESP32TransceiverStreamIEEE802_15_4::setSendDelay ( int  delay_ms)
inline

Set the delay between sends or send retries.

Parameters
delay_msDelay in milliseconds.

◆ setSendRetryCount()

void ieee802154::ESP32TransceiverStreamIEEE802_15_4::setSendRetryCount ( int  count)
inline

Defines the retry count for faild send requests.

Parameters
countNumber of retries.

◆ setTxBufferSize()

bool ieee802154::ESP32TransceiverStreamIEEE802_15_4::setTxBufferSize ( int  buffer_size)
inline

Set the transmit buffer size for the stream. This defines how much data can be buffered for sending before it is flushed.

Parameters
buffer_sizeThe desired buffer size in bytes. Must be greater than 0 but not exceed the maximum data MTU size.
Returns
True if the buffer size was set successfully, false if the specified size is invalid.

◆ setTxPower()

bool ieee802154::ESP32TransceiverStreamIEEE802_15_4::setTxPower ( int  power)
inline

Set the transmit power in dBm.

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

◆ write() [1/2]

size_t ieee802154::ESP32TransceiverStreamIEEE802_15_4::write ( const uint8_t *  buffer,
size_t  size 
)
inlineoverride

Write a buffer of bytes to the transceiver.

Parameters
bufferPointer to data buffer.
sizeNumber of bytes to write.
Returns
Number of bytes written.

◆ write() [2/2]

size_t ieee802154::ESP32TransceiverStreamIEEE802_15_4::write ( const uint8_t  byte)
inlineoverride

Write a single byte to the transceiver.

Parameters
byteByte to write.
Returns
1 if written, 0 otherwise.

Member Data Documentation

◆ frame

Frame ieee802154::ESP32TransceiverStreamIEEE802_15_4::frame
protected

◆ is_auto_flush

bool ieee802154::ESP32TransceiverStreamIEEE802_15_4::is_auto_flush = false
protected

◆ is_open_frame

bool ieee802154::ESP32TransceiverStreamIEEE802_15_4::is_open_frame = false
protected

◆ is_send_confirations_enabled

bool ieee802154::ESP32TransceiverStreamIEEE802_15_4::is_send_confirations_enabled = false
protected

◆ last_seq

int ieee802154::ESP32TransceiverStreamIEEE802_15_4::last_seq = -1
protected

◆ last_tx_error

esp_ieee802154_tx_error_t ieee802154::ESP32TransceiverStreamIEEE802_15_4::last_tx_error = ESP_IEEE802154_TX_ERR_NONE
protected

◆ MTU

constexpr int ieee802154::ESP32TransceiverStreamIEEE802_15_4::MTU = 116
staticconstexprprotected

◆ owns_transceiver

bool ieee802154::ESP32TransceiverStreamIEEE802_15_4::owns_transceiver = false
protected

◆ p_transceiver

ESP32TransceiverIEEE802_15_4* ieee802154::ESP32TransceiverStreamIEEE802_15_4::p_transceiver = nullptr
protected

◆ receive_msg_buffer_size

int ieee802154::ESP32TransceiverStreamIEEE802_15_4::receive_msg_buffer_size
protected
Initial value:
=
(sizeof(frame_data_t) + 4) * 100

◆ rx_buffer

RingBuffer ieee802154::ESP32TransceiverStreamIEEE802_15_4::rx_buffer {1024 + MTU}
protected

◆ send_confirmation_state

volatile send_confirmation_state_t ieee802154::ESP32TransceiverStreamIEEE802_15_4::send_confirmation_state
protected
Initial value:
=
@ WAITING_FOR_CONFIRMATION
Definition ESP32TransceiverStreamIEEE802_15_4.h:427

◆ send_delay_ms

int ieee802154::ESP32TransceiverStreamIEEE802_15_4::send_delay_ms = 10
protected

Delay after sending a frame when confirmations are not used.

◆ send_retry_count

int ieee802154::ESP32TransceiverStreamIEEE802_15_4::send_retry_count = 2
protected

◆ TAG

constexpr const char* ieee802154::ESP32TransceiverStreamIEEE802_15_4::TAG = "ESP32TransceiverStream"
staticconstexprprotected

◆ tx_buffer

RingBuffer ieee802154::ESP32TransceiverStreamIEEE802_15_4::tx_buffer {MTU}
protected

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