feat: review of 57 and numerous other formatting issues

51-rooftop-hvac-predictive-maintenance/README.md

@@ -340,22 +340,39 @@ If a problem isn't on this list, the [Blues community forum](https://discuss.blu
 
 This pack is deliberately a starting point — small, retrofittable, and aimed at the failure modes a single technician already knows how to recognize. A handful of things are out of scope on purpose, and a longer list of extensions makes sense once the basic detector is paying for itself.
 
-**Simplified for the POC:**
-- Detection is rule-based — three scalar threshold checks, not a trained model. That catches the impending-failure patterns HVAC technicians already recognize on a service call, but it isn't the anomaly-detection or drift-analysis that a more sophisticated predictive-maintenance platform would layer on top.
-- CT readings are single-phase only. Three-phase commercial RTUs need three CTs and a firmware change to sum them.
-- The SDP810 CRC byte is read and discarded rather than verified — a communication-layer fault on the I²C bus won't be caught.
-- Compressor-start detection is sampled, not interrupt-driven: transitions that occur and finish entirely inside one `sample_interval_sec` window won't be counted. The 60-second default is well below normal RTU cycle times, but a badly-misbehaving contactor could in principle cycle faster than the sampler sees.
-- No local storage of historical samples — the Notecard does its own multi-day Note queue, but the sketch itself keeps only the current summary window in RAM plus a 16-slot ring buffer of recent compressor starts.
-- The 120VAC power path assumes the installer can tap the RTU service disconnect. Installations that can only offer the 24VAC control-transformer rail need a 24VAC-input supply instead (e.g. a Functional Devices PSH40A or a Mornsun LH05-23B05R3); the downstream 5V wiring is unchanged. A Scoop / solar variant is a reasonable addition for units where neither rail is practical.
-- Mojo is bench-validation equipment in this POC — the firmware does not read its LTC2959 coulomb counter over the Qwiic bus. Adding a runtime mAh field to the summary is a straightforward extension if fleet-level power telemetry is valuable.
-
-**Production next steps:**
-- Three-phase CT support (or 208/240V split-phase) for larger units — a second and third CT on A3/A4 plus an RMS sum in firmware.
-- Add a duct-static-pressure sensor on the supply side to distinguish "clogged filter" from "blocked coil." The two look similar from the return side alone, but a clogged coil shows rising static on *both* sides while a clogged filter only rises on the return.
-- CRC check on all SDP810 I²C reads — the bytes are already there in the frame, the firmware just ignores them today.
-- Field-upgradeable firmware via [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) so a service company can push a threshold recipe or a new failure-mode detector to the entire fleet without a truck roll.
-- Per-unit commissioning: probe-offset correction via an environment variable. Thermistors drift a few degrees with duct placement, and calibrating once at install time is strictly better than living with the noise.
-- Weather-input overlay: correlate delta-T against outside-air temperature (via a Notehub environment variable sourced from a weather API route, or a dedicated outdoor-air probe) so refrigerant-loss detection isn't falsely triggered during mild-weather startup cycles, when delta-T naturally runs low before the coil saturates.
+### Simplified for the POC
+
+The following are scope choices, not oversights — each trades a capability a fuller platform would want against the simplicity that makes this pack retrofittable by a single technician.
+
+**Detection is rule-based.** The firmware runs three scalar threshold checks, not a trained model. That catches the impending-failure patterns HVAC technicians already recognize on a service call, but it isn't the anomaly-detection or drift-analysis that a more sophisticated predictive-maintenance platform would layer on top.
+
+**CT readings are single-phase only.** Three-phase commercial RTUs need three CTs and a firmware change to sum them.
+
+**The SDP810 CRC byte is read and discarded rather than verified**, which means a communication-layer fault on the I²C bus won't be caught.
+
+**Compressor-start detection is sampled, not interrupt-driven.** Transitions that occur and finish entirely inside one `sample_interval_sec` window won't be counted. The 60-second default is well below normal RTU cycle times, but a badly-misbehaving contactor could in principle cycle faster than the sampler sees.
+
+**No local storage of historical samples.** The Notecard does its own multi-day Note queue, but the sketch itself keeps only the current summary window in RAM plus a 16-slot ring buffer of recent compressor starts.
+
+**The 120VAC power path assumes the installer can tap the RTU service disconnect.** Installations that can only offer the 24VAC control-transformer rail need a 24VAC-input supply instead (for example, a Functional Devices PSH40A or a Mornsun LH05-23B05R3); the downstream 5V wiring is unchanged. A Scoop / solar variant is a reasonable addition for units where neither rail is practical.
+
+**Mojo is bench-validation equipment in this POC.** The firmware does not read its LTC2959 coulomb counter over the Qwiic bus. Adding a runtime mAh field to the summary is a straightforward extension if fleet-level power telemetry is valuable.
+
+### Production Next Steps
+
+Once the basic detector is paying for itself, a handful of extensions make sense — roughly from the most immediately useful to the most infrastructure-dependent.
+
+**Three-phase CT support** (or 208/240V split-phase) brings larger units into scope: a second and third CT on A3/A4 plus an RMS sum in firmware.
+
+**A duct-static-pressure sensor on the supply side** would distinguish "clogged filter" from "blocked coil." The two look similar from the return side alone, but a clogged coil shows rising static on *both* sides while a clogged filter only rises on the return.
+
+**A CRC check on all SDP810 I²C reads** is low-hanging fruit — the bytes are already there in the frame, the firmware just ignores them today.
+
+**Field-upgradeable firmware via [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/)** would let a service company push a threshold recipe or a new failure-mode detector to the entire fleet without a truck roll.
+
+**Per-unit commissioning** via a probe-offset correction environment variable tightens accuracy: thermistors drift a few degrees with duct placement, and calibrating once at install time is strictly better than living with the noise.
+
+**A weather-input overlay** correlates delta-T against outside-air temperature — via a Notehub environment variable sourced from a weather API route, or a dedicated outdoor-air probe — so refrigerant-loss detection isn't falsely triggered during mild-weather startup cycles, when delta-T naturally runs low before the coil saturates.
 
 ## 12. Summary
 

