LoRa and FSK packets with sx127x
sx127x drives Semtech SX1276, SX1277, SX1278 and SX1279 radios. It has
the same send and receive API as sx126x, so a component that sends or receives its
own packets can use either radio the same way. The packet_transport platform in
esphome/components/sx127x/packet_transport is a small example.
Take the radio by ID and register the component as its child:
import esphome.codegen as cgfrom esphome.components.sx127x import CONF_SX127X_ID, SX127ximport esphome.config_validation as cvfrom esphome.const import CONF_ID
my_protocol_ns = cg.esphome_ns.namespace("my_protocol")MyProtocol = my_protocol_ns.class_("MyProtocol", cg.Component)
CONFIG_SCHEMA = cv.Schema( { cv.GenerateID(): cv.declare_id(MyProtocol), cv.GenerateID(CONF_SX127X_ID): cv.use_id(SX127x), }).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_SX127X_ID])Sending and receiving need LoRa, or packet mode in FSK and OOK, and the radio’s dio0_pin.
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<sx127x::SX127x>, public sx127x::SX127xTransmitListener { public: void send(const uint8_t *data, size_t len) { auto result = this->parent_->start_transmit_async(this, data, len); if (result != sx127x::SX127xError::SX127X_ERROR_NONE) { // Rejected: no completion follows. BUSY means try again later. } }
void on_transmit_complete(sx127x::SX127xError 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
SX127X_ERROR_TIMEOUTif DIO0 has not signaled the end of the send by then. cancel_transmit_async(listener)ends the listener’s send, and calls its completion withSX127X_ERROR_CANCELLEDbefore returning. It returnsfalse, without a completion, if that listener does not own the current send.- The completion always gets the send’s own result. If the radio then does not enter RX or sleep, it also sets a warning, and the radio is configured again within about a second.
Results
Section titled “Results”| Result | Meaning |
|---|---|
SX127X_ERROR_NONE | Accepted (async), or sent (blocking). |
SX127X_ERROR_BUSY | Another send is running, or a received packet is waiting to be delivered. Try again after loop(). |
SX127X_ERROR_NOT_READY | Setup has not finished or failed, or the radio is being configured again after a mode change that did not take. |
SX127X_ERROR_INVALID_PARAMS | Missing, empty or too long data, the wrong length for a fixed payload length, a timeout out of range, no listener, or no dio0_pin. |
SX127X_ERROR_TIMEOUT | The send did not finish in time (completion and blocking result only). |
SX127X_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<sx127x::SX127x>, public sx127x::SX127xListener { 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 and OOK modes the driver reports no signal quality: rssi is 0 and
snr is NAN.
Calling the radio from callbacks
Section titled “Calling the radio from callbacks”Completions, packet listeners and on_packet automations 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 SX127X_ERROR_BUSY if another packet is already waiting; that packet is delivered by the next
loop().
Settings and modes
Section titled “Settings and modes”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. configure() is ignored while a send is running, and it
resets the radio and discards a received packet still waiting.
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 that a send found waiting is held for
delivery) or is being configured again.
If the radio does not enter a requested mode, sends return SX127X_ERROR_NOT_READY, and the driver calls
configure() every second until it succeeds. Sleep keeps the radio’s settings.
Changes in ESPHome 2026.12.0
Section titled “Changes in ESPHome 2026.12.0”Asynchronous sending was added, with the same API and listener rules as sx126x. Unlike sx126x, a failed return
to RX or sleep after a send does not replace the send’s result (see Sending).
SX127xError::NONE, TIMEOUT and INVALID_PARAMS are renamed SX127X_ERROR_NONE, SX127X_ERROR_TIMEOUT and
SX127X_ERROR_INVALID_PARAMS, like the other values, so code that compares a result against them needs the new
names. FSK and OOK packets report NAN for the SNR, where they reported 0.
A mode change that does not take now sets a warning and the radio is configured again, where before the component was
marked failed. A send that finds a received packet waiting returns SX127X_ERROR_BUSY and keeps the packet, where
before the send wrote over it. set_dio0_pin() and set_rst_pin() take a GPIOPin *.
Copyright © 2026 ESPHome - A project from the Open Home Foundation