Merge pull request #38 from cnbhl/feature/docker-support

feat: Docker support for containerized deployment

Author: cnbhl

.dockerignore

@@ -0,0 +1,46 @@
+# Build artifacts
+build-*/
+build-local/
+
+# Dependency cloned repos (will be fetched during build)
+deps/lgw/git-repo/
+deps/lgw/platform-*/
+deps/lgw1302/git-repo/
+deps/lgw1302/platform-*/
+deps/mbedtls/git-repo/
+deps/mbedtls/platform-*/
+deps/smtcpico/
+
+# Credentials (never include in image)
+*.key
+*.trust
+*.crt
+cups.uri
+tc.uri
+examples/corecell/cups-ttn/station.conf
+examples/corecell/cups-ttn/board.conf
+
+# Tests
+regr-tests/
+tests/
+
+# Documentation
+docs/
+*.md
+!examples/corecell/cups-ttn/*.md
+
+# Logs
+*.log
+
+# Editor and IDE files
+*~
+*.swp
+.vscode/
+.idea/
+
+# Git
+.git/
+.gitignore
+
+# Docker files (no recursive build)
+docker-compose.yml

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+## 2.0.6-cnbhl.1.6 - 2025-02-04
+
+* feature: Docker support for containerized deployment
+  - Multi-stage Dockerfile (builder compiles station + chip_id, runner is minimal Debian bookworm-slim)
+  - `docker/entrypoint.sh` validates env vars, generates config, auto-detects Gateway EUI, starts station
+  - `docker-compose.yml` with all environment variables documented
+  - `.dockerignore` excludes build artifacts, credentials, tests
+  - Support for all board types (WM1302, PG1302, LR1302, SX1302_WS, SEMTECH, custom GPIO)
+  - Auto EUI detection from SX1302 chip via `chip_id`
+  - GPS passthrough support
+  - Custom SPI device path support
+  - `EUI_ONLY=1` mode for detecting Gateway EUI before TTN registration
+* fix: Add python3, python3-jsonschema, python3-jinja2 to Docker builder (required by mbedtls 3.6.0)
+* fix: Clean up stale PID files before station start in Docker (prevents restart failures)
+* fix: Use station's built-in `stderr` log mode instead of `/dev/stderr` path for Docker log compatibility
 * fix: Zero-initialize ifconf struct before JSON channel config parsing (cherry-pick from MultiTech `64f634f`)
 * feature: mbedtls 3.x compatibility with TLS 1.3 support (cherry-pick from MultiTech)
   - PSA crypto initialization for mbedtls 3.x
@@ -22,6 +37,10 @@
   - LNS can control GPS via `router_config` with `gps_enable` field
   - Advertises `gps-ctrl` feature flag to LNS
 * fix: Use correct TX command when checking nocca response (cherry-pick from MultiTech `5c54f11`)
+* feature: Fine timestamp support for SX1302/SX1303 with GPS PPS
+* feature: SF5/SF6 spreading factor support (LoRaWAN RP2 1.0.5)
+* fix: SX1302 LBT error handling (correct error constants for SX1302 vs SX1301)
+* fix: Exit on stuck concentrator (excessive clock drift detection)
 
 ## 2.0.6-cnbhl.1.0 - 2025-01-25
 

CLAUDE.md

@@ -12,6 +12,7 @@ This is a fork of [lorabasics/basicstation](https://github.com/lorabasics/basics
 - Automatic Gateway EUI detection from SX1302/SX1303 chips
 - Systemd service configuration
 - Fine timestamp support for SX1302/SX1303 with GPS PPS
+- Docker support for containerized deployment
 
 For upstream Basic Station documentation: https://doc.sm.tc/station
 
@@ -481,6 +482,96 @@ sudo systemctl start basicstation.service
 sudo journalctl -u basicstation.service -f
 ```
 
+## Docker Support
+
+Build and run the station as a Docker container on Raspberry Pi.
+
+### Build
+
+```bash
+docker build -t basicstation .
+# Debug variant:
+docker build -t basicstation --build-arg VARIANT=debug .
+```
+
+### Detect EUI (new board)
+
+```bash
+docker run --rm --privileged -e BOARD=WM1302 -e EUI_ONLY=1 basicstation
+```
+
+Register the printed EUI on TTN Console, then start:
+
+### Run
+
+```bash
+# Using docker-compose (recommended)
+CUPS_KEY="NNSXS.xxx..." docker compose up -d
+docker logs -f basicstation
+
+# Using docker run
+docker run -d --privileged --network host \
+  --name basicstation --restart unless-stopped \
+  -e BOARD=PG1302 -e REGION=eu1 \
+  -e GATEWAY_EUI=auto \
+  -e CUPS_KEY="NNSXS.xxx..." \
+  basicstation
+```
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BOARD` | Yes | -- | WM1302, PG1302, LR1302, SX1302_WS, SEMTECH, or `custom` |
+| `REGION` | Yes | -- | TTN region: eu1, nam1, au1 |
+| `GATEWAY_EUI` | Yes | -- | 16 hex chars or `auto` (chip detection) |
+| `CUPS_KEY` | Yes | -- | TTN CUPS API key (NNSXS.xxx...) |
+| `EUI_ONLY` | No | -- | Set to `1` to detect Gateway EUI and exit (only `BOARD` required) |
+| `GPS_DEV` | No | _(disabled)_ | GPS device path (e.g. `/dev/ttyS0`) or `none` |
+| `ANTENNA_GAIN` | No | `0` | Antenna gain in dBi (0-15) |
+| `SPI_DEV` | No | `/dev/spidev0.0` | SPI device path |
+| `LOG_LEVEL` | No | `DEBUG` | Station log level |
+| `SX1302_RESET_GPIO` | If custom | -- | BCM pin for SX1302 reset |
+| `POWER_EN_GPIO` | If custom | -- | BCM pin for power enable |
+| `SX1261_RESET_GPIO` | If custom | -- | BCM pin for SX1261 reset |
+
+### Docker Files
+
+- `Dockerfile` - Multi-stage build (builder compiles station + chip_id, runner is minimal)
+- `docker/entrypoint.sh` - Validates env vars, generates config, starts station
+- `docker-compose.yml` - Example compose file with all env vars documented
+- `.dockerignore` - Excludes build artifacts, credentials, tests from context
+
+### Container Layout
+
+```
+/app/
+├── bin/station              # Station binary
+├── bin/chip_id              # EUI detection tool
+├── scripts/
+│   ├── reset_lgw.sh         # GPIO reset (SX1302 + SX1261 + Power EN)
+│   ├── rinit.sh             # Radio init wrapper
+│   └── board.conf           # Generated at runtime by entrypoint
+├── templates/
+│   ├── station.conf.template
+│   └── board.conf.template
+├── config/                  # Station home dir (generated at runtime)
+│   ├── station.conf
+│   ├── cups.uri
+│   ├── cups.key
+│   └── cups.trust
+└── entrypoint.sh
+```
+
+### Notes
+
+- Requires `privileged: true` or sysfs GPIO access for concentrator reset
+- Requires `network_mode: host` for LoRaWAN packet reception
+- Logs go to stderr via station's built-in stderr mode (`log_file: "stderr"`) — visible via `docker logs`
+- Uses the same `station.conf.template` and `board.conf.template` as `setup-gateway.sh`
+- Builder stage requires `python3`, `python3-jsonschema`, `python3-jinja2` for mbedtls 3.6.0 PSA crypto wrapper generation
+- Stale PID files (`/var/tmp/station.pid`, `/tmp/station.pid`) are cleaned up before station start to prevent restart failures
+
 ## Build System Notes
 
 Platform/variant configuration in `setup.gmk`:
@@ -578,7 +669,7 @@ Format: `2.0.6-cnbhl.X.Y` or `2.0.6-cnbhl.X.Ya`
 - **Tag**: No "v" prefix (e.g., `2.0.6-cnbhl.1.0`)
 - **Release title**: `Release 2.0.6-cnbhl.X.Y` (prefix with "Release ")
 
-**Current version**: `2.0.6-cnbhl.1.5`
+**Current version**: `2.0.6-cnbhl.1.6`
 
 **History**: Versions `2.0.6-cnbhl.1` through `2.0.6-cnbhl.5` used the old single-number scheme.
 Starting with `2.0.6-cnbhl.1.0`, we use the new X.Y format.

Dockerfile

@@ -1,32 +1,76 @@
-FROM ubuntu:18.04
+# Multi-stage Dockerfile for cnbhl/basicstation-rpi64
+# Builds and runs Basic Station with SX1302/SX1303 corecell support
+#
+# Build:  docker build -t basicstation .
+# Run:    docker run -d --privileged --network host \
+#           -e BOARD=PG1302 -e REGION=eu1 -e GATEWAY_EUI=auto \
+#           -e CUPS_KEY="NNSXS.xxx..." basicstation
 
-ENV container=docker TERM=xterm LC_ALL=en_US LANGUAGE=en_US LANG=en_US.UTF-8
-ENV DEBIAN_FRONTEND=noninteractive
+ARG VARIANT=std
 
-# locale
-RUN apt-get update -q > /dev/null && \
-        apt-get install --no-install-recommends -yq apt-utils locales language-pack-en dialog \
-        > /dev/null && \
-        locale-gen $LANGUAGE $LANG
+# =============================================================================
+# Stage 1: Builder
+# =============================================================================
+FROM debian:bookworm-slim AS builder
 
-# sudo commmand
-RUN apt-get -yq install sudo > /dev/null
+ARG VARIANT=std
 
-# non-privileged user
-RUN echo "nonprivuser ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
-RUN useradd --no-log-init --home-dir /home/nonprivuser --create-home --shell /bin/bash -u 1000 \
-        nonprivuser && adduser nonprivuser sudo
-USER nonprivuser
-WORKDIR /home/nonprivuser
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential \
+        git \
+        curl \
+        ca-certificates \
+        python3 \
+        python3-jsonschema \
+        python3-jinja2 \
+    && rm -rf /var/lib/apt/lists/*
 
-# system packages
-RUN sudo apt-get install --no-install-recommends -yq \
-        git psmisc build-essential lcov curl netcat-openbsd \
-        python3 python3-pip python3-setuptools python3-wheel \
-        > /dev/null && \
-        sudo apt-get clean -q && \
-        sudo ln -s /usr/bin/python3 /usr/bin/python
+COPY . /build
+WORKDIR /build
 
-RUN pip3 install aiohttp websockets
+# Build station binary (deps/*/prep.sh clone HAL and mbedtls via git)
+RUN make platform=corecell variant=${VARIANT}
 
