Skip to the content
2 layers59.7 × 48.3 mmRAK 3172 relay controll, the printed circuit board in 3D

A WhatsApp and Telegram service for the tenants of a business complex. It does two jobs:

Size
59.7 × 48.3 mm
Copper layers
2
Thickness
1.6 mm
Parts
23
Nets
38
Pads
77
Tracks, vias
86, 9
Pours
1
Routed
Yes
KiCad
KiCad 8.0 (file 20240108)
Created
6 Sep 2026
Updated
16 Sep 2026

Overview

RAK 3172 relay controll is an open-source printed circuit board by StanZalewski, from the StanZalewski/lorawan-tenant-assistant repository on GitHub, published under the MIT licence. It is a 2-layer board of 59.7 × 48.3 mm with 23 parts on 38 nets, routed with 86 tracks and 9 vias.

It is built around the IRM-01-3.3, RAK3172-SIP and DG126-5.0-02P-14-00A(H), with the FDN335N among its other parts. Its parts include 5 resistors, 3 capacitors, 3 connectors, 2 diodes and 2 transistors. It belongs with the home automation and IoT and radio and wireless boards and the STM32 boards of this library.

Main components

4

README

README.md

Gate Access & Tenant Support over LoRaWAN

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.

text
WhatsApp / Telegram
        │
        ▼
  FastAPI service  ──► SQLite (members, permissions, access log)
        │
        ▼  MQTT downlink
   ChirpStack v4  ──► LoRaWAN gateway ──► RAK3172 board (firmware/) ──► gate
        │
        ◄── ACK (~3 s) ─────────────────────────────────────────┘

Hardware

hardware/ contains a mains powered LoRaWAN relay controller built around the RAK3172 (STM32WLE5, LoRa SoC).

Assembled end device with STATUS and RELAY lit

FrontBack
PCB frontPCB back
RadioRAK3172 module, LoRaWAN Class C
PowerIRM-01-3.3 AC/DC module, runs directly from mains
SwitchingTE 1461103-1 SPST-NO relay (10 A max), 2× FDN335N N-channel MOSFETs
Indicators2× 0603 LEDs: STATUS and RELAY
I/O2× screw terminals (DG126-5.0), 4-pin programming header
Board2-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.

Enclosure

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.

  • STATUS lights once the board is powered and has joined the network (it blinks while joining).
  • RELAY lights while the relay contacts are closed.

Enclosure cross-section with the PCB and light guide

Files

  • hardware/kicad/: schematic, layout, 3D STEP model, custom footprints
  • hardware/fabrication/: Gerbers, Excellon drill files, drill maps
  • hardware/docs/: schematic PDF, board PDF, BOM

The board switches mains-adjacent loads and carries a high voltage warning on the silkscreen. Treat it accordingly.

Firmware

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.

Software

Python 3.12 · FastAPI · Jinja2 · paho-mqtt · SQLAlchemy · python-telegram-bot

text
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

Design notes

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.

Running it

bash
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.

Status

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.

Not in this repository

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.

License

MIT, see LICENSE.

Parts

23
QtyValueFootprintReferences
3MountingHoleMountingHole:MountingHole_3.2mm_M3_ISO7380H1, H2, H3
2220Resistor_SMD:R_0402_1005Metric_Pad0.72x0.64mm_HandSolderR2, R3
268Resistor_SMD:R_1206_3216Metric_Pad1.30x1.75mm_HandSolderR4, R5
2DG126-5.0-02P-14-00A(H)Connector:DG126-5.0J1, J2
2FDN335NPackage_TO_SOT_SMD:SuperSOT-3Q1, Q2
10u1Capacitor_SMD:C_0603_1608MetricC3
10u1Capacitor_SMD:C_0603_1608Metric_Pad1.08x0.95mm_HandSolderC1
110kResistor_SMD:R_0603_1608Metric_Pad0.98x0.95mm_HandSolderR1
110uCapacitor_SMD:C_0603_1608Metric_Pad1.08x0.95mm_HandSolderC2
119-21SURCLED_SMD:LED_0603_1608Metric_Pad1.05x0.95mm_HandSolderD2
1Conn_01x04_PinConnector:SMD_Pad 4x1J3
1IRM-01-3.3Converter_ACDC:IRM-01PS1
1LOGOGraphics:logoG***
1LOGOGraphics:high_voltage_dangerG***
1RAK3172RF_Module:RAK3172U1
1RF-AUB190TS-EDLED_SMD:LED_0603_1608Metric_Pad1.05x0.95mm_HandSolderD1
1Relay_SPST-NORelay_THT:Relay TE CONNECTIVITY 1461103-1K1

