This repository is “Work in Progress”. Comments are most welcome.
The aim is to make the LoRa radio available, in the direct LoRa radio mode of operation, in ESPHome. The goal is to make the use of SX126X radio chip as easy and simple as possible, using a configuration in the ESPHome YAML files, with as many sensible defaults as possible.
NOTE: A LoRaWAN configuration is not yet available, but would become available as a separate component.
This component is being developed on the Heltec V3 Development Boards which use the LoRa SX1262 chip. Namely:
- Heltec Wifi LoRa 32 (V3) - heltec_wifi_kit_32_V3 (in expressif)
- Heltec Wireless Stick (V3) - heltec_wireless_stick_V3
- Heltec Wireless Stick Lite (V3) - heltec_wireless_stick_lite_V3
At the present, these boards are not listed to be selected in the ESPHome YAML file (when using the Arduino framework). In order to make these boards work with the available version of ESPHome, the following YAML is required:
esp32:
board: esp32-s3-devkitc-1
framework:
type: arduinoThe place where these boards are defined in the platform-espessif32 project is here. It is hoped that these configurations will be picked up when a new version of espressif32 is pull into ESPHome.
The Arduino library being used is beegee-tokyo/SX126X-Arduino.
The following header file contains the descriptions of the fields used by the library:
The files lora-sx126x.yaml and secret.yaml provide a example of how to use the integration. To use with a working version of ESPHome:
- Edit lora-sx126x.yaml and ensure that the correct frequency (and band) is being used for your board. This varies from region to region and board to board.
- Edit secret.yaml and add your local Wifi details, API and OTA secrets;
then run:
esphome run lora-sx126x.yamlThis esphome component currently does some things which are not encouraged by the ESPHome Core and Component developers.
A this stage it does not look like it will be possible to be included in the main esphome project as it is making direct use of an SPI library to directly access this hardware.
It is always hoped that this component will become compliant enough to be included in ESPHome, but in the meantime, it can be included in your ESPHome build by either cloning this repository locally and adding an external_component with a local source; or by including the github repository directly as an external_component. See the External Components documentation.
Local source for external component:
external_components:
- source:
type: local
path: esphome/components
components: ["lora-sx126x"]or, Github source for external component
external_components:
- source:
type: git
url: https://github.com/PaulSchulz/esphome-lora-sx126x
ref: main
components: ["lora-sx126x"]Proposed example YAML configuration
esphome:
name: "lora-sx126x"
libraries:
- "SPI"
- "Ticker"
- "SX126x-Arduino"
...
external_components:
- source:
type: local
path: esphome/components
components: [lora-sx126x]
...
lora-sx126x:
rf_frequency: 915000000 # Manditory for user to set
sensor:
- platform: lora-sx126x
id: lorarssi
name: lorarssi # Required for publishing into API and HA
text_sensor:
- platform: lora-sx126x
id: packet_in
name: packet_in
sx126x:
# optional, with sensile defaults, if possible from board id.
pin_lora_reset: 12
pin_lora_dio_1: 14
pin_lora_busy: 13
pin_lora_nss: 8
pin_lora_sclk: 9
pin_lora_miso: 11
pin_lora_mosi: 10
radio_txen: -1
radio_rxen: -1
use_dio2_ant_switch: true
use_dio3_tcx0: true
use_dxo3_ant_switch: false
# required - depends on region and frequency band being used
rf_frequency: 915000000
# optional (sensible defaults)
tx_output_power: 22
lora_bandwidth: 0
lora_spreading_factor: 7
lora_codingrate: 1
lora_preamble_length: 8
lora_symbol_timeout: 0
lora_fix_length_layload_on: false
lora_iq_inversion_on: false
rx_timeout_value: 3000
tx_timeout_value: 3000
text_sensor:
- platform: sx126x
id: message
name: LoRa Message
# Is there a component for this in ESPHome?
# Sending a string to a component.
text_message:
- platform: sx126x
id: send_message
name: Send LoRa Message
binary_sensor:
- platform: sx126x
id: lora_sensor
name: LoRa Sensor
on_string: "@+++"
off_string: "@---"
switch:
- platform: sx126x
id: lora_switch
name: LoRa Switch
on_string: "@+++"
off_string: "@---"If possible, the SX126x-Arduino library needs to be implemented natively in ESPHome, to make use of the native ESPHome SPI code.
It is uncertain at the moment whether this component can be used generally with other devices that use the same SPI interface.
The SX126x-Arduino library does not allow the ‘syncword’ to be set on the radio and has hardcoded values for a private (0x1424) or public (0x3444) radio setup.
Meshtastic, another LoRa radio protocol, uses the RadioLib library, which supports a wider range of LoRa chips and allows the ‘syncword’ to be configured. They are currently using ‘0x2b’ (or 0x24b4 to be precise).
It would be good to be able to also interoperate with the Meshtastic radio network. an
The following environment is used:
- On Ubuntu 24.10
- Check out the repository
git clone https://github.com/PaulSchulz/esphome-lora-sx126x.git cd esphome-lora-sx126x - Checkout the latest esphome
python -m venv venv
. venv/bin/activate
pip install esphome- (Optional) Edit ‘secrets.yaml’ file with local credentials
- Compile example
esphome compile lora-sx126x.yaml