+# Build chip_id tool for EUI auto-detection
+RUN gcc -std=gnu11 -O2 \
+        -I build-corecell-${VARIANT}/include/lgw \
+        tools/chip_id/chip_id.c tools/chip_id/log_stub.c \
+        -L build-corecell-${VARIANT}/lib -llgw1302 -lm -lpthread -lrt \
+        -o build-corecell-${VARIANT}/bin/chip_id
 
+# =============================================================================
+# Stage 2: Runner
+# =============================================================================
+FROM debian:bookworm-slim
+
+ARG VARIANT=std
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create directory structure
+RUN mkdir -p /app/bin /app/scripts /app/templates /app/config
+
+# Copy binaries from builder
+COPY --from=builder /build/build-corecell-${VARIANT}/bin/station /app/bin/station
+COPY --from=builder /build/build-corecell-${VARIANT}/bin/chip_id /app/bin/chip_id
+
+# Copy runtime scripts
+COPY examples/corecell/cups-ttn/reset_lgw.sh /app/scripts/reset_lgw.sh
+COPY examples/corecell/cups-ttn/rinit.sh /app/scripts/rinit.sh
+
+# Copy templates
+COPY examples/corecell/cups-ttn/station.conf.template /app/templates/station.conf.template
+COPY examples/corecell/cups-ttn/board.conf.template /app/templates/board.conf.template
+
+# Copy entrypoint
+COPY docker/entrypoint.sh /app/entrypoint.sh
+
+RUN chmod +x /app/bin/station /app/bin/chip_id \
+              /app/scripts/reset_lgw.sh /app/scripts/rinit.sh \
+              /app/entrypoint.sh
+
+WORKDIR /app/config
+
+ENTRYPOINT ["/app/entrypoint.sh"]

