Introduction
This post describes “Work in Progress”. I have deliberately decided to put these details together now as it has been possible to build something that ‘sort of’ works, in that all the pieces are there, ot nearly there. The end is in sight, albeit a reasonably long way away in time and effort.
The original aim was to make the SX1282 LoRa radio chip available, for both LoRa and LoRaWAN modes, directly in ESPHome. It is hoped that the use of the SX126X series of radio chips can be as easy as possible to use and in most cases wholly driven from the ESPHome YAML files. When creating an IoT device with a new dev board, this has been one of the frustrating pieces of the excercise, particularly when using the Arduino IDE and programmer.
The Github repository of the component is here: https://github.com/PaulSchulz/esphome-lora-sx126x
These notes assume that you have ESPHome installed (
To include this external component in your own ESPHome yaml file, see below, or read the repository’s documentation (which will be newer than this).
Hardware
This ESPHome component is being developed on the Heltec V3 Development Boards which use the LoRa SX1262 chip. These dev boards are:
- 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 time, these boards are not available for selecting directly 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: arduino
These board definitions are imported from the platform-espessif32 project here.
The LoRa Arduino Library
The Arduino library being used is beegee-tokyo/SX126X-Arduino, which itself is based on several other libraries. It appear to currently be the best and most maintained LoRa library available for these radio chips.
The following header file contains the descriptions of the functions and fields used by the library: https://github.com/beegee-tokyo/SX126x-Arduino/blob/master/src/radio/radio.h
Testing and Usage
The files lora-sx126x.yaml and secret.yaml provide an example of how to use the
component. To use with a working version of ESPHome, edit secret.yaml to add
your local Wifi details, then run:
esphome run lora-sx126x.yaml
Development Comments
To get the component into a working state, this ESPHome component currently does some things which are not encouraged by the ESPHome Core and Component developers (see below).
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 for more details
If downloading and using as a local source for external component:
external_components:
- source:
type: local
path: esphome/components
components: ["lora_sx126x"]
and, using directly from the Github source for an external component
external_components:
- source:
type: git
url: https://github.com/PaulSchulz/esphome-lora-sc126x
ref: main
components: ["lora_sx126x"]
Considerations / Things to fix
Direct use of SPI and SX126x-Arduino libraries
If possible, the SX126x-Arduino library needs to be implemented natively in
ESPHome, to make use of the native ESPHome SPI code.
By using the Library directly, it is uncertain at the moment whether this component can be used generally with other devices that use the same SPI interface.
Example YAML
The following is the proposed example YAML configuration, for a ESPHome image that will enable the SX126X radio.
esphome:
name: "lora-sx126x"
libraries:
- "SPI"
- "Ticker"
- "SX126x-Arduino"
...
external_components:
- source:
type: local
path: esphome/components
...
lora_sx126x:
# The frequency to use needs to be specified as will depend on the
# hardware and the region in which the it is being used.
frequency: 915000000
Development
Proposed YAML Options
The following is an example of the proposed full option list, for using the LoRa radio chip.
lora_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
It should then be possible to use the radio with the various builtin types. This has yet to be implemented.
text_sensor:
- platform: lora_sx126x
id: lora_message
name: LoRa Message
# Is there a component for this in ESPHome?
# Sending a string to a component?
text_message:
- platform: lora_sx126x
id: send_message
name: "Send LoRa Message"
binary_sensor:
- platform: lora_sx126x
id: lora_sensor
name: LoRa Sensor
on_string: "@+++"
off_string: "@---"
switch:
- platform: lora_sx126x
id: lora_switch
name: LoRa Switch
on_string: "@^^^"
off_string: "@vvv"
binary_input:
- platform: lora_sx126x
id: lora_input
name: LoRa Binary Input
on_string: "@***"
off_string: "@..."
binary_output:
- platform: lora_sx126x
id: lora_output
name: LoRa Binary Ouput
on_string: "@>>>"
off_string: "@<<<"