Similar boards

  • 2 layers116.3 × 102.2 mmRočníkový projekt S3E, the printed circuit board in 3D

    Ročníkový projekt S3E

    HexCatDev/Rocnikovy_projekt

    Po konzultaci s panem Máchou by bylo lepší Multiplexovat číslice 1:6 tzn. že v jednom okamžiku problikne jeden segment, takto se "probliká" každý segment zvlášť v určité rychlosti(Hz), od určité rychlosti ± 30 Hz se…

    77 parts
  • 2 layers94 × 78 mmGateway rev2, the printed circuit board in 3D

    Gateway rev2

    npeixoto64/ExitGuardian

    A full product project that watches windows with wireless sensors and has a gateway for the main door with wireless sensors. When you open the exit door to leave, it checks:

    68 parts1
  • 4 layers100 × 66.2 mmTop PCB, the printed circuit board in 3D

    Top PCB

    StanZalewski/Autonomous-remote-monitoring-system-based-on-the-LoRaWAN-protocol

    Solar-powered LoRaWAN weather station — 3 custom PCBs, bare-metal STM32, 4.3 km verified link

    57 parts
  • 4 layers59.8 × 41.1 mmSmartPowerBoard, the printed circuit board in 3D

    SmartPowerBoard

    murexrobotics/electrical

    Highly integrated electronics design and printed circuit boards (PCBs) for the MATE ROV Competition. Attempt the impossible.

    117 parts192MIT
  • 8 layers110 × 181.8 mmZest, the printed circuit board in 3D

    Zest

    BerkeleyLab/Zest

    Zest is a FMC mezzanine board with 8 ADC channels and 2 DACs

    441 parts12
  • 4 layers33.5 × 24 mmUSBPowerMeter, the printed circuit board in 3D

    USBPowerMeter

    JunKimmmy/USBPowerMeter

    A compact USB-C passthrough power meter that displays real-time voltage, current, and power on an integrated 128×64 OLED screen.

    84 parts8
  • 2 layers100 × 50 mmPower Supply, the printed circuit board in 3D

    Power Supply

    adsehgal/Bench_Power_Supply

    A design for a custom bench top power supply for prototyping.

    106 parts2
  • 6 layers84 × 69 mmClk input fmc, the printed circuit board in 3D

    Clk input fmc

    osprey-dcs/clk-input-fmc

    Clock Input FMC board design

    164 parts1

Questions

How big is the RAK 3172 relay controll PCB?

It measures 59.7 × 48.3 mm and has 2 copper layers, 1.6 mm thick.

What parts does the RAK 3172 relay controll use?

23 parts, built around the IRM-01-3.3, RAK3172-SIP, DG126-5.0-02P-14-00A(H) and FDN335N. The full list of its parts is on this page, with links to each part's symbol and footprint where PCBKit's library has them.

Where can I download the RAK 3172 relay controll KiCad files?

From the StanZalewski/lorawan-tenant-assistant repository on GitHub, at the commit this page was made from: the board is hardware/kicad/RAK_3172_relay_controll.kicad_pcb and its schematic hardware/kicad/RAK_3172_relay_controll.kicad_sch. PCBKit opens the board in the browser, with nothing to install.

Can I use the RAK 3172 relay controll design in my own project?

Its repository publishes it under the MIT licence: you may reuse it on that licence's terms (keep the author's notice, and for a copyleft licence share your changes alike).