52-vfd-pump-predictive-maintenance/README.md

@@ -32,7 +32,7 @@ A failing pump rarely just stops. It signals first: motor current can shift at c
 
 **Notecard responsibilities.** The Notecard's on-device queue holds every Note the host writes, then ships them out on the [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence (default hourly). Anything tagged `sync:true` jumps the queue and the radio comes up immediately. The same module also pulls [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) on every inbound sync, which is what lets a maintenance lead retune thresholds — or even point the firmware at a different drive vendor's register addresses — from a browser, without anyone visiting the panel.
 
-**Notehub responsibilities.** [Notehub](https://notehub.io) is where the events land — every one ingested, every one stored, project-level [routes](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub) fanning them onward. Because every plant's VFDs may sit at different register addresses, the per-fleet [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) story is what keeps a single firmware image servicing an ABB plant in Ohio and a Yaskawa plant in São Paulo. See [Smart Fleets](https://dev.blues.io/notehub/notehub-walkthrough/#using-smart-fleet-rules) for how to organize them by vendor or site.
+**Notehub responsibilities.** [Blues Notehub](https://blues.com/notehub/) is where the events land — every one ingested, every one stored, project-level [routes](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub) fanning them onward. Because every plant's VFDs may sit at different register addresses, the per-fleet [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) story is what keeps a single firmware image servicing an ABB plant in Ohio and a Yaskawa plant in São Paulo. See [Smart Fleets](https://dev.blues.io/notehub/notehub-walkthrough/#using-smart-fleet-rules) for how to organize them by vendor or site.
 
 **Routing to the cloud (high level).** Notehub supports HTTP, MQTT, AWS, Azure, GCP, Snowflake, and several other destinations; route setup is project-specific. See the [Notehub routing docs](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub) for more information.
 
@@ -368,22 +368,37 @@ A reference design that drops into thousands of different drive configurations h
 
 **Signal limitations.** VFD telemetry is valuable but it is not equivalent to full pump instrumentation. Current, torque, speed, temperature, and active fault codes can identify abnormal *patterns*, but they cannot conclusively distinguish between worn impeller, clogged suction strainer, closed discharge valve, cavitation, bearing drag, increased fluid viscosity, debris, or process changes — without supporting context such as suction/discharge pressure, flow, vibration, or known duty cycle. Treat every alert this firmware emits as an *early maintenance indicator*, not a diagnosis.
 
-**Simplified for this reference design:**
-
-- **Vendor-specific register addresses, scaling, signedness, word counts.** Defaults are illustrative for a fictional contiguous map. Each VFD vendor publishes its own Modbus map; commissioning a real plant means looking up the actual addresses, scaling factors (e.g. current may be 0.1 A, 0.01 A, or % of rated), signedness (torque/temperature often signed), word counts (runtime hours often a 32-bit value across two registers with vendor-specific word order), and addressing convention (0-based wire-level vs 1-based / Modicon "40001" notation). The shipped firmware reads six contiguous 16-bit registers with hardcoded scaling — production builds need vendor-specific firmware (one build per `vfd_profile`).
-- **Active fault code only, not fault history log.** The firmware reads the active-fault register once per cycle. A vendor-specific fault-log readout (typically a multi-register block with circular-buffer semantics) is a future enhancement.
-- **Single drive per OPTA.** The firmware reads one slave ID. A pump room with N drives needs either N OPTAs, or firmware extension to round-robin across slave IDs on the same RS-485 bus.
-- **Heuristic thresholds.** Four threshold-based rules catch common load-anomaly, transient-fault, runtime-drift, and overtemp patterns. They will *not* catch every failure mode, and they will sometimes fire on benign conditions (e.g. a seasonally hotter ambient, a deliberate process change). Production deployments should commission thresholds per pump after a baseline period.
-- **No Modbus writes.** The firmware reads only. Writing setpoints to the drive (start/stop, speed reference, etc.) is intentionally out of scope — that's a different safety conversation involving E-stop wiring, lockout/tagout, and functional safety certification.
-- **No host firmware updates wired up.** [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) is supported on STM32H7 (the OPTA's MCU family) but requires AUX wiring that Blues Wireless for OPTA does not currently break out. For now, host firmware updates are local-only via USB-C.
-
-**Production next steps:**
-- Vendor-specific `vfd_profile` builds: ABB ACS580, Yaskawa GA500, Danfoss FC-302, Schneider ATV — each with the correct register addresses, scaling, signedness, and word handling baked in.
-- Per-pump baseline learning — store rolling 30-day current-vs-frequency tables in flash and trigger `load_anomaly` against the *learned* curve, not a static factor.
-- Fault history log readout (vendor-specific, typically multi-register with timestamp).
-- Multi-drive support via round-robin polling and per-slave-ID summaries.
-- Add a `vfd_command.qi` inbound Notefile for service-tech-initiated diagnostic dumps.
-- Wire ODFU to the OPTA's BOOT/RESET pins for over-the-air host updates.
+### Simplified for this reference design
+
+Beyond the signal limitation above, the firmware draws a deliberate scope boundary in a few places. Each of these is a place a real fleet deployment will extend the design rather than a defect.
+
+**Vendor-specific register addresses, scaling, signedness, and word counts.** Defaults are illustrative for a fictional contiguous map. Each VFD vendor publishes its own Modbus map, so commissioning a real plant means looking up the actual addresses, scaling factors (current may be 0.1 A, 0.01 A, or % of rated), signedness (torque and temperature are often signed), word counts (runtime hours are often a 32-bit value across two registers with vendor-specific word order), and addressing convention (0-based wire-level vs. 1-based / Modicon "40001" notation). The shipped firmware reads six contiguous 16-bit registers with hardcoded scaling — **production builds need vendor-specific firmware, one build per `vfd_profile`.**
+
+**Active fault code only, not fault history log.** The firmware reads the active-fault register once per cycle. A vendor-specific fault-log readout — typically a multi-register block with circular-buffer semantics — is a future enhancement.
+
+**Single drive per OPTA.** The firmware reads one slave ID. A pump room with N drives needs either N OPTAs or a firmware extension to round-robin across slave IDs on the same RS-485 bus.
+
+**Heuristic thresholds.** Four threshold-based rules catch common load-anomaly, transient-fault, runtime-drift, and overtemp patterns. They will *not* catch every failure mode, and they will sometimes fire on benign conditions such as a seasonally hotter ambient or a deliberate process change. Production deployments should commission thresholds per pump after a baseline period.
+
+**No Modbus writes.** The firmware reads only. Writing setpoints to the drive (start/stop, speed reference, and the like) is intentionally out of scope — that's a different safety conversation involving E-stop wiring, lockout/tagout, and functional safety certification.
+
+**No host firmware updates wired up.** [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) is supported on STM32H7 (the OPTA's MCU family) but requires AUX wiring that Blues Wireless for OPTA does not currently break out. For now, **host firmware updates are local-only via USB-C.**
+
+### Production Next Steps
+
+When a real fleet starts deploying, the scope choices above become the roadmap — roughly in order from the most immediately useful to the most infrastructure-dependent.
+
+**Vendor-specific `vfd_profile` builds** are the first need: ABB ACS580, Yaskawa GA500, Danfoss FC-302, Schneider ATV — each with the correct register addresses, scaling, signedness, and word handling baked in.
+
+**Per-pump baseline learning** sharpens detection considerably. Storing rolling 30-day current-vs-frequency tables in flash lets the firmware trigger `load_anomaly` against the *learned* curve rather than a static factor.
+
+**Fault history log readout** — vendor-specific and typically multi-register with timestamps — captures the events leading up to a trip, not just the active fault.
+
+**Multi-drive support** via round-robin polling and per-slave-ID summaries lets a single OPTA service an entire pump room.
+
+**A `vfd_command.qi` inbound Notefile** would allow service-tech-initiated diagnostic dumps on demand.
+
+**Wiring ODFU to the OPTA's BOOT/RESET pins** is the longest-horizon item, enabling over-the-air host updates across the fleet once the hardware path is available.
 
 ## 13. Summary