Skip to content

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])

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_TIMEOUT if 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 with SX126X_ERROR_CANCELLED before returning. It returns false, 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.

ResultMeaning
SX126X_ERROR_NONEAccepted (async), or sent (blocking).
SX126X_ERROR_BUSYAnother send is running, or a received packet is waiting to be delivered. Try again after loop().
SX126X_ERROR_NOT_READYSetup has not finished or failed, the radio is in cold sleep, or it is being configured again after a failure.
SX126X_ERROR_INVALID_PARAMSMissing, empty or too long data, the wrong length for a fixed payload length, a timeout out of range, or no listener.
SX126X_ERROR_BUSY_TIMEOUTThe radio did not answer. The radio was restored, or it is configured again within about a second.
SX126X_ERROR_TIMEOUTThe send did not finish in time (completion and blocking result only).
SX126X_ERROR_CANCELLEDThe 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.

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.

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().

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.

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.