# dirkbeer/helium_bridge_ws80 architecture

> Architecture diagram of the GitHub repository dirkbeer/helium_bridge_ws80, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dirkbeer/helium_bridge_ws80
- Repository: https://github.com/dirkbeer/helium_bridge_ws80

## Overview

This project is a specialized IoT application designed to bridge sensor data from the Ecowitt WS-80 weather station and similar ISM devices to the Helium LoRaWAN network. It is built on top of the LMIC-node software framework (itself built upon the LMIC LoRaWAN libraries) and includes not only the core source code for handling sensor reading, uplink scheduling, and downlink command processing but also hardware design files (PCB schematics and KiCad files) and payload formatter code (JavaScript for TTN console integration).

##### Main components
- Hardware Layer:
– The physical sensor (Ecowitt WS-80 weather station) that emits FSK encoded signals in the sub-1GHz ISM bands.
– The LoRaWAN bridge device (which in practice can be implemented on a development board like a TTGO LoRa32, Heltec Wifi LoRa 32, or other supported boards) that integrates the CC1101 transceiver module (or similar) and the associated battery/solar power circuitry.
– PCB design files in the “pcb” folder are the actual hardware schematics and layout for a custom LoRaWAN bridge.
- Firmware/Software Layer:
– The core application code in the “src” folder, including files such as LMIC-node.cpp (which contains the scheduling “doWork” job and processes sensor data and downlink commands), WS80.cpp, WeatherStationData.cpp, and AcuriteTower support code.
– Board Support Files (BSFs) in the “src/boards” directory that encapsulate hardware-specific initializations and pin mappings.
- Configuration/Security:
– The keyfiles folder with “lorawan-keys_example.h” (and by extension, the user’s version of lorawan-keys.h) that manages the LoRaWAN credentials for OTAA/ABP activations.
- Integration with LoRaWAN Ecosystem:
– The “payload-formatters” folder which supplies JavaScript uplink payload decoder functions to be used in the TTN (or Helium network) console.
– The PlatformIO configuration file (platformio.ini) which centralizes build settings, board selection, and LMIC configuration.

##### Relationships and interactions
- Data Acquisition:
– The sensor (WS-80) transmits raw data measured in the ISM band.
– The LoRaWAN bridge (embedded microcontroller) receives these signals via the CC1101 transceiver.
- Data Processing:
– The firmware (LMIC-node-based code) processes the incoming sensor data, simulates data (using a counter mechanism as a placeholder in the provided code), packages information into uplink messages, and schedules transmission using the LMIC library.
– Downlink commands (for example, to reset the counter) are processed via the processDownlink() function.
- Communication:
– Uplink messages are transmitted over the LoRaWAN protocol to the Helium network (or TTN) where they are decoded by the payload formatter in the “payload-formatters” folder.
- Hardware Abstraction:
– Board-specific BSF layers ensure that components such as LED indicators, OLED display (if attached), and serial communications are correctly initialized per target board.

##### Architectural patterns and design principles
- Modularization:
– The codebase clearly separates hardware-specific components (PCB designs, BSF files) from the core software logic (src folder) and network/configuration elements (platformio.ini, keyfiles, payload-formatters).
- Layered Architecture:
– The system can be depicted as several layers: physical hardware (sensor, transceiver, power management PCB), firmware abstraction (board support files and LMIC-node functions), and network integration (LoRaWAN uplinks, downlink processing, and payload decoding on the Helium network).
- Separation of Concerns:
– Configuration (keys and platform settings) is kept separate from application logic, making it easier to swap out keys, change boards, or modify sensor formulas.

##### Relevant technologies and frameworks
- Microcontroller programming using the Arduino framework via PlatformIO.
- LMIC LoRaWAN libraries (either MCCI LMIC for 32-bit boards or the IBM LMIC framework for 8-bit boards).
- PCB design tools (KiCad) as exemplified by the files in the “pcb” directory.
- U8g2 for OLED display support and EasyLed for LED control.
- JavaScript for uplink payload formatting used in the network console.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        sensor["Ecowitt WS-80 Sensor"]:::hardware
        bridge["LoRaWAN Bridge Device"]:::hardware
        pcb["PCB – Helium Bridge"]:::hardware
    end

    %% Firmware/Software Layer
    subgraph "Firmware/Software Layer"
        ws80["WS-80 Sensor Data Handling"]:::firmware
        lmic["LMIC-node Logic"]:::firmware
        weather["WeatherStationData Processing"]:::firmware
        acurite["AcuriteTower Support"]:::firmware
        board["Board Support Files"]:::firmware
    end

    %% Configuration and Security
    subgraph "Configuration & Security"
        configCred["LoRaWAN Credentials"]:::config
        configBuild["Build & Environment"]:::config
    end

    %% Network Integration
    subgraph "Network Integration"
        network["LoRaWAN/Helium Network"]:::network
        payload["Payload Formatter"]:::network
    end

    %% Data Flow Connections
    sensor -->|"FSK encoded signals"| bridge
    bridge -->|"Receives via CC1101"| ws80

    ws80 -->|"Processes sensor data"| lmic
    lmic -->|"Packages uplink messages"| network
    lmic -->|"Processes downlink commands"| acurite

    board -->|"Initializes hardware"| lmic

    network -->|"Sends downlink"| lmic
    network -->|"Uses decoder"| payload

    %% Configuration dependencies
    configCred ---|"Provides keys"| lmic
    configBuild ---|"Configures build"| lmic

    %% Additional processing connection
    lmic -->|"Formats weather data"| weather

    %% Click Events
    click pcb "https://github.com/dirkbeer/helium_bridge_ws80/tree/main/pcb/LoRaWan_Bridge"
    click ws80 "https://github.com/dirkbeer/helium_bridge_ws80/blob/main/src/WS80.cpp"
    click lmic "https://github.com/dirkbeer/helium_bridge_ws80/blob/main/src/LMIC-node.cpp"
    click weather "https://github.com/dirkbeer/helium_bridge_ws80/blob/main/src/WeatherStationData.cpp"
    click acurite "https://github.com/dirkbeer/helium_bridge_ws80/blob/main/src/AcuriteTower.cpp"
    click board "https://github.com/dirkbeer/helium_bridge_ws80/tree/main/src/boards"
    click configCred "https://github.com/dirkbeer/helium_bridge_ws80/blob/main/keyfiles/lorawan-keys_example.h"
    click payload "https://github.com/dirkbeer/helium_bridge_ws80/tree/main/payload-formatters"
    click configBuild "https://github.com/dirkbeer/helium_bridge_ws80/blob/main/platformio.ini"

    %% Styles
    classDef hardware fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef firmware fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef config fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef network fill:#fff3cd,stroke:#333,stroke-width:2px;
```
