DOCSEARCHbyAlgolia
Submit Docs

CapiBridge

repository·main·Indexed 41 days ago

https://github.com/pricelesstoolkit/capibridge

A dual-microcontroller gateway that bridges low-power LoRa and ESP-NOW sensors to an MQTT server, optimized for Home Assistant integration via dynamic topic separation and autodiscovery.

Tokens
13.4K
Snippets
23
Records
59
Agent score
99%

What's inside CapiBridge

  1. Overview of CapiBridge Gateway

    main

    CapiBridge is an open-source two-way gateway designed for low-power devices. It acts as a bridge between LoRa/ESP-NOW sensors and an MQTT server.

    Key Features:

    • Multi-Protocol Support: Receives data via LoRa and ESP-NOW and publishes it to MQTT.
    • Dynamic MQTT Topics: Automatically parses JSON strings from sensors and separates them into dynamic MQTT topics based on keys (e.g., b for battery, m for motion).
    • Home Assistant Integration: Highly compatible with Home Assistant via MQTT-Autodiscovery.
    • WebUI: Includes a built-in Web Interface for configuration and monitoring.

  2. Overview of RadioLib

    main

    RadioLib is a universal wireless communication library for embedded devices designed to provide a consistent system for integrating various wireless communication modules, protocols, and digital modes. It is highly portable, natively supporting Arduino but also capable of running in non-Arduino environments via a hardware abstraction layer.

    Key features include:

    • Consistent API: Use the same interface to control different wireless modules.
    • Extensive Module Support: Covers LoRa, FSK, GFSK, BLE, and more.
    • Protocol Support: Includes AX.25, RTTY, Morse Code, SSTV, Hellschreiber, APRS, POCSAG, and LoRaWAN.
    • Portability: Works across a wide range of Arduino platforms (AVR, ESP32, STM32, etc.) and non-Arduino environments.

  3. Hardware compatibility and limitations

    main

    Supported Hardware

    • Semtech SX1276/77/78/79 boards: Including Dragino LoRa Shield, HopeRF RFM95W/96W/98W, and Modtronix inAir4/9/9B.
    • Arduino MKR WAN 1300:
      • Requirement: Requires firmware v1.1.6 or later on the Murata module.
      • Warning: LoRa.onReceive(...) and LoRa.receive() are not compatible with this specific board.

    Key Concepts

    • LoRa vs LoRaWAN: This library provides direct access to the LoRa radio. It is a broadcast-based system with no addressing or built-in encryption. Unlike LoRaWAN, it does not require a gateway or network server.
    • Security: Data sent via this library is unencrypted. You must implement your own encryption/decryption logic before passing data to the library if security is required.
    • Duty Cycles: This library does not automatically honor legal duty cycle requirements; you must manage timing and duty cycles manually in your code.

  4. Configure Radio Pinmaps

    main

    The pinmap defines the connection between your microcontroller (e.g., ESP32, ATmega, SAMD) and your radio module (e.g., SX1276, SX1262, LR1110).

    For commonly used radio modules, it is recommended to use the RadioBoards library, which can automatically detect your platform and radio to configure pins. If your specific board is not supported, you can find pin definitions in the RadioBoards repository.

  5. Best practices for LoRaWAN Uplink Intervals and Airtime

    main

    LoRaWAN is designed for low-power, infrequent data transmission. To ensure device longevity and compliance with network policies, follow these guidelines:

    • Uplink Interval: Aim for intervals between 15 minutes and once per day. This allows devices to run on batteries for years.
    • Duty Cycle: Be aware of legal limits on transmission time (typically 1% or 0.1% depending on the region).
    • TTN Fair Use Policy (FUP): For the TTN Sandbox, limit airtime to 30 seconds per day and approximately 10 downlinks per day. A common practice is 1 downlink per fortnight for configuration updates.
    • Avoid Real-time Tracking: Do not use LoRaWAN for real-time GPS tracking or high-frequency command & control, as this breaches FUP and legal duty cycle limits.
    • Spreading Factor (SF): Devices further from gateways may require a higher Spreading Factor. Note that an uplink can take 6+ seconds to complete.

  6. Structure of the RadioLib ESP-IDF example

    main

    The ESP-IDF example project is organized with the following key files:

    • main/CMakeLists.txt: The IDF component CMake configuration file.
    • main/EspHal.h: An example implementation of the RadioLib HAL for ESP-IDF.
    • main/idf_component.yml: Declares the RadioLib dependency for the ESP-IDF component manager.
    • main/main.cpp: The primary source code for the example.
    • sdkconfig.defaults: Contains preset configuration values for ESP-IDF; other options fall back to ESP-IDF defaults.

  7. Optimize LoRa Spreading Factor (SF)

    main

    When configuring LoRa in the WebUI, choose the SPREADING_FACTOR (SF) based on your specific environment to balance range, speed, and power consumption.

    • Avoid SF11 by default: While SF11 provides maximum distance, it significantly slows down data transmission and increases 'Time on Air' (ToA), which consumes more power.
    • Use lower SF for closer sensors: If your furthest sensor is only ~100 meters away, use SF7. It is faster and more power-efficient than higher SF settings.

  8. Security best practices for LoRaWAN development

    main

    When developing with LoRaWAN, distinguish between public and private information:

    Public Information (Safe to share for debugging)

    • JoinEUI / DevEUI: These are transmitted in plain text during the join process.
    • Gateway ID: This is public information.

    Private Information (NEVER share)

    • Your TTN Account Password
    • Encryption Keys: Specifically the AppKey and NwkKey.
    • API Keys: Any keys created for accessing your data or configuration via external services.

  9. Getting started with LoRaWAN in RadioLib

    main

    For new users, the LoRaWAN_Starter example is the recommended entry point. It is essential to read the accompanying notes.md file provided with the starter sketch to understand LoRaWAN fundamentals and how they are implemented within the RadioLib library.

    Before moving to advanced examples, it is highly recommended to review the The Things Network documentation to understand the underlying protocol.

  10. Implement LoRaWAN ABP (Activation By Address)

    main

    If your use case requires ABP instead of the recommended OTAA (Over-the-Air Activation), use the LoRaWAN_ABP example.

    Important Note on Persistence: To comply with the LoRaWAN specification, the full session must persist through device resets and power loss. This example does not implement persistence; for production, you must implement a mechanism using Non-Volatile Memory (NVM) to store session data.

  11. Register and set up a device on The Things Network (TTN)

    main

    To use RadioLib with LoRaWAN, you must register your device on a LoRaWAN Network Server (LNS) like The Things Stack (TTS) Sandbox.

    Registration Steps:

    1. Create an Application: In the TTN console, create an application. The ID must be unique across the entire TTN community, use only lowercase letters, numbers, or dashes, and contain no spaces.
    2. Register End Device:
      • Select 'Enter end device specifics manually' (since RadioLib is a third-party stack).
      • Frequency Plan: Choose the plan appropriate for your region (e.g., the recommended option for Europe).
      • LoRaWAN Version: Select LoRaWAN 1.1.0 (the latest specification).
      • JoinEUI: For DIY RadioLib devices, you can use all zeros (0x0000000000000000) as per TR007 recommendations.
      • DevEUI, AppKey, and NwkKey: It is recommended to let the TTN console generate these to ensure proper formatting.
    3. Enable Development Mode: To allow joining and uplinking outside of standard production sequences, go to General Settings -> Join settings -> Expand and enable 'Resets join nonces'.

  12. Install the Arduino LoRa library

    main

    You can install the LoRa library using either the Arduino IDE Library Manager or by cloning the repository via Git.

    Using Arduino IDE Library Manager

    1. Open Arduino IDE.
    2. Navigate to Sketch -> Include Library -> Manage Libraries....
    3. Search for LoRa.
    4. Select the library and click Install.

    Using Git

    Clone the repository directly into your Arduino libraries folder:

    cd ~/Documents/Arduino/libraries/
git clone https://github.com/sandeepmistry/arduino-LoRa LoRa