Simut PCB

SIMUT — Sistema Integrado de Monitoramento Universal e Telemetria

In English, Integrated Universal Monitoring and Telemetry System. The name is Portuguese, and so is the acronym: it is not translated.

Offline-first monitoring and telemetry for the Raspberry Pi Pico W and Pico 2 W, on sixteen universal sensor slots

English | Português | Español

Overview

SIMUT is monitoring and telemetry firmware for the Raspberry Pi Pico W and the Pico 2 W. It reads up to 16 sensors on universal slots — temperature, humidity and pressure today, through its DS18B20, DHT22 and BMP280/BME280 drivers — records them on the device, raises alarms, and keeps working with or without a network. One source tree builds three published devices:

• a touch-panel monitor (320×240 TFT);
• a character-LCD monitor (16×2, the alpha);
• a battery logger that hibernates between readings (the Air, experimental).

They share one core:

• binary on-device history and per-channel alarms;
• 32 user accounts with 13 permission bits;
• an embedded web interface;
• telemetry over HTTP(S) or MQTT(S), with a separate line for alarms;
• Home Assistant MQTT Discovery, a Prometheus /metrics endpoint and remote syslog (RFC 5424);
• over-the-air updates and a serial console.

Universal is the direction, not a feature. A slot has no fixed quantity: a sensor type is a driver under src/sensors/ and an entry in the type table, a new quantity is a row in the channel table (four of the eight it has room for are used), and the dashboard, the history, the alarms, the calibration and the telemetry read the driver's metadata instead of special-casing a part (adding a sensor). Three drivers ship today, and the table already has a row for luminosity that none of them fills. The project's direction is more drivers, contributed one at a time, and slots that actuate — relays, valves, signals — as well as read. No image drives an output yet: an alarm is a sound, a screen and a message to your server.

Project status

Known limitations. Each one is documented where it applies.

• Updates. On the Pico W, an update over the air reformats the filesystem:
  • Wi-Fi, accounts and sensor slots are carried across. History, calibration files and language packs are not, so the web page downloads a backup before it starts, and restoring it brings them back.
  • On the Pico W there is one firmware slot and no rollback. A bad flash is recovered with BOOTSEL and a USB cable. The Pico 2 W has two slots: an update goes into the other slot, leaves the filesystem alone and boots on trial, and the image it replaced comes back by itself if the new one does not keep itself (What an update destroys, Rollback).
  • Since v2.9.0, only an image the project signed installs over the air: a release .bin, or a build from the configurator. A build of your own goes over USB.
