Host Monitor

00Overview

Host Monitor is an Arduino IDE project that turns a Waveshare ESP32-S3 touch display into a standalone uptime monitor. It loads a host list from hosts.csv in on-board flash (LittleFS), runs six checks against each host on independent schedules, and reports fleet status three ways: on the LCD, over an embedded web dashboard, and through alert delivery.

01Hardware

• Waveshare ESP32-S3-Touch-LCD-4.3 — ESP32-S3, 8 MB OPI PSRAM, 8 MB flash (some revisions ship 16 MB — match Flash Size + partitions to your chip)
• No microSD card and no RTC battery needed — the host list and dashboard both live in on-board flash

The board library owns the I2C bus and brings up the expander → RGB bus → GT911 touch automatically once you select the Waveshare board in its config (covered in Installation).

02Installation

This is an Arduino IDE project. Set up the board package, libraries, and Tools-menu settings in order.

1. Install the ESP32 board package (pinned)

   Add the boards-manager URL, then install esp32 by Espressif → version 3.3.8 — the version this code is built against (it relies on the IDF v5 / core 3.x APIs).

   Preferences → Additional boards manager URLsCopy

   https://espressif.github.io/arduino-esp32/package_esp32_index.json

2. Install libraries

   From Library Manager unless noted. Versions matter — LVGL v9 and on-board TLS won't work against this code.

   Library	Version	Notes
   lvgl	8.4.x	Graphics engine. v9 will not compile.
   ESP32_Display_Panel	1.0.4	Drives the CH422G expander + RGB bus + GT911 touch.
   ESP32_IO_Expander	1.1.1	Dependency of ESP32_Display_Panel.
   esp-lib-utils	0.3.0	Dependency of the panel stack.
   ESP32_IDF5_HTTPS_Server	1.1.1	Used for its HTTP server + Basic Auth only (IDF5 fork of fhessel's server). Its TLS classes are not used — on-device HTTPS isn't viable here.
   ArduinoJson	7.4.x	JSON API (code still uses the DynamicJsonDocument alias).

   LittleFS, WiFi, HTTPClient, WiFiClientSecure, ESPmDNS, Preferences, the esp_ping/lwIP stack and mbedTLS ship with the ESP32 core. (mbedTLS is pulled in by WiFiClientSecure for the SSL check, HTTPS host checks and webhooks — all unverified.)

   i

   ESP Mail Client is no longer required. SMTP / email alerting was removed (its TLS footprint exceeded this board's free internal RAM) — webhook is the only delivery channel now, so you can uninstall it.

3. Place lv_conf.h

   Copy lv_conf.h from the sketch folder into your Arduino libraries/ folder — it must sit next to the lvgl folder. This build sets LV_MEM_CUSTOM=1 and allocates the LVGL pool in PSRAM, which frees internal RAM for Wi-Fi and the checks — don't skip it.

   ~/Arduino/libraries/lv_conf.hCopy

   …/Arduino/libraries/lv_conf.h   # next to the lvgl/ folder

4. Select the Waveshare board in ESP32_Display_Panel

   This is the single most important step. Place a file named esp_panel_board_supported_conf.h at your Arduino libraries/ root (next to lv_conf.h) — the library finds it via __has_include("../../../…"), so it must live there, not inside the library folder. Without the board selected, Board::init() fails and the screen stays black (backlight on).

   ~/Arduino/libraries/esp_panel_board_supported_conf.hCopy

   #define ESP_PANEL_BOARD_DEFAULT_USE_SUPPORTED   (1)
   #define BOARD_WAVESHARE_ESP32_S3_TOUCH_LCD_4_3

5. Arduino IDE board settings (Tools menu)

   PSRAM must be OPI PSRAM. The app build is large (LVGL + HTTP server + mbedTLS + ESP Mail Client + Display Panel), so use the bundled custom partition table — a default scheme won't fit.

   Board	ESP32S3 Dev Module
   PSRAM	OPI PSRAM — mandatory
   Flash Size	8MB (64Mb) — or 16MB if your board has it
   Partition Scheme	Custom → bundled partitions.csv (5 MB app / ~2.9 MB LittleFS / coredump)
   Upload Speed	921600
   USB CDC On Boot	Enabled (serial log; unreliable once RGB + Wi-Fi are live — the LCD surfaces diagnostics)

03Dashboard assets

There is no separate filesystem upload. The data/ folder (HTML / CSS / JS + setup.html) is gzip-compressed into web_assets.h and compiled straight into the binary, then served by the API's default route. Flashing the sketch ships the dashboard with it.

1. Edit the dashboard (optional)

   Change the files under data/, then regenerate web_assets.h from them so the embedded copy matches.

2. Upload the sketch

   Sketch → Upload. That's it — the dashboard travels inside the firmware image. No LittleFS data-upload tool required.

3. (Optional) seed a host list

   Fresh flash starts with no hosts — add them in the dashboard, or pre-seed by writing a hosts.csv to LittleFS. Either way it's persisted to and reloaded from flash.

04First run

Get the device onto your Wi-Fi one of two ways. Method 1 bakes the network name and password into the firmware for a fixed deployment; Method 2 is the interactive AP wizard. Either way you finish at the same place — open the dashboard.

Method 1 — hardcode the Wi-Fi name & password in config.h

For a fixed deployment, set the SSID and password in config.h before flashing and skip the wizard entirely. If WIFI_SSID_BUILTIN is non-empty the device joins that network on every boot and ignores saved / AP credentials.

#define WIFI_SSID_BUILTIN  "my-ssid"
#define WIFI_PASS_BUILTIN  "my-pass"   // leave both "" for the AP wizard

Method 2 — AP setup wizard

1. Join the AP

   With no saved Wi-Fi, the device raises an open access point named HostMon. Join it from a phone, then browse manually to http://192.168.4.1 — there's no captive-portal auto-popup, so open the address by hand.

2. Choose a network

   Pick your network and enter the password — the device saves them and reboots onto your LAN. There's no “stay an access point” mode; AP mode is only the no-credentials fallback.

Open the dashboard

Once the device is on your LAN, browse to http://monitor.local/ (or http://<ip>/, shown on the LCD). It's HTTP only — read the auto-generated login off the screen (see below).

Transport & TLS

The dashboard + API serve over plain HTTP only. On-device HTTPS was removed — it isn't viable on this board: an mbedTLS connection needs ~16–32 KB of contiguous internal RAM, which the device can't reliably spare alongside Wi-Fi + the check engine + the web server. With it enabled the TLS listener came up but handshakes reset (ERR_CONNECTION_RESET) regardless of cert type, so the TLS server, cert provisioning, and embedded cert/key were all deleted.

Login — auto-generated password

On first boot the device generates a random per-device web password (12 chars, unambiguous alphabet) and shows it on the LCD Alerts·Setup card as Web login: admin / …. There is no shared default password — read it off the screen to log in, then set your own in Settings (8–39 chars); the LCD line disappears once you do.

Timekeeping

Time comes from NTP once the network is up. Offline, or before NTP completes, the device falls back to an uptime-based runtime clock. The active source is reported as device.time (ntp / runtime) in GET /api/summary.

05Security

This is a LAN appliance, not an internet-facing service. Every data endpoint is gated by auth and every write is validated server-side, but it deliberately stops short of protections the hardware can't support (on-device TLS). The web-layer checks live in api.cpp / validate.cpp and run on every request.

06hosts.csv format

A header row is required, then one host per line. Every row is validated on load — malformed rows are skipped and logged over serial. Edits made in the dashboard are written back to this file in flash. New hosts default to ping only (enable other checks per host in the dashboard).

name,address,group,checks,intervals,alerts
nas-01,192.168.1.10,Storage,ping|dns|port|http,,down|recovered
pihole,192.168.1.12,Network,ping|dns|port|http,http:30,down|warn|recovered
home-asst,192.168.1.20,Apps,ping|dns|port|https,ping:10|port:10,down|warn|recovered
example-blog,example.com,External,ping|dns|port|https|ssl|trace,ping:60,down|warn|recovered

07The six checks

Each host enables any subset of these. Every check runs on its own interval and reports its own state — the host's overall status is the worst of its active checks. The engine runs on a statically-allocated task pinned to core 0, away from the LVGL display loop on core 1.

08Web / JSON API

Everything is served over plain HTTP behind Basic Auth. Cross-origin POSTs are blocked, and every POST body is validated server-side; invalid input returns 400 {ok:false, error:"…"}.

Read

Host governance & editing

Settings & system

09Source layout

10Limitations

Capabilities that were attempted and then removed (or never shipped) because of hardware or platform constraints on this board. Recorded here so the gaps — and why they exist — are explicit.

On-device TLS — one insecure session, no verification

An mbedTLS session needs ~16–44 KB of contiguous internal RAM. After MAX_HOSTS was reduced (and the old cert / HTTPS-server cruft removed) to reclaim RAM, the board now runs one insecure session at a time — confirmed by a boot self-test reporting ~23 KB still free at the session's peak. That re-enabled the cert-expiry check plus insecure HTTPS checks / webhooks, serialised by the TLS gate — which also enforces a pre-session heap floor (≥20 KB contiguous & ≥48 KB total free internal), skipping a session as low mem if RAM is too tight rather than faulting. What still doesn't fit is multiple concurrent sessions or verified TLS (CA-bundle chain validation).

• HTTPS for the dashboard — removed; a page load opens several concurrent TLS sessions, which don't fit. TLS server, cert provisioning and embedded cert/key all deleted; the dashboard is plain HTTP only.
• Self-signed cert + trust-on-first-use — wired up as a lighter alternative, then abandoned; handshakes reset regardless of cert type (tested RSA and ECDSA).
• SSL/TLS certificate-expiry check — removed in 1.4.3, restored (insecure) in 1.4.8 once the self-test confirmed a single session fits. Reads the cert notAfter; does not validate the chain.
• HTTPS host-check “verify” option — removed; HTTPS host checks are insecure-only (reachability + status, not cert trust).
• Email / SMTP alerting (ESP Mail Client) — removed in 1.4.9. It was the heaviest TLS user; dropping it raises the worst-case internal-RAM floor. Webhook is the only delivery channel now — route it to a relay if you need email.
• Notifier outbound TLS verification — removed; HTTPS webhooks are encrypted but the server identity is not checked.
• Verified HTTPS via setCACertBundle() — abandoned earlier: the core CA bundle couldn't be referenced by symbol on this core (undefined reference _binary_…_crt_bundle_bin).

Hardware / driver conflicts

• On-board PCF85063 RTC — disabled. The build stays Wire-free to avoid the legacy/driver_ng I²C clash, so there's no wall clock across a power-cycle until NTP re-syncs.
• SD-card storage — dropped. SD chip-select falls back to GPIO10, an active RGB data line (DATA4); mounting SD while the panel runs corrupts the parallel bus. Persistence uses LittleFS instead.
• Captive-portal auto-redirect — dropped. The bundled DNSServer calls udp_new() without the lwIP core lock and asserts under core-locking. The AP still works — browse to its IP manually.
• Reliable runtime USB-serial logging — given up as the primary diagnostic channel; serial is unreliable once RGB + Wi-Fi are both live, so diagnostics surface on the LCD Alerts·Setup card.

Tried & reverted (memory pressure)

• Internal-RAM LVGL draw buffers — attempted to fix the green RGB flicker, but consumed enough internal heap that the check task failed to create. Reverted to PSRAM draw buffers; the flicker was fixed instead with conditional markDirty.

Accepted platform pins

• LVGL stays on v8.4 — v9 won't compile against this code.
• A custom partitions.csv is mandatory — the app won't fit a default partition scheme.
• The build must stay Wire-free — see the RTC note above.