Loading 3D model… large boards can take a moment.
A WhatsApp and Telegram service for the tenants of a business complex. It does two jobs:
Gate access. A tenant sends a message, the service works out which gate they mean and whether they are allowed through it, publishes an MQTT downlink to a LoRaWAN Class C controller, and confirms back once the device acknowledges.
Tenant support. The same conversation handles pomoc (help), which lists
the gates that particular tenant may open, and usterka (fault report), a
guided flow that collects a description and contact address and routes it to
the administrator by email.
The full stack is here: the relay board (hardware/), the controller firmware
(firmware/) and the server side service (bot/). It is deployed and running
24/7.
WhatsApp / Telegram
│
▼
FastAPI service ──► SQLite (members, permissions, access log)
│
▼ MQTT downlink
ChirpStack v4 ──► LoRaWAN gateway ──► RAK3172 board (firmware/) ──► gate
│
◄── ACK (~3 s) ─────────────────────────────────────────┘
hardware/ contains a mains powered LoRaWAN relay controller built around the
RAK3172 (STM32WLE5, LoRa SoC).
| Front | Back |
|---|---|
| Radio | RAK3172 module, LoRaWAN Class C |
| Power | IRM-01-3.3 AC/DC module, runs directly from mains |
| Switching | TE 1461103-1 SPST-NO relay (10 A max), 2× FDN335N N-channel MOSFETs |
| Indicators | 2× 0603 LEDs: STATUS and RELAY |
| I/O | 2× screw terminals (DG126-5.0), 4-pin programming header |
| Board | 2-layer, SMD, hand-solderable footprints |
The low voltage side (radio, drivers, LEDs) and the mains side (supply input and relay contacts) are kept on separate halves of the board. The mains half is marked with a high voltage warning on the back silkscreen.
The board sits in a custom enclosure designed in Fusion 360, with the cable brought in through a PG9 gland. The LEDs stay on the PCB. Custom plexiglass pieces set into the lid capture their light and carry it up to windows next to the STATUS and RELAY labels, so both indicators are visible from outside without any wiring to the lid. The photo above shows the working device with both lit.
hardware/kicad/: schematic, layout, 3D STEP model, custom footprintshardware/fabrication/: Gerbers, Excellon drill files, drill mapshardware/docs/: schematic PDF, board PDF, BOMThe board switches mains-adjacent loads and carries a high voltage warning on the silkscreen. Treat it accordingly.
firmware/ is an RUI3 sketch for the RAK3172-T on the relay board. It joins as
a LoRaWAN Class C device, so downlinks arrive at any time.
Commands are one byte: pulse, hold on, off, toggle, a pulse of caller specified length, and a status query. The controller answers on a separate port, and the ACK is sent after the relay action completes, not when the packet arrives, so the server can tell a tenant the gate actually moved. A status uplink reports relay state, join state and uptime. A heartbeat goes out every five minutes.
Per-device OTAA credentials live in a gitignored secrets.h; see
firmware/README.md.
Python 3.12 · FastAPI · Jinja2 · paho-mqtt · SQLAlchemy · python-telegram-bot
bot/
├── adapters/ messaging channels (BaseAdapter → telegram, whatsapp)
├── web/ FastAPI app, admin GUI, privacy page
├── gates_config.py gate registry + phrase matching
├── mqtt_handler.py ChirpStack downlink + ACK correlation
├── claude_router.py optional LLM fallback intent classification
├── database.py members, permissions, access log
└── email_utils.py fault-report mail with Reply-To routing
Routing order. Inbound text is matched most specific first: an in-progress fault report, then a gate phrase, then help/fault keywords, then the optional LLM fallback, then a generic reply. Unknown senders are rejected before any of it and logged.
Adapter pattern. Each messaging channel is self-contained and extends
BaseAdapter. Telegram polls; WhatsApp is webhook driven. Adding a channel
does not touch the gate or MQTT layer.
Gate resolution. Tenants write natural Polish, not commands. The complex has
three gates, and matching runs in two tiers. First, short numeric codes and
distinguishing keywords, with Polish diacritics folded so główna and glowna
match the same way. Context words are taken into account, so "brama obok
szlabanu" (the gate next to the barrier) resolves to the gate and not the
barrier. Second, token level difflib fuzzy matching on the distinguishing
words only, to absorb typos. A message that fits more than one gate, or a bare
"brama", is treated as ambiguous and never guessed.
ACK correlation. Downlinks are sent confirmed. The service subscribes to the device's ACK topic and correlates the response before telling the tenant the gate actually opened, with a configurable timeout.
Webhook verification. Inbound WhatsApp requests are verified via
X-Hub-Signature-256 HMAC against the app secret. Message IDs are de-duplicated
for 5 minutes so Meta's retries cannot double-open a gate.
Tenant support flow. pomoc answers with the gates that specific member is
permitted to open, resolved from their own record rather than a static list.
usterka opens a three step conversation: describe the fault, then give a
contact address (validated and re-prompted if malformed), and the administrator
gets an email with Reply-To set to the tenant. Hitting Reply therefore
reaches the tenant directly, in one thread, without the bot in the middle. The
sender's display name is set from the member record, with Polish diacritics
encoded correctly, so the administrator's inbox stays readable. Pending reports
are held in memory with a 10 minute expiry and take priority over every other
match, so a tenant in the middle of a report is never misread as asking for a
gate.
Fault reports are written to the same access log as gate openings, giving one chronological record per tenant.
Optional LLM fallback. When deterministic matching fails, the message can
be classified by an LLM constrained to a strict JSON schema
(open_gate | fault_report | help | unrelated). The model can never emit text
that reaches a user; every reply is a hard-coded template. Gate permissions are
re-checked against the database after classification, so a manipulated
classification cannot grant access. It is rate limited per phone number and
fails closed: a missing key, a rate limit or any exception falls back to plain
keyword matching.
cp .env.example .env # fill in your own credentials
docker compose up -d --build
The admin GUI is served on WEB_PORT. It has no authentication, so bind it
to a trusted network only. If you expose the service publicly (e.g. for the
WhatsApp webhook), restrict ingress to the webhook path alone.
Running in production. Currently operating in single pulse mode: each message
issues one pulse per gate. The scheduling service (schedule_utils.py,
gate_actions.py) is present but inactive pending a firmware revision on the
receiver side.
Runtime data (the member database and access logs) is deliberately excluded,
because it contains personal data of the complex's tenants. Credentials are
supplied through .env (service) and secrets.h (firmware), neither of which
is committed.
MIT, see LICENSE.
No comments yet. Be the first to ask about this board.