Skip to content

Software Overview

The Xengineering Regulator firmware runs on an ESP32-S3 (16 MB flash, 8 MB PSRAM) and serves a browser-based dashboard over WiFi. The codebase is split between firmware (Arduino C++ across eight .ino files) and the client (HTML, CSS, JavaScript served from LittleFS).

This section documents:

ESP32 firmware

  • System Overview — Hardware target, partition map, task layout, control-tick scheduling, mode/state machines
  • Sensor Systems — ADS1115, INA228, DS18B20, BMP388, LSM6DSOX drivers and data validation
  • Communication Interfaces — NMEA2000, Victron VE.Direct, NMEA0183, I²C bus configuration
  • Field Control — Three nested PID loops, charging stages, anti-windup, governor, override modes
  • Field Bucketer — RPM × temp × field-volts efficiency tracking and anomaly detection
  • Important Functions — Plumbing recipes for CSV streams, timed functions, freshness tracking
  • Main Code — File-by-file map of what lives where
  • Battery Management — Coulomb counting, Peukert correction, full-charge detection, auto-cal
  • Network & Web System — WiFi mode selection, web server endpoints, SSE dispatch, HTTPS task, OTA pipeline
  • Safeties & Protections — Eight overvoltage groups, voltage-sensor failure detection, T0–T5 temperature handling, overcurrent, RPM gate, watchdog
  • Advanced Features — Weather mode, alternator lifetime modeling, IMU comfort metrics, sensor history, System ID step test, tuning scoring
  • Configuration — Build / flash / deploy, storage layers, recovery modes, backtrace decoding
  • Non-Important Functions — Utility helpers (LittleFS, password, mDNS, message queue, math primitives)

Client (browser dashboard)

  • HTML Structure — Single-page layout, tab system, form patterns, header/status bar
  • JavaScript Logic — SSE streams, CSV parsing, plot management, echo system, reconnect logic
  • CSS Styling — Component classes, dark mode, responsive breakpoints, iOS safe-area handling

Reading Order Recommendations

If you're new to the project: start with System Overview and read down the ESP32 list. The order above progresses from foundational to specialized.

If you're touching a specific subsystem, the cross-reference links at the bottom of each page point at related pages without you having to read everything.

If you're adding a new tunable parameter or a new live-data field, read Important Functions first — it has the canonical recipe.

If you're tracing a bug or unexpected behavior, Main Code tells you which file to grep.

Source

The firmware source is at github.com/markliquid1/Regulator2026-public. The website source (this site) is at github.com/markliquid1/xengineering-site.