LoRa and FSK packets with sx126x
sx126x drives Semtech SX1261, SX1262, SX1268 and LLCC68 radios. A component that sends or receives its own packets,
such as a mesh protocol, uses the radio through its C++ API. The packet_transport platform in
esphome/components/sx126x/packet_transport is a small example.
Take the radio by ID and register the component as its child:
from esphome.components.sx126x import CONF_SX126X_ID, SX126x
CONFIG_SCHEMA = cv.Schema( { cv.GenerateID(CONF_SX126X_ID): cv.use_id(SX126x), }).extend(cv.COMPONENT_SCHEMA)
async def to_code(config): var = cg.new_Pvariable(config[CONF_ID]) await cg.register_component(var, config) await cg.register_parented(var, config[CONF_SX126X_ID])Sending
Section titled “Sending”transmit_packet() sends a packet and returns once it has been sent or has failed. It holds up the main loop for the
whole time on air, so other components cannot run meanwhile:
auto result = this->parent_->transmit_packet(data, len);start_transmit_async() copies the packet into the radio and returns at once. The radio sends it while the main loop
keeps running, and calls the listener from loop() when the send ends:
class MyProtocol : public Component, public Parented<sx126x::SX126x>, public sx126x::SX126xTransmitListener { public: void send(const uint8_t *data, size_t len) { auto result = this->parent_->start_transmit_async(this, data, len); if (result != sx126x::SX126xError::SX126X_ERROR_NONE) { // Rejected: no completion follows. BUSY means try again later. } }
void on_transmit_complete(sx126x::SX126xError result) override { // Called exactly once for each accepted send. }};- The packet buffer can be reused as soon as
start_transmit_async()returns. - The listener must stay alive until its completion.
- One send runs at a time;
is_transmitting()tells whether one is running. - The optional timeout is 1 to 262143 ms and defaults to 4000 ms. The send fails with
SX126X_ERROR_TIMEOUTif it has not finished by then, even if the radio never signals. cancel_transmit_async(listener)ends the listener’s send, and calls its completion withSX126X_ERROR_CANCELLEDbefore returning. It returnsfalse, without a completion, if that listener does not own the current send.
SPI commands and their short waits for the radio stay synchronous; only the time on air runs in the background.
Results
Section titled “Results”| Result | Meaning |
|---|---|
SX126X_ERROR_NONE | Accepted (async), or sent (blocking). |
SX126X_ERROR_BUSY | Another send is running, or a received packet is waiting to be delivered. Try again after loop(). |
SX126X_ERROR_NOT_READY | Setup has not finished or failed, the radio is in cold sleep, or it is being configured again after a failure. |
SX126X_ERROR_INVALID_PARAMS | Missing, empty or too long data, the wrong length for a fixed payload length, a timeout out of range, or no listener. |
SX126X_ERROR_BUSY_TIMEOUT | The radio did not answer. The radio was restored, or it is configured again within about a second. |
SX126X_ERROR_TIMEOUT | The send did not finish in time (completion and blocking result only). |
SX126X_ERROR_CANCELLED | The send was cancelled (completion only). |
A rejected async send never gets a completion. transmit_packet() logs every failure; start_transmit_async() leaves
that to its caller.
Receiving
Section titled “Receiving”Register a listener to receive packets:
class MyProtocol : public Component, public Parented<sx126x::SX126x>, public sx126x::SX126xListener { public: void setup() override { this->parent_->register_listener(this); }
void on_packet(const std::vector<uint8_t> &packet, float rssi, float snr) override { // The packet is only valid until this returns; copy what you keep. }};on_packet() is called from loop(). In FSK mode the radio measures no SNR, so snr is NAN.
Calling the radio from callbacks
Section titled “Calling the radio from callbacks”Completions, packet listeners, on_packet automations and the radio’s own status messages run only after the radio
has finished updating its state. From any of them you may start the next send, cancel a send, change mode or call configure().
A send started from on_packet() returns SX126X_ERROR_BUSY if another packet is already waiting; that packet is
delivered by the next loop().
Settings and sleep
Section titled “Settings and sleep”The set_*() setters change the requested settings only. They take effect when configure() succeeds; until then,
sends and received packets use the settings applied last. If configure() fails, or a command leaves the radio
unconfigured, sends return SX126X_ERROR_NOT_READY, and the driver calls configure() again every second until it
succeeds.
set_mode_rx(), set_mode_tx(), set_mode_standby(), set_mode_sleep() and run_image_cal() are ignored with a
warning while the radio is in use (a send is running, or a received packet is waiting) or is being configured again.
Cold sleep (set_mode_sleep(true)) loses the radio’s settings, and the driver does not wake the radio by itself.
set_mode_rx(), set_mode_tx(), set_mode_standby() and run_image_cal() apply the settings again first, which
wakes it; set_mode_sleep() leaves it asleep. configure() also wakes it. Until then, sends return
SX126X_ERROR_NOT_READY.
Changes in ESPHome 2026.12.0
Section titled “Changes in ESPHome 2026.12.0”Asynchronous sending was added. SX126x no longer inherits spi::SPIDevice, so enable(), transfer_byte(),
write_byte() and other raw SPI calls are no longer available on it. Use transmit_packet(),
start_transmit_async(), the set_mode_*() methods and configure() instead.
SX126xError::NONE, TIMEOUT and INVALID_PARAMS are renamed SX126X_ERROR_NONE, SX126X_ERROR_TIMEOUT and
SX126X_ERROR_INVALID_PARAMS, like the other values, so code that compares a result against them needs the new
names. FSK packets report NAN for the SNR, where they reported 0.
Copyright © 2026 ESPHome - A project from the Open Home Foundation