# aws-samples/aws-iot-core-lorawan architecture

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

- Interactive diagram: https://gitdiagram.com/aws-samples/aws-iot-core-lorawan
- Repository: https://github.com/aws-samples/aws-iot-core-lorawan

## Overview

##### Project type and purpose
- This is a “sample-solutions” monorepo for AWS IoT Core for LoRaWAN.
- It provides multiple reference architectures and code samples (Python/Node.js) for:
- Binary payload decoding (transform_binary_payload, cayenneLPPDecoder, etc.)
- Downlink messaging (send_downlink_payload)
- Thing shadow updates (iotthingshadow)
- Telemetry visualization (timestream, timestream_for_transform_binary_payload)
- Condition monitoring and alarm workflows (soilmoisture_alarming, gateway_watchdog)
- Automation scripts (automation/*) and observability guidelines (observability)

##### File structure
- Top-level folders each represent an independent sample or pattern.
- Most samples follow AWS Serverless + IoT Rule Engine + Lambda:
- src-<component> directories contain Lambda functions (app.py or index.js).
- template.yaml or CDK stacks describe infrastructure.
- Some modules use AWS CDK (gateway_watchdog) or raw CloudFormation/SAM (template.yaml).
- automation/ holds CLI- and Boto3-based scripts executed outside AWS (batch device/gateway registration).
- Observability guidelines are documentation only.

##### Key insights from README
- The core flow: LoRaWAN Devices → Gateways → AWS IoT Core for LoRaWAN → IoT Core message broker → IoT Rules → Lambda → downstream AWS services.
- Each sample wires IoT Rules to specific actions: e.g. transform payload, write to Timestream, update Thing Shadow, send SNS/SMS.
- Decoders exist as standalone JS/Python libraries, some packaged as Lambda layers.

a. Main components
- LoRaWAN Devices (end-nodes)
- LoRaWAN Gateways
- AWS IoT Core for LoRaWAN service (network server)
- AWS IoT Core (message broker + Rules Engine)
- Lambda functions (decoders, transformers, metrics publishers)
- Downstream services: Amazon Timestream, AWS IoT Events, AWS IoT Thing Shadows, Amazon SNS/SMS, CloudWatch Metrics, Grafana plugin, Pilot Things Sensor Library (external SaaS)
- Automation clients (local scripts using AWS CLI / Boto3)

b. Relationships & data flow
1. Device → Gateways: radio uplink
2. Gateway → AWS IoT Core for LoRaWAN: MQTT over Internet
3. IoT Core for LoRaWAN → AWS IoT Core broker: Pub/Sub topics
4. IoT Rules Engine → invokes Lambdas based on topic filters
5. Lambda decoders/transformers → JSON → route to downstream service via SDK/API
6. Downlink path (reverse): Clients or Lambdas → AWS IoT Core → LoRaWAN Network → Device

c. Architectural patterns
- Event-driven: IoT Rules trigger micro-Lambdas.
- Serverless: minimal servers, pay-per-use.
- Infrastructure as code: SAM template.yaml or AWS CDK stack.py definitions.
- Modular decoders: language-agnostic, shareable libraries/layers.
- CI/CD / code scanning: GitHub Actions (codeql-analysis.yml), CodeBuild badge.

d. Key technologies & frameworks
- AWS LoRaWAN managed network
- AWS IoT Core & Rules Engine
- AWS Lambda (Python, Node.js)
- AWS CDK (Python) and SAM/CloudFormation
- AWS SDK (Boto3, AWS CLI)
- Storage & analytics: Amazon Timestream, Grafana plugin, CloudWatch, IoT Events, SNS
- External: Pilot Things Sensor Library

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core flow
    subgraph "LoRaWAN Ingress"
        direction TB
        Devices["LoRaWAN Devices"]:::external
        Gateways["LoRaWAN Gateways"]:::managed
        LoRaWAN["AWS IoT Core for LoRaWAN"]:::managed
        Devices -->|"Radio Uplink"| Gateways
        Gateways -->|"MQTT over Internet"| LoRaWAN
    end

    subgraph "AWS IoT Core"
        direction TB
        IoTCore["AWS IoT Core (Broker)"]:::managed
        IoTRule["IoT Rule Engine"]:::managed
        LoRaWAN -->|"Pub/Sub Topic"| IoTCore
        IoTCore -->|"SQL Filter"| IoTRule
    end

    %% Sample: Binary Payload Decoding
    subgraph "Binary Payload Decoding" 
        direction TB
        TPTL["transform_binary_payload Lambda"]:::lambda
        DecLibPy["Decoder Lib (Python)"]:::lambda
        DecLibJS["Decoder Lib (Node.js)"]:::lambda
        InfraTBL["transform_binary_payload Infra"]:::infra
        IoTRule -->|"transform_binary_payload rule"| TPTL
        TPTL -->|"uses"| DecLibPy
        TPTL -->|"uses"| DecLibJS
    end

    %% Cayenne LPP Decoder Library
    subgraph "Cayenne LPP Decoder"
        direction TB
        CayJS["cayenneLPPDecoder JS Lib"]:::external
        IoTRule -->|"library only"| CayJS
    end

    %% Downlink Messaging
    subgraph "Downlink Messaging"
        direction TB
        SendDL["send_downlink_payload Lambda"]:::lambda
        InfraDL["send_downlink_payload Infra"]:::infra
        SendDL -->|"Invoke via SDK"| LoRaWAN
    end

    %% Thing Shadow Updates
    subgraph "Thing Shadow Updates"
        direction TB
        ShadowTrans["Shadow Transform Lambda"]:::lambda
        MapThing["Thing Name Mapper Lambda"]:::lambda
        DecPyTS["Decoder Lib (Python)"]:::lambda
        InfraTS["iotthingshadow Infra"]:::infra
        IoTRule -->|"shadow update rule"| ShadowTrans
        ShadowTrans -->|"map to thing"| MapThing
        MapThing -->|"uses"| DecPyTS
    end

    %% Telemetry Visualization - Timestream
    subgraph "Telemetry: Timestream"
        direction TB
        TransTS["Transform Lambda"]:::lambda
        WriteTS["Write-to-Timestream Lambda"]:::lambda
        LayerDecTS["Decoder Layer (Python)"]:::lambda
        InfraTST["timestream Infra"]:::infra
        IoTRule -->|"timestream rule"| TransTS
        TransTS -->|"invoke"| WriteTS
        TransTS -->|"uses"| LayerDecTS
    end

    %% Telemetry Visualization for Binary Payload
    subgraph "Telemetry: Timestream (Binary)"
        direction TB
        WriteBTS["Write-to-Timestream Lambda"]:::lambda
        InfraBTS["timestream_for_transform_binary_payload Infra"]:::infra
        IoTRule -->|"binary timestream rule"| WriteBTS
    end

    %% Condition Monitoring & Alarming
    subgraph "Soil Moisture Alarming"
        direction TB
        InfraSMA["soilmoisture_alarming Infra"]:::infra
        IoTRule -->|"alarming rule"| InfraSMA
    end

    subgraph "Gateway Watchdog"
        direction TB
        CDKStack["CDK Stack"]:::infra
        DetectorModel["Detector Model"]:::infra
        GWStats["Gateway Stats Lambda"]:::lambda
        CWMetrics["CloudWatch Metrics Lambda"]:::lambda
        CDKStack --> DetectorModel
        CDKStack --> GWStats
        CDKStack --> CWMetrics
    end

    %% Automation Scripts
    subgraph "Automation Scripts"
        direction TB
        DevWS["Developer Workstation"]:::external
        BatchReg["Batch Register Devices Script"]:::external
        DevWS -->|"runs"| BatchReg
    end

    %% Observability Guidelines
    subgraph "Observability"
        direction TB
        ObsDoc["Observability README"]:::external
    end

    %% Click Events
    click TPTL "https://github.com/aws-samples/aws-iot-core-lorawan/blob/main/transform_binary_payload/src-iotrule-transformation/app.py"
    click DecLibPy "https://github.com/aws-samples/aws-iot-core-lorawan/tree/main/transform_binary_payload/src-payload-decoders/python/"
    click DecLibJS "https://github.com/aws-samples/aws-iot-core-lorawan/tree/main/transform_binary_payload/src-payload-decoders/node/"
    click InfraTBL "https://github.com/aws-samples/aws-iot-core-lorawan/blob/main/transform_binary_payload/template.yaml"
    click CayJS "https://github.com/aws-samples/aws-iot-core-lorawan/blob/main/cayenneLPPDecoder/decoder.js"
    click SendDL "https://github.com/aws-samples/aws-iot-core-lorawan/blob/main/send_downlink_payload/src/app.py"
    click InfraDL "https://github.com/aws-samples/aws-iot-core-lorawan/blob/main/send_downlink_payload/template.yaml"
    click ShadowTrans "https://github.com/aws-samples/aws-iot-core-lorawan/blob/main/iotthingshadow/src-iotrule-transformation/app.py"
    click MapThing "https://github.com/aws-samples/aws-iot-core-lorawan/blob/main/iotthingshadow/src-mapthingname/app.py"
    click DecPyTS "https://github.com/aws-samples/aws-iot-core-lorawan/tree/main/iotthingshadow/src-payload-decoders/python/"
    click InfraTS "https://github.com/aws-samples/aws-iot-core-lorawan/blob/main/iotthingshadow/template.yaml"
    click TransTS "https://github.com/aws-samples/aws-iot-core-lorawan/blob/main/timestream/src-lambda-transform/app.py"
    click WriteTS "https://github.com/aws-samples/aws-iot-core-lorawan/blob/main/timestream/src-lambda-write-to-timestream/app.py"
    click LayerDecTS "https://github.com/aws-samples/aws-iot-core-lorawan/tree/main/timestream/src-layer-payload-decoders/python/"
    click InfraTST "https://github.com/aws-samples/aws-iot-core-lorawan/blob/main/timestream/template.yaml"
    click WriteBTS "https://github.com/aws-samples/aws-iot-core-lorawan/blob/main/timestream_for_transform_binary_payload/src-lambda-write-to-timestream/app.py"
    click InfraBTS "https://github.com/aws-samples/aws-iot-core-lorawan/blob/main/timestream_for_transform_binary_payload/template.yaml"
    click InfraSMA "https://github.com/aws-samples/aws-iot-core-lorawan/blob/main/soilmoisture_alarming/template.yaml"
    click CDKStack "https://github.com/aws-samples/aws-iot-core-lorawan/blob/main/gateway_watchdog/cdkstack/lorawan_connectivity_watchdog_stack.py"
    click DetectorModel "https://github.com/aws-samples/aws-iot-core-lorawan/blob/main/gateway_watchdog/cdkstack/lorawan_gateway_monitoring_detectormodel.py"
    click GWStats "https://github.com/aws-samples/aws-iot-core-lorawan/blob/main/gateway_watchdog/src_get_wireless_gateway_statistics_lambda/lambda.py"
    click CWMetrics "https://github.com/aws-samples/aws-iot-core-lorawan/blob/main/gateway_watchdog/src_put_cloudwatch_metrics/lambda.py"
    click DevWS "https://github.com/aws-samples/aws-iot-core-lorawan/blob/main/automation/batchregistration/batch_register_lorawan_devices.py"
    click BatchReg "https://github.com/aws-samples/aws-iot-core-lorawan/blob/main/automation/batchregistration/batch_register_lorawan_devices.py"
    click ObsDoc "https://github.com/aws-samples/aws-iot-core-lorawan/blob/main/observability/README.md"

    %% Styles
    classDef managed fill:#cfe2f3,stroke:#0366d6,color:#0366d6
    classDef lambda fill:#d0f0c0,stroke:#2e7d32,color:#2e7d32
    classDef external fill:#ffe5b4,stroke:#e65100,color:#e65100
    classDef infra fill:#f3e5f5,stroke:#6a1b9a,color:#6a1b9a
```
