Skip to content

v0.2.0 — Hardware Safety Release

Latest
Latest

Choose a tag to compare

View all tags
@rjsears rjsears released this 17 May 02:34
v0.2.0
5293f3a

v0.2.0 — Hardware Safety Release

This release adds operator-side and generator-side hardware switches for physical safety and everyday mode control, plus a substantial round of UI, notification, and documentation improvements.

The two optional switches (an Emergency Power Off button at the generator and a Hand-Off-Auto selector at the operator location) are the headline change. The system still runs fine without either — existing v0.1.0 deployments behave identically until the switches are wired in — but together they give you the kind of hardware-enforced safety and operator-side mode control you'd expect from a production-grade generator setup. The full operator guide is at docs/manual/hardware-switches.md.

This is still a 0.x release, so expect refinements between minor versions.

What's in this release

  • GenSlave EPO (Emergency Power Off) — Schneider XB4 mushroom E-stop at the generator. The NC contact physically opens the start-relay circuit, and a second NO contact signals GenSlave so the web UI banner, the GenSlave LCD ("EPO SAFETY ON"), and the start-blocked notifications all stay in sync. Hardware enforcement is the actual safety guarantee; software is just for state consistency.
  • GenMaster HOA selector — Schneider XB4 3-position rotary at the operator location. Quiet suppresses automatic runs, Auto is normal operation, Run is a held manual start. Read at GenMaster GPIO22 and GPIO27 with a configurable boot delay.
  • Quiet web override — temporarily bypass HOA Quiet for one Victron event without turning the knob. Survives a GenMaster restart and auto-clears when the timer expires, on operator cancel, or when the selector leaves Quiet.
  • System → Hardware tab — new sub-tab on the System page showing live state of both switches and the override window, plus a GPIO Assignments panel for pin reassignment with live conflict detection.
  • Eleven new notification events — covering everything the switches do: EPO engage/release, Quiet engage/release, Quiet override enable, HOA-Run start/end, manual run reminder, run blocked by safety, automation suppressed by Quiet, and a one-shot boot-state alert that fires only when GenMaster boots into a non-default hardware state.
  • EPO + HOA combined banners — when both are active, the HOA banner wording changes to acknowledge the EPO ("Run Mode — Held by EPO", "Quiet Mode — EPO Active") and the Override button is hidden in the Quiet case.
  • Disabled Start/Stop controls when the EPO is engaged — both buttons grey out and the Emergency Stop card dims so it's visually obvious why nothing's happening.
  • History page trigger badges for HOA-triggered runs so physical-switch runs are distinguishable from automation runs.

Fixes

  • Rate-limit-exceeded alert now fires at most once per hour window. Previously the alert itself was sent on every suppressed notification, which defeated the purpose of the rate limit.
  • Notification history timestamps now serialize with a UTC marker. The System Events tab no longer shows "Just now" for every row, and the detail modal's Triggered/Sent times match the Event Data field.
  • Channel Tests tab in the Notifications History view now correctly filters to actual test sends (the ▷ button on a channel) instead of showing every per-channel delivery.

Upgrade

cd /root/pizero_generator_control/genmaster
docker compose pull
docker compose up -d
docker compose exec genmaster alembic upgrade head

Eight new Alembic migrations (015 through 022). No breaking changes; v0.1.0 deployments that don't add the hardware will see no behavioral difference.

GenSlave upgrade is the same shape:

cd /opt/genslave
docker compose pull
docker compose up -d

Optional hardware shopping list

Both switches are optional, but if you want them, this is the parts list. Total cost is around $70–120 from AutomationDirect, Mouser, or Digikey. Avoid no-name Amazon listings — counterfeit Schneider parts are common and defeat the point of paying for rated safety hardware.

  • EPO actuator: Schneider XB4-BS542 (22 mm red mushroom E-stop, push to engage, twist clockwise to release, IP66)
  • EPO contact block: Schneider ZB4-BZ104 (1 NC + 1 NO in a single mechanically-linked block)
  • HOA actuator: Schneider XB4-BD33 (22 mm 3-position rotary, stay-put in all positions)
  • HOA contact block: Schneider ZB4-BZ103 (2 NO in a single block — Block A closes in Quiet, Block B closes in Run)
  • HOA legend plate (optional): ZBY2-series with printed QUIET / AUTO / RUN labels around the knob

Wiring details, including the Auto Hat Mini polarity gotcha for the EPO signal contact, are in docs/manual/hardware-switches.md.

Documentation

Full docs at https://rjsears.github.io/pizero_generator_control/.

New and updated for this release:

  • Hardware Switches — master operator guide for both switches, wiring, behavior, troubleshooting
  • Quick Reference — Emergency — printable one-pager designed to laminate and keep at the generator panel
  • Generator Control — updated with the new EPO/HOA banner table and the "Start disabled while EPO engaged" admonition
  • System — new Hardware sub-tab section
  • Notifications — eleven new event-row entries and the rate-limit clarification
  • Appendix — new sections for hardware-switch API endpoints, env vars, and Alembic migrations
  • SECURITY.md — new "Hardware safety — two-layer EPO pattern" section explaining hardware-as-guarantee vs software-as-signal
  • ARCHITECTURE.md — new "Hardware Switches — Asymmetric Design" section with EPO state-flow diagram and HOA precedence stack
  • README.md — new "Safety by Design" section with the EPO + HOA interaction infographic

Known limitations

  • The four physical install photos in the manual (80-epo-installed.png, 81-hoa-installed.png, 82-autohat-to-epo-wiring.png, 83-genmaster-to-hoa-wiring.png) are still placeholders pending real bench photos from the deployed unit. The doc text and wiring details are accurate; only the photos are stand-ins.
  • Hardware bench-tested end-to-end (EPO engage/release, HOA all positions including fault, Quiet override start/cancel/auto-clear, combined EPO + HOA states) but only on a single deployment. Field testing on additional installs welcome.

Feedback

Assets 2
Loading