• Unexplained resets. A watchdog reset (ctx=209 or ctx=455) appeared three times on the test image on 20–21 September and not since; the one caught with its context had Core 0 in the console (ctx=209). Both cores are now instrumented to explain the next one. A ctx=455 (empty trace) on the first boot after picotool load -x is not this: that reboot goes through the watchdog, and the record appeared after 11 of 11 such flashes and after none of 7 hardware resets (2026-09-30).
• Idle connections. During the v2.7.0 soak, 7.1 % of responses on an idle keep-alive connection arrived cut short. The device drops a stream it cannot send for 4 s.
• Chunked replies. Read in a tight loop, 0.15–0.6 % of /api/status replies arrive with their chunked framing broken (#189). The device does not restart and the next request works; the page misses one update.
• Not a certified instrument. SIMUT is not a certified metrological instrument. Validate it against your own reference before relying on it for regulated storage.

Why SIMUT?

SIMUT is for you if: you need a standalone, secure, auditable monitoring system that works with or without internet — today typical in laboratories, pharmacies, blood banks, vaccine storage and food cold chains, and wherever a sensor with a driver needs a screen, a history and an alarm.

ESPHome/Tasmota may be better if: you don't need a local display and prefer YAML configuration over a built-in web UI. (If what kept you there was Home Assistant: SIMUT speaks MQTT Discovery.)

Architecture

Core 0 runs everything but the display, in one cooperative loop, and is the only core that writes the flash; Core 1 runs only the display, the touch panel or the LCD. The rules between the two are in docs/CONCURRENCY.md. The figure is drawn from the source by tools/readme_diagram.py, and CI checks that it still matches the code.

Screenshots

TFT dashboard (Pico W)	TFT history graph (Pico W)	Web dashboard	Early alpha

Every screen of the Pico W's original panel, captured off the real panel framebuffer: docs/images/screens/screens.md.

The early alpha video shows the first TFT + touch prototype — the UI has been redesigned since.

Hardware

See the wiring guide for the complete pinout and connection diagrams.

SIMUT PCB — layout available for download — the KiCad board design (.kicad_pcb, .kicad_sch) lives in PCB_test/, and the ready-to-fab package (Gerbers + PTH/NPTH drills, no paste layers) is published as a public release: simut-pcb-v1.1 — simut_pcb_fabrication.zip.

Features

• Sensing and alarms — 16 universal sensor slots assigned at runtime, three drivers today (DS18B20, DHT22, BMP280/BME280) in a channel table open to more, calibration curves, per-channel limits, a fault alarm and maintenance windows.
• Touch panel (release) — dashboard, history graphs and calendar, and identity at the glass: an account, then its PIN. The Pico 2 W release draws it in the Ângulo look; the Pico W release keeps the original panel. v2.12.0 and earlier drew the original panel on the Pico 2 W.
• Character LCD (alpha) — every slot in turn, the setup access point and a Bluetooth console; since v2.14.0 the web dashboard draws the glass itself, captured once or live (GET /api/lcd).
• Web interface — 11 pages, a live panel mirror, history graphs and CSV export in the browser.
• HTTP API — 63 routes. Each one is either gated by a permission or public by design, and CI checks it. The images with the Ângulo panel add GET /api/ui, gated.
• Telemetry — HTTP, HTTPS, MQTT and MQTTS, batched by quantity, and a second, acknowledged line for alarms; Home Assistant, Prometheus and syslog.
• Network and time — Wi-Fi that reconnects itself, a setup access point opened on request, and NTP with a provisional clock until it syncs.
• Storage — the V5 binary history (about 116 days in 1 MB), a configuration with CRC32 and a .bak, and an event log with 170 event codes.
• Security — 32 accounts, 13 permission bits, salted HMAC-SHA256, lockouts and optional HTTPS.
• Updates — signed over-the-air updates from the web page, and backup and restore of the whole filesystem.
• SIMUT Air (experimental) — a battery logger that hibernates between readings.
• Languages — English built in; pt-BR and es-ES as language packs.

Every feature in detail, and which ones a custom build can leave out: docs/FEATURES.md.

Quick start

Prerequisites

• PlatformIO (Core 6.x or later)
• pip install zopfli — optional; the web pages compress 2,888 B smaller with it, and the flash budgets are measured with it
• Raspberry Pi Pico W
• No local toolchain? docker compose run build builds in a container — the path CONTRIBUTING.md recommends for new contributors

Build and flash

# Clone the repository
git clone https://github.com/angeloINTJ/simut.git
cd simut

# Build firmware
pio run -e pico_w_release

# Flash to Pico W (auto-reset via 1200 bps touch; BOOTSEL works too)
pio run -e pico_w_release -t upload

# First flash only: upload LittleFS data (language packs, themes, favicon).
# Warning: uploadfs reformats the LittleFS partition — on a device already in
# service it destroys history, config and calibration. Never run it again
# after the device has data; language packs can be uploaded later from the
# web file manager instead. It copies both language packs, and the device
# loads the first alphabetically (es-ES): delete the one you do not want.
pio run -e pico_w_release -t uploadfs

Prefer not to build? Every release ships simut_vX.Y.Z_release.uf2, _alpha.uf2 and _air.uf2 for the Pico W and, since v2.11.0, _releasetwo.uf2 for the Pico 2 W (drag-and-drop with BOOTSEL held), the matching .bin for over-the-air updates, and the pt-BR and es-ES language packs. An image with a different set of features comes from the build configurator.

First boot

1. Capture the admin password. A factory-fresh unit prints a random 8-character admin password once on the USB serial console (115200 baud). It is never stored in plain text. If you miss it, system admin reset confirm over USB prints a new one.

2. Join it to your network. The setup access point opens when you ask for it: type ap on the console (on the Air, after enable), or use Settings → 8 on the touch panel. From v2.7.1 to v2.8.0, a unit with no network configured opened it by itself; it no longer does.

   • Join <name>_SETUP (simut_SETUP from the factory). It is WPA2, and its per-device key is in the reply to ap, on the USB console and on the TFT's boot terminal.
   • The portal opens at http://192.168.4.1.
   • The device keeps measuring while the access point is up; only telemetry and syslog wait for the network. v2.7.1 to v2.8.0 read no sensors, checked no alarms and recorded no history while it was up.

   Without a screen, you can use the console instead: system ssid <name>, system pass <secret>, then reload confirm. The console stops at the first space, so a network name or password with a space has to go through the web page.

   With no network configured, the unit asks for the date and time at the end of the boot, because without a network there is no NTP: the touch panel opens a date-and-time screen (SKIP leaves it, and Settings → 4 sets the clock later), and every image prints No network, provisional clock: conf time YYYY-MM-DD HH:MM:SS on the console. That command works on every image's console, over USB or Bluetooth: on the alpha and the Air, which have no panel, it is how the question is answered. The web page's Date & Time section sets the clock too.

3. Open the web interface at the address the device got — on the release image also http://simut.local — and log in as admin with the password from step 1. You will be asked to choose a new one.

4. Add sensors in Config → Sensors & GPIO, or let Scan for probes find them.

5. On the touch panel, Settings asks for an account and its PIN. The factory admin PIN is 1234, and it must be changed on first use.

Project structure

simut/
├── src/                    # Firmware source (C++17)
│   ├── main.cpp            # Entry point
│   ├── AppManager*         # Application state machine, boot, alarms, Air cycle
│   ├── DisplayManager*     # TFT panel and alpha LCD (Core 1), touch, themes
│   ├── WebManager*         # Web server, HTTP API, sessions, OTA, TLS
│   ├── StorageManager*     # LittleFS, config, accounts, history files
│   ├── SensorManager*      # The sensor host: driver registry, read loop, error hysteresis
│   ├── NetworkManager*     # Wi-Fi, reconnect ladder, setup AP, mDNS, NTP
│   ├── TelemetryManager*   # HTTP(S)/MQTT(S) telemetry and the alarm line
│   ├── CommandManager*     # Serial and Bluetooth console
│   ├── LogManager*         # Event log and crash forensics
│   ├── HistoryV5.*         # V5 history codec
│   ├── air/                # SIMUT Air configuration
│   ├── display/            # Keypads, fonts and labels shared by the displays
│   ├── net/                # The network as a driver: CYW43 Wi-Fi, ENC28J60 (the Wire)
│   ├── sensors/            # Sensor drivers (DS18B20, DHT22, BMx280), channel table, calibration curves
│   ├── ota/                # Update staging, validation and applier
│   ├── ui/                 # The panel's UI drivers: original and Ângulo
│   └── SystemDefs*.h       # System constants and limits
├── data/                   # LittleFS assets (language packs, themes, favicon)
├── PCB_test/               # KiCad PCB design + Gerber/DRL fabrication files
├── test/                   # Native unit tests (Unity), eleven suites
├── tools/                  # Build gates, bench suites, PicoHand, release scripts, theme editor

Building

Environments

Security note for pico_w_alpha and pico_w_air: both compile the Bluetooth SPP console in (SIMUT_BLUETOOTH=1), so on those two images it is live attack surface. It is authenticated by the admin web password, with an exponential lockout that survives a reconnect, and a discovery window that closes 5 minutes after boot. Recovery commands are restricted to USB.

The setup access point is WPA2 on every image, with a per-device key shown on the console and, where there is one, on the display. See SECURITY.md §2 and §8.

There is no debug environment. pico_w_debug was removed in v2.4.1 after never once linking: at -Og the image overflowed the 1020 KB app slot by ~100 KB. Flash is tight. The release image uses 98.2 % of the 1,044,480 B program slot (tools/flash_budget.json keeps the measured value), and CI checks every .bin, with its 241 B signature, against the 1,040,384 B over-the-air ceiling. A GDB target would have to be built by cutting features. For the concurrency tripwire on hardware, use pico_w_asserts.

Build flags

• -Os — optimize for size
• -Wall -Wextra, and -Werror on src/ (third-party libraries are not held to it)
• -specs=nano.specs — newlib-nano for smaller binary
• -DNDEBUG on every image
• LTO is disabled (toolchain limitation with earlephilhower Arduino-Pico)
• The framework is pinned to arduino-pico 5.6.1 and patched by tools/arduino_pico_overrides/patch.sh

Configuration

Console (CLI)

A serial console is available over USB (115200 baud), and over Bluetooth SPP on the alpha and the Air.

• The emergency console runs on the release and alpha images. Its 15 commands:

  • show net status, show system info, show system log
  • debug on|off
  • system admin reset, system format, system factory, system https off
  • system ssid <name>, system pass <secret>, system cors <origin|off>
  • ap, time <date> <time>, reload, help

  Destructive commands ask for confirm, and the four recoveries (system factory, system format, system admin reset, system https off) are refused over Bluetooth.

• The full Cisco-style console (enable / configure terminal) runs on the air image and the pico_w_test bench images — see the CLI manual (in Portuguese). The Air adds air status | hibernate | stop | idle <sec> | charger <gpio|off>.

Where configuration happens:

• The web interface is the day-to-day tool.
• The touch panel covers what an operator needs at the device: themes, alarms, sounds, language, their own PIN, users, the PIN policy, touch calibration, display offset, status, the setup access point and the date and time.

Web API

The device exposes a REST API at http://<device-ip>/api/:

• 63 routes — 53 gated by a permission, 10 public by design, 0 ungated, checked by tools/check_authz.py in CI;
• the images with the Ângulo panel also serve GET /api/ui, gated by PERM_SYS_CONFIG and counted apart, outside the 62;
• the route table is in the user manual;
• docs/AUTHORIZATION.md maps each route to its permission;
• docs/API_POST.md documents the POST bodies.

Testing

Host tests

pio test -e native             # validators, telemetry cursor, labels, parsers, language packs, the License and update screens, the Settings menu, the password check, the web session, the alpha LCD's screens and the shadow of its glass (450 cases)
pio test -e native_history_v5  # V5 history codec (62)
pio test -e native_cli         # CLI parser (43)
pio test -e native_lan         # CLI parser, pack help, Settings menu, log codes and the alpha LCD's cable cells of a wired build (19)
pio test -e native_logpolicy   # edge-triggered log persistence, autopsy bands, touch wake (59)
pio test -e native_alarmqueue  # alarm telemetry queue (54)
pio test -e native_network     # Wi-Fi reconnect state machine (54)
pio test -e native_wired       # wired network state machine, against a fake ENC28J60 (19)
pio test -e native_air         # SIMUT Air persistent config (17)
pio test -e native_sensors     # sensor type table, scan JSON, the real BMx280 scan (23)
pio test -e native_otasig      # OTA image signature check, the backup restore, and the RP2350's slot writer and update on trial (83)

# V5 codec reference checks (Python vs C++, 20k random cases)
python3 tools/check_history_v5_parity.py --cases 20000
python3 tools/history_v5.py --selftest --trials 200000

Continuous integration

Every push and pull request to main runs four jobs:

• gates — the host suites plus these checks:
  • secret scan, log-code tables, authorization matrix;
  • licence consistency, filesystem guard, Air consistency;
  • history day-merge tests.
• firmware — all eleven images, built from a cold cache:
  • each is checked against its flash budget and the over-the-air ceiling;
  • the build itself enforces -Werror and the web UI, CLI help, log-code, channel-table and language-pack gates.
• fuzz — 60 s of libFuzzer against the web-API validators, with contract oracles.
• static analysis — cppcheck, at a pinned version.

main is protected: nine of these checks must pass before anything merges, every job except the pico_w_test_https, pico_wire, pico_wiretft, pico_wiretft_angulo and pico2_w_original images.

Verification on hardware

Behaviour is checked on a bench: a Pico 2 W with the TFT panel and touch, and a Pico W, the PicoHand, that works the target's RESET and BOOTSEL lines. Every measurement, dated, with its numbers: docs/VERIFICATION.md.

Documentation

How SIMUT is developed

Most changes are written by an AI coding agent (Claude Code) in sessions the maintainer directs: from 1 September to 2 October 2026, 275 of the 371 commits on main carried a Co-Authored-By: Claude line. The instructions those sessions follow are CLAUDE.md and AGENTS.md (in Portuguese). The rules are the same for every change, whoever typed it:

• it reaches main only through a pull request, after nine required checks pass: the eleven host test suites, also under AddressSanitizer and UBSan, 60 s of fuzzing, static analysis, and six of the eleven firmware images built from a cold cache;
• the tests come first: a fix carries a reproduction that fails before it and passes after, and a refactor shows that the behaviour did not change;
• a claim about bytes, speed or a fix carries its measurement, and what was not checked on hardware says so;
• product decisions, and the decision to merge, are the maintainer's.

Contributing

Contributions are welcome. Read CONTRIBUTING.md for the development setup, the code conventions and the pull request process.

All contributors must follow the Code of Conduct.

Support

• Bug reports: GitHub Issues
• Feature requests: GitHub Issues
• Security vulnerabilities: See SECURITY.md — do not open a public issue
• Questions: Open a discussion or issue

Contributors

Thanks to everyone who has contributed:

Ângelo Moisés Alves 💻 📖 🎨 🔌 🛡️ 🚧

Lorenzo Longaretto 🧪 💻

John Martin 🚇 💻

f p 📖

Mike 💻 🧪 📖

This project follows the all-contributors specification.

Powered by SIMUT

Is your product or project using SIMUT? Add this badge to your README, documentation, or product page:

[![Powered by SIMUT](docs/images/powered-by-simut.svg)](https://github.com/angeloINTJ/simut)

Large version (for presentations, posters, or product packaging):

[![Powered by SIMUT](docs/images/powered-by-simut-large.svg)](https://github.com/angeloINTJ/simut)

License

MIT License — see LICENSE for details.

The firmware images also carry third-party software. THIRD_PARTY_NOTICES.md names each component, its copyright holder, its licence and the images that carry it, and LICENSES/ holds the licence texts. The device shows the same list on its License screen and on the /license page.

Copyright © 2026 Ângelo Moisés Alves