dernasherbrezon/sx127x

uploaded 4 weeks ago

[](https://registry.platformio.org/libraries/dernasherbrezon/sx127x) [](https://components.espressif.com/components/dernasherbrezon/sx127x) [](https://sonarcloud.io/summary/new_code?id=dernasherbrezon_sx127x) [](https://github.com/dernasherbrezon/sx127x/actions/workflows/main.yml) # About Library to work with semtech sx127x chips. # Features There are several similar libraries exist, but this one is much better: * LoRa, FSK and OOK modulations * Support for resume from deep sleep. Most of libraries re-init the chip upon the startup and erase everything that was received previously. This library provides granular initialization functions. See ```examples/receive_lora_deepsleep/main/main.c``` for more info. * Written in C. It is so much easier to integrate with another C project. But also possible to use from C++ project. * Doesn't have external dependencies. This library is based on C99 standard. * Can work with 2 or more modules connected to the same SPI bus. * No busy loops for handling RX and TX events. See examples on how to configure and handle interrupts. * Good documentation. * Can be used on ESP32 or RaspberryPI or any other linux with GPIO pins. This library supports all standard LoRa features: * RX/TX * CAD (Channel activity detection). Can be used to reduce power consumption in RX mode. * TX with +20dbm power * Explicit and implicit headers * Granular sx127x register configuration And FSK/OOK features: * RX/TX * Short messages and extra long messages (up to 2047 bytes). For messages more than 62 bytes digital pins DIO1 and DIO2 must be wired up and configured properly. * CRC, Encoding, RSSI, address filtering, AFC and syncword configurations * Fixed and variable packet formats * Periodic beacons # How to use ## esp-idf Clone this repository somewhere, e.g.: ``` cd ~/myprojects/esp git clone https://github.com/dernasherbrezon/sx127x.git ``` Add path to components: ```cmake set(EXTRA_COMPONENT_DIRS /home/user/myprojects/esp/sx127x) include($ENV{IDF_PATH}/tools/cmake/project.cmake) project(my-esp-project) ``` ## platformio Add the following dependency to platformio.ini: ``` lib_deps = dernasherbrezon/sx127x ``` ## Linux Linux version depends on kernel SPI driver only. Make sure it is enabled. Clone this repository somewhere, e.g.: ``` cd ~/myprojects/esp git clone https://github.com/dernasherbrezon/sx127x.git ``` Add subdirectory: ```cmake add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/sx127x) target_link_libraries(my_application sx127x) ``` ## Custom architecture It is possible to use this library in any other microcontroller architecture. To do this several steps are required. 1. Implement functions to work via SPI. Interface is defined in ```include/sx127x_spi.h``` and put implementation somewhere inside your project. 2. Clone this library into your project 3. Connect all things together in your application's cmake file: ```cmake include_directories(${CMAKE_CURRENT_SOURCE_DIR}/sx127x/include) add_library(sx127x STATIC "${CMAKE_CURRENT_SOURCE_DIR}/sx127x/src/sx127x.c" "${CMAKE_CURRENT_SOURCE_DIR}/src/sx127x_custom_spi_implementation.c") target_link_libraries(my_application sx127x) ``` ## Functions All functions follow the same format: ``` sx127x_(modulation)_(rx or tx or empty)_(set or get)_(parameter) ``` Where: * modulation - can be "lora", "fsk" or "ook" or "fsk_ook" or empty. If empty, then applicable for all modulation types * rx or tx - some functions specific for rx or tx. If empty, then applicable for both * set or get - normally functions operate over sx127x registers - either set or get them # Examples ```examples``` folder contains the following examples: * ```receive_lora``` - RX in LoRa mode and explicit header. Uses CAD to quickly detect presence of the message and switch into RX mode. * ```receive_lora_deepsleep``` - RX in LoRa mode while in the deep sleep * ```receive_lora_implicit_header``` - RX in LoRa mode and implicit header (without header) * ```receive_lora_raspberrypi``` - RX in LoRa mode on RaspberryPI via GPIO pins and onboard SPI. Tested on module RA-02 * ```receive_fsk``` - RX in FSK mode. Variable packet length, NRZ encoding, CRC, AFC on. * ```receive_fsk_filtered``` - RX in FSK mode where only messages with NODE address 0x11 and Broadcast NODE address 0x00 are accepted. Variable packet length, NRZ encoding, CRC, AFC on. * ```receive_fsk_fixed``` - RX in FSK mode. Accepted packets with fixed packet length - 2047 bytes (max possible), NRZ encoding, CRC, AFC on. * ```receive_fsk_raspberry``` - RX in FSK mode on RaspberryPI via GPIO pins and onboard SPI. Variable packet length, NRZ encoding, CRC, AFC on. * ```receive_ook``` - RX in OOK mode. Variable packet length, NRZ encoding, CRC, AFC on. * ```transmit_lora``` - TX in LoRa mode and explicit header. Several messages of different sizes and at all supported power levels * ```transmit_lora_implicit_header``` - TX in LoRa mode and implicit header (without header) * ```transmit_lora_raspberrypi``` - TX messages using LoRa mode from RaspberryPI. Tested on module RA-02 * ```transmit_fsk``` - TX in FSK mode. Variable packet length, NRZ encoding, CRC, AFC on. Sending several messages: small 2 byte, messages that can fit into FIFO fully, max messages for variable packet type - 255 bytes and same messages, but for node address 0x11 and 0x00. * ```transmit_fsk_fixed``` - TX in FSK mode. Fixed packet length - 2047 bytes, NRZ encoding, CRC, AFC on. * ```transmit_ook``` - TX in OOK mode. Variable packet length, NRZ encoding, CRC, AFC on. Sending several messages: small 2 byte, messages that can fit into FIFO fully, max messages for variable packet type - 255 bytes and same messages, but for node address 0x11 and 0x00. # Tests There are several unit tests in the ```test``` folder. They can be executed on any host machine using the commands below: ``` cd test mkdir build cd build cmake .. make test ``` ## Integration tests Integration tests can verify communication between real devices in different modes. Tests require two LoRa boards connected to the same host. It is possible to test on any other boards by overriding pin mappings in ```test/test_app/main.c```. By default tests require: * Receiver is Heltec lora32 v2 * Transmitter is TTGO lora32 Before running tests from ESP-IDF make sure [pytest is installed](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/contribute/esp-idf-tests-with-pytest.html). Run the following command to test: ``` cd test/test_app idf.py build pytest --target esp32 --port="/dev/ttyUSB0|/dev/ttyACM0" pytest_* ``` This command assumes ```/dev/ttyUSB0``` is receiver, ```/dev/ttyACM0``` is transmitter.