Developing a component for ESPHome, for the SX1262 LoRa Radio Chip – Part 1

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:

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: "@<<<"