Skip to content

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 cg
from esphome.components.sx127x import CONF_SX127X_ID, SX127x
import esphome.config_validation as cv
from 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.

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_TIMEOUT if DIO0 has not signaled the end of the send by then.
  • cancel_transmit_async(listener) ends the listener’s send, and calls its completion with SX127X_ERROR_CANCELLED before returning. It returns false, 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.
ResultMeaning
SX127X_ERROR_NONEAccepted (async), or sent (blocking).
SX127X_ERROR_BUSYAnother send is running, or a received packet is waiting to be delivered. Try again after loop().
SX127X_ERROR_NOT_READYSetup has not finished or failed, or the radio is being configured again after a mode change that did not take.
SX127X_ERROR_INVALID_PARAMSMissing, 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_TIMEOUTThe send did not finish in time (completion and blocking result only).
SX127X_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<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.

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

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.

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 *.