README.md

@@ -8,11 +8,32 @@ Fork of [lorabasics/basicstation](https://github.com/lorabasics/basicstation) (v
 - Automated TTN CUPS setup with `setup-gateway.sh`
 - Automatic Gateway EUI detection from SX1302/SX1303
 - Systemd service configuration
+- **Docker support** for containerized deployment
 
 See [docs/FEATURES.md](docs/FEATURES.md) for a complete list of features and fixes.
 
 For upstream documentation: [doc.sm.tc/station](https://doc.sm.tc/station)
 
+## Table of Contents
+
+- [Quick Start](#quick-start)
+  - [Options](#options)
+  - [Non-Interactive Mode](#non-interactive-mode)
+- [Supported Boards](#supported-boards)
+- [Tested Platforms](#tested-platforms)
+- [Prerequisites](#prerequisites)
+- [Docker Deployment](#docker-deployment)
+  - [Step 1: Detect Gateway EUI](#step-1-detect-gateway-eui)
+  - [Step 2: Start the station](#step-2-start-the-station)
+  - [Environment Variables](#environment-variables)
+- [Running](#running)
+- [Repository Structure](#repository-structure)
+- [Testing](#testing)
+- [Raspberry Pi GPIO Support](#raspberry-pi-gpio-support)
+- [Dependencies](#dependencies)
+- [Third-Party Components](#third-party-components)
+- [License](#license)
+
 ## Quick Start
 
 ```bash
@@ -103,6 +124,58 @@ Run `sudo raspi-config` → Interface Options:
 
 Reboot after changes.
 
+## Docker Deployment
+
+Run the station as a Docker container — no build tools or dependencies needed on the host.
+
+```bash
+docker build -t basicstation .
+```
+
+### Step 1: Detect Gateway EUI
+
+For a new board, detect the EUI first to register on TTN:
+
+```bash
+docker run --rm --privileged -e BOARD=WM1302 -e EUI_ONLY=1 basicstation
+```
+
+This prints the Gateway EUI and exits. Register the gateway at [TTN Console](https://console.cloud.thethings.network/) and generate a CUPS API key.
+
+### Step 2: Start the station
+
+```bash
+docker run -d --privileged --network host \
+  --name basicstation --restart unless-stopped \
+  -e BOARD=WM1302 -e REGION=eu1 \
+  -e GATEWAY_EUI=auto \
+  -e CUPS_KEY="NNSXS.xxx..." \
+  basicstation
+```
+
+Or with docker compose:
+
+```bash
+CUPS_KEY="NNSXS.xxx..." docker compose up -d
+docker logs -f basicstation
+```
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BOARD` | Yes | -- | WM1302, PG1302, LR1302, SX1302_WS, SEMTECH, or `custom` |
+| `REGION` | Yes | -- | TTN region: eu1, nam1, au1 |
+| `GATEWAY_EUI` | Yes | -- | 16 hex chars or `auto` (chip detection) |
+| `CUPS_KEY` | Yes | -- | TTN CUPS API key |
+| `EUI_ONLY` | No | -- | Set to `1` to detect EUI and exit (no CUPS_KEY needed) |
+| `GPS_DEV` | No | _(disabled)_ | GPS device path or `none` |
+| `ANTENNA_GAIN` | No | `0` | Antenna gain in dBi (0-15) |
+| `SPI_DEV` | No | `/dev/spidev0.0` | SPI device path |
+| `LOG_LEVEL` | No | `DEBUG` | Station log level |
+
+For custom boards, set `BOARD=custom` and provide `SX1302_RESET_GPIO`, `POWER_EN_GPIO`, `SX1261_RESET_GPIO`.
+
 ## Running
 
 **Via systemd** (if configured during setup):
@@ -123,6 +196,9 @@ cd examples/corecell/cups-ttn
 ```
 basicstation/
 ├── setup-gateway.sh              # Main setup script
+├── Dockerfile                    # Multi-stage Docker build
+├── docker-compose.yml            # Docker compose example
+├── docker/entrypoint.sh          # Container entrypoint
 ├── lib/                          # Modular shell libraries
 │   ├── common.sh                 # Output, logging, dependency checks
 │   ├── validation.sh             # Input validation

VERSION.txt

@@ -1 +1 @@
-2.0.6-cnbhl.1.0
+2.0.6-cnbhl.1.6