Skip to content

Features

What the regulator does. Every claim here points at the firmware / hardware page that describes the implementation in detail.

Field Control & Charging Management

Control Modes

  • Auto (default): Cascaded current/voltage/temperature regulation through AdjustFieldLearnMode() running every fresh CH1 ADC sample (~4.7 ms). See Field Control.
  • Manual: User-set PWM duty cycle. Bypasses charging-stage logic but not all safeties — INA228 hardware OV, hard overcurrent, RPM gate, and T3 critical temperature still fire. See Safeties → Mode-by-Mode.
  • MaintainMode: Regulates Bcur (net battery current) to ≈ 0 A. CV loop runs at BulkVoltage but uTargetAmps = 0. Useful for parallel-source operation or pure house-load draw through the alternator.
  • TargetVoltageMode: CV loop holds a user-specified voltage with full current protection active.
  • Weather Mode: Disables charging when 3-day Open-Meteo solar forecast predicts ≥ 2 of the next 3 days will exceed UVThresholdHigh. See Advanced Features → Weather Mode.
  • Limp Home: 30 % fixed duty, all safeties bypassed except INA228 hardware ALERT. Emergency-only when sensors have failed.

Charging Stages

  • Bulk → Absorption → Float / Idle state machine with two-sided voltage hysteresis on bulk-to-absorption transition, tail-current exit from absorption (with thermal-constraint suppression so a hot alternator doesn't fake "battery full"), float duration timeout, multi-criteria re-bulk (voltage sag OR discharge-current threshold), and SOC-aware re-bulk gating. See Field Control → Charging-Stage State Machine.
  • 10-point RPM tables (current cap, power cap, minimum field duty) with linear interpolation. Separate "Normal" and "Low Charge Rate" tables stored in NVS.
  • BMS Integration: GPIO42 input gates chargingEnabled. Polarity configurable (bmsLogicLevelOff).

Sensor Systems & Monitoring

Measurements

  • Battery voltage — INA228 bus voltage (20-bit, primary), ADS1115 channel 0 (16-bit, cross-validation only). 1 MΩ / 49.9 kΩ divider on the ADS1115 side; direct VBUS on the INA228. See Hardware → INA228 and Hardware → Analog Inputs.
  • Battery current — INA228 low-side shunt measurement, ±163.84 mV differential, configurable shunt resistance (typ. 75–150 µΩ).
  • Alternator current — QNHCK1-21 Hall-effect clamp via ADS1115 channel 1. Configurable sensor range (200 / 300 / 500 A) via AmpSensorRange.
  • Alternator temperature — DS18B20 OneWire digital sensor on GPIO13, 12-bit (0.0625 °C), 5-checks-deep validation gauntlet. See Sensor Systems → DS18B20.
  • Thermistor backup — NTC via ADS1115 channel 3 with Steinhart-Hart conversion.
  • Engine RPM — LM2907 frequency-to-voltage converter from stator tap, into ADS1115 channel 2. See Hardware → LM2907 Resistor Mod.
  • Barometric pressure / ambient temp — BMP388 (I²C 0x76), 8-second forced-mode cycle.
  • IMU — LSM6DSOX 6-axis (accel + gyro), 104 Hz / 52 Hz FIFO, drives motion-comfort and tipping analytics.

Data Quality

  • Per-sensor freshness tracking — MARK_FRESH(IDX_*) on every validated read; IS_STALE(IDX_*) consults the per-source threshold. 35 DataIndex slots covering every sensor source and derived value.
  • Sanity bands — every read is bounded-checked (voltage, current, RPM, temperature, IMU) before being marked fresh.
  • Cross-validation — BatteryV (ADS) vs IBV (INA) disagreement triggers warning (VoltageDisagreeThreshold = 0.15 V) or critical (auto-scaled threshold by 12/24/48 V class) ramps.
  • Auto-disable — 5 consecutive I²C failures on the ADS1115, 10 IMU errors in any 60-second window, or DS18B20 enumeration failure each auto-disables the corresponding driver. Other subsystems continue.

Battery Management

  • Coulomb counting with floating-point accumulator and integer commits.
  • Peukert correction above C/100 discharge rate.
  • Charge efficiency factor (percent × 10 fixed-point, typically 85–99 %).
  • Full charge detection by |current| ≤ TailCurrent AND V ≥ ChargedVoltage continuously for ChargedDetectionTime. Works from any source (solar, shore, alternator).
  • Auto-zero alternator current every 1 hour or 20 °F temperature shift — briefly forces field off, captures Hall sensor offset.
  • Auto-gain correction — adjusts DynamicShuntGainFactor at each full-charge detection so calculated capacity matches BatteryCapacity_Ah.
  • Charge-time prediction — linear projection from current SoC and net current.
  • Energy accumulators — ChargedEnergy / DischargedEnergy / AlternatorChargedEnergy / SolarChargedEnergy, all with session + lifetime variants.
  • Fuel-consumption estimate — diesel L computed from electrical Wh assuming 30 % engine × 50 % alternator efficiency.

See Battery Management.

Communication & Integration

  • NMEA2000 (CAN) on GPIO16/17, 12 PGN handlers (heading, GPS, COG/SOG, wind, attitude, battery, time, etc.). See Communication Interfaces → NMEA2000.
  • Victron VE.Direct on Serial1 GPIO7, 19200 8N1 inverted. Reads V/I/PPV from connected Victron device, accumulates solar Wh.
  • NMEA0183 wired (Serial2 GPIO6, 19200 8N1) — parser scaffolding present, not currently active.
  • WiFi — three modes (CONFIG / AP / CLIENT) selected at boot by GPIO pin reads (GPIO45, GPIO46) or first-boot detection. mDNS publishes alternator.local. See Network & Web System.
  • Cloud (Supabase) — sensor-history upload (5-min cadence, 70 s field-off settle), config snapshot (40-min cadence), forced-OTA check at boot, version reporting.

Web Interface

  • One-page dashboard served gzipped from LittleFS. Six top-level tabs: Live Data, Settings, Tuning, Plots, Console, Cloud.
  • Real-time streaming via SSE — four channels (CSV1, CSV2, CSV3, TimestampData) with priority gating. CSV1 carries ~34 live values every webgaugesinterval (default 100 ms); CSV2 carries hundreds of slower values every 5 s; CSV3 is event-driven on settings changes; TS is staleness ages every 3 s. See JavaScript Logic.
  • uPlot interactive plots — Volts, Amps, Duty, PID terms, IMU motion, RPM, field-efficiency matrix.
  • Password-gated settings — bcrypt-equivalent SHA-256 with salt. All destructive endpoints (factory reset, account delete) require the password.
  • OTA updates — RSA-signed tar bundle (firmware + web files), streaming download with incremental SHA-256, partition-isolated A/B with automatic rollback. See Network & Web System → OTA.

Safety & Protection Systems

Comprehensive coverage detailed in Safeties and Protections. High-level inventory:

  • Voltage — Three overvoltage throttling groups (Group 1 predictive, Group 2 measured, Group 3 iExcess current supervisor), load-dump 3-tier rate-of-change detection, software absolute hard-shutdown, INA228 hardware ALERT (operates without firmware).
  • Voltage sensor failure — Disagreement warning, disagreement critical (auto-scaled by 12/24/48 V class), and implausibility (both sensors out of plausible range).
  • Temperature — Five-stage hierarchy: T0 thermal PID continuous derate, T1 warning ramp, T2 sustained-warning ramp + lockout, T3 critical immediate cut (active even in MANUAL), T4 TempTask hang heartbeat, T5 data-stale field cut.
  • Current — Hard overcurrent immediate cut (debounced); alternator current and battery current alarms (buzzer-only).
  • RPM gate — Immediate cut when engine not running.
  • Watchdog — 16-second hardware timeout on Core 1 with automatic reboot (GPIO LOW on reset cuts field).

Advanced Features

  • Alternator lifetime modeling — Arrhenius-based insulation aging, RPM-and-temperature-aware grease wear, RPM-and-temperature brush wear. Outputs InsulationLifePercent, GreaseLifePercent, BrushLifePercent, PredictedLifeHours, color-coded indicator.
  • Motion comfort metrics (IMU) — Heel / pitch / yaw rate, MSI score (Lawther & Griffin 1987), vomit-percentage estimate, anchorage comfort score, slam counter, capsize/pitch-pole lifetime counters (never resettable).
  • Field-efficiency tracker — 8 RPM × 7 temperature × 7 field-volts bins (392 cells); accumulates steady-state seconds; auto-selects reference bins; anomaly-scores live operation against the references.
  • Plant-delay characterization (System ID) — User-triggered step-test that measures dead time, rise time, and slope for inner-PID tuning.
  • Online tuning scoring — Square-wave injection systems for inner current PID, outer voltage CV PID, and temperature PID. Persistent score log with 50 records per system.
  • Sensor history — Local PSRAM ring holds ~83 hours of 5-minute snapshots; cloud upload when field-off settled; LittleFS backup on shutdown for power-loss survival.

Hardware Specifications

  • Input voltage: 4.2 V – 65 V (12 / 24 / 48 V systems) via TPS48000-Q1 protection.
  • Field current: up to 15 A continuous, PWM ~ 1.2 kHz.
  • Current measurement: ±163.84 mV at INA228 differential — supports up to 500 A with appropriate shunt.
  • MCU: ESP32-S3 WROOM-1 @ 240 MHz, 16 MB flash, 8 MB PSRAM.
  • Operating temperature: −40 °C to +85 °C.
  • Mounting: 4-layer PCB suitable for marine-grade conformal coating.

See Hardware → System Architecture.

Recovery and Maintenance

  • GPIO45 LOW at boot — forced configuration mode, default AP credentials, alternator disabled (safety).
  • GPIO46 LOW at boot — operational AP mode, custom AP credentials, full alternator functionality. Used when ship WiFi is down.
  • GPIO41 LOW at boot — boot from factory partition (bypasses any bad OTA).
  • Password-gated factory reset via dashboard — reformats LittleFS and erases NVS.
  • Scheduled maintenance restart every 12 hours (RESTART_INTERVAL) — long-term memory-fragmentation hedge. Holds the restart up to 30 s for any in-flight upload to complete.

Open Source