atmowx.net / awn-bridge
Publish your Ambient Weather station to the AT Protocol — SI observations in your own atproto repo, indexed live at atmowx.net
Star 2
Fork 0
Watch
TypeScript 99%
Dockerfile 1%
3 1 3
packages
.dockerignore
.env.example
.gitignore
docker-compose.yml
Dockerfile
LICENSE
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
README.md
tsconfig.base.json
vitest.config.ts
README.md

awn-bridge #

Publish your Ambient Weather station to the AT Protocol.

Your station's observations become records in your own atproto repo — you own the data. The atmowx.net map discovers new stations automatically from the firehose and indexes their history; no registration, no API key, no permission needed.

Two ways in, run either or both:

  • Cloud polling — the bridge polls the Ambient Weather Network API (WS-2902 and friends with an AWN account)
  • Direct station push — your console posts straight to the bridge over its "custom server" feature (Ambient Weather and Ecowitt protocols), no cloud account needed; runs fine on a Raspberry Pi

All measurements are converted to SI units and published under the open net.atmowx.* lexicons.

Prerequisites #

  • An atproto account (any PDS — Bluesky or self-hosted) and an app password
  • For cloud polling and history backfill: Ambient Weather API Key and Application Key (ambientweather.net → Account → API Keys) — optional in push-only setups
  • Docker (for the always-on bridge) and Node 22 + pnpm (for the one-time setup)

Quickstart #

git clone https://tangled.org/atmowx.net/awn-bridge
cd awn-bridge && pnpm install
cp .env.example .env    # fill in AWN + atproto credentials

# Create your public station record (pick coordinates at whatever
# precision you're comfortable publishing — it's your privacy knob):
pnpm tsx --env-file=.env packages/bridge/src/cli.ts station create \
  --name "My Station" --lat 45.55 --lon -122.67 --elevation 61 \
  --timezone America/Los_Angeles --make "Ambient Weather" --model WS-2902

# Put the printed AT-URI into AWN_DEVICE_MAP in .env:
#   AWN_DEVICE_MAP={"AA:BB:CC:DD:EE:FF":"at://did:plc:you/net.atmowx.station/..."}
# (your station's MAC address is shown on ambientweather.net)

docker compose up -d          # live observations every 5 minutes

# Import your full station history (idempotent — safe to re-run anytime):
pnpm tsx --env-file=.env packages/bridge/src/cli.ts backfill \
  --from 2024-01-01T00:00:00Z --to 2026-08-21T15:46:52Z

Within a minute your station appears on the map.

Direct station push #

Cut the AWN cloud out of the live path — your console posts each reading straight to the bridge:

  1. In .env, set PUSH_LISTEN_PORT=8080 (AWN keys become optional; backfill still needs them since history only exists in the cloud).
  2. Uncomment the ports mapping in docker-compose.yml and docker compose up -d.
  3. Point the console at the bridge:
    • Ambient Weather (awnet app): Custom Server → protocol Ambient Weather, host = the bridge's address, port 8080, path /data/report/, interval ≥ 16 s
    • Ecowitt (WSView Plus app): Customized → same fields
  4. Watch the bridge logs: a misconfigured MAC shows up as a loud push: UNKNOWN DEVICE line telling you what to add to AWN_DEVICE_MAP.

The console speaks plain HTTP only (firmware limitation) — keep the console→bridge leg on your LAN/VPN, or set PUSH_PATH_TOKEN so the required path becomes /data/report/<token>/ and accept the exposure. PUSH_MIN_INTERVAL_SECONDS (default 60) throttles how often readings are written; pushes and polling can run together — deterministic record keys make overlap harmless.

How it works #

  • One immutable net.atmowx.observation record per reading, SI units as scaled integers ({"value": 214, "scale": -1} = 21.4 °C)
  • Record keys derive deterministically from the reading time, so re-running a backfill can never create duplicates
  • Schemas are published, resolvable lexicons — API docs · join guide

Development #

pnpm typecheck && pnpm test (typecheck first — it builds the workspace packages the tests import). This repo is a curated release snapshot of the atmowx monorepo (this release: 2266093); issues and patches are welcome via Tangled.

License #

MIT