From 9511f0c10cf22f030fc050cdbae0613391028f22 Mon Sep 17 00:00:00 2001 From: Rob Lauer Date: Tue, 2 Jun 2026 13:46:55 -0500 Subject: [PATCH 1/6] switch from bullet lists to more prose for the limitations sections --- .../README.md | 49 ++++++++----- 52-vfd-pump-predictive-maintenance/README.md | 49 ++++++++----- .../README.md | 47 ++++++++----- .../README.md | 46 ++++++++----- .../README.md | 68 ++++++++++++------- 5 files changed, 170 insertions(+), 89 deletions(-) diff --git a/51-rooftop-hvac-predictive-maintenance/README.md b/51-rooftop-hvac-predictive-maintenance/README.md index c50a4420..3d6bc550 100644 --- a/51-rooftop-hvac-predictive-maintenance/README.md +++ b/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 diff --git a/52-vfd-pump-predictive-maintenance/README.md b/52-vfd-pump-predictive-maintenance/README.md index 1484816f..d213f0f6 100644 --- a/52-vfd-pump-predictive-maintenance/README.md +++ b/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 diff --git a/53-municipal-wastewater-lift-station-monitor/README.md b/53-municipal-wastewater-lift-station-monitor/README.md index 41ab5c78..0a826721 100644 --- a/53-municipal-wastewater-lift-station-monitor/README.md +++ b/53-municipal-wastewater-lift-station-monitor/README.md @@ -16,7 +16,7 @@ This project is a [downtime prevention](https://blues.com/downtime-prevention/) When a lift station fails, the **wet well** — the collection basin that feeds the pumps — fills up and overflows. The result is a **SSO**: a sanitary sewer overflow. SSOs draw immediate regulatory attention; they trigger EPA reporting obligations, risk consent decree violations, and require expensive emergency cleanups. A station that fails on a Friday evening and isn't discovered until Monday morning is a public health event, a PR crisis, and a significant unplanned expense all at once. The failure modes are rarely dramatic: a pump fails to start because its float control sticks, a discharge check valve fails and allows backflow that clogged the impeller, or a wet-well float switch trips but no one receives the alarm because the SCADA dial-up modem lost its phone line. Each of these is detectable minutes after it starts — if someone is watching. -This project is that watcher. It straps to the inside of the station, samples the wet-well level every 60 seconds, measures current draw on each pump, and monitors the high-water float switch — four sensing points across three sensor types. Onboard edge logic on the STM32-based host MCU evaluates three fault rules every 60 seconds and routes alerts to the Blues Notehub cloud service the instant any rule trips — over cellular where a tower is in reach, and over the Skylo satellite network where one isn't. The on-call crew gets paged before the wet well overflows, not after. +This project is that watcher. It straps to the inside of the station, samples the wet-well level every 60 seconds, measures current draw on each pump, and monitors the high-water float switch — four sensing points across three sensor types. Onboard edge logic on the STM32-based host MCU evaluates three fault rules every 60 seconds and routes alerts to the [Blues Notehub](https://blues.com/notehub/) cloud service the instant any rule trips — over cellular where a tower is in reach, and over the Skylo satellite network where one isn't. The on-call crew gets paged before the wet well overflows, not after. **Why Notecard for Skylo.** The wireless-first architecture here isn't a convenience — it's a necessity. Lift stations sit in concrete vaults underground, often with no AC power outlet in the vault itself (power runs to the pump control panel, not a wall socket). They're geographically distributed across a municipality in a pattern that matches the sewer network, not the municipal network — there's no fiber running to a roadside pump cabinet, and there's no corporate WiFi AP that can reach through a concrete lid to a sensor inside. Utility supervisors would need to deploy and maintain a WiFi access point at every single station to achieve what one Notecard covers automatically. @@ -471,24 +471,39 @@ arduino-cli lib install "Blues Wireless Notecard" This reference design covers the bulk of typical municipal lift stations, but it deliberately stops short of full SCADA replacement. The simplifications below are scope choices — places where a production deployment will want to add another sensor, another field-tunable, or another integration once a real utility starts running it. -**Simplified for the POC:** +### Simplified for the POC -- **Level sensor accuracy assumes a clean straight wet well.** The firmware maps ADC counts linearly to % fill using the transducer's pressure-to-level formula, assuming a uniform cross-section. Wet wells with irregular geometry or foaming conditions will read inaccurately; a field-calibrated offset via an environment variable is the production fix. -- **CT range and motor type.** The SCT-013-030 (30 A) suits single-phase motors up to ~5 HP at 230 V. Motors larger than 5 HP single-phase, or any three-phase motor, require a higher-ratio CT (e.g. SCT-013-060, 60 A / 1 V). Three-phase installations also require one CT per phase; the current sketch reads one CT per pump, which serves as a running/not-running indicator on a single leg but does not produce true 3-phase RMS power. -- **fail-to-start detection is level-threshold only.** The firmware does not know what level the pump float controls are actually set to. The `high_level_pct` threshold is a firmware-side approximation of the hardware float control setpoint; the two may not match unless calibrated after installation. -- **No discharge pressure or flow measurement.** The pump_clog rule fires on level-rising-while-running, which is a necessary but not sufficient condition for a clog — it also fires on genuine high-inflow conditions (heavy rain) or when both pumps are running and inflow exceeds combined capacity. Production deployments benefit from a discharge pressure sensor that can distinguish "pump is pumping but line is blocked" from "pump is pumping but inflow is just overwhelming." -- **No SCADA integration.** The sketch is standalone. Most municipal lift stations already have a local RTU or telemetry unit. Integrating with that system (e.g., reading dry contacts from the existing SCADA outputs, or making the Notecard's data available to the local RTU) is outside the scope of this POC. -- **Satellite (NTN) operation caveats.** The firmware is identical everywhere, but when the Notecard for Skylo falls back to the satellite link it carries material operational differences. Alert and summary Notes queue in the Notecard's local store and sync on the satellite session schedule — `sync:true` Notes are prioritized for the next available session, but locating a Skylo satellite and completing transmission takes several minutes (not seconds). Each Note must stay within the NTN 256-byte maximum; Notes exceeding this are silently dropped by the satellite network without transmission. Inbound syncs (env-var pulls) consume approximately 50 bytes of the 10 KB bundled satellite data allocation each; the default 2-hour inbound cadence costs roughly 600 bytes/day. The Skylo-certified main antenna must be mounted outdoors with an unobstructed sky view (in the northern hemisphere, an unobstructed view of the southern sky) for the satellite link to work; stations with the enclosure entirely below grade will need an above-grade cable run. Satellite operation is opt-in at the Notecard level: the firmware enables it by setting `card.transport` to `wifi-cell-ntn` — without an `ntn` transport mode the board would stay on cellular/WiFi only and never reach the satellite network. See [Section 2](#satellite-ntn-operation-considerations) and [Section 8](#9-validation-and-testing) for the full breakdown. -- **Mojo is bench-validation only.** The firmware does not read the Mojo's coulomb counter register over Qwiic. Adding a `mojo_mah` field to the hourly summary is a simple extension using the LTC2959 register map if fleet-level energy telemetry is valuable. +The simplifications below are scope choices — each is a place where a production deployment will want to add another sensor, another field-tunable, or another integration once a real utility starts running it. -**Production next steps:** +**Level sensor accuracy assumes a clean, straight wet well.** The firmware maps ADC counts linearly to % fill using the transducer's pressure-to-level formula, assuming a uniform cross-section. Wet wells with irregular geometry or foaming conditions will read inaccurately; a field-calibrated offset via an environment variable is the production fix. -- Per-station level calibration: add `level_offset_pct` environment variable for wet-well geometry corrections applied after the ADC-to-percent conversion. -- Three-phase current support: add `A3` for the third CT leg on 3-phase pumps and sum squared contributions for a true 3-phase RMS reading. -- Discharge pressure sensor on I²C (e.g., a 4–20 mA→I²C transducer) to distinguish clog from high-inflow, reducing false positives from storm events. -- [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) for over-the-air host firmware updates (on cellular/WiFi only) so threshold algorithm improvements roll out to the fleet without a truck roll to each underground vault. -- Pump cycle-count tracking: log each pump start and stop (transition from below to above `pump_on_amps`) to accumulate lifetime cycle counts and flag motors approaching their rated duty cycle limits. -- Integration with the municipal SCADA or CMMS: a `lift_alert.qo` Notehub route that creates a CMMS work order automatically, so the on-call response begins the moment the Notecard transmits, not the moment an engineer reads an SMS. +**CT range and motor type.** The SCT-013-030 (30 A) suits single-phase motors up to ~5 HP at 230 V. Motors larger than 5 HP single-phase, or any three-phase motor, require a higher-ratio CT (for example, the SCT-013-060, 60 A / 1 V). Three-phase installations also require one CT per phase; the current sketch reads one CT per pump, which serves as a running/not-running indicator on a single leg but **does not produce true 3-phase RMS power.** + +**Fail-to-start detection is level-threshold only.** The firmware does not know what level the pump float controls are actually set to. The `high_level_pct` threshold is a firmware-side approximation of the hardware float-control setpoint; the two may not match unless calibrated after installation. + +**No discharge pressure or flow measurement.** The `pump_clog` rule fires on level-rising-while-running, which is a necessary but not sufficient condition for a clog — it also fires on genuine high-inflow conditions (heavy rain) or when both pumps are running and inflow exceeds combined capacity. Production deployments benefit from a discharge pressure sensor that can distinguish "pump is pumping but the line is blocked" from "pump is pumping but inflow is just overwhelming." + +**No SCADA integration.** The sketch is standalone. Most municipal lift stations already have a local RTU or telemetry unit, and integrating with that system — reading dry contacts from the existing SCADA outputs, or making the Notecard's data available to the local RTU — is outside the scope of this POC. + +**Satellite (NTN) operation caveats.** The firmware is identical everywhere, but when the Notecard for Skylo falls back to the satellite link it carries material operational differences. Alert and summary Notes queue in the Notecard's local store and sync on the satellite session schedule — `sync:true` Notes are prioritized for the next available session, but locating a Skylo satellite and completing transmission takes several minutes, not seconds. Each Note must stay within the **NTN 256-byte maximum**; Notes exceeding this are silently dropped by the satellite network without transmission. Inbound syncs (env-var pulls) consume approximately 50 bytes of the 10 KB bundled satellite data allocation each, so the default 2-hour inbound cadence costs roughly 600 bytes/day. The Skylo-certified main antenna must be mounted outdoors with an unobstructed sky view (in the northern hemisphere, an unobstructed view of the southern sky) for the satellite link to work, so stations with the enclosure entirely below grade will need an above-grade cable run. Satellite operation is opt-in at the Notecard level: the firmware enables it by setting `card.transport` to `wifi-cell-ntn` — without an `ntn` transport mode the board would stay on cellular/WiFi only and never reach the satellite network. See [Section 2](#satellite-ntn-operation-considerations) and [Section 8](#9-validation-and-testing) for the full breakdown. + +**Mojo is bench-validation only.** The firmware does not read the Mojo's coulomb counter register over Qwiic. Adding a `mojo_mah` field to the hourly summary is a simple extension using the LTC2959 register map if fleet-level energy telemetry is valuable. + +### Production Next Steps + +Once a real utility is running the basic monitor, the following extensions are the natural progression — roughly from the most immediately useful to the most integration-dependent. + +**Per-station level calibration** is the first refinement: a `level_offset_pct` environment variable for wet-well geometry corrections, applied after the ADC-to-percent conversion. + +**Three-phase current support** adds `A3` for the third CT leg on 3-phase pumps and sums the squared contributions for a true 3-phase RMS reading. + +**A discharge pressure sensor on I²C** (for example, a 4–20 mA → I²C transducer) would distinguish a clog from high-inflow, reducing false positives from storm events. + +**[Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/)** enables over-the-air host firmware updates (on cellular/WiFi only), so threshold-algorithm improvements roll out to the fleet without a truck roll to each underground vault. + +**Pump cycle-count tracking** logs each pump start and stop (the transition from below to above `pump_on_amps`) to accumulate lifetime cycle counts and flag motors approaching their rated duty-cycle limits. + +**Integration with the municipal SCADA or CMMS** closes the loop: a `lift_alert.qo` Notehub route that creates a CMMS work order automatically, so the on-call response begins the moment the Notecard transmits, not the moment an engineer reads an SMS. ## 12. Summary diff --git a/54-multi-site-walk-in-cooler-energy-setpoint-monitor/README.md b/54-multi-site-walk-in-cooler-energy-setpoint-monitor/README.md index 84d94484..46e251b4 100644 --- a/54-multi-site-walk-in-cooler-energy-setpoint-monitor/README.md +++ b/54-multi-site-walk-in-cooler-energy-setpoint-monitor/README.md @@ -16,7 +16,7 @@ This project is a cellular [energy savings](https://blues.com/energy-savings/) r The harder problem is that an operator running 800 locations has 800 different network environments — franchisees on consumer ISPs, independent operators with POS (point-of-sale) systems that their IT vendors won't let anyone touch, convenience stores with back-office networks that preclude any new guest devices. Getting corporate visibility through all of that friction is the barrier that keeps most energy-monitoring pilots from becoming fleet-wide programs. The pilot sites get instrumented; the rollout stalls at 50. -This project is the device that gets past that barrier. One SKU, cellular-connected, no IT ticket required. Stick a temperature probe inside the box, clamp a split-core current transformer on the compressor hot leg, mount a magnetic reed switch on the door, and you get a per-unit compressor energy proxy — compressor apparent kWh per summary window (per-day totals derived downstream by summing `kwh_window` records), door-open events, and temperature-to-target deviation — delivered to Notehub and routed wherever corporate needs it. +This project is the device that gets past that barrier. One SKU, cellular-connected, no IT ticket required. Stick a temperature probe inside the box, clamp a split-core current transformer on the compressor hot leg, mount a magnetic reed switch on the door, and you get a per-unit compressor energy proxy — compressor apparent kWh per summary window (per-day totals derived downstream by summing `kwh_window` records), door-open events, and temperature-to-target deviation — delivered to the [Blues Notehub](https://blues.com/notehub/) cloud service and routed wherever corporate needs it. **Why Notecard.** The project description says it plainly: corporate energy management can't touch 800 independent-operator or franchisee WiFi networks — each would be its own ticket. A cellular Notecard is one SKU the field can plug in without asking anyone for a WiFi password. That's not a convenience; it's the difference between a program that deploys at fleet scale and one that stays perpetually in pilot. Deploying on cellular also keeps the energy-monitoring data stream entirely off the POS network, which matters both for network security and for the operational reality that POS downtime is the one thing nobody is willing to accept as a side effect of an energy program. The [Notecard Cell+WiFi](https://dev.blues.io/datasheets/notecard-datasheet/note-mbglw/) variant keeps WiFi as an opportunistic fallback for the occasional site that can offer it, without compromising the cellular-first deployment model. @@ -389,25 +389,39 @@ The *shape* of the trace is as informative as the absolute level. What you want A reference design that has to drop onto 800 different walk-in boxes has to be deliberately modest about what it measures and what it concludes. The simplifications below are scope choices — places where a particular operator will want to add a sensor, calibrate a probe, or wire in a controller-side integration once the basic fleet visibility is paying for itself. -**Simplified for this POC:** +### Simplified for this POC -- **Sensor reads are sample-based, not interrupt-driven.** All three sensors are polled once per `sample_interval_sec` (default 60 seconds). Any door opening, door closing, or compressor start/stop that occurs *and completes* within one 60-second sleep interval goes undetected. This quantizes edge timing to the sample period, which directly affects `door_opens`, `door_open_sec`, compressor runtime, and `kwh_window` — all can undercount if events are shorter than the sample period. `door_open_long` alert timing is similarly quantized: a door that opens just after one sample and closes just before the next may not trip the alert even if the physical open duration exceeded `door_open_alert_sec`. Reducing `sample_interval_sec` via environment variable improves resolution but increases host awake time and may increase alert frequency (more frequent checks means alert conditions are detected sooner and `sync:true` sessions may be triggered more often); scheduled outbound cellular sessions are still governed by `summary_interval_min` and do not increase with the sample interval alone. +The simplifications below are scope choices — places where a particular operator will want to add a sensor, calibrate a probe, or wire in a controller-side integration once the basic fleet visibility is paying for itself. -- **AC supply voltage.** The MeanWell IRM-10-5 in the BOM accepts 85–264VAC wide-range input and handles both 120VAC and 208/240VAC single-phase — the majority of walk-in condensing unit installations. Some mechanical rooms provide only a 24VAC or 24VDC control-transformer rail rather than mains voltage; those installs require a different converter (a 24VAC-input or 24VDC-input step-down regulator) rather than the AC/DC supply listed here. Always confirm the available supply with the field electrician before ordering components. +**Sensor reads are sample-based, not interrupt-driven.** All three sensors are polled once per `sample_interval_sec` (default 60 seconds). Any door opening, door closing, or compressor start/stop that occurs *and completes* within one 60-second sleep interval goes undetected. This quantizes edge timing to the sample period, which directly affects `door_opens`, `door_open_sec`, compressor runtime, and `kwh_window` — all of which can undercount if events are shorter than the sample period. `door_open_long` alert timing is similarly quantized: a door that opens just after one sample and closes just before the next may not trip the alert even if the physical open duration exceeded `door_open_alert_sec`. Reducing `sample_interval_sec` via environment variable improves resolution but increases host awake time and may increase alert frequency (more frequent checks mean alert conditions are detected sooner and `sync:true` sessions may be triggered more often). Note that scheduled outbound cellular sessions are still governed by `summary_interval_min` and do not increase with the sample interval alone. -- **Compressor apparent energy only, not total cooler energy.** The single CT clamps one hot leg of the compressor circuit. Evaporator fans, defrost heaters, door heaters, controls, lighting, and other loads on the cooler's electrical service are not measured. `kwh_window` is a compressor energy proxy, not total cooler or site energy consumption. A revenue-grade multifunction meter or additional CT channels for the non-compressor loads would be required if total box energy is the intended metric. In addition, the estimate uses apparent power (V × I) rather than real power (V × I × PF). For a typical single-phase hermetic compressor motor, power factor runs 0.75–0.90, so the estimate will overstate actual compressor energy by 10–25 %. A calibrated kilowatt-hour meter with a pulse output is the right solution for billing-grade energy monitoring; the single-CT apparent-power approach gives a useful relative metric for comparing compressor behavior across units and tracking trends over time, not an absolute kWh figure. -- **Single-phase only.** Larger walk-in boxes (over 4,000 sq ft) or walk-in freezers may run three-phase compressors. That requires three CTs, additional ADC channels, and firmware changes to sum the per-phase apparent power. -- **Temperature sensor without calibration offset.** DS18B20 probe accuracy is ±0.5 °C (±0.9 °F) factory-calibrated. For temperature-to-target deviation monitoring at ±1 °F precision, an in-situ calibration offset stored as an environment variable would eliminate unit-to-unit spread. -- **Temperature-to-target deviation is a downstream-derived metric, not an on-device rule. The cooler controller's thermostat setpoint is not observed.** The device has no connection to the cooler's onboard controller or thermostat — `setpoint_f` in every summary Note is the corporate target temperature configured as a Notehub environment variable (`temp_setpoint_f`), not a value read from the cooler's electronic or mechanical controller. If actual controller-setpoint monitoring is required, integration with the cooler controller (e.g. via Modbus or a proprietary serial interface) would be needed. A downstream dashboard can compute deviation (`temp_f − setpoint_f`) per record, but the firmware itself never compares temperature against `setpoint_f`. The only on-device temperature alerting is the `temp_high` rule, which fires when `temp_f` exceeds the separate `temp_alert_f` threshold (default 40 °F). Because `temp_high` is a fixed threshold rather than a setpoint-relative check, a legitimate spike during a freight delivery (door held open 10 minutes) triggers the same alert as a genuine refrigerant problem. Gating the alert on compressor runtime and recent door activity would reduce false positives significantly. -- **No GNSS.** The Notecard Cell+WiFi includes a GNSS module. This project does not use it, because a fixed-location walk-in cooler box doesn't move. One-time site location can be bootstrapped from cellular tower triangulation via [`card.location`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-location) if site lat/lon is needed for mapping dashboards. +**AC supply voltage.** The MeanWell IRM-10-5 in the BOM accepts 85–264VAC wide-range input and handles both 120VAC and 208/240VAC single-phase — the majority of walk-in condensing-unit installations. Some mechanical rooms provide only a 24VAC or 24VDC control-transformer rail rather than mains voltage; those installs require a different converter (a 24VAC-input or 24VDC-input step-down regulator) rather than the AC/DC supply listed here. **Always confirm the available supply with the field electrician before ordering components.** -**Production next steps:** -- Per-unit calibration offset for the DS18B20 (`temp_offset_f` env var) applied in `readBoxTempF()` at runtime. -- Add a `door_open_max_sec` field to the summary payload capturing the longest single uninterrupted door-open event within the window — useful for distinguishing a normal rapid-turnaround pattern from a single sustained-open incident, beyond what `door_open_sec` (total) alone conveys. -- Three-phase compressor support: three SCT-013-030 CTs on A0/A1/A2, RMS per leg, summed apparent power. -- kWh power-factor correction via a `power_factor` environment variable (0.80 default) that ops can dial in per unit type after a baseline period against a reference meter. -- [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) for over-the-air firmware updates, so threshold algorithm improvements can roll out fleet-wide without truck rolls. -- A `cooler_config.qi` inbound Notefile for ops-team-initiated diagnostic dumps (full state snapshot on demand without waiting for the next summary). +**Compressor apparent energy only, not total cooler energy.** The single CT clamps one hot leg of the compressor circuit, so evaporator fans, defrost heaters, door heaters, controls, lighting, and other loads on the cooler's electrical service are not measured. `kwh_window` is a compressor-energy proxy, **not** total cooler or site energy consumption — a revenue-grade multifunction meter or additional CT channels for the non-compressor loads would be required if total box energy is the intended metric. In addition, the estimate uses apparent power (V × I) rather than real power (V × I × PF). For a typical single-phase hermetic compressor motor, power factor runs 0.75–0.90, so **the estimate will overstate actual compressor energy by 10–25 %.** A calibrated kilowatt-hour meter with a pulse output is the right solution for billing-grade energy monitoring; the single-CT apparent-power approach gives a useful *relative* metric for comparing compressor behavior across units and tracking trends over time, not an absolute kWh figure. + +**Single-phase only.** Larger walk-in boxes (over 4,000 sq ft) or walk-in freezers may run three-phase compressors. That requires three CTs, additional ADC channels, and firmware changes to sum the per-phase apparent power. + +**Temperature sensor without calibration offset.** DS18B20 probe accuracy is ±0.5 °C (±0.9 °F) factory-calibrated. For temperature-to-target deviation monitoring at ±1 °F precision, an in-situ calibration offset stored as an environment variable would eliminate unit-to-unit spread. + +**Temperature-to-target deviation is a downstream-derived metric, not an on-device rule — and the cooler controller's thermostat setpoint is not observed.** The device has no connection to the cooler's onboard controller or thermostat: `setpoint_f` in every summary Note is the corporate *target* temperature configured as a Notehub environment variable (`temp_setpoint_f`), not a value read from the cooler's electronic or mechanical controller. If actual controller-setpoint monitoring is required, integration with the cooler controller (via Modbus or a proprietary serial interface) would be needed. A downstream dashboard can compute deviation (`temp_f − setpoint_f`) per record, but the firmware itself never compares temperature against `setpoint_f`. The only on-device temperature alerting is the `temp_high` rule, which fires when `temp_f` exceeds the separate `temp_alert_f` threshold (default 40 °F). Because `temp_high` is a fixed threshold rather than a setpoint-relative check, **a legitimate spike during a freight delivery (door held open 10 minutes) triggers the same alert as a genuine refrigerant problem.** Gating the alert on compressor runtime and recent door activity would reduce false positives significantly. + +**No GNSS.** The Notecard Cell+WiFi includes a GNSS module, but this project does not use it because a fixed-location walk-in cooler box doesn't move. One-time site location can be bootstrapped from cellular tower triangulation via [`card.location`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-location) if site lat/lon is needed for mapping dashboards. + +### Production Next Steps + +Once the basic fleet visibility is established, the following extensions are the natural progression — roughly from the most immediately useful to the most infrastructure-dependent. + +**A per-unit calibration offset for the DS18B20** (`temp_offset_f` env var, applied in `readBoxTempF()` at runtime) is the first refinement, tightening per-probe accuracy across the fleet. + +**A `door_open_max_sec` field on the summary payload** would capture the longest single uninterrupted door-open event within the window — useful for distinguishing a normal rapid-turnaround pattern from a single sustained-open incident, beyond what `door_open_sec` (total) alone conveys. + +**Three-phase compressor support** brings larger boxes into scope: three SCT-013-030 CTs on A0/A1/A2, RMS per leg, summed apparent power. + +**kWh power-factor correction** via a `power_factor` environment variable (0.80 default) lets ops dial in a per-unit-type correction after a baseline period against a reference meter, narrowing the apparent-vs-real-power gap noted above. + +**[Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/)** enables over-the-air firmware updates, so threshold-algorithm improvements can roll out fleet-wide without truck rolls. + +**A `cooler_config.qi` inbound Notefile** would allow ops-team-initiated diagnostic dumps — a full state snapshot on demand, without waiting for the next summary. ## 12. Summary diff --git a/55-demand-response-solar-battery-dispatcher/README.md b/55-demand-response-solar-battery-dispatcher/README.md index 4dd91052..cdb4723b 100644 --- a/55-demand-response-solar-battery-dispatcher/README.md +++ b/55-demand-response-solar-battery-dispatcher/README.md @@ -8,7 +8,7 @@ This reference application is intended to provide inspiration and help you get s -This project is an [energy savings](https://blues.com/energy-savings/) reference design that gives a commercial solar + battery installation an independent cellular control channel, so the asset owner can dispatch the battery to discharge during expensive peak-rate hours, charge during cheap overnight hours, and curtail grid export when the utility calls a demand-response (DR) event, without depending on the building's IT network or a vendor's proprietary cloud portal. The device reads live operating state from the inverter and the battery's management system (BMS) over the industrial bus they already share, and signals each one to enter the right mode at the right time — driven by a schedule or by live commands routed through the Blues cloud service, Notehub. +This project is an [energy savings](https://blues.com/energy-savings/) reference design that gives a commercial solar + battery installation an independent cellular control channel, so the asset owner can dispatch the battery to discharge during expensive peak-rate hours, charge during cheap overnight hours, and curtail grid export when the utility calls a demand-response (DR) event, without depending on the building's IT network or a vendor's proprietary cloud portal. The device reads live operating state from the inverter and the battery's management system (BMS) over the industrial bus they already share, and signals each one to enter the right mode at the right time — driven by a schedule or by live commands routed through the the [Blues Notehub](https://blues.com/notehub/) cloud service. **Scope.** This is a *mode enable / curtail* controller, not a power dispatcher. It closes and opens four dry-contact relays wired to digital control inputs the inverter and battery already expose; the field devices' own firmware then decides the actual charge, discharge, and export behavior — ramp rates, power limits, setpoints — based on their pre-commissioning configuration. The controller does not command power setpoints, verify that a requested dispatch profile was executed, or close any control loop around site load. @@ -546,29 +546,49 @@ Note that the OPTA itself is an always-on 24 VDC device whose steady-state draw This is a control-channel reference design, not a finished energy-management product. The simplifications below are deliberate scope choices — places where a real PPA operator or utility-integration partner will want to add vendor-specific register maps, deeper safety review, or a richer dispatch policy once the basic relay-and-uplink architecture is in place. -**Simplified for this reference design:** - -- **Demo Modbus register map.** The firmware reads four contiguous 16-bit registers from each device with hardcoded scaling and signedness. Real commercial inverters (SolarEdge, Fronius, SMA, Huawei SUN2000, Sungrow) and BMS units (BYD Battery-Box, PYLON, CATL) each publish their own Modbus maps with vendor-specific register addresses, scaling factors, and word orders. Commissioning against real hardware requires a vendor-specific firmware build. See the Notehub `reg_inv_base` / `reg_bms_base` environment variables as a first step, but per-vendor register maps will need code changes for scaling and signedness. -- **Single shared Modbus RTU bus.** The firmware uses one RS-485 physical segment with one set of serial parameters (`modbus_baud`, `modbus_parity`, `modbus_stop_bits`) shared by both the inverter and the BMS. Both devices must be configurable to the same baud rate, parity, and stop bits — a hard commissioning prerequisite. On real sites this constraint is commonly violated when inverter and BMS come from different vendors with different factory defaults. If the two devices cannot be brought to the same serial settings, this reference topology is unworkable without hardware modifications (a second UART or USB-to-RS-485 adapter) and matching firmware changes to address each device on its own independent serial port. -- **SOC guard hysteresis defaults are proof-of-concept values.** The firmware applies anti-chatter hysteresis at both ends of the SOC operating range: `soc_hyst_pct` (default 5 %) prevents discharge-relay chatter near the `soc_min_pct` floor, and `soc_max_hyst_pct` (default 3 %) prevents charge-relay chatter near the `soc_max_pct` ceiling. Both are starting points, not field-tuned values. BMS units with high-noise SOC reporting or slow charge recovery may need wider bands; units with tightly regulated reporting may need narrower ones. Tune both variables for each site based on observed SOC reading jitter during commissioning. Note that the belt-and-suspenders hard guard in `applyRelays()` retains the unmodified `soc_min_pct` as an absolute discharge floor — it is not subject to hysteresis, so a brief over-protection window between `soc_min_pct` and `soc_min_pct + soc_hyst_pct` is intentional and prevents the discharge relay from toggling on a borderline reading. -- **Relay wiring is application-specific.** This reference design assumes the inverter and BMS each expose a digital control input for the functions mapped to the relay outputs. Not every commercial product does. Many inverters accept grid-export enable/disable via Modbus write command rather than a contact input; in that case the relay output is redundant and the appropriate command needs to be added to the firmware. -- **TOU schedule is UTC-only.** Peak window start and end are configured in UTC hours. Operators must convert their local TOU peak window to UTC. A `tz_offset_hours` environment variable and a proper local-time calculation would be a straightforward improvement. -- **Autonomous TOU dispatch requires valid Notecard UTC time.** `resolveMode()` calls `currentUtcEpoch()`, which issues a `card.time` request and returns `0` if the Notecard has not yet completed a Notehub sync. On cold boot or after a power event before the Notecard re-acquires time, TOU window evaluation is suspended and the controller stays in `normal` mode. TOU windows resume automatically once a non-zero epoch is available. Design the commissioning workflow so the Notecard has synced at least once — confirming that `card.time` returns a non-zero `time` field — before relying on autonomous TOU behavior in the field. -- **Relay contacts assert enable inputs only — actual dispatch behavior is vendor-defined.** All control is via relay contact closures that assert or de-assert digital enable inputs on the field devices. Closing a relay enables a mode on the field device; the actual charge, discharge, and export behavior — ramp rates, power limits, setpoints — is determined entirely by the inverter and BMS firmware and their pre-commissioning configuration. This proof of concept does not command power setpoints, verify that a requested profile was executed, or close any control loop around actual site load or grid flow. Commissioning against a specific inverter and BMS model requires verifying that asserting each control input produces the expected operational response. -- **No Modbus writes.** The firmware reads inverter and BMS state but all control is via relay contact closures. Writing Modbus setpoints to the devices (target SOC, charge current limit, export cap) is intentionally out of scope — it requires a safety review for each device type and is a meaningful production enhancement, not a sensible starting point for a proof-of-concept. -- **Single inverter and BMS per OPTA.** The firmware reads one inverter and one BMS. Sites with multiple strings or battery racks need either multiple OPTAs or firmware extended to round-robin across slave IDs on the same RS-485 bus. -- **One dispatch command consumed per sample cycle.** `checkDispatch()` pops exactly one Note from `dispatch.qi` per sample cycle. If commands arrive faster than `sample_minutes`, for example, a utility DR event and a rate-schedule override queued within the same 5-minute inbound sync window — they backlog in the Notecard queue and are processed one per cycle, up to `sample_minutes` apart per command. In the default 1-minute sample cadence this gap is small, but at longer cadences or during rapid command sequences the backlog can cause unexpected sequential mode transitions. Production systems with higher command rates should drain the queue within a single cycle (loop `checkDispatch()` until it returns no Note) or use idempotent commands with expiry timestamps. -- **Dispatch state held in RAM only.** `g_commanded_mode` and `g_dr_expires_epoch` are stored in RAM. A power cycle, watchdog reset, or MCU fault clears the active dispatch: the device reverts to the TOU schedule (or `normal` if outside all configured windows) until the cloud system resends the command. The Notehub telemetry stream will reflect the mode change, but there is no automatic re-delivery of the original command. For dispatch-critical deployments where a commanded relay state must survive power events, persist the active mode and expiry epoch to the Notecard's nonvolatile storage (a `note.add` to a `.db` Notefile on the Notecard) and restore them on boot before the first `resolveMode()` call — taking care to discard an expired epoch rather than re-applying a stale command. -- **Dispatch commands have no authentication.** Any Notehub API caller with a valid token can queue a `dispatch.qi` Note. Production deployments should scope API tokens to the minimum required permissions and consider note-level signing or encryption for additional assurance. -- **The TOU autonomous schedule alone is not a full energy management strategy.** The firmware dispatches peak discharge based on the configured hour window, but it doesn't account for forecast PV generation, real-time spot prices, battery degradation, or multi-day SOC planning. It's the right starting point, not the finished product. - -**Production next steps:** -- Vendor-specific inverter profile builds: SolarEdge SunSpec, Fronius Solar API, Huawei SUN2000, Sungrow — each with the correct register addresses, scaling, and Modbus function codes. -- Modbus write support for inverters that accept export-cap or charge-limit commands over the bus, with appropriate safety interlocks. -- Local-time conversion via a configurable `tz_offset_hours` environment variable so the TOU schedule can be expressed in local hours. -- Multi-battery support: round-robin polling of up to N BMS units on the same RS-485 bus, with per-unit SOC tracking and aggregate discharge allocation. -- Fleet-level SOC and energy telemetry aggregated in Notehub → historian for PPA performance reporting: total kWh discharged per DR event, aggregate daily export, battery cycle count, etc. -- Over-the-air host firmware updates: [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) is supported on the STM32H7 MCU family (the OPTA's processor) but requires AUX wiring that Blues Wireless for OPTA does not currently break out. Host firmware updates remain local-only via USB-C until that hardware path changes. When it does, Outboard DFU enables pushing a new vendor register map or TOU algorithm to the entire fleet without a truck roll. +### Simplified for this POC + +**Demo Modbus register map.** The firmware reads four contiguous 16-bit registers from each device with hardcoded scaling and signedness. Real commercial inverters (SolarEdge, Fronius, SMA, Huawei SUN2000, Sungrow) and BMS units (BYD Battery-Box, PYLON, CATL) each publish their own Modbus maps with vendor-specific register addresses, scaling factors, and word orders. Commissioning against real hardware requires a vendor-specific firmware build. See the Notehub `reg_inv_base` / `reg_bms_base` environment variables as a first step, but per-vendor register maps will need code changes for scaling and signedness. + +**Single shared Modbus RTU bus.** The firmware uses one RS-485 physical segment with one set of serial parameters (`modbus_baud`, `modbus_parity`, `modbus_stop_bits`) shared by both the inverter and the BMS. Both devices must be configurable to the same baud rate, parity, and stop bits — a hard commissioning prerequisite. On real sites this constraint is commonly violated when inverter and BMS come from different vendors with different factory defaults. If the two devices cannot be brought to the same serial settings, this reference topology is unworkable without hardware modifications (a second UART or USB-to-RS-485 adapter) and matching firmware changes to address each device on its own independent serial port. + +**SOC guard hysteresis defaults are proof-of-concept values.** The firmware applies anti-chatter hysteresis at both ends of the SOC operating range: `soc_hyst_pct` (default 5 %) prevents discharge-relay chatter near the `soc_min_pct` floor, and `soc_max_hyst_pct` (default 3 %) prevents charge-relay chatter near the `soc_max_pct` ceiling. Both are starting points, not field-tuned values. BMS units with high-noise SOC reporting or slow charge recovery may need wider bands; units with tightly regulated reporting may need narrower ones. Tune both variables for each site based on observed SOC reading jitter during commissioning. Note that the belt-and-suspenders hard guard in `applyRelays()` retains the unmodified `soc_min_pct` as an absolute discharge floor — it is not subject to hysteresis, so a brief over-protection window between `soc_min_pct` and `soc_min_pct + soc_hyst_pct` is intentional and prevents the discharge relay from toggling on a borderline reading. + +**Relay wiring is application-specific.** This reference design assumes the inverter and BMS each expose a digital control input for the functions mapped to the relay outputs. Not every commercial product does. Many inverters accept grid-export enable/disable via Modbus write command rather than a contact input; in that case the relay output is redundant and the appropriate command needs to be added to the firmware. + +**TOU schedule is UTC-only.** Peak window start and end are configured in UTC hours. Operators must convert their local TOU peak window to UTC. A `tz_offset_hours` environment variable and a proper local-time calculation would be a straightforward improvement. + +**Autonomous TOU dispatch requires valid Notecard UTC time.** `resolveMode()` calls `currentUtcEpoch()`, which issues a `card.time` request and returns `0` if the Notecard has not yet completed a Notehub sync. On cold boot or after a power event before the Notecard re-acquires time, TOU window evaluation is suspended and the controller stays in `normal` mode. TOU windows resume automatically once a non-zero epoch is available. Design the commissioning workflow so the Notecard has synced at least once — confirming that `card.time` returns a non-zero `time` field — before relying on autonomous TOU behavior in the field. + +**Relay contacts assert enable inputs only — actual dispatch behavior is vendor-defined.** All control is via relay contact closures that assert or de-assert digital enable inputs on the field devices. Closing a relay enables a mode on the field device; the actual charge, discharge, and export behavior — ramp rates, power limits, setpoints — is determined entirely by the inverter and BMS firmware and their pre-commissioning configuration. This proof of concept does not command power setpoints, verify that a requested profile was executed, or close any control loop around actual site load or grid flow. Commissioning against a specific inverter and BMS model requires verifying that asserting each control input produces the expected operational response. + +**No Modbus writes.** The firmware reads inverter and BMS state but all control is via relay contact closures. Writing Modbus setpoints to the devices (target SOC, charge current limit, export cap) is intentionally out of scope — it requires a safety review for each device type and is a meaningful production enhancement, not a sensible starting point for a proof-of-concept. + +**Single inverter and BMS per OPTA.** The firmware reads one inverter and one BMS. Sites with multiple strings or battery racks need either multiple OPTAs or firmware extended to round-robin across slave IDs on the same RS-485 bus. + +**One dispatch command consumed per sample cycle.** `checkDispatch()` pops exactly one Note from `dispatch.qi` per sample cycle. If commands arrive faster than `sample_minutes`, for example, a utility DR event and a rate-schedule override queued within the same 5-minute inbound sync window — they backlog in the Notecard queue and are processed one per cycle, up to `sample_minutes` apart per command. In the default 1-minute sample cadence this gap is small, but at longer cadences or during rapid command sequences the backlog can cause unexpected sequential mode transitions. Production systems with higher command rates should drain the queue within a single cycle (loop `checkDispatch()` until it returns no Note) or use idempotent commands with expiry timestamps. + +**Dispatch state held in RAM only.** `g_commanded_mode` and `g_dr_expires_epoch` are stored in RAM. A power cycle, watchdog reset, or MCU fault clears the active dispatch: the device reverts to the TOU schedule (or `normal` if outside all configured windows) until the cloud system resends the command. The Notehub telemetry stream will reflect the mode change, but there is no automatic re-delivery of the original command. For dispatch-critical deployments where a commanded relay state must survive power events, persist the active mode and expiry epoch to the Notecard's nonvolatile storage (a `note.add` to a `.db` Notefile on the Notecard) and restore them on boot before the first `resolveMode()` call — taking care to discard an expired epoch rather than re-applying a stale command. + +**Dispatch commands have no authentication.** Any Notehub API caller with a valid token can queue a `dispatch.qi` Note. Production deployments should scope API tokens to the minimum required permissions and consider note-level signing or encryption for additional assurance. + +**The TOU autonomous schedule alone is not a full energy management strategy.** The firmware dispatches peak discharge based on the configured hour window, but it doesn't account for forecast PV generation, real-time spot prices, battery degradation, or multi-day SOC planning. It's the right starting point, not the finished product. + +### Production Next Steps + +Taking this proof-of-concept toward a production deployment means hardening the device for the specific inverters, batteries, and reporting obligations of a real PPA portfolio. The following extensions are the natural progression, roughly from the most immediately useful to the most infrastructure-dependent. + +**Vendor-specific inverter profile builds** are the first thing most deployments will need. Rather than a generic SunSpec read, ship dedicated profiles for SolarEdge SunSpec, the Fronius Solar API, Huawei SUN2000, and Sungrow — each with the correct register addresses, scaling factors, and Modbus function codes for that manufacturer's map. + +**Modbus write support** is the largest functional leap. Inverters that accept export-cap or charge-limit commands over the bus could be commanded directly rather than through relay enable inputs alone, but this must be gated behind appropriate safety interlocks and a per-device safety review. + +**Local-time conversion** is a small but high-value usability improvement: a configurable `tz_offset_hours` environment variable so the TOU schedule can be expressed in local hours instead of UTC, which is how operators actually think about peak windows. + +**Multi-battery support** extends the controller to sites with more than one battery rack. Round-robin polling of up to N BMS units on the same RS-485 bus, with per-unit SOC tracking and aggregate discharge allocation, would let a single OPTA service a larger installation. + +**Fleet-level telemetry aggregation** turns the raw event stream into reporting. Rolling SOC and energy telemetry up through Notehub into a historian supports PPA performance reporting — total kWh discharged per DR event, aggregate daily export, battery cycle count, and similar settlement-grade metrics. + +**Over-the-air host firmware updates** are the longest-horizon item, because they currently depend on a hardware path that isn't yet available. [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) is supported on the STM32H7 MCU family (the OPTA's processor) but requires AUX wiring that Blues Wireless for OPTA does not currently break out, so **host firmware updates remain local-only via USB-C until that hardware path changes.** When it does, Outboard DFU would enable pushing a new vendor register map or TOU algorithm to the entire fleet without a truck roll. ## 12. Summary From 232662a68b7461ca9e52bca86f43eeaa2dfb4e36 Mon Sep 17 00:00:00 2001 From: Rob Lauer Date: Tue, 2 Jun 2026 13:47:04 -0500 Subject: [PATCH 2/6] add notehub link --- 56-commercial-plug-load-after-hours-waste-dashboard/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/56-commercial-plug-load-after-hours-waste-dashboard/README.md b/56-commercial-plug-load-after-hours-waste-dashboard/README.md index 17d91c89..33982529 100644 --- a/56-commercial-plug-load-after-hours-waste-dashboard/README.md +++ b/56-commercial-plug-load-after-hours-waste-dashboard/README.md @@ -8,7 +8,7 @@ This reference application is intended to provide inspiration and help you get s -This project is a cellular-connected [energy savings](https://blues.com/energy-savings/) monitor that clips non-invasive CT (current transformer) clamps onto branch circuits in a commercial sub-panel, samples RMS current once a minute, and transmits hourly per-circuit profiles to the Blues cloud service, Notehub — giving energy consultants a view into which circuits are burning money at 2 AM, without ever touching the building's corporate network. +This project is a cellular-connected [energy savings](https://blues.com/energy-savings/) monitor that clips non-invasive CT (current transformer) clamps onto branch circuits in a commercial sub-panel, samples RMS current once a minute, and transmits hourly per-circuit profiles to the [Blues Notehub](https://blues.com/notehub/) cloud service — giving energy consultants a view into which circuits are burning money at 2 AM, without ever touching the building's corporate network. ## 1. Project Overview From c92be86ccdcedea4d879761553d797325c63998f Mon Sep 17 00:00:00 2001 From: Rob Lauer Date: Tue, 2 Jun 2026 13:47:24 -0500 Subject: [PATCH 3/6] review of 57 --- 57-propane-lpg-tank-fill-telemetry/README.md | 46 +++++++------------- 1 file changed, 15 insertions(+), 31 deletions(-) diff --git a/57-propane-lpg-tank-fill-telemetry/README.md b/57-propane-lpg-tank-fill-telemetry/README.md index 5fcd8b39..6f22cc03 100644 --- a/57-propane-lpg-tank-fill-telemetry/README.md +++ b/57-propane-lpg-tank-fill-telemetry/README.md @@ -8,37 +8,29 @@ This reference application is intended to provide inspiration and help you get s -This project is a [truck roll reduction](https://blues.com/truck-roll-reduction/) reference design that gives propane dealers per-tank fill telemetry across their entire delivery territory — replacing fixed-schedule routes with demand-driven dispatch and projecting days-until-empty for every tank in the fleet. A level sensor at the tank's existing gauge port and a temperature probe on the tank shell turn each tank into a self-reporting asset; a single [Notecard for Skylo](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) — one module carrying cellular, WiFi, and Skylo satellite radios that fails over between them automatically — carries the data from the tank three minutes outside town just as readily as from the remote mountain cabin beyond any cell tower. One SKU and one firmware image cover every site type in the territory. Specific part numbers, gauge-port plumbing, and the wiring details land in §4 and §5 — the lead intentionally stays at the "what it does and why" level. +This project is a [truck roll reduction](https://blues.com/truck-roll-reduction/) reference design that gives propane dealers per-tank fill telemetry across their entire delivery territory — replacing fixed-schedule routes with demand-driven dispatch and projecting days-until-empty for every tank in the fleet. A level sensor at the tank's existing gauge port and a temperature probe on the tank shell turn each tank into a self-reporting asset; a single [Notecard for Skylo](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) (one module carrying cellular, WiFi, and Skylo satellite radios that fails over between them automatically) carries the data from the tank three minutes outside town just as readily as from the remote mountain cabin beyond any cell tower. One SKU and one firmware image cover every site type in the territory. ## 1. Project Overview - -**The problem.** Most propane dealers still run their delivery routes on a fixed calendar: every six weeks, every tank gets a truck. That schedule exists not because it matches demand, but because dealers have no way to know which tanks actually need filling. The result is trucks rolling to tanks that are at 60 % (wasted capacity, wasted diesel) and tanks at remote farm properties that run dry between scheduled visits (angry customer, weekend emergency call). Neither failure is exotic — they're structural consequences of not having fill-level data. +**The problem.** Most propane dealers still run their delivery routes on a fixed calendar: every six weeks, every tank gets a truck. That schedule exists not because it matches demand, but because dealers have no way to know which tanks actually need filling. The result is trucks rolling to tanks that are at 60% and tanks at remote farm properties that run dry between scheduled visits. Neither failure is exotic — they're structural consequences of not having fill-level data. The root cause is infrastructure. A propane tank sits in a field, on a farm, at a cabin, at a rural business — almost never near a WiFi access point the dealer can use, and often in areas where cellular is marginal to nonexistent. The tank itself is a sealed pressure vessel with no native communication capability. Retrofitting telemetry means solving a connectivity problem that varies by site, a sensor problem specific to LP (liquefied petroleum) gas vessels, and a data problem — turning raw fill readings into actionable dispatch intelligence. -This project solves all three. A weatherproof electronics enclosure mounted on a post or bracket **outside the AHJ-defined classified area**, connected by field wiring to a 4-20 mA LP gauge-port float transmitter at the tank's existing dip-tube gauge port and a DS18B20 temperature probe strapped to the tank shell. The device wakes every 15 minutes, reads the transmitter current and tank temperature, converts the transmitter's linear 4–20 mA output directly to fill percentage, updates a smoothed daily consumption rate, and reports a daily summary to Notehub. When fill drops below a configurable low-fill threshold, an alert fires immediately. The dealer's dispatch system sees fill %, gallons remaining, and projected days-until-empty for every tank in the fleet — enough to replace the calendar with a demand-driven route that only rolls a truck when a tank actually needs it. +This project solves all three. **A weatherproof electronics enclosure mounted on a post or bracket outside the AHJ-defined classified area**, connected by field wiring to a 4-20 mA LP gauge-port float transmitter at the tank's existing dip-tube gauge port and a DS18B20 temperature probe strapped to the tank shell. The device wakes every 15 minutes, reads the transmitter current and tank temperature, converts the transmitter's linear 4–20 mA output directly to fill percentage, updates a smoothed daily consumption rate, and reports a daily summary to the [Blues Notehub](https://blues.com/notehub/) cloud service. When fill drops below a configurable low-fill threshold, an alert fires immediately. The dealer's dispatch system sees fill %, gallons remaining, and projected days-until-empty for every tank in the fleet — enough to replace the calendar with a demand-driven route that only rolls a truck when a tank actually needs it. -**Why Notecard for Skylo.** Propane tanks are at farms, cabins, rural businesses, and residential properties — most with no customer WiFi the dealer can use, and many in areas where cellular coverage is spotty to nonexistent. A dealer network spans all of these site types and can't afford a different hardware solution for each one. The [Notecard for Skylo](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) (NOTE-NBGLWX) carries three radios on one M.2 module — cellular (LTE-M / NB-IoT / GPRS), WiFi, and satellite over the [Skylo](https://www.skylo.tech/) non-terrestrial network (NTN) — and selects among them automatically. The firmware sets a single [`card.transport`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-transport) preference of `wifi-cell-ntn`: prefer WiFi where a provisioned AP happens to be in range (the rare residential tank), fall back to cellular (the de-facto primary across the bulk of the territory), and fall back again to Skylo satellite at the remote 5 % of sites — mountain cabins, properties beyond any cell tower. Failover is handled inside the Notecard; the host firmware never branches on which network is live. That collapses what used to be a two-device decision — a cellular Notecard for in-coverage tanks plus a separate satellite add-on for the rest — into a single part number, a single antenna kit, and a single firmware image that deploys unchanged across the entire fleet. The Notecard for Skylo ships with an active global SIM including 500 MB of cellular data and 10 years of service, plus 10 KB of bundled Skylo satellite data — no activation fees and no monthly per-SIM commitment. There is nothing to swap when a site turns out to have weaker coverage than the survey suggested: the same board that runs on cellular near town automatically reaches the Skylo network at the cabin. See [§4](#4-hardware-requirements), [§5](#5-wiring-and-assembly), [§6](#6-notehub-setup), and [§11](#11-limitations-and-next-steps) for the satellite operational details. +**Why Notecard for Skylo.** Propane tanks are at farms, cabins, rural businesses, and residential properties — most with no customer WiFi the dealer can use, and many in areas where cellular coverage is spotty to nonexistent. A dealer network spans all of these site types and can't afford a different hardware solution for each one. [Notecard for Skylo](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) (NOTE-NBGLWX) carries three radios on one M.2 module — cellular (LTE-M / NB-IoT / GPRS), WiFi, and satellite over the [Skylo](https://www.skylo.tech/) non-terrestrial network (NTN) — and selects among them automatically. The firmware sets a single [`card.transport`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-transport) preference of `wifi-cell-ntn`: prefer WiFi where a provisioned AP happens to be in range (the rare residential tank), fall back to cellular (the de-facto primary across the bulk of the territory), and fall back again to Skylo satellite at remote sites. Failover is handled by the Notecard; the host firmware never branches on which network is live. That collapses what used to be a two-device decision — a cellular Notecard for in-coverage tanks plus a separate satellite add-on for the rest — into a single part number, a single antenna kit, and a single firmware image that deploys unchanged across the entire fleet. Notecard for Skylo ships with an active global SIM including 500 MB of cellular data and 10 years of service, plus 10 KB of bundled Skylo satellite data — no activation fees and no monthly per-SIM commitment. There is nothing to swap when a site turns out to have weaker coverage than the survey suggested: the same board that runs on cellular near town automatically reaches the Skylo network at the cabin. **Deployment scenario.** A weatherproof NEMA 4X enclosure mounted on a separate post, wall, or bracket **outside the AHJ-defined classified area** (see the safety notice in §4), powered by a solar-charged 12 V sealed lead-acid battery. A 4-20 mA LP gauge-port float transmitter (Rochester Sensors M6300-LP Magnetel® gauge + R6315-12 transmitter, or equivalent) connects at the tank's existing 1¼″ NPT dip-tube gauge port; field wiring from the transmitter runs to the electronics enclosure outside the hazardous boundary. A waterproof DS18B20 temperature probe is clamped to the tank shell and logged in daily summary Notes for seasonal demand analytics. The Notecard for Skylo's antenna cables exit the enclosure to outdoor-mounted antennas with a clear sky view — the same Skylo-certified antenna carries both cellular and satellite, so where cellular coverage is absent the board falls back to the Skylo NTN satellite network automatically over the same Notehub project, with no antenna swap and no firmware changes. No modifications to the tank itself, no on-site internet infrastructure, and no OEM cooperation required. - - -**Sensor architecture Note — this document is a float-transmitter variant.** The original project specification called for a low-power ultrasonic or pressure level sensor with a temperature probe used for vapor-pressure compensation in the fill measurement path. **This document covers a 4–20 mA float-transmitter variant that intentionally departs from that specification; it should be read as one concrete implementation path for this use case, not as a complete delivery of the original brief.** After evaluating both approaches specifically for LP gas tank service (see the full rationale in [§7](#7-firmware-design)), this variant uses a Rochester Sensors float-type 4–20 mA transmitter. The float tracks the physical liquid propane surface directly, making its 4–20 mA output inherently temperature-independent — no vapor-pressure or density correction is needed or applied in firmware. The DS18B20 temperature probe is retained and its reading is included in every daily summary Note for cloud-side seasonal demand analytics, but temperature is **not** an input to the fill calculation. The principal trade-off accepted by this architecture change is a continuously-powered 4–20 mA current loop (the dominant load in the power budget); the implications are discussed in [§11](#11-limitations-and-next-steps). - - - ## 2. System Architecture - ![System architecture: propane tank with 4–20 mA float transmitter and DS18B20 → edge enclosure outside hazardous area → Notecard for Skylo (cellular / WiFi / satellite) → Notehub → dispatch / ERP / time-series DB](diagrams/01-system-architecture.svg) **Device-side responsibilities.** Inside the post-mounted enclosure, the Cygnet STM32 host on the Notecarrier CX wakes every `sample_interval_min` (default 15 minutes), reads the 4-20 mA float transmitter and the DS18B20 shell probe, converts the linear current straight to fill percentage and gallons remaining, and updates a smoothed consumption-rate estimate. If a threshold trips, it queues an alert Note right then; otherwise it just goes back to sleep. Once per `report_interval_hr` (default 24 hours) it ships a templated summary carrying current fill %, fill gallons, minimum fill seen in the window, window-averaged temperature, daily consumption rate, and projected days-until-empty. Between wakes the host is cut entirely via [`card.attn`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-attn) and the Notecard for Skylo idles at ~8 µA — every queued [Note](https://dev.blues.io/api-reference/glossary/#note) travels over I²C with no JSON hand-rolling and no AT commands. -**Notecard responsibilities.** The Notecard for Skylo runs the same playbook regardless of which radio is live: hold Notes in its on-device queue, open a session on the [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence, and push any `sync:true` alert through immediately. The `card.transport` `wifi-cell-ntn` preference set at boot decides the path automatically — WiFi where a provisioned AP is reachable, cellular at the bulk of sites, and Skylo satellite at the remote 5 % of tanks beyond any tower — with no firmware branching. (Satellite operation requires the antenna outdoors with a clear sky view; see §4 and §5.) Either way, the same module pulls [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) from Notehub on every inbound sync, so a dispatcher can retune transmitter calibration or alert thresholds for any tank in the fleet without anyone driving out to it. +**Notecard responsibilities.** The Notecard for Skylo runs the same playbook regardless of which radio is live: hold Notes in its on-device queue, open a session on the [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence, and push any `sync:true` alert through immediately. The `card.transport` `wifi-cell-ntn` preference set at boot decides the path automatically — WiFi where a provisioned AP is reachable, cellular at the bulk of sites, and Skylo satellite at remote sites — with no firmware branching. Either way, the same module pulls [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) from Notehub on every inbound sync, so a dispatcher can retune transmitter calibration or alert thresholds for any tank in the fleet without anyone driving out to it. **Notehub responsibilities.** Events land in [Notehub](https://dev.blues.io/notehub/notehub-walkthrough/) from whatever transport carried them, where they're ingested, stored, and fanned out through project-level routes. Per-fleet [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) are how a single firmware image services tanks of every capacity — the tank size and sensor calibration live in Notehub, not in compiled constants. [Smart Fleets](https://dev.blues.io/notehub/notehub-walkthrough/#using-smart-fleet-rules) make it easy to group tanks by territory, capacity class, or customer type so the right calibration values flow to the right tanks automatically. @@ -46,7 +38,6 @@ This project solves all three. A weatherproof electronics enclosure mounted on a ## 3. Technical Summary - Clone this repository, build the firmware, and deploy: 1. **Get the firmware onto your Notecarrier CX:** @@ -90,7 +81,6 @@ Here is a sample Note this device emits: ## 4. Hardware Requirements - | Part | Qty | Rationale | |------|-----|-----------| | [Notecarrier CX](https://shop.blues.com/products/notecarrier-cx?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Integrated carrier with onboard Cygnet STM32 host — handles the 12-bit ADC for the 4-20 mA loop and OneWire for the temperature probe with no external MCU needed. | @@ -124,14 +114,13 @@ Here is a sample Note this device emits: ## 5. Wiring and Assembly - ![Wiring: 4–20 mA float transmitter with 120 Ω shunt → A0; DS18B20 with 4.7 kΩ pull-up → D2; 24 V boost converter for transmitter loop; solar + SLA dual-rail power chain (5 V → +VBAT, 24 V → loop)](diagrams/02-wiring-assembly.svg) All Notecarrier CX host I/O lands on its dual 16-pin header. The Notecard for Skylo seats into the M.2 slot. The Mojo sits inline between the 5 V step-down and the Notecarrier +VBAT pad during bench validation only; it is not deployed in the field. -**Enclosure placement first.** Blues Notecard and Notecarrier CX electronics must be installed **outside** the classified-area boundary defined by NFPA 58 and the authority having jurisdiction — confirm that boundary with the installing LP gas technician before drilling cable-gland holes or positioning the enclosure (see the safety notice in §4). +**Enclosure placement first.** Blues Notecard and Notecarrier CX electronics must be installed **outside** the classified-area boundary defined by NFPA 58 and the authority having jurisdiction — confirm that boundary with the installing LP gas technician before drilling cable-gland holes or positioning the enclosure. @@ -244,7 +233,6 @@ No additional module or wiring is required for satellite operation — the Notec ## 6. Notehub Setup - 1. **Create a project.** Sign up at [notehub.io](https://notehub.io) and create a project. Copy the [ProductUID](https://dev.blues.io/notehub/notehub-walkthrough/#finding-a-productuid) and paste it into the firmware as `PRODUCT_UID`. 2. **Claim the Notecard.** Power the unit; on first cellular session the Notecard associates with the project automatically. Verify the device appears in the Notehub device list and shows a recent session. @@ -281,7 +269,6 @@ No additional module or wiring is required for satellite operation — the Notec ## 7. Firmware Design - Main sketch: [`firmware/propane_tank_telemetry/propane_tank_telemetry.ino`](firmware/propane_tank_telemetry/propane_tank_telemetry.ino). Sensor math, fill-level calculation, and consumption tracking are factored into [`firmware/propane_tank_telemetry/propane_tank_telemetry_helpers.h`](firmware/propane_tank_telemetry/propane_tank_telemetry_helpers.h). Dependencies: @@ -485,7 +472,6 @@ delay((uint32_t)SAMPLE_INTERVAL_MIN * 60UL * 1000UL); ## 8. Data Flow - ![Data flow: 15-min sample of 4–20 mA loop current → fill % and consumption EWMA → two rules (low_fill, sensor_fault) → tank_alert.qo (sync:true) and tank_status.qo (daily templated) → Notehub routes](diagrams/03-data-flow.svg) Every `sample_interval_min` (default 15 min) the Cygnet wakes, reads the LP gauge-port level transmitter and DS18B20 temperature probe, converts the transmitter current directly to fill %, updates the consumption EWMA, and evaluates three alert conditions. @@ -507,7 +493,6 @@ Every `sample_interval_min` (default 15 min) the Cygnet wakes, reads the LP gaug ## 9. Validation and Testing - **Expected cadence in steady state.** A correctly-functioning unit on a residential propane tank should produce one `tank_status.qo` event per day and zero `tank_alert.qo` events during normal operation. During commissioning, expect a `sensor_fault` event if the transmitter wiring is incomplete, and low-fill alerts if the tank happens to already be below threshold. **Bench validation before field deployment.** To simulate the transmitter on the bench, drive the A0 analog input with a variable voltage in the 0.48–2.40 V range (a potentiometer from the 3.3 V rail to GND, or a bench DC supply, works). Confirm the firmware maps 0.48 V to 0 % fill (4 mA), 1.44 V to 50 % fill (12 mA), and 2.40 V to 100 % fill (20 mA). Verify the open-circuit condition (drive A0 to 0 V or below 0.42 V, corresponding to < 3.5 mA) emits a `sensor_fault` alert Note. For the DS18B20, confirm the firmware reports a valid temperature on the serial port and that a missing probe produces `NAN` (which becomes the `-9999` sentinel in summary Notes) rather than a garbage reading. @@ -530,7 +515,6 @@ Note: the 4-20 mA transmitter loop is powered from the 24 V boost converter circ ## 10. Troubleshooting - **No device appearing in Notehub after power-up.** - Confirm the Notecard MAIN u.FL antenna is connected to an external antenna (not left stubbed internally). A missing or unplugged antenna will prevent cellular registration entirely. - Check that `PRODUCT_UID` is defined in the firmware and matches the UUID shown in Notehub under **Projects → ProjectUID**. @@ -569,23 +553,23 @@ Note: the 4-20 mA transmitter loop is powered from the 24 V boost converter circ This reference design covers the common case of a dealer instrumenting a tank fleet for demand-driven dispatch — float transmitter at the gauge port, temperature probe on the shell, cellular (or satellite) backhaul. The trade-offs below are deliberate scope choices; each has a clear extension path for a production rollout. -**Simplified for the POC:** +### Simplified for the POC -- **Continuously-powered current loop.** The Rochester Sensors M6300-LP + R6315-12 and similar LP gauge-port float transmitters use a **continuously-powered 4–20 mA current loop**. Powered from the 24 V boost converter, the loop draws 96–480 mW from the 24 V rail (4 mA × 24 V to 20 mA × 24 V); accounting for the boost converter's ≈ 87 % efficiency, the draw on the 12 V system rail ranges from ≈ 110 mW (empty tank) to ≈ 550 mW (full tank) continuously. This is the dominant load in the system power budget. At worst case (full tank, 20 mA), the transmitter loop draws ≈ 550 mW for 24 h = ≈ 13.2 Wh/day from the 12 V rail; a 10 W solar panel at ≥ 4 h/day peak sun yields ≈ 40 Wh — well above the combined transmitter and electronics load for mid-latitude deployments. In low-sun environments or high-latitude winter deployments, size the panel to 20 W. Note: the tank spends most of its time between 20–80 % fill (8–16 mA), so the average draw is typically 250–370 mW, materially below the 550 mW worst case. +**Continuously-powered current loop.** The Rochester Sensors M6300-LP + R6315-12 and similar LP gauge-port float transmitters use a **continuously-powered 4–20 mA current loop**. Powered from the 24 V boost converter, the loop draws 96–480 mW from the 24 V rail (4 mA × 24 V to 20 mA × 24 V); accounting for the boost converter's ≈ 87 % efficiency, the draw on the 12 V system rail ranges from ≈ 110 mW (empty tank) to ≈ 550 mW (full tank) continuously. This is the dominant load in the system power budget. At worst case (full tank, 20 mA), the transmitter loop draws ≈ 550 mW for 24 h = ≈ 13.2 Wh/day from the 12 V rail; a 10 W solar panel at ≥ 4 h/day peak sun yields ≈ 40 Wh — well above the combined transmitter and electronics load for mid-latitude deployments. In low-sun environments or high-latitude winter deployments, size the panel to 20 W. Note: the tank spends most of its time between 20–80 % fill (8–16 mA), so the average draw is typically 250–370 mW, materially below the 550 mW worst case. -- **Fill-gallons calculation uses a linear scale.** `computeFillGal` computes `fill_gal = (fill_pct / 100) × tank_capacity_gal`. The horizontal-cylinder cross-section introduces a small nonlinearity between liquid height and volume (the relationship curves near the top and bottom of the tank). This nonlinearity is not corrected in firmware — an additional geometry correction table keyed to `tank_inner_diameter_in` could improve accuracy at fill levels below ~20 % or above ~80 %, at the cost of an additional environment variable and more complex calibration. For the typical operating range (20–80 % fill) the linear-scale error is small. +**Fill-gallons calculation uses a linear scale.** `computeFillGal` computes `fill_gal = (fill_pct / 100) × tank_capacity_gal`. The horizontal-cylinder cross-section introduces a small nonlinearity between liquid height and volume (the relationship curves near the top and bottom of the tank). This nonlinearity is not corrected in firmware — an additional geometry correction table keyed to `tank_inner_diameter_in` could improve accuracy at fill levels below ~20 % or above ~80 %, at the cost of an additional environment variable and more complex calibration. For the typical operating range (20–80 % fill) the linear-scale error is small. -- **Satellite (NTN) operation requires an unobstructed sky-view antenna and an initial non-NTN sync.** The Notecard for Skylo adds satellite with no extra module, but to use the Skylo link the Skylo-certified MAIN antenna must be mounted outdoors with a clear view of the sky (northern hemisphere: the southern sky) — it cannot reach the satellite from beneath a metal obstruction. Satellite operation is also opt-in at the Notecard level: the firmware enables it by setting `card.transport` to `wifi-cell-ntn`, and the board must complete at least one initial non-NTN (cellular or WiFi) sync to associate with Notehub and register Notefile templates before NTN works — commission each unit where it has terrestrial coverage. Over satellite, expect alert latency in minutes (not seconds), keep each Note within the NTN payload budget, and remember that inbound syncs draw on the bundled 10 KB satellite allocation. At remote tank sites, confirm a suitable sky-view antenna location before relying on the satellite path. +**Satellite (NTN) operation requires an unobstructed sky-view antenna and an initial non-NTN sync.** The Notecard for Skylo adds satellite with no extra module, but to use the Skylo link the Skylo-certified MAIN antenna must be mounted outdoors with a clear view of the sky (northern hemisphere: the southern sky) — it cannot reach the satellite from beneath a metal obstruction. Satellite operation is also opt-in at the Notecard level: the firmware enables it by setting `card.transport` to `wifi-cell-ntn`, and the board must complete at least one initial non-NTN (cellular or WiFi) sync to associate with Notehub and register Notefile templates before NTN works — commission each unit where it has terrestrial coverage. Over satellite, expect alert latency in minutes (not seconds), keep each Note within the NTN payload budget, and remember that inbound syncs draw on the bundled 10 KB satellite allocation. At remote tank sites, confirm a suitable sky-view antenna location before relying on the satellite path. -- **Electronics must be outside the classified area; IS barrier may be required.** Blues Notecard and Notecarrier CX electronics are not rated for hazardous locations and must be installed outside the classified area boundary defined by NFPA 58 and the authority having jurisdiction. For 4–20 mA wiring that crosses the classified-area boundary, the AHJ may require a listed intrinsic-safety (IS) barrier in the loop circuit between the tank-side transmitter and the enclosure-side electronics. Transmitter selection, fitting compatibility, classified-area boundary determination, and any IS barrier requirement are outside the scope of the electronics design. Any connection to a propane pressure vessel must comply with NFPA 58, applicable codes, and be performed by a licensed LP gas technician. +**Electronics must be outside the classified area; IS barrier may be required.** Blues Notecard and Notecarrier CX electronics are not rated for hazardous locations and must be installed outside the classified area boundary defined by NFPA 58 and the authority having jurisdiction. For 4–20 mA wiring that crosses the classified-area boundary, the AHJ may require a listed intrinsic-safety (IS) barrier in the loop circuit between the tank-side transmitter and the enclosure-side electronics. Transmitter selection, fitting compatibility, classified-area boundary determination, and any IS barrier requirement are outside the scope of the electronics design. Any connection to a propane pressure vessel must comply with NFPA 58, applicable codes, and be performed by a licensed LP gas technician. -- **Consumption rate requires stable readings over time.** The EWMA consumption rate is meaningful only after several days of operation. On first deployment, `days_until_empty` may be unreliable until the EWMA has converged. The firmware initializes consumption to zero and does not report `days_until_empty` until at least two consecutive valid fill readings exist. +**Consumption rate requires stable readings over time.** The EWMA consumption rate is meaningful only after several days of operation. On first deployment, `days_until_empty` may be unreliable until the EWMA has converged. The firmware initializes consumption to zero and does not report `days_until_empty` until at least two consecutive valid fill readings exist. -- **No flow meter.** Consumption rate is estimated from successive fill readings — a delta-volume over delta-time approximation. This is accurate enough for daily route planning but not for billing or leak detection at high precision. A turbine or ultrasonic flow meter at the regulator outlet would give direct consumption measurement; integration would require an additional pulse-counting or analog input channel. +**No flow meter.** Consumption rate is estimated from successive fill readings — a delta-volume over delta-time approximation. This is accurate enough for daily route planning but not for billing or leak detection at high precision. A turbine or ultrasonic flow meter at the regulator outlet would give direct consumption measurement; integration would require an additional pulse-counting or analog input channel. -- **Mojo is bench-validation equipment only.** The firmware does not read the Mojo's LTC2959 coulomb counter at runtime. Adding cumulative mAh to the daily summary is a straightforward extension if fleet-level power telemetry is useful for the dealer's operations team. +**Mojo is bench-validation equipment only.** The firmware does not read the Mojo's LTC2959 coulomb counter at runtime. Adding cumulative mAh to the daily summary is a straightforward extension if fleet-level power telemetry is useful for the dealer's operations team. -**Production next steps:** +### Production Next Steps - Transmitter calibration tool — a Notehub JSONata route transform that reads `transmitter_ma` from the first three Notes after provisioning and auto-suggests a `sensor_full_ma` correction, removing the manual commissioning step. - Refill event detection: when `fill_pct` increases by more than 10 % in a single sample cycle, emit a `refill_detected` Note with the pre- and post-fill readings. This lets the dealer's billing system close the loop on deliveries without a separate ticket. From 0a74543e5de9ece3ff0b75a5e447076da37166be Mon Sep 17 00:00:00 2001 From: Rob Lauer Date: Tue, 2 Jun 2026 13:53:07 -0500 Subject: [PATCH 4/6] get rid of "the" before notecard for skylo (most of the time) --- .../README.md | 26 +++++++------- 57-propane-lpg-tank-fill-telemetry/README.md | 34 +++++++++---------- .../README.md | 32 ++++++++--------- .../README.md | 20 +++++------ .../README.md | 8 ++--- .../README.md | 20 +++++------ .../README.md | 24 ++++++------- .../README.md | 12 +++---- .../README.md | 2 +- .../README.md | 20 +++++------ .../README.md | 12 +++---- .../README.md | 10 +++--- .../README.md | 10 +++--- .../README.md | 14 ++++---- 14 files changed, 122 insertions(+), 122 deletions(-) diff --git a/53-municipal-wastewater-lift-station-monitor/README.md b/53-municipal-wastewater-lift-station-monitor/README.md index 0a826721..60e71a7b 100644 --- a/53-municipal-wastewater-lift-station-monitor/README.md +++ b/53-municipal-wastewater-lift-station-monitor/README.md @@ -20,11 +20,11 @@ This project is that watcher. It straps to the inside of the station, samples th **Why Notecard for Skylo.** The wireless-first architecture here isn't a convenience — it's a necessity. Lift stations sit in concrete vaults underground, often with no AC power outlet in the vault itself (power runs to the pump control panel, not a wall socket). They're geographically distributed across a municipality in a pattern that matches the sewer network, not the municipal network — there's no fiber running to a roadside pump cabinet, and there's no corporate WiFi AP that can reach through a concrete lid to a sensor inside. Utility supervisors would need to deploy and maintain a WiFi access point at every single station to achieve what one Notecard covers automatically. -The [Notecard for Skylo](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) (NOTE-NBGLWX) carries three radios on one M.2 module — cellular (LTE-M / NB-IoT / GPRS), WiFi, and satellite over the [Skylo](https://www.skylo.tech/) non-terrestrial network (NTN) — and selects among them automatically. The firmware sets a single [`card.transport`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-transport) preference of `wifi-cell-ntn`: prefer WiFi where an accessible AP happens to be in range (rare for a sealed vault), fall back to cellular (the de-facto primary at the vast majority of municipal infrastructure), and fall back again to Skylo satellite at stations on the fringe of the service territory, beyond the reach of any cellular carrier. Failover is handled inside the Notecard; the host firmware never branches on which network is live. That collapses what used to be a two-SKU decision — a cellular Notecard for in-coverage stations, a satellite device for the rest — into a single part number, a single antenna kit, and a single firmware image that deploys unchanged across the entire fleet. There is nothing to swap when a station turns out to have weaker coverage than the survey suggested: the same board that runs on cellular downtown automatically reaches the Skylo network at the rural lift station. +[Notecard for Skylo](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) (NOTE-NBGLWX) carries three radios on one M.2 module — cellular (LTE-M / NB-IoT / GPRS), WiFi, and satellite over the [Skylo](https://www.skylo.tech/) non-terrestrial network (NTN) — and selects among them automatically. The firmware sets a single [`card.transport`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-transport) preference of `wifi-cell-ntn`: prefer WiFi where an accessible AP happens to be in range (rare for a sealed vault), fall back to cellular (the de-facto primary at the vast majority of municipal infrastructure), and fall back again to Skylo satellite at stations on the fringe of the service territory, beyond the reach of any cellular carrier. Failover is handled inside the Notecard; the host firmware never branches on which network is live. That collapses what used to be a two-SKU decision — a cellular Notecard for in-coverage stations, a satellite device for the rest — into a single part number, a single antenna kit, and a single firmware image that deploys unchanged across the entire fleet. There is nothing to swap when a station turns out to have weaker coverage than the survey suggested: the same board that runs on cellular downtown automatically reaches the Skylo network at the rural lift station. -**Deployment scenario.** A sealed NEMA 4X enclosure mounted **inside the lift station's above-grade control cabinet**, powered from the 120 VAC control circuit that already powers the pump starters. The specified Blues hardware and NEMA 4X ABS enclosure are **not** rated for hazardous (classified) locations. Wet wells and sealed vaults can accumulate methane and hydrogen sulfide — both potentially classified atmospheres under NFPA 820 / NEC Article 820. Do not install this hardware inside the wet well or any classified-atmosphere zone. If your jurisdiction classifies the vault interior as a hazardous location, any hardware in that zone must be rated for the classification; consult a licensed electrical engineer before proceeding. Sensor cables enter through conduit fittings: one multiconductor cable to the submersible level transducer in the wet well, two split-core CT jaws clamped around the pump motor supply conductors inside the control panel, and one float switch cable to a new dedicated high-water alarm float switch hung in the wet well alongside the station's existing level floats. No station modification is required beyond adding three sensor connections to the existing control wiring. The Notecard for Skylo's antenna cables exit through a conduit fitting to outdoor-mounted antennas on the cabinet exterior or above-grade access point — the same Skylo-certified antenna carries both cellular and satellite, so no antenna swap is needed if a station ends up relying on the satellite link. +**Deployment scenario.** A sealed NEMA 4X enclosure mounted **inside the lift station's above-grade control cabinet**, powered from the 120 VAC control circuit that already powers the pump starters. The specified Blues hardware and NEMA 4X ABS enclosure are **not** rated for hazardous (classified) locations. Wet wells and sealed vaults can accumulate methane and hydrogen sulfide — both potentially classified atmospheres under NFPA 820 / NEC Article 820. Do not install this hardware inside the wet well or any classified-atmosphere zone. If your jurisdiction classifies the vault interior as a hazardous location, any hardware in that zone must be rated for the classification; consult a licensed electrical engineer before proceeding. Sensor cables enter through conduit fittings: one multiconductor cable to the submersible level transducer in the wet well, two split-core CT jaws clamped around the pump motor supply conductors inside the control panel, and one float switch cable to a new dedicated high-water alarm float switch hung in the wet well alongside the station's existing level floats. No station modification is required beyond adding three sensor connections to the existing control wiring. Notecard for Skylo's antenna cables exit through a conduit fitting to outdoor-mounted antennas on the cabinet exterior or above-grade access point — the same Skylo-certified antenna carries both cellular and satellite, so no antenna swap is needed if a station ends up relying on the satellite link. ## 2. System Architecture @@ -32,7 +32,7 @@ The [Notecard for Skylo](https://shop.blues.com/products/notecard-for-skylo?utm_ **Device-side responsibilities.** Inside the above-grade cabinet, the Cygnet STM32L433 host on the Notecarrier CX wakes once a minute via [`card.attn`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-attn), reads three sensor types across four inputs (level, CT1, CT2, float switch), and walks the three fault rules before the wet well can shift more than an inch or two. The Notecard sits next to it on I²C — no AT commands, no modem state machine, no serial buffers to babysit. Anything that has to survive the next 60-second power-cut (the previous level reading, alert cooldowns, summary accumulators) gets persisted into the Notecard's flash via `NotePayloadSaveAndSleep` / `NotePayloadRetrieveAfterSleep`, so the host can lose power between samples and pick up exactly where it left off. -**Notecard responsibilities.** The Notecard for Skylo runs the same playbook regardless of which radio is live: queue [Notes](https://dev.blues.io/api-reference/glossary/#note) locally, ship them on the [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence (default 60 minutes), and push any `sync:true` alert to the head of the queue for the next available session. The `card.transport` `wifi-cell-ntn` preference set at boot decides the path automatically: on cellular that means a Note in flight 15–60 seconds after the host queues it; when the unit has fallen back to satellite it means first-in-line for the next Skylo session, which takes a few minutes rather than seconds. The same Notecard also distributes [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) from Notehub on every inbound sync, so a utility supervisor can retune level setpoints, current thresholds, or rising-rate sensitivity for the whole fleet from a browser — no firmware reflash, no vault lid lifted. +**Notecard responsibilities.** Notecard for Skylo runs the same playbook regardless of which radio is live: queue [Notes](https://dev.blues.io/api-reference/glossary/#note) locally, ship them on the [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence (default 60 minutes), and push any `sync:true` alert to the head of the queue for the next available session. The `card.transport` `wifi-cell-ntn` preference set at boot decides the path automatically: on cellular that means a Note in flight 15–60 seconds after the host queues it; when the unit has fallen back to satellite it means first-in-line for the next Skylo session, which takes a few minutes rather than seconds. The same Notecard also distributes [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) from Notehub on every inbound sync, so a utility supervisor can retune level setpoints, current thresholds, or rising-rate sensitivity for the whole fleet from a browser — no firmware reflash, no vault lid lifted. **Notehub responsibilities.** The Notecard's embedded global SIM and bundled Skylo satellite allocation hand events off to [Notehub](https://notehub.io), which timestamps and stores every one and applies project-level [routes](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub). Alerts and summaries land in separate [Notefiles](https://dev.blues.io/api-reference/glossary/#notefile) by design — `lift_alert.qo` can fan out to PagerDuty or SMS while `lift_summary.qo` lands in a long-term analytics store, with no filter logic in the route itself. [Smart Fleets](https://dev.blues.io/notehub/notehub-walkthrough/#using-smart-fleet-rules) make it easy to group stations by service zone or pump type while still allowing per-station overrides for the one vault that always reads a little funny. @@ -48,11 +48,11 @@ The same Notecard for Skylo runs the same firmware everywhere, but at stations t **Payload discipline.** The Skylo NTN link enforces a hard 256-byte maximum per Note; Notes exceeding this limit are silently dropped by the satellite network. The [`note.template`](https://dev.blues.io/api-reference/notecard-api/note-requests/#note-template) encoding used by this firmware (with `format:"compact"` and a numeric `port`) keeps both `lift_alert.qo` and `lift_summary.qo` well within that ceiling. Do not add free-form string fields to these Notefiles, and validate payload size on any schema change. -**Antenna placement.** Satellite operation requires the Notecard for Skylo's main antenna outdoors and free from obstructions — for the northern hemisphere, an unobstructed view of the southern sky, where Skylo's GEO satellites sit above the equator. A station where the enclosure is entirely below grade or inside a steel cabinet will require an above-grade antenna cable run; plan that conduit path at installation time. Use only the Skylo-certified antenna supplied with the Notecard for Skylo on the `MAIN` u.FL port; substituting an uncertified antenna risks regulatory non-compliance and link failure. This same antenna also carries the terrestrial cellular signal, so the placement that enables satellite fallback serves cellular as well. +**Antenna placement.** Satellite operation requires Notecard for Skylo's main antenna outdoors and free from obstructions — for the northern hemisphere, an unobstructed view of the southern sky, where Skylo's GEO satellites sit above the equator. A station where the enclosure is entirely below grade or inside a steel cabinet will require an above-grade antenna cable run; plan that conduit path at installation time. Use only the Skylo-certified antenna supplied with Notecard for Skylo on the `MAIN` u.FL port; substituting an uncertified antenna risks regulatory non-compliance and link failure. This same antenna also carries the terrestrial cellular signal, so the placement that enables satellite fallback serves cellular as well. -**Power envelope.** The Notecard for Skylo idles at typically ~8 µA. A network session — cellular or satellite — draws on the order of ~250 mA average from the onboard modem, with brief higher peaks (the BG95-S5 can pull nearly 2 A for a few milliseconds on a 2G transmit burst). The HDR-15-5 (3 A rated) handles these peaks with margin. See the [Validation section](#9-validation-and-testing) for a per-state current breakdown. +**Power envelope.** Notecard for Skylo idles at typically ~8 µA. A network session — cellular or satellite — draws on the order of ~250 mA average from the onboard modem, with brief higher peaks (the BG95-S5 can pull nearly 2 A for a few milliseconds on a 2G transmit burst). The HDR-15-5 (3 A rated) handles these peaks with margin. See the [Validation section](#9-validation-and-testing) for a per-state current breakdown. -**Mandatory initial non-NTN sync.** Before any satellite (NTN) operation is possible, the Notecard for Skylo must complete at least one non-NTN sync with Notehub over cellular or WiFi to associate with the project and register Notefile templates. The cold-boot `hub.set` in `periodic` mode performs that first sync over cellular/WiFi automatically, so ensure the unit has cellular (or WiFi) coverage during initial commissioning, even if the deployment site relies on satellite for routine operation. +**Mandatory initial non-NTN sync.** Before any satellite (NTN) operation is possible, Notecard for Skylo must complete at least one non-NTN sync with Notehub over cellular or WiFi to associate with the project and register Notefile templates. The cold-boot `hub.set` in `periodic` mode performs that first sync over cellular/WiFi automatically, so ensure the unit has cellular (or WiFi) coverage during initial commissioning, even if the deployment site relies on satellite for routine operation. ## 3. Technical Summary @@ -109,7 +109,7 @@ Here is a sample Note this device emits: | Gems Sensors RS-500-Y-PP, SPST N.O., polypropylene float switch | 1 | Sewage-rated polypropylene construction; normally-open contact closes on high-water. Mounts through the wet-well cover or on a cable-held hanger bracket. Available from Grainger and industrial distributors. Specify vertical or horizontal actuation to match the wet-well geometry. | | [MeanWell HDR-15-24](https://www.meanwell.com/Upload/PDF/HDR-15/HDR-15-SPEC.PDF), 85–264 VAC input, 24 VDC / 0.63 A, DIN-rail | 1 | AC–DC DIN-rail supply that derives 24 VDC from the station's 120 VAC control circuit. Powers the 4–20 mA sensor loop; 15 W is ample for the 0.48 W peak loop load. | | [MeanWell HDR-15-5](https://www.meanwell.com/Upload/PDF/HDR-15/HDR-15-SPEC.PDF), 85–264 VAC input, 5 VDC / 3 A, DIN-rail | 1 | AC–DC DIN-rail supply that derives 5 VDC for the Notecarrier CX USB-C port from the same 120 VAC control leg. | -| Skylo-certified LTE/satellite antenna included with the Notecard for Skylo (u.FL, supports the S-Band / L-Band B23 / B255 / B256 bands) | 1 | Connects to the `MAIN` u.FL port and carries **both** the terrestrial cellular signal and the Skylo satellite link — a single antenna for both networks. Use only the Skylo-certified antenna supplied with the Notecard for Skylo; substituting an uncertified antenna risks regulatory non-compliance and link failure. Mount outdoors on the cabinet exterior or above-grade access point with an unobstructed view of the sky (northern hemisphere: the southern sky); route through a liquid-tight fitting. For an external SMA mag-mount instead of the bare u.FL antenna, add a u.FL-to-SMA-F bulkhead pigtail (e.g. Taoglas CAB.0150.A.01). | +| Skylo-certified LTE/satellite antenna included with Notecard for Skylo (u.FL, supports the S-Band / L-Band B23 / B255 / B256 bands) | 1 | Connects to the `MAIN` u.FL port and carries **both** the terrestrial cellular signal and the Skylo satellite link — a single antenna for both networks. Use only the Skylo-certified antenna supplied with Notecard for Skylo; substituting an uncertified antenna risks regulatory non-compliance and link failure. Mount outdoors on the cabinet exterior or above-grade access point with an unobstructed view of the sky (northern hemisphere: the southern sky); route through a liquid-tight fitting. For an external SMA mag-mount instead of the bare u.FL antenna, add a u.FL-to-SMA-F bulkhead pigtail (e.g. Taoglas CAB.0150.A.01). | | Passive GPS/GNSS antenna (u.FL) per the [Notecard for Skylo datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) | 1 | Connects to the `GPS` u.FL port for GNSS time/location. Mount outdoors with a clear sky view alongside the main antenna; route through a liquid-tight fitting. | | Hammond 1554N2GCLY NEMA 4X ABS enclosure, 8.07 × 6.10 × 3.94″ | 1 | Polycarbonate-gasketed splash-resistant housing. Use liquid-tight conduit fittings (Heyco or equivalent) for all sensor cable entries. | @@ -125,7 +125,7 @@ Here is a sample Note this device emits: -All host I/O lands on the [Notecarrier CX](https://dev.blues.io/datasheets/notecarrier-datasheet/notecarrier-cx-v1-3/) dual 16-pin headers. The Notecard for Skylo seats into the M.2 slot. Its `MAIN` u.FL port connects to the included Skylo-certified antenna, which carries both the cellular and satellite signals — connect it directly, or route it through a u.FL-to-SMA-F bulkhead pigtail in the enclosure wall if you are using an external SMA mag-mount. Its `GPS` u.FL port connects to the passive GPS/GNSS antenna. Both antennas mount outdoors with a clear sky view (northern hemisphere: the southern sky), so the unit can reach the Skylo satellite network wherever it falls back from cellular. The Mojo connects via the [Qwiic](https://www.sparkfun.com/qwiic) connector on the Notecarrier and sits inline between the 5 V supply and the Notecarrier's +VBAT pad during bench validation. +All host I/O lands on the [Notecarrier CX](https://dev.blues.io/datasheets/notecarrier-datasheet/notecarrier-cx-v1-3/) dual 16-pin headers. Notecard for Skylo seats into the M.2 slot. Its `MAIN` u.FL port connects to the included Skylo-certified antenna, which carries both the cellular and satellite signals — connect it directly, or route it through a u.FL-to-SMA-F bulkhead pigtail in the enclosure wall if you are using an external SMA mag-mount. Its `GPS` u.FL port connects to the passive GPS/GNSS antenna. Both antennas mount outdoors with a clear sky view (northern hemisphere: the southern sky), so the unit can reach the Skylo satellite network wherever it falls back from cellular. The Mojo connects via the [Qwiic](https://www.sparkfun.com/qwiic) connector on the Notecarrier and sits inline between the 5 V supply and the Notecarrier's +VBAT pad during bench validation. **Level sensor (4–20 mA current loop)** @@ -298,11 +298,11 @@ Fields: ### Low-power strategy -Each wake cycle lasts only a few seconds: read sensors (~300 milliseconds for CT RMS), evaluate rules, queue or sync Notes, then call `NotePayloadSaveAndSleep`. The Notecard cuts power to the Cygnet host entirely via the ATTN pin connection on the Notecarrier CX; the host draws essentially zero from the rail during sleep. The Notecard for Skylo itself sits in its own [low-power idle](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design/) state between radio sessions (~8 µA @ 5 V), regardless of which radio it last used. +Each wake cycle lasts only a few seconds: read sensors (~300 milliseconds for CT RMS), evaluate rules, queue or sync Notes, then call `NotePayloadSaveAndSleep`. The Notecard cuts power to the Cygnet host entirely via the ATTN pin connection on the Notecarrier CX; the host draws essentially zero from the rail during sleep. Notecard for Skylo itself sits in its own [low-power idle](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design/) state between radio sessions (~8 µA @ 5 V), regardless of which radio it last used. **Sync strategy.** The Notecard runs in [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `mode:"periodic"` — the correct choice for a duty-cycled sensor node. In `periodic` mode the radio is fully off between sessions; the Notecard wakes on the configured `outbound` timer, ships queued Notes, then returns to low-power idle. `notecardConfigure` sets `outbound:60` (60-minute outbound sync interval) and `inbound:120` (2-hour env-var pull cadence). These cadences are deliberately decoupled from the 60-second sample interval: sensor reads accumulate in the in-flight summary window, and the Notecard opens a radio session only once per hour for summaries. Alert Notes set `sync:true`, which causes the Notecard to open a session as soon as the host queues the Note — bypassing the `outbound` timer entirely. `notecardConfigure` also issues a one-time [`card.transport`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-transport) `{"method":"wifi-cell-ntn"}` so the Notecard prefers WiFi, then cellular, then Skylo satellite (NTN) — the fallback that lets the same firmware serve both in-coverage and beyond-coverage stations. For stations expected to operate over satellite, `outbound:60` is a reasonable starting point, but the `inbound:120` cadence should be reviewed: each inbound satellite check consumes approximately 50 bytes of bundled satellite data, and twice-hourly polling is a significant fraction of the 10 KB bundled allocation. Raise `inbound_interval_min` to `240` or higher via the Notehub env-var panel for satellite stations. If the outbound summary rate is also reduced (via `summary_interval_min`), set both env vars together. The firmware re-issues `hub.set` with the updated outbound and inbound values whenever either variable changes — no firmware reflash needed. -Sampling cadence (60 seconds) and transmission cadence (default 60 minutes, set by `summary_interval_min`) are deliberately decoupled: each summary window's sensor reads feed one summary Note, but only alert Notes bypass the outbound timer. The firmware re-issues `hub.set` if an operator changes `summary_interval_min` via Notehub, so the Notecard's outbound window stays aligned with the summary rate automatically. At nominal operating conditions a single-station deployment generates one outbound session per summary interval plus occasional alert sessions — a tiny fraction of the Notecard for Skylo's included 500 MB of cellular data, and (for stations operating over satellite) a meaningful but manageable fraction of its bundled 10 KB satellite allocation. +Sampling cadence (60 seconds) and transmission cadence (default 60 minutes, set by `summary_interval_min`) are deliberately decoupled: each summary window's sensor reads feed one summary Note, but only alert Notes bypass the outbound timer. The firmware re-issues `hub.set` if an operator changes `summary_interval_min` via Notehub, so the Notecard's outbound window stays aligned with the summary rate automatically. At nominal operating conditions a single-station deployment generates one outbound session per summary interval plus occasional alert sessions — a tiny fraction of Notecard for Skylo's included 500 MB of cellular data, and (for stations operating over satellite) a meaningful but manageable fraction of its bundled 10 KB satellite allocation. ### Retry and error handling @@ -412,7 +412,7 @@ bool ok = notecard.sendRequestWithRetry(req, 5); **Power validation with Mojo.** Insert the [Mojo](https://dev.blues.io/datasheets/mojo-datasheet/) inline on the 5 V rail feeding the Notecarrier CX during a bench run; Mojo measures the entire Notecarrier subsystem (Notecard + Cygnet + carrier regulators), not the Notecard alone. Approximate per-state draw at the 5 V rail ([low-power design guide](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design/)): -The Notecard for Skylo's draw depends on which radio is active for a given session, but the idle and host-active states are identical regardless of network. Cellular and satellite sessions are similar in magnitude (~250 mA average from the onboard BG95-S5 modem), with brief higher peaks — a 2G transmit burst can momentarily pull nearly 2 A for a few milliseconds. +Notecard for Skylo's draw depends on which radio is active for a given session, but the idle and host-active states are identical regardless of network. Cellular and satellite sessions are similar in magnitude (~250 mA average from the onboard BG95-S5 modem), with brief higher peaks — a 2G transmit burst can momentarily pull nearly 2 A for a few milliseconds. | Operating state | Notecard for Skylo | Cygnet host | 5 V rail total | |---|---|---|---| @@ -454,7 +454,7 @@ arduino-cli lib install "Blues Wireless Notecard" **No events appearing in Notehub after 5 minutes.** Check: 1. **Network availability** — does the Notecard have cellular or WiFi access? Use the serial log or `card.signal` to verify. -2. **Event payload size** — when the Notecard for Skylo is transmitting over satellite (NTN), Notes exceeding 256 bytes are silently dropped. Check the serial log for `note.add` success/failure status. +2. **Event payload size** — when Notecard for Skylo is transmitting over satellite (NTN), Notes exceeding 256 bytes are silently dropped. Check the serial log for `note.add` success/failure status. 3. **Outbound sync window** — summaries are queued and synced every 60 minutes by default. Alerts fire immediately with `sync:true`, so if you've triggered an alert and the Notecard has coverage, it should appear within 60 seconds. If not, check the serial log for `sendAlert` and `note.add` output. **Constant non-zero current when powered (Mojo shows ~10–50 mA instead of spike pattern).** The ATTN pin is not cutting host power: @@ -485,7 +485,7 @@ The simplifications below are scope choices — each is a place where a producti **No SCADA integration.** The sketch is standalone. Most municipal lift stations already have a local RTU or telemetry unit, and integrating with that system — reading dry contacts from the existing SCADA outputs, or making the Notecard's data available to the local RTU — is outside the scope of this POC. -**Satellite (NTN) operation caveats.** The firmware is identical everywhere, but when the Notecard for Skylo falls back to the satellite link it carries material operational differences. Alert and summary Notes queue in the Notecard's local store and sync on the satellite session schedule — `sync:true` Notes are prioritized for the next available session, but locating a Skylo satellite and completing transmission takes several minutes, not seconds. Each Note must stay within the **NTN 256-byte maximum**; Notes exceeding this are silently dropped by the satellite network without transmission. Inbound syncs (env-var pulls) consume approximately 50 bytes of the 10 KB bundled satellite data allocation each, so the default 2-hour inbound cadence costs roughly 600 bytes/day. The Skylo-certified main antenna must be mounted outdoors with an unobstructed sky view (in the northern hemisphere, an unobstructed view of the southern sky) for the satellite link to work, so stations with the enclosure entirely below grade will need an above-grade cable run. Satellite operation is opt-in at the Notecard level: the firmware enables it by setting `card.transport` to `wifi-cell-ntn` — without an `ntn` transport mode the board would stay on cellular/WiFi only and never reach the satellite network. See [Section 2](#satellite-ntn-operation-considerations) and [Section 8](#9-validation-and-testing) for the full breakdown. +**Satellite (NTN) operation caveats.** The firmware is identical everywhere, but when Notecard for Skylo falls back to the satellite link it carries material operational differences. Alert and summary Notes queue in the Notecard's local store and sync on the satellite session schedule — `sync:true` Notes are prioritized for the next available session, but locating a Skylo satellite and completing transmission takes several minutes, not seconds. Each Note must stay within the **NTN 256-byte maximum**; Notes exceeding this are silently dropped by the satellite network without transmission. Inbound syncs (env-var pulls) consume approximately 50 bytes of the 10 KB bundled satellite data allocation each, so the default 2-hour inbound cadence costs roughly 600 bytes/day. The Skylo-certified main antenna must be mounted outdoors with an unobstructed sky view (in the northern hemisphere, an unobstructed view of the southern sky) for the satellite link to work, so stations with the enclosure entirely below grade will need an above-grade cable run. Satellite operation is opt-in at the Notecard level: the firmware enables it by setting `card.transport` to `wifi-cell-ntn` — without an `ntn` transport mode the board would stay on cellular/WiFi only and never reach the satellite network. See [Section 2](#satellite-ntn-operation-considerations) and [Section 8](#9-validation-and-testing) for the full breakdown. **Mojo is bench-validation only.** The firmware does not read the Mojo's coulomb counter register over Qwiic. Adding a `mojo_mah` field to the hourly summary is a simple extension using the LTC2959 register map if fleet-level energy telemetry is valuable. diff --git a/57-propane-lpg-tank-fill-telemetry/README.md b/57-propane-lpg-tank-fill-telemetry/README.md index 6f22cc03..4897fac7 100644 --- a/57-propane-lpg-tank-fill-telemetry/README.md +++ b/57-propane-lpg-tank-fill-telemetry/README.md @@ -22,15 +22,15 @@ This project solves all three. **A weatherproof electronics enclosure mounted on -**Deployment scenario.** A weatherproof NEMA 4X enclosure mounted on a separate post, wall, or bracket **outside the AHJ-defined classified area** (see the safety notice in §4), powered by a solar-charged 12 V sealed lead-acid battery. A 4-20 mA LP gauge-port float transmitter (Rochester Sensors M6300-LP Magnetel® gauge + R6315-12 transmitter, or equivalent) connects at the tank's existing 1¼″ NPT dip-tube gauge port; field wiring from the transmitter runs to the electronics enclosure outside the hazardous boundary. A waterproof DS18B20 temperature probe is clamped to the tank shell and logged in daily summary Notes for seasonal demand analytics. The Notecard for Skylo's antenna cables exit the enclosure to outdoor-mounted antennas with a clear sky view — the same Skylo-certified antenna carries both cellular and satellite, so where cellular coverage is absent the board falls back to the Skylo NTN satellite network automatically over the same Notehub project, with no antenna swap and no firmware changes. No modifications to the tank itself, no on-site internet infrastructure, and no OEM cooperation required. +**Deployment scenario.** A weatherproof NEMA 4X enclosure mounted on a separate post, wall, or bracket **outside the AHJ-defined classified area** (see the safety notice in §4), powered by a solar-charged 12 V sealed lead-acid battery. A 4-20 mA LP gauge-port float transmitter (Rochester Sensors M6300-LP Magnetel® gauge + R6315-12 transmitter, or equivalent) connects at the tank's existing 1¼″ NPT dip-tube gauge port; field wiring from the transmitter runs to the electronics enclosure outside the hazardous boundary. A waterproof DS18B20 temperature probe is clamped to the tank shell and logged in daily summary Notes for seasonal demand analytics. Notecard for Skylo's antenna cables exit the enclosure to outdoor-mounted antennas with a clear sky view — the same Skylo-certified antenna carries both cellular and satellite, so where cellular coverage is absent the board falls back to the Skylo NTN satellite network automatically over the same Notehub project, with no antenna swap and no firmware changes. No modifications to the tank itself, no on-site internet infrastructure, and no OEM cooperation required. ## 2. System Architecture ![System architecture: propane tank with 4–20 mA float transmitter and DS18B20 → edge enclosure outside hazardous area → Notecard for Skylo (cellular / WiFi / satellite) → Notehub → dispatch / ERP / time-series DB](diagrams/01-system-architecture.svg) -**Device-side responsibilities.** Inside the post-mounted enclosure, the Cygnet STM32 host on the Notecarrier CX wakes every `sample_interval_min` (default 15 minutes), reads the 4-20 mA float transmitter and the DS18B20 shell probe, converts the linear current straight to fill percentage and gallons remaining, and updates a smoothed consumption-rate estimate. If a threshold trips, it queues an alert Note right then; otherwise it just goes back to sleep. Once per `report_interval_hr` (default 24 hours) it ships a templated summary carrying current fill %, fill gallons, minimum fill seen in the window, window-averaged temperature, daily consumption rate, and projected days-until-empty. Between wakes the host is cut entirely via [`card.attn`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-attn) and the Notecard for Skylo idles at ~8 µA — every queued [Note](https://dev.blues.io/api-reference/glossary/#note) travels over I²C with no JSON hand-rolling and no AT commands. +**Device-side responsibilities.** Inside the post-mounted enclosure, the Cygnet STM32 host on the Notecarrier CX wakes every `sample_interval_min` (default 15 minutes), reads the 4-20 mA float transmitter and the DS18B20 shell probe, converts the linear current straight to fill percentage and gallons remaining, and updates a smoothed consumption-rate estimate. If a threshold trips, it queues an alert Note right then; otherwise it just goes back to sleep. Once per `report_interval_hr` (default 24 hours) it ships a templated summary carrying current fill %, fill gallons, minimum fill seen in the window, window-averaged temperature, daily consumption rate, and projected days-until-empty. Between wakes the host is cut entirely via [`card.attn`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-attn) and Notecard for Skylo idles at ~8 µA — every queued [Note](https://dev.blues.io/api-reference/glossary/#note) travels over I²C with no JSON hand-rolling and no AT commands. -**Notecard responsibilities.** The Notecard for Skylo runs the same playbook regardless of which radio is live: hold Notes in its on-device queue, open a session on the [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence, and push any `sync:true` alert through immediately. The `card.transport` `wifi-cell-ntn` preference set at boot decides the path automatically — WiFi where a provisioned AP is reachable, cellular at the bulk of sites, and Skylo satellite at remote sites — with no firmware branching. Either way, the same module pulls [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) from Notehub on every inbound sync, so a dispatcher can retune transmitter calibration or alert thresholds for any tank in the fleet without anyone driving out to it. +**Notecard responsibilities.** Notecard for Skylo runs the same playbook regardless of which radio is live: hold Notes in its on-device queue, open a session on the [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence, and push any `sync:true` alert through immediately. The `card.transport` `wifi-cell-ntn` preference set at boot decides the path automatically — WiFi where a provisioned AP is reachable, cellular at the bulk of sites, and Skylo satellite at remote sites — with no firmware branching. Either way, the same module pulls [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) from Notehub on every inbound sync, so a dispatcher can retune transmitter calibration or alert thresholds for any tank in the fleet without anyone driving out to it. **Notehub responsibilities.** Events land in [Notehub](https://dev.blues.io/notehub/notehub-walkthrough/) from whatever transport carried them, where they're ingested, stored, and fanned out through project-level routes. Per-fleet [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) are how a single firmware image services tanks of every capacity — the tank size and sensor calibration live in Notehub, not in compiled constants. [Smart Fleets](https://dev.blues.io/notehub/notehub-walkthrough/#using-smart-fleet-rules) make it easy to group tanks by territory, capacity class, or customer type so the right calibration values flow to the right tanks automatically. @@ -90,9 +90,9 @@ Here is a sample Note this device emits: | [SparkFun Waterproof DS18B20 Temperature Sensor (SEN-11050)](https://www.sparkfun.com/products/11050) | 1 | OneWire temperature probe clamped to the tank shell. Included in daily summary Notes for cloud-side consumption correlation against ambient conditions. | | 120 Ω 0.1 % precision resistor | 1 | Shunt across the 4-20 mA current loop. Converts 4–20 mA to 0.48–2.40 V DC at the Cygnet's A0 ADC pin. The 120 Ω value provides safe electrical headroom for standard 4–20 mA transmitter fault currents: a 24 mA diagnostic output produces only 2.88 V at A0 — well within the 3.3 V ADC absolute maximum. The firmware rejects currents outside the 3.5–21 mA valid window as `NAN` and emits a `sensor_fault` alert; with this shunt the ADC is electrically safe up to ~27 mA (3.3 V ÷ 120 Ω). | | 4.7 kΩ resistor | 1 | OneWire pull-up for the DS18B20 data line. | -| 12 V DC/DC step-down module, 5 V / 2.5 A output (e.g. [Pololu D24V22F5](https://www.pololu.com/product/2858)) | 1 | Steps 12 V battery rail down to 5 V for the Notecarrier CX VBAT input. A 2.5 A continuous output rating is required for this design: the Notecard for Skylo's onboard modem (Quectel BG95-S5) can momentarily demand up to ~2 A in brief bursts, and a 1 A regulator cannot reliably source that peak. The D24V22F5 delivers 5 V at up to 2.5 A continuous from a 4.5–42 V input, giving comfortable headroom above the Notecard's 2 A burst demand plus the Cygnet host's active-mode draw. | +| 12 V DC/DC step-down module, 5 V / 2.5 A output (e.g. [Pololu D24V22F5](https://www.pololu.com/product/2858)) | 1 | Steps 12 V battery rail down to 5 V for the Notecarrier CX VBAT input. A 2.5 A continuous output rating is required for this design: Notecard for Skylo's onboard modem (Quectel BG95-S5) can momentarily demand up to ~2 A in brief bursts, and a 1 A regulator cannot reliably source that peak. The D24V22F5 delivers 5 V at up to 2.5 A continuous from a 4.5–42 V input, giving comfortable headroom above the Notecard's 2 A burst demand plus the Cygnet host's active-mode draw. | | 24 V DC/DC boost converter module, input 8–16 V, output regulated 24 V, ≥ 100 mA (e.g. [Pololu U3V50F24](https://www.pololu.com/product/2569)) | 1 | Provides a stable, regulated 24 V supply for the 4–20 mA transmitter current loop. A regulated 24 V loop supply guarantees transmitter compliance across the full SLA discharge cycle, any practical cable run, and an AHJ-required IS barrier. See the loop compliance calculation in §5 Step 7. **Do not drive the transmitter loop from the 12 V system rail**: at battery sag (11–11.5 V under partial charge and load) the loop supply falls below the R6315-12's 12 V minimum specification, and any IS barrier in the loop worsens the margin further. The Pololu U3V50F24 accepts 2–16 V input and delivers a regulated 24 V at up to 500 mA; it is powered from the same 12 V system rail as the 5 V step-down module. | -| Skylo-certified LTE/satellite antenna included with the Notecard for Skylo (u.FL) | 1 | Connects to the **MAIN** u.FL port and carries **both** the terrestrial cellular signal and the Skylo satellite link — a single antenna for both networks. Use only the Skylo-certified antenna supplied with the Notecard for Skylo; substituting an uncertified antenna risks regulatory non-compliance and link failure. Mount outdoors with an unobstructed view of the sky (northern hemisphere: the southern sky) so the board can reach Skylo wherever it falls back from cellular; route through a cable gland. Do not rely on the bare antenna inside a polycarbonate enclosure at tank-side — signal margin is too variable. | +| Skylo-certified LTE/satellite antenna included with Notecard for Skylo (u.FL) | 1 | Connects to the **MAIN** u.FL port and carries **both** the terrestrial cellular signal and the Skylo satellite link — a single antenna for both networks. Use only the Skylo-certified antenna supplied with Notecard for Skylo; substituting an uncertified antenna risks regulatory non-compliance and link failure. Mount outdoors with an unobstructed view of the sky (northern hemisphere: the southern sky) so the board can reach Skylo wherever it falls back from cellular; route through a cable gland. Do not rely on the bare antenna inside a polycarbonate enclosure at tank-side — signal margin is too variable. | | u.FL-to-SMA-F bulkhead pigtail, ~15–20 cm (e.g. Taoglas CAB.0150.A.01 or equivalent) | 0–1 | **Optional.** Only needed to mount an external SMA-terminated antenna instead of routing the bare u.FL antenna through the enclosure wall. Adapts the MAIN u.FL port to an external SMA bulkhead, then connects to the external antenna cable outside. Not required when the included Skylo-certified antenna is routed directly through a gland. | | Passive GPS/GNSS antenna (u.FL) per the [Notecard for Skylo datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) | 1 | Connects to the **GPS** u.FL port for GNSS time/location. Mount outdoors with a clear sky view alongside the main antenna; route through a cable gland. | | IP68-rated PG-11 nylon cable gland, 5–10 mm cable OD (e.g. Lapp SKINTOP® MS-M PG 11 or equivalent) | 4 | One gland per field cable entering the enclosure. This installation requires penetrations for: **(1)** the Skylo-certified MAIN antenna lead (or its SMA bulkhead); **(2)** the GPS/GNSS antenna lead; **(3)** DS18B20 temperature probe cable; and **(4)** 4–20 mA transmitter loop wiring (two conductors from transmitter to enclosure). Every penetration must be sealed to maintain the NEMA 4X enclosure rating. Select gland cable-OD range to match each specific cable's outer diameter. | @@ -116,7 +116,7 @@ Here is a sample Note this device emits: ![Wiring: 4–20 mA float transmitter with 120 Ω shunt → A0; DS18B20 with 4.7 kΩ pull-up → D2; 24 V boost converter for transmitter loop; solar + SLA dual-rail power chain (5 V → +VBAT, 24 V → loop)](diagrams/02-wiring-assembly.svg) -All Notecarrier CX host I/O lands on its dual 16-pin header. The Notecard for Skylo seats into the M.2 slot. The Mojo sits inline between the 5 V step-down and the Notecarrier +VBAT pad during bench validation only; it is not deployed in the field. +All Notecarrier CX host I/O lands on its dual 16-pin header. Notecard for Skylo seats into the M.2 slot. The Mojo sits inline between the 5 V step-down and the Notecarrier +VBAT pad during bench validation only; it is not deployed in the field. @@ -171,9 +171,9 @@ During bench validation the Mojo sits in this path to measure 5 V rail current. **Step 6 — Notecard installation and antenna connections.** -Seat the Notecard for Skylo (NOTE-NBGLWX) into the Notecarrier CX M.2 slot and secure the retaining screw. +Seat Notecard for Skylo (NOTE-NBGLWX) into the Notecarrier CX M.2 slot and secure the retaining screw. -The Notecard for Skylo exposes two antenna u.FL ports — **MAIN** and **GPS**. The single Skylo-certified antenna on the MAIN port carries **both** the cellular and the satellite signal; there is no separate satellite antenna to install. Connect antennas as follows: +Notecard for Skylo exposes two antenna u.FL ports — **MAIN** and **GPS**. The single Skylo-certified antenna on the MAIN port carries **both** the cellular and the satellite signal; there is no separate satellite antenna to install. Connect antennas as follows: - **MAIN port** — attach the included Skylo-certified antenna, routed through Gland 1 (connect it directly, or adapt it to an external SMA bulkhead with a u.FL-to-SMA-F pigtail). Mount the antenna outdoors with an unobstructed view of the sky (northern hemisphere: the southern sky) so the board can reach the Skylo satellite network wherever it falls back from cellular. Use only the Skylo-certified antenna; an uncertified part risks regulatory non-compliance and link failure. *Do not skip this connection — both cellular and satellite operation require this external antenna.* - **GPS port** — attach the passive GPS/GNSS antenna, routed through Gland 2, and mount it outdoors with a clear sky view alongside the main antenna. @@ -219,7 +219,7 @@ Route the DS18B20 cable through Gland 3. Mount the probe body against the tank s **Step 9 — Satellite operation (automatic, no added hardware).** -No additional module or wiring is required for satellite operation — the Notecard for Skylo's satellite radio is on the same M.2 board as cellular and WiFi, and the single Skylo-certified MAIN antenna (Step 6) carries the satellite link. The firmware enables cellular→satellite fallback by setting `card.transport` to `wifi-cell-ntn` at boot (see §7); the Notecard then routes queued Notes over the Skylo NTN satellite network automatically at any site where cellular is unavailable. To make satellite work in the field, the MAIN antenna must be mounted **outdoors with an unobstructed view of the sky** (northern hemisphere: the southern sky) — confirm a suitable mounting location at remote tank sites. The daily summary Note (~40 bytes) fits well within the NTN payload budget. Note that the board must complete at least one initial non-NTN (cellular or WiFi) sync to associate with Notehub and register Notefile templates before satellite can be used; commission each unit where it has terrestrial coverage even if it will routinely operate over satellite. Review the [Satellite Best Practices guide](https://dev.blues.io/starnote/satellite-best-practices/) for duty-cycle and data-budget considerations before deploying to a cellular-dark site. +No additional module or wiring is required for satellite operation — Notecard for Skylo's satellite radio is on the same M.2 board as cellular and WiFi, and the single Skylo-certified MAIN antenna (Step 6) carries the satellite link. The firmware enables cellular→satellite fallback by setting `card.transport` to `wifi-cell-ntn` at boot (see §7); the Notecard then routes queued Notes over the Skylo NTN satellite network automatically at any site where cellular is unavailable. To make satellite work in the field, the MAIN antenna must be mounted **outdoors with an unobstructed view of the sky** (northern hemisphere: the southern sky) — confirm a suitable mounting location at remote tank sites. The daily summary Note (~40 bytes) fits well within the NTN payload budget. Note that the board must complete at least one initial non-NTN (cellular or WiFi) sync to associate with Notehub and register Notefile templates before satellite can be used; commission each unit where it has terrestrial coverage even if it will routinely operate over satellite. Review the [Satellite Best Practices guide](https://dev.blues.io/starnote/satellite-best-practices/) for duty-cycle and data-budget considerations before deploying to a cellular-dark site. **Final pre-power checklist.** @@ -237,7 +237,7 @@ No additional module or wiring is required for satellite operation — the Notec 2. **Claim the Notecard.** Power the unit; on first cellular session the Notecard associates with the project automatically. Verify the device appears in the Notehub device list and shows a recent session. -3. **Optional: configure WiFi credentials.** The Notecard for Skylo supports WiFi as an optional secondary transport — the device operates normally on cellular (or satellite) alone if no WiFi credentials are set. Two reliable provisioning paths are available for this hardware stack: +3. **Optional: configure WiFi credentials.** Notecard for Skylo supports WiFi as an optional secondary transport — the device operates normally on cellular (or satellite) alone if no WiFi credentials are set. Two reliable provisioning paths are available for this hardware stack: - **Preferred — Notehub environment variables (works on deployed hardware).** Set the `wifi_ssid` and `wifi_password` environment variables in Notehub (see the env var table in step 5 below). Env vars are delivered to the device on the next **inbound sync**. Because `hubConfigure()` sets inbound at 2× the outbound period, the default 24-hour report cadence means inbound syncs occur every 48 hours — **WiFi credentials set in Notehub may take up to 48 hours to reach the device.** Once the inbound sync delivers the vars, the firmware issues `card.wifi` to store the credentials on the Notecard; the Notecard then connects over WiFi when it provides better or equivalent coverage to cellular. For faster credential rollout, temporarily lower `report_interval_hr` (e.g. set to 1 hour), confirm connectivity, then restore the original value. Credentials persist on the Notecard even if the env vars are later cleared. @@ -263,7 +263,7 @@ No additional module or wiring is required for satellite operation — the Notec | `wifi_ssid` | *(unset)* | SSID of a WiFi network to use as a secondary transport. Both `wifi_ssid` and `wifi_password` must be set; the firmware issues `card.wifi` on the next inbound sync (up to 48 hours at the default cadence. See step 3 above) so the Notecard stores the credentials and connects over WiFi when available. Credentials persist on the Notecard even if the env vars are later cleared. Note: env var values are visible to Notehub project collaborators — use a dedicated IoT or guest network. | | `wifi_password` | *(unset)* | WPA2 passphrase for the network specified by `wifi_ssid`. | -6. **Satellite deployments (cellular-dark sites).** No hardware change is needed — the Notecard for Skylo's satellite radio is already on the board, and the firmware enables cellular→satellite fallback by setting `card.transport` to `wifi-cell-ntn` (see §7). At sites with no cellular coverage the board falls back to the Skylo NTN satellite network automatically; all events travel through the same Notehub project regardless of transport. The board must complete at least one initial non-NTN (cellular or WiFi) sync to associate with the project and register Notefile templates before satellite can be used, so commission each unit where it has terrestrial coverage even if it will routinely operate over satellite. The daily summary Note (~40 bytes per record) fits within typical NTN satellite payload budgets; each inbound sync also consumes some of the bundled 10 KB satellite allocation, so consider widening `report_interval_hr` (which also widens the inbound cadence) at satellite sites. Review the [Satellite Best Practices guide](https://dev.blues.io/starnote/satellite-best-practices/) before deploying to understand satellite-specific duty-cycle and data-budget considerations. +6. **Satellite deployments (cellular-dark sites).** No hardware change is needed — Notecard for Skylo's satellite radio is already on the board, and the firmware enables cellular→satellite fallback by setting `card.transport` to `wifi-cell-ntn` (see §7). At sites with no cellular coverage the board falls back to the Skylo NTN satellite network automatically; all events travel through the same Notehub project regardless of transport. The board must complete at least one initial non-NTN (cellular or WiFi) sync to associate with the project and register Notefile templates before satellite can be used, so commission each unit where it has terrestrial coverage even if it will routinely operate over satellite. The daily summary Note (~40 bytes per record) fits within typical NTN satellite payload budgets; each inbound sync also consumes some of the bundled 10 KB satellite allocation, so consider widening `report_interval_hr` (which also widens the inbound cadence) at satellite sites. Review the [Satellite Best Practices guide](https://dev.blues.io/starnote/satellite-best-practices/) before deploying to understand satellite-specific duty-cycle and data-budget considerations. 7. **Configure routes.** Add one [route](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub) for `tank_alert.qo` (real-time delivery to the dealer's dispatch or routing system) and a second for `tank_status.qo` (batched delivery to a time-series store for historical trend analysis and route-density modeling). Keeping the two Notefiles separate at the source means each can be fanned out to a different destination at a different urgency — alerts go somewhere that pages an operator; daily summaries go somewhere that feeds a dashboard. @@ -373,13 +373,13 @@ Two alert types are defined: `low_fill` (fill percentage dropped below `fill_ale -**Satellite alert latency.** When the Notecard for Skylo is operating over the satellite (NTN) link, `sync:true` does not eliminate latency — the alert must wait for an available satellite pass, and Skylo's network duty-cycle rules constrain how often sessions can be opened. Treat satellite alert latency as **minutes**, not seconds. The session energy profile over satellite also differs from a cellular session; the cellular Mojo current figures in §9 do not directly apply to satellite sessions. Validate alert timing and solar/battery sizing separately for sites expected to operate over satellite, using the [Satellite Best Practices guide](https://dev.blues.io/starnote/satellite-best-practices/) before commissioning. +**Satellite alert latency.** When Notecard for Skylo is operating over the satellite (NTN) link, `sync:true` does not eliminate latency — the alert must wait for an available satellite pass, and Skylo's network duty-cycle rules constrain how often sessions can be opened. Treat satellite alert latency as **minutes**, not seconds. The session energy profile over satellite also differs from a cellular session; the cellular Mojo current figures in §9 do not directly apply to satellite sessions. Validate alert timing and solar/battery sizing separately for sites expected to operate over satellite, using the [Satellite Best Practices guide](https://dev.blues.io/starnote/satellite-best-practices/) before commissioning. ### Low-power strategy -Between samples, the Cygnet is cut entirely. `loop()` runs one sample cycle, then serializes state into the Notecard's flash via `NotePayloadSaveAndSleep`, which internally calls [`card.attn`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-attn) to cut host power for `sample_interval_min × 60` seconds. The Notecard for Skylo itself idles at ~8 µA between network sessions (NOTE-NBGLWX published idle figure), regardless of which radio it last used. On the next scheduled wake the host enters `setup()`, calls `NotePayloadRetrieveAfterSleep` to rehydrate state (including the running consumption history and alert cooldown timestamps), then hands off to `loop()` for the next sample cycle. +Between samples, the Cygnet is cut entirely. `loop()` runs one sample cycle, then serializes state into the Notecard's flash via `NotePayloadSaveAndSleep`, which internally calls [`card.attn`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-attn) to cut host power for `sample_interval_min × 60` seconds. Notecard for Skylo itself idles at ~8 µA between network sessions (NOTE-NBGLWX published idle figure), regardless of which radio it last used. On the next scheduled wake the host enters `setup()`, calls `NotePayloadRetrieveAfterSleep` to rehydrate state (including the running consumption history and alert cooldown timestamps), then hands off to `loop()` for the next sample cycle. This structure matters beyond battery life. Because sampling lives in `loop()`, the same code path runs on every iteration — both after a hardware power-cut (deep-sleep field mode) and after the bench `delay()` fallback (USB-powered mode). The behavior you observe on the bench is the behavior you'll see in the field. @@ -505,13 +505,13 @@ Every `sample_interval_min` (default 15 min) the Cygnet wakes, reads the LP gaug |---|---|---| | Deep sleep (host cut via `card.attn`, Notecard idle, radio off) | ~8 µA @ 5 V | Blues-published idle figure for the NOTE-NBGLWX; see the [low-power design guide](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design/) and [firmware best practices guide](https://dev.blues.io/connected-product-guidebook/firmware-best-practices-guide/). The Mojo measures the **entire powered subsystem** (Notecard + Notecarrier CX regulators), so the bench reading will be modestly above the Notecard-only figure; use trace shape and per-session energy as the primary commissioning targets, not an exact match to the Notecard-only idle number. | | Host awake — sampling (Cygnet active, 16-sample ADC average, DS18B20 750 ms conversion, I²C Notecard call, ~5 s total) | 30–50 mA | Bench estimate for the host subsystem only — not a Blues-published figure. Covers Cygnet STM32 active-mode current, 12-bit ADC operation, DS18B20 conversion current, and I²C Notecard transactions. The exact value varies with supply voltage and MCU clock. Trace shape (brief spike every `sample_interval_min`, then flat near zero) is the more reliable commissioning indicator than the absolute mA reading. | -| Notecard network session — cellular (or satellite), small queued Note, good signal | in-session average ~250 mA from the onboard modem; brief peaks up to ~2 A for a few ms | The Notecard for Skylo's Quectel BG95-S5 modem draws on the order of **~250 mA average** during a network session (cellular or satellite are similar in magnitude), with brief higher peaks — a 2G transmit burst can momentarily pull nearly **2 A for a few milliseconds** (see the [Blues low-power hardware design application Note](https://dev.blues.io/datasheets/application-notes/low-power-hardware-design/)). The Pololu D24V22F5 step-down (2.5 A rated) and SLA battery in this design comfortably source ≥ 2 A. Session duration is typically 30–60 s on cellular — expect a broad hump on the Mojo trace, not a sharp spike. Weaker signal or first-time network registration lengthens the session and raises per-session energy; the Blues [low-power design guide](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design/) RSRP/SINR signal-quality table shows how signal conditions affect mAh per session. | +| Notecard network session — cellular (or satellite), small queued Note, good signal | in-session average ~250 mA from the onboard modem; brief peaks up to ~2 A for a few ms | Notecard for Skylo's Quectel BG95-S5 modem draws on the order of **~250 mA average** during a network session (cellular or satellite are similar in magnitude), with brief higher peaks — a 2G transmit burst can momentarily pull nearly **2 A for a few milliseconds** (see the [Blues low-power hardware design application Note](https://dev.blues.io/datasheets/application-notes/low-power-hardware-design/)). The Pololu D24V22F5 step-down (2.5 A rated) and SLA battery in this design comfortably source ≥ 2 A. Session duration is typically 30–60 s on cellular — expect a broad hump on the Mojo trace, not a sharp spike. Weaker signal or first-time network registration lengthens the session and raises per-session energy; the Blues [low-power design guide](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design/) RSRP/SINR signal-quality table shows how signal conditions affect mAh per session. | The expected Mojo trace for a 15-minute sample / 24-hour cellular sync cycle: a brief (~5 s) 30–50 mA spike every 15 minutes from host-awake sampling, and once per day a broader 30–60 s hump averaging ~250 mA for the cellular sync. Between sample spikes the trace should sit flat at the ~8 µA idle floor — continuously elevated current between spikes means the host is not entering deep sleep (check the `card.attn` wiring and the `NotePayloadSaveAndSleep` return path). At the 15-minute default cadence the expected 24-hour Mojo total has three contributors: **(1) idle** — ~8 µA Notecard floor × 24 h ≈ **~0.2 mAh** (the total 5 V rail idle including Notecarrier CX regulator quiescent will read modestly above the Notecard-only figure at the bench); **(2) sampling** — 96 host-awake wakes/day × ~5 s @ 30–50 mA = **~4–6.7 mAh** (96 wakes × 5 s ÷ 3 600 s/h × 30–50 mA); **(3) daily sync** — ~250 mA × ~45 s ÷ 3 600 s/h ≈ **~3 mAh**. The expected daily total is therefore roughly **7–10 mAh/day**. If the Mojo 24-hour total runs materially above this range, the network session may be staying open longer than expected or the Notecard may be in `continuous` mode rather than `periodic`; confirm with `hub.status`. Note: the 4-20 mA transmitter loop is powered from the 24 V boost converter circuit and does **not** appear on the Mojo trace (Mojo measures the 5 V Notecarrier rail only). For a complete energy audit of the transmitter loop, place a bench ammeter in series with the boost converter's Vin+ lead on the 12 V system rail. Expect a draw of approximately 50–110 mW (4 mA loop, empty tank) to 550 mW (20 mA loop, full tank) from the 12 V rail continuously, accounting for boost converter losses; the 4–20 mA loop current itself can be read directly in serial debug output as `xmtr_ma`. -**When operating over satellite (NTN).** The session-duration and daily-energy figures above describe cellular sessions. When the Notecard for Skylo falls back to the Skylo satellite link the idle draw is unchanged (~8 µA) and a satellite session draws a similar ~250 mA average from the same modem, but session duration, the number of sessions Skylo's duty-cycle rules allow per day, and per-session energy differ from cellular. `sync:true` alert delivery depends on a satellite pass being available — latency is minutes, not seconds. Each inbound sync also consumes some of the bundled 10 KB satellite allocation, so widen `report_interval_hr` at satellite sites to conserve it. **Validate solar panel sizing, battery capacity, and alert latency separately for any site expected to operate over satellite** using the [Satellite Best Practices guide](https://dev.blues.io/starnote/satellite-best-practices/) before commissioning; do not assume the cellular sizing figures in this section are sufficient. +**When operating over satellite (NTN).** The session-duration and daily-energy figures above describe cellular sessions. When Notecard for Skylo falls back to the Skylo satellite link the idle draw is unchanged (~8 µA) and a satellite session draws a similar ~250 mA average from the same modem, but session duration, the number of sessions Skylo's duty-cycle rules allow per day, and per-session energy differ from cellular. `sync:true` alert delivery depends on a satellite pass being available — latency is minutes, not seconds. Each inbound sync also consumes some of the bundled 10 KB satellite allocation, so widen `report_interval_hr` at satellite sites to conserve it. **Validate solar panel sizing, battery capacity, and alert latency separately for any site expected to operate over satellite** using the [Satellite Best Practices guide](https://dev.blues.io/starnote/satellite-best-practices/) before commissioning; do not assume the cellular sizing figures in this section are sufficient. ## 10. Troubleshooting @@ -547,7 +547,7 @@ Note: the 4-20 mA transmitter loop is powered from the 24 V boost converter circ **WiFi is not connecting even after credentials are set.** - WiFi credentials are delivered via environment variables and applied on the next inbound sync. At the default 24-hour report cadence, inbound syncs occur every 48 hours — **credentials may take up to 48 hours to reach the device**. Temporarily lower `report_interval_hr` to 1 hour to speed delivery, then restore the original value after confirming connection. - Alternatively, set WiFi credentials via USB at the bench (see §6 step 3) before sealing the enclosure. -- The Notecard for Skylo's WiFi uses its onboard 2.4 GHz antenna; a metal enclosure will attenuate that signal. If WiFi fallback is important at this site, prefer a non-metallic enclosure or rely on cellular/satellite, which use the external MAIN antenna. +- Notecard for Skylo's WiFi uses its onboard 2.4 GHz antenna; a metal enclosure will attenuate that signal. If WiFi fallback is important at this site, prefer a non-metallic enclosure or rely on cellular/satellite, which use the external MAIN antenna. ## 11. Limitations and Next Steps @@ -559,7 +559,7 @@ This reference design covers the common case of a dealer instrumenting a tank fl **Fill-gallons calculation uses a linear scale.** `computeFillGal` computes `fill_gal = (fill_pct / 100) × tank_capacity_gal`. The horizontal-cylinder cross-section introduces a small nonlinearity between liquid height and volume (the relationship curves near the top and bottom of the tank). This nonlinearity is not corrected in firmware — an additional geometry correction table keyed to `tank_inner_diameter_in` could improve accuracy at fill levels below ~20 % or above ~80 %, at the cost of an additional environment variable and more complex calibration. For the typical operating range (20–80 % fill) the linear-scale error is small. -**Satellite (NTN) operation requires an unobstructed sky-view antenna and an initial non-NTN sync.** The Notecard for Skylo adds satellite with no extra module, but to use the Skylo link the Skylo-certified MAIN antenna must be mounted outdoors with a clear view of the sky (northern hemisphere: the southern sky) — it cannot reach the satellite from beneath a metal obstruction. Satellite operation is also opt-in at the Notecard level: the firmware enables it by setting `card.transport` to `wifi-cell-ntn`, and the board must complete at least one initial non-NTN (cellular or WiFi) sync to associate with Notehub and register Notefile templates before NTN works — commission each unit where it has terrestrial coverage. Over satellite, expect alert latency in minutes (not seconds), keep each Note within the NTN payload budget, and remember that inbound syncs draw on the bundled 10 KB satellite allocation. At remote tank sites, confirm a suitable sky-view antenna location before relying on the satellite path. +**Satellite (NTN) operation requires an unobstructed sky-view antenna and an initial non-NTN sync.** Notecard for Skylo adds satellite with no extra module, but to use the Skylo link the Skylo-certified MAIN antenna must be mounted outdoors with a clear view of the sky (northern hemisphere: the southern sky) — it cannot reach the satellite from beneath a metal obstruction. Satellite operation is also opt-in at the Notecard level: the firmware enables it by setting `card.transport` to `wifi-cell-ntn`, and the board must complete at least one initial non-NTN (cellular or WiFi) sync to associate with Notehub and register Notefile templates before NTN works — commission each unit where it has terrestrial coverage. Over satellite, expect alert latency in minutes (not seconds), keep each Note within the NTN payload budget, and remember that inbound syncs draw on the bundled 10 KB satellite allocation. At remote tank sites, confirm a suitable sky-view antenna location before relying on the satellite path. **Electronics must be outside the classified area; IS barrier may be required.** Blues Notecard and Notecarrier CX electronics are not rated for hazardous locations and must be installed outside the classified area boundary defined by NFPA 58 and the authority having jurisdiction. For 4–20 mA wiring that crosses the classified-area boundary, the AHJ may require a listed intrinsic-safety (IS) barrier in the loop circuit between the tank-side transmitter and the enclosure-side electronics. Transmitter selection, fitting compatibility, classified-area boundary determination, and any IS barrier requirement are outside the scope of the electronics design. Any connection to a propane pressure vessel must comply with NFPA 58, applicable codes, and be performed by a licensed LP gas technician. diff --git a/60-lone-worker-panic-fall-detection-beacon/README.md b/60-lone-worker-panic-fall-detection-beacon/README.md index d5db5b32..db0c613d 100644 --- a/60-lone-worker-panic-fall-detection-beacon/README.md +++ b/60-lone-worker-panic-fall-detection-beacon/README.md @@ -28,7 +28,7 @@ This project is that device — a wearable safety beacon built on two core detec -That's the reason the [Notecard for Skylo](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) (NOTE-NBGLWX) is the foundation of this design, not as a nice-to-have, but as the architectural foundation. It carries three radios on one M.2 module — cellular (LTE-M / NB-IoT / GPRS), WiFi, and satellite over the [Skylo](https://www.skylo.tech/) non-terrestrial network (NTN) — and selects among them automatically. The cellular path covers the vast majority of activations — cellular is broadly deployed, even in surprisingly rural areas. But when cellular genuinely fails, the Skylo satellite link is there, on the same board: no companion module, no second device to wire in. Skylo covers supported regions (see the [Notecard for Skylo datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) for the current coverage footprint); within that footprint, a device with an unobstructed view of the sky can deliver a distress message to Notehub even when every terrestrial network is unavailable. Satellite coverage is not guaranteed in every no-cellular location — it depends on the Skylo coverage region, sky-view geometry, and antenna orientation, but for the substations, oilfields, and rural worksites this design targets, it provides the safety margin that cellular alone cannot. +That's the reason [Notecard for Skylo](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) (NOTE-NBGLWX) is the foundation of this design, not as a nice-to-have, but as the architectural foundation. It carries three radios on one M.2 module — cellular (LTE-M / NB-IoT / GPRS), WiFi, and satellite over the [Skylo](https://www.skylo.tech/) non-terrestrial network (NTN) — and selects among them automatically. The cellular path covers the vast majority of activations — cellular is broadly deployed, even in surprisingly rural areas. But when cellular genuinely fails, the Skylo satellite link is there, on the same board: no companion module, no second device to wire in. Skylo covers supported regions (see the [Notecard for Skylo datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) for the current coverage footprint); within that footprint, a device with an unobstructed view of the sky can deliver a distress message to Notehub even when every terrestrial network is unavailable. Satellite coverage is not guaranteed in every no-cellular location — it depends on the Skylo coverage region, sky-view geometry, and antenna orientation, but for the substations, oilfields, and rural worksites this design targets, it provides the safety margin that cellular alone cannot. The firmware sets a single [`card.transport`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-transport) preference of `wifi-cell-ntn`: the Notecard prefers WiFi where a provisioned AP is reachable, falls back to cellular (the de-facto primary for a roaming worker), and falls back again to Skylo satellite when every terrestrial network is unavailable. Failover happens inside the Notecard; the host firmware never branches on which network is live. The WiFi path is an opportunistic bonus — a field tech standing near a facility WiFi AP may sync an alert without any cellular usage at all — but it is only active when network credentials have been provisioned on the Notecard and a compatible AP is within range. @@ -42,7 +42,7 @@ The firmware sets a single [`card.transport`](https://dev.blues.io/api-reference **Notecard responsibilities.** The Notecard holds the daily flush schedule via [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) but treats any `sync:true` alert Note as an immediate interrupt — the dispatcher hears about a fall in the same minute it happens, not at the next scheduled outbound window. The Notecard also owns the location story: once the host calls `card.location.mode`, the Notecard caches each GPS fix and embeds it in every subsequent compact template Note via `_lat`/`_lon`, so the firmware never has to pass coordinates in its Note body. -When the worker walks into a coverage hole and cellular fails, the Notecard for Skylo quietly switches to its onboard Skylo satellite (NTN) radio and tries the satellite path. The failover is transparent to both the firmware and to Notehub — the same Note, the same template, the same event structure arrives regardless of which radio carried it. +When the worker walks into a coverage hole and cellular fails, Notecard for Skylo quietly switches to its onboard Skylo satellite (NTN) radio and tries the satellite path. The failover is transparent to both the firmware and to Notehub — the same Note, the same template, the same event structure arrives regardless of which radio carried it. **Notehub responsibilities.** [Notehub](https://notehub.io) ingests every Note across both transports, stores each event, and fans out to whatever dispatch system the operator has configured. `beacon_alert.qo` events and their paired `beacon_location.qo` follow-ups land at the dispatcher's real-time endpoint. [Environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) flow the other direction on each inbound sync — a safety supervisor can retune the free-fall threshold or change a worker ID from the Notehub console without ever opening an enclosure. @@ -122,7 +122,7 @@ Here is a sample Note this device emits: |------|-----|-----------| | [Notecarrier CX](https://shop.blues.com/products/notecarrier-cx?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Integrated carrier with an embedded Cygnet STM32L433 host — no separate MCU needed. I²C, SPI, analog, and GPIO headers support the full sensor stack. | | [Notecard for Skylo (NOTE-NBGLWX)](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) ([datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/)) | 1 | One M.2 module carrying cellular (LTE-M / NB-IoT / GPRS, Quectel BG95-S5 modem), WiFi (Silicon Labs WFM200S), and Skylo satellite (NTN) radios, plus an integrated GPS/GNSS. Seats in the Notecarrier CX's M.2 slot. The firmware's `card.transport` `wifi-cell-ntn` setting makes it prefer WiFi, fall back to cellular, and fall back again to the Skylo satellite network when every terrestrial network is unavailable — no companion module, no second device, automatic failover. Requires the antennas below. | -| Skylo-certified LTE/satellite antenna included with the Notecard for Skylo (u.FL) | 1 | Connects to the `MAIN` u.FL port and carries **both** the terrestrial cellular signal and the Skylo satellite link — a single antenna for both networks. Use only the Skylo-certified antenna supplied with the Notecard for Skylo; substituting an uncertified antenna risks regulatory non-compliance and link failure. A belt-worn beacon needs this antenna where it can see the sky: position it against the top (sky-facing) wall of the polycarbonate enclosure (polycarbonate is RF-transparent, so no external routing or bulkhead is required), and in the northern hemisphere a southward orientation improves Skylo link margin. The same placement that enables satellite fallback serves cellular as well. | +| Skylo-certified LTE/satellite antenna included with Notecard for Skylo (u.FL) | 1 | Connects to the `MAIN` u.FL port and carries **both** the terrestrial cellular signal and the Skylo satellite link — a single antenna for both networks. Use only the Skylo-certified antenna supplied with Notecard for Skylo; substituting an uncertified antenna risks regulatory non-compliance and link failure. A belt-worn beacon needs this antenna where it can see the sky: position it against the top (sky-facing) wall of the polycarbonate enclosure (polycarbonate is RF-transparent, so no external routing or bulkhead is required), and in the northern hemisphere a southward orientation improves Skylo link margin. The same placement that enables satellite fallback serves cellular as well. | | Passive GPS/GNSS antenna (u.FL) per the [Notecard for Skylo datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) | 1 | Connects to the `GPS` u.FL port for the Notecard's own GNSS time/location — this is the device's location source, and `card.location` draws from it for the coordinates embedded in alert Notes. Adhere it alongside the main antenna on the top (sky-facing) interior wall of the polycarbonate enclosure for best acquisition geometry during GPS-on events. | | [Blues Mojo](https://shop.blues.com/products/mojo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Coulomb-counter on the LiPo rail for ground-truth current and energy measurement during bench validation. | | [SparkFun Triple Axis Accelerometer Breakout — LIS3DH (SEN-13963)](https://www.sparkfun.com/products/13963) | 1 | 3-axis MEMS accelerometer at 0x18 on I²C. Configured at 100 Hz ODR (10 milliseconds hardware sample period). The firmware samples at ~100 Hz via a 10-sample inner loop (one read every 10 milliseconds), matching the sensor ODR and reliably catching free-fall phases as short as 80 ms. ±4g range provides headroom for both normal impacts and genuine falls. Built-in free-fall and shock interrupt hardware is a production upgrade path. | @@ -131,9 +131,9 @@ Here is a sample Note this device emits: | [SparkFun Momentary Push Button Switch — 12mm Square (COM-09190)](https://www.sparkfun.com/products/9190) | 1 | Panic input, wired to D9 with firmware INPUT_PULLUP. Choose a cap that can be operated with a gloved hand for field deployability. | | 3.7V LiPo battery, 1200 mAh, JST-PH 2-pin (e.g. [Adafruit #258](https://www.adafruit.com/product/258)) | 1 | Powers the device. Runtime depends on alert frequency and transport conditions — validate with Mojo before sizing for deployment. Use a cell with built-in protection circuitry. | | [Adafruit JST PH 2-Pin Cable — Female Connector 100mm (#261)](https://www.adafruit.com/product/261) | 1 | Adapts the LiPo cell's JST-PH male plug to bare wire leads for connection to the Mojo `BAT+` and `GND` solder pads. Required to complete the LiPo→Mojo power path without cutting or modifying the LiPo cell's factory connector. | -| Polycarbonate project enclosure, ≥120 × 80 × 40 mm interior, IP54+ (e.g., Hammond 1553JGYBK) | 1 | Protects the board stack, battery, and connectors in a field-deployable package. The Notecarrier CX (83 × 63 mm) sets the minimum floor area. **Must be polycarbonate (non-metal)** — metal enclosures block cellular, WiFi, GNSS, and satellite signals. Requires cutouts for the panic button and the LiPo JST connector for battery access; the Notecard for Skylo's `MAIN` and `GPS` u.FL antennas adhere to the interior enclosure walls without external routing. IP54 or better is recommended for outdoor field use. Verify interior dimensions against your specific board-and-battery stack before ordering. **No charging circuit is included in this BOM**. See [Section 9](#11-limitations-and-next-steps) for rationale; plan enclosure cutouts for any charging connector you add downstream. | +| Polycarbonate project enclosure, ≥120 × 80 × 40 mm interior, IP54+ (e.g., Hammond 1553JGYBK) | 1 | Protects the board stack, battery, and connectors in a field-deployable package. The Notecarrier CX (83 × 63 mm) sets the minimum floor area. **Must be polycarbonate (non-metal)** — metal enclosures block cellular, WiFi, GNSS, and satellite signals. Requires cutouts for the panic button and the LiPo JST connector for battery access; Notecard for Skylo's `MAIN` and `GPS` u.FL antennas adhere to the interior enclosure walls without external routing. IP54 or better is recommended for outdoor field use. Verify interior dimensions against your specific board-and-battery stack before ordering. **No charging circuit is included in this BOM**. See [Section 9](#11-limitations-and-next-steps) for rationale; plan enclosure cutouts for any charging connector you add downstream. | -The Notecard for Skylo ships with an active global SIM including 500 MB of cellular data and 10 years of service, **plus** 10 KB of bundled Skylo satellite data — no activation fees, no monthly commitment, and no separate satellite provider subscription. Additional satellite data is billed per byte (see the [Notecard for Skylo datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) for current pricing). +Notecard for Skylo ships with an active global SIM including 500 MB of cellular data and 10 years of service, **plus** 10 KB of bundled Skylo satellite data — no activation fees, no monthly commitment, and no separate satellite provider subscription. Additional satellite data is billed per byte (see the [Notecard for Skylo datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) for current pricing). @@ -151,7 +151,7 @@ The Notecard for Skylo ships with an active global SIM including 500 MB of cellu ![Wiring: LIS3DH + DRV2605L on shared I²C; panic button to D9 INPUT_PULLUP; Notecard for Skylo MAIN (cellular+satellite) + GPS u.FL antennas; LiPo 3.7 V → Mojo → +VBAT](diagrams/02-wiring-assembly.svg) -The whole stack — Notecarrier CX, Notecard for Skylo, accelerometer, haptic driver, and panic button — has to fit inside a belt-clip enclosure that a worker will forget they're wearing. Every host I/O lands on the [Notecarrier CX](https://dev.blues.io/datasheets/notecarrier-datasheet/notecarrier-cx-v1-3/) dual 16-pin headers; the Notecard for Skylo seats into the M.2 slot and talks to the Cygnet host over the carrier's internal I²C. Because cellular, WiFi, and Skylo satellite all live on that one module, there is no companion satellite device to wire in — only the two u.FL antennas described below. The Mojo sits inline between the LiPo JST connector and the Notecarrier CX `+VBAT` pad during bench validation. +The whole stack — Notecarrier CX, Notecard for Skylo, accelerometer, haptic driver, and panic button — has to fit inside a belt-clip enclosure that a worker will forget they're wearing. Every host I/O lands on the [Notecarrier CX](https://dev.blues.io/datasheets/notecarrier-datasheet/notecarrier-cx-v1-3/) dual 16-pin headers; Notecard for Skylo seats into the M.2 slot and talks to the Cygnet host over the carrier's internal I²C. Because cellular, WiFi, and Skylo satellite all live on that one module, there is no companion satellite device to wire in — only the two u.FL antennas described below. The Mojo sits inline between the LiPo JST connector and the Notecarrier CX `+VBAT` pad during bench validation. All I²C peripherals (LIS3DH and DRV2605L) share the SDA/SCL bus exposed on the Notecarrier CX headers. On-board pull-ups are provided by the carrier; no external resistors are needed for the I²C lines. @@ -169,11 +169,11 @@ Pin-by-pin: 3. **LiPo `−` lead** → Mojo `GND` solder pad. The Mojo's `GND` terminal is common to both the battery-negative rail and the load-negative rail. 4. **Mojo `LOAD+` output** → Notecarrier CX **`+VBAT`** pad (completes the positive supply to the board stack). 5. **Mojo `GND` terminal** → Notecarrier CX **`GND`** header pin (completes the ground-return path; without this connection the circuit is open). -- **Notecard for Skylo antennas** → `MAIN` u.FL port → included Skylo-certified antenna (carries both cellular and satellite); `GPS` u.FL port → passive GPS/GNSS antenna. Both adhere to the top (sky-facing) interior wall of the polycarbonate enclosure (see the antenna Note below). No companion satellite module and no JST cable are involved — all three radios are on the Notecard for Skylo itself. +- **Notecard for Skylo antennas** → `MAIN` u.FL port → included Skylo-certified antenna (carries both cellular and satellite); `GPS` u.FL port → passive GPS/GNSS antenna. Both adhere to the top (sky-facing) interior wall of the polycarbonate enclosure (see the antenna Note below). No companion satellite module and no JST cable are involved — all three radios are on Notecard for Skylo itself. -**Antenna placement and connector mapping.** The Notecard for Skylo uses two u.FL ports. Connect the included Skylo-certified antenna to the `MAIN` port — it carries **both** the cellular signal and the Skylo satellite link, so a single antenna serves both networks — and connect the passive GPS/GNSS antenna to the `GPS` port. Adhere both elements to the top (sky-facing) interior wall of the polycarbonate enclosure: polycarbonate is RF-transparent, so no external pigtail routing or bulkhead is needed. A belt-worn beacon only reaches the Skylo satellite network when its `MAIN` antenna can see the sky, so orient that wall upward when the unit is worn; in the northern hemisphere a southward orientation improves Skylo link margin. Use only the Skylo-certified antenna supplied with the Notecard for Skylo on the `MAIN` port — substituting an uncertified antenna risks regulatory non-compliance and link failure. The `GPS` port is the location source for all `card.location` data embedded in alert Notes. +**Antenna placement and connector mapping.** Notecard for Skylo uses two u.FL ports. Connect the included Skylo-certified antenna to the `MAIN` port — it carries **both** the cellular signal and the Skylo satellite link, so a single antenna serves both networks — and connect the passive GPS/GNSS antenna to the `GPS` port. Adhere both elements to the top (sky-facing) interior wall of the polycarbonate enclosure: polycarbonate is RF-transparent, so no external pigtail routing or bulkhead is needed. A belt-worn beacon only reaches the Skylo satellite network when its `MAIN` antenna can see the sky, so orient that wall upward when the unit is worn; in the northern hemisphere a southward orientation improves Skylo link margin. Use only the Skylo-certified antenna supplied with Notecard for Skylo on the `MAIN` port — substituting an uncertified antenna risks regulatory non-compliance and link failure. The `GPS` port is the location source for all `card.location` data embedded in alert Notes. @@ -193,7 +193,7 @@ The LIS3DH's SDO/SA0 pin sets the I²C address. Leave it unconnected or pulled t 2. **Claim the Notecard.** Power the beacon with a Notecard inserted and provisioned SIM. On first cellular or satellite session the Notecard associates with your project automatically. Verify in Notehub: navigate to **Devices** → click on your device's UID — it should appear within 30–90 seconds. -3. **Complete the initial non-NTN sync.** Before any Skylo satellite (NTN) transmission is possible, the Notecard for Skylo must complete at least one successful cellular or WiFi sync to associate with your project and register the compact template definitions in Notehub. The firmware's `card.transport` `wifi-cell-ntn` setting performs that first sync over cellular/WiFi automatically, so commission each beacon where it has terrestrial coverage — even if it will routinely operate over satellite — and confirm a sync lands in Notehub before deploying. See the [`card.transport` API reference](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-transport) for details. +3. **Complete the initial non-NTN sync.** Before any Skylo satellite (NTN) transmission is possible, Notecard for Skylo must complete at least one successful cellular or WiFi sync to associate with your project and register the compact template definitions in Notehub. The firmware's `card.transport` `wifi-cell-ntn` setting performs that first sync over cellular/WiFi automatically, so commission each beacon where it has terrestrial coverage — even if it will routinely operate over satellite — and confirm a sync lands in Notehub before deploying. See the [`card.transport` API reference](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-transport) for details. 4. **Create a Fleet per region or team.** [Fleets](https://dev.blues.io/guides-and-tutorials/fleet-admin-guide/) group devices for shared configuration. A natural structure is one fleet per crew or site — all devices in a fleet share the same detection thresholds, with per-device worker ID overrides. [Smart Fleets](https://dev.blues.io/notehub/notehub-walkthrough/#using-smart-fleet-rules) can route a device to a different fleet automatically based on its reported location if workers cross territories. @@ -300,7 +300,7 @@ The `type` field in `beacon_alert.qo` carries one of two values: `fall` (two-sta **This POC keeps the host MCU awake continuously — this is a deliberate design choice, not an oversight.** The device must detect a fall or button press at any moment, so `card.attn` sleep mode (which cuts host power entirely) is incompatible with the monitoring requirement. Instead, the host MCU remains awake continuously, running a dual-cadence loop: the LIS3DH is sampled at ~100 Hz via a 10-sample inner loop (10 milliseconds between reads), and Notecard/GPS/haptic state advances at the outer ~10 Hz cadence. The inner-loop delays pace the outer cadence without a separate top-level `delay()` call. The battery-life penalty is real and significant: the STM32L433 at its default clock draws approximately 10–15 mA active, making host idle the dominant draw at steady state. See the [power validation table](#9-validation-and-testing) for per-state figures and validate total runtime with Mojo before sizing a battery for deployment. -The Notecard for Skylo runs in `periodic` mode with `outbound: 1440` (daily flush) and `inbound: 120` (2-hour environment-variable refresh). `notecardConfigure()` also issues a one-time `card.transport` `wifi-cell-ntn` so the Notecard prefers WiFi, then cellular, then Skylo satellite (NTN) — the failover is handled inside the Notecard, with no firmware branching. All emergency Notes carry `sync:true`, which bypasses the outbound interval and triggers an immediate session over whichever radio is reachable — the daily flush is a backstop for any queued data that sync:true did not deliver. Between sessions the Notecard sits in its own low-power idle state (~8 µA), regardless of which radio it last used. GPS is off by default and turned on only during alert events (fall, panic) — continuous GPS would consume an additional 30+ mA and is unnecessary given the design's event-driven location update cadence. +Notecard for Skylo runs in `periodic` mode with `outbound: 1440` (daily flush) and `inbound: 120` (2-hour environment-variable refresh). `notecardConfigure()` also issues a one-time `card.transport` `wifi-cell-ntn` so the Notecard prefers WiFi, then cellular, then Skylo satellite (NTN) — the failover is handled inside the Notecard, with no firmware branching. All emergency Notes carry `sync:true`, which bypasses the outbound interval and triggers an immediate session over whichever radio is reachable — the daily flush is a backstop for any queued data that sync:true did not deliver. Between sessions the Notecard sits in its own low-power idle state (~8 µA), regardless of which radio it last used. GPS is off by default and turned on only during alert events (fall, panic) — continuous GPS would consume an additional 30+ mA and is unnecessary given the design's event-driven location update cadence. A production implementation should use STM32L433 low-power STOP2 mode with GPIO wakeup on the LIS3DH hardware interrupt (INT1) and button pin — dropping host idle to ~2–3 µA while still catching every fall event in real time. See [Limitations](#11-limitations-and-next-steps). @@ -341,7 +341,7 @@ notecard.sendRequest(req); ### Key Code Snippet 2: Immediate-Sync Alert -`sync:true` tells the Notecard to attempt a session immediately, bypassing the periodic outbound interval. The Notecard for Skylo selects the radio per its `card.transport` `wifi-cell-ntn` preference; if WiFi and cellular both fail, the Note routes over Skylo satellite automatically. +`sync:true` tells the Notecard to attempt a session immediately, bypassing the periodic outbound interval. Notecard for Skylo selects the radio per its `card.transport` `wifi-cell-ntn` preference; if WiFi and cellular both fail, the Note routes over Skylo satellite automatically. ```cpp J *req = notecard.newRequest("note.add"); @@ -468,7 +468,7 @@ If GPS times out, only the initial `beacon_alert.qo` Note is sent; the cached lo **Simulating a panic.** Hold the button for 2+ seconds. After the 30 milliseconds debounce settles on the press edge, the haptic motor emits one click to confirm the press was registered. When the hold threshold is reached, the firmware evaluates the 60-second alert cooldown before queuing anything: if the cooldown has expired, the panic alert is accepted and three haptic buzzes (non-blocking, each fires 220 milliseconds apart without pausing button monitoring) confirm the alert is queued for transmission. The triple-buzz means the alert has been accepted for transmission handling — either directly into the Notecard's outbound queue (if `note.add` succeeded) or into the firmware's local retry queue for delivery as soon as the Notecard is reachable (if `note.add` failed transiently). If the device is still within the cooldown window, a single buzz acknowledges the hold without queuing an alert — use Notehub's event log to distinguish a suppressed panic from a queued one. A `beacon_alert.qo` with `"type":"panic"` should arrive in Notehub within session-establishment time. If GPS acquires a fresh fix during the background search, a `beacon_location.qo` follow-up Note will appear as well. -**Simulating satellite failover.** With the device outdoors (the `MAIN` antenna has sky view), force a satellite session by temporarily restricting the Notecard for Skylo to NTN-only (via `{"req":"card.transport","method":"ntn"}` issued from the blues.dev In-Browser Terminal). Trigger a panic. The alert should arrive in Notehub over the satellite path — verifiable in the event metadata, which will show `"transport":"ntn"`. Reset transport afterward to restore automatic failover: `{"req":"card.transport","method":"wifi-cell-ntn"}`. +**Simulating satellite failover.** With the device outdoors (the `MAIN` antenna has sky view), force a satellite session by temporarily restricting Notecard for Skylo to NTN-only (via `{"req":"card.transport","method":"ntn"}` issued from the blues.dev In-Browser Terminal). Trigger a panic. The alert should arrive in Notehub over the satellite path — verifiable in the event metadata, which will show `"transport":"ntn"`. Reset transport afterward to restore automatic failover: `{"req":"card.transport","method":"wifi-cell-ntn"}`. **Power validation with Mojo.** The [Mojo](https://dev.blues.io/datasheets/mojo-datasheet/) sits inline between the LiPo and the Notecarrier CX `+VBAT` pad. It accumulates the charge consumed by the board stack and makes the reading available over its Qwiic I²C link. **The beacon firmware does not read the Mojo** — it is a bench measurement instrument only. To retrieve the mAh reading during validation, connect a separate Qwiic-capable host (a SparkFun RedBoard Qwiic, a Notecarrier AL with its own sketch, or any I²C host with a Qwiic port) running the Mojo readout sketch to the Mojo's Qwiic connector. Run that host alongside the beacon during your validation window; its USB serial output gives you real-time mAh accumulation without touching the beacon firmware. @@ -530,7 +530,7 @@ A productive bench exercise: run the device for 2 hours on a known-capacity LiPo - Use Mojo (see [Section 8](#9-validation-and-testing)) to measure actual current in different states (idle, fall/panic event, GPS search, sync). Compare against the estimated figures in the power validation table. If measured idle is >25 mA, a peripheral may be drawing unexpectedly — check I²C for clock-stretching issues or peripheral misconfigurations. **Skylo satellite transmission fails or never completes.** -- The Skylo NTN path is only active after the Notecard for Skylo has completed at least one successful cellular or WiFi sync to associate with your project and deliver the compact template definitions to Notehub. If the beacon launches in a no-cellular area, it cannot use satellite until it has found cellular (or WiFi) coverage at least once. Move the device to coverage, power it on, wait for a sync (check Notehub device status), then move back to the satellite-only zone. +- The Skylo NTN path is only active after Notecard for Skylo has completed at least one successful cellular or WiFi sync to associate with your project and deliver the compact template definitions to Notehub. If the beacon launches in a no-cellular area, it cannot use satellite until it has found cellular (or WiFi) coverage at least once. Move the device to coverage, power it on, wait for a sync (check Notehub device status), then move back to the satellite-only zone. - Verify the `MAIN` antenna orientation: it should face the sky (polycarbonate enclosure top is sufficient); in the northern hemisphere, southward orientation improves link margin. If the antenna is buried against a body or oriented away from the sky, Skylo acquisition may fail. - Check Skylo coverage: the Skylo network covers specific regions (see the [Notecard for Skylo datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/)). If you're outside the coverage footprint, NTN transmission will fail silently. - From the [Blues In-Browser Terminal](https://dev.blues.io/terminal/), issue `{"req":"card.transport","method":"ntn"}` to force satellite-only operation (cellular and WiFi disabled). Trigger a test panic from a location with sky view. Check the event metadata: if `"transport":"ntn"` is present, the satellite path is working. Re-enable automatic failover: `{"req":"card.transport","method":"wifi-cell-ntn"}`. @@ -563,9 +563,9 @@ This is a reference design, not a finished safety product. Several things a real - **No data encryption.** Notes travel over TLS between Notecard and Notehub; the Notefile body is not additionally encrypted. For sensitive safety applications with worker location data, consider using `beacon_alert.qos` (`.qos` suffix enables encrypted transport at the Notecard level). -- **Skylo NTN requires an initial non-NTN sync.** The Skylo satellite (NTN) path is not available until the Notecard for Skylo has completed at least one successful cellular or WiFi session to associate with Notehub and register the Notefile templates. A device that ships directly into a no-cellular zone will be unable to send via satellite until it has found cellular (or WiFi) coverage at least once. Pre-provisioning during QA on a cellular-capable bench is the standard mitigation. +- **Skylo NTN requires an initial non-NTN sync.** The Skylo satellite (NTN) path is not available until Notecard for Skylo has completed at least one successful cellular or WiFi session to associate with Notehub and register the Notefile templates. A device that ships directly into a no-cellular zone will be unable to send via satellite until it has found cellular (or WiFi) coverage at least once. Pre-provisioning during QA on a cellular-capable bench is the standard mitigation. -- **Satellite payload budget.** The Notecard for Skylo bundle includes 10 KB of Skylo satellite data, and the Skylo NTN link enforces a hard 256-byte maximum per Note. The compact alert template is well under that ceiling; frequent triggering in a no-cellular environment will consume the bundle faster. Monitor satellite usage via [Notehub billing/usage data](https://dev.blues.io/notehub/notehub-walkthrough/#configuring-your-billing-account). +- **Satellite payload budget.** Notecard for Skylo bundle includes 10 KB of Skylo satellite data, and the Skylo NTN link enforces a hard 256-byte maximum per Note. The compact alert template is well under that ceiling; frequent triggering in a no-cellular environment will consume the bundle faster. Monitor satellite usage via [Notehub billing/usage data](https://dev.blues.io/notehub/notehub-walkthrough/#configuring-your-billing-account). - **Single I²C bus for all peripherals.** LIS3DH and DRV2605L share the bus with the internal Notecard connection. A severe I²C lockup (e.g., a partially-completed transaction interrupted by a reset) could block all communication. A production design should include bus-error recovery and a hardware watchdog. @@ -585,4 +585,4 @@ This is a reference design, not a finished safety product. Several things a real ## 12. Summary -The lineman at the edge of the substation, the pumper at the rural wellhead, the field tech in the 2 AM boiler room — each of them now clips on a device that does what no check-in procedure ever could: it watches them automatically, with no worker action required, and reaches a dispatcher even when cellular goes dark. The two-stage fall algorithm rejects everyday bumps without losing genuine falls; the panic button is there for the situations that don't look like physics; the Notecard for Skylo's onboard satellite radio covers the specific sites where cellular fails first and matters most — no companion module, no second device. The cellular path handles the vast majority of activations quickly and inexpensively; the satellite path is the safety margin underneath it. That combination, in a belt-clip enclosure, is the practical shape of lone-worker safety assurance — supplementing, not replacing, the procedures and PPE that came before it. +The lineman at the edge of the substation, the pumper at the rural wellhead, the field tech in the 2 AM boiler room — each of them now clips on a device that does what no check-in procedure ever could: it watches them automatically, with no worker action required, and reaches a dispatcher even when cellular goes dark. The two-stage fall algorithm rejects everyday bumps without losing genuine falls; the panic button is there for the situations that don't look like physics; Notecard for Skylo's onboard satellite radio covers the specific sites where cellular fails first and matters most — no companion module, no second device. The cellular path handles the vast majority of activations quickly and inexpensively; the satellite path is the safety margin underneath it. That combination, in a belt-clip enclosure, is the practical shape of lone-worker safety assurance — supplementing, not replacing, the procedures and PPE that came before it. diff --git a/63-construction-equipment-anti-theft-tracker-with-immobilizer/README.md b/63-construction-equipment-anti-theft-tracker-with-immobilizer/README.md index 16b82a80..2fbb1fee 100644 --- a/63-construction-equipment-anti-theft-tracker-with-immobilizer/README.md +++ b/63-construction-equipment-anti-theft-tracker-with-immobilizer/README.md @@ -18,7 +18,7 @@ The result is an industry that leans heavily on equipment marking, insurance cla This project is that device. It monitors GPS location against a configurable job-site geofence, watches for unexpected after-hours motion, and accepts a remote immobilizer command from Notehub that stages a relay to cut the ignition circuit on the thief's next key-on attempt — a polled, staged proof-of-concept immobilizer rather than a continuously-held cut, with the limitations that implies (see §11). The whole stack — GPS, cellular, and satellite fallback — is contained in a single Blues Notecard for Skylo installed in a weatherproof enclosure that runs indefinitely on a LiPo battery topped off by a small solar panel. -**Why Notecard.** Construction sites have no WiFi. Even if a site happens to have a hotspot, requiring site IT coordination for a security device defeats the purpose. Cellular works for the vast majority of scenarios, but a stolen skid steer doesn't stay parked in a well-covered urban area. It ends up in a rural equipment yard, a metal barn, or a shipping container at a port. That's the scenario where cellular alone fails and satellite becomes the difference between a recovered asset and a total write-off. The Notecard for Skylo ([NOTE-NBGLWX](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/)) handles all three radio paths — LTE-M/NB-IoT cellular, WiFi (where available), and Skylo satellite — in a single M.2 module, without any firmware branching. Planetary roaming and satellite fallover are not optional extras for this use case; they are the core differentiators. +**Why Notecard.** Construction sites have no WiFi. Even if a site happens to have a hotspot, requiring site IT coordination for a security device defeats the purpose. Cellular works for the vast majority of scenarios, but a stolen skid steer doesn't stay parked in a well-covered urban area. It ends up in a rural equipment yard, a metal barn, or a shipping container at a port. That's the scenario where cellular alone fails and satellite becomes the difference between a recovered asset and a total write-off. Notecard for Skylo ([NOTE-NBGLWX](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/)) handles all three radio paths — LTE-M/NB-IoT cellular, WiFi (where available), and Skylo satellite — in a single M.2 module, without any firmware branching. Planetary roaming and satellite fallover are not optional extras for this use case; they are the core differentiators. @@ -30,7 +30,7 @@ This project is that device. It monitors GPS location against a configurable job **Device-side responsibilities.** The Cygnet STM32 host in the [Notecarrier CX](https://dev.blues.io/datasheets/notecarrier-datasheet/notecarrier-cx-v1-3/) spends almost all of its time asleep — the whole power budget depends on it. When the configurable wake timer fires, the firmware reads ignition state from a voltage divider on the 12 V ignition line, polls the Notecard's built-in accelerometer via [`card.motion`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-motion), and pulls the most recent GPS fix via [`card.location`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-location). It then runs three checks in order: is the position outside the Haversine-evaluated job-site geofence; is this the after-hours window; and is there a fresh immobilize command sitting in the inbound queue? Any heartbeat or alert Notes ride to the Notecard over I²C using the `note-arduino` request helpers, and the runtime state — geofence center, immobilizer stage, cadence parameters — is serialized to Notecard flash before sleep and rehydrated on the next wake via [`NotePayloadSaveAndSleep`](https://dev.blues.io/guides-and-tutorials/notecard-guides/attention-pin-guide/) / `NotePayloadRetrieveAfterSleep`. -**Notecard responsibilities.** The Notecard for Skylo is doing most of the connectivity work behind the scenes. It buffers queued [Notes](https://dev.blues.io/api-reference/glossary/#note) in on-device flash, opens a cellular or satellite session on the [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence, and treats any `sync:true` alert Note as an immediate uplink — the difference between an alert reaching the operator in seconds and the equipment crossing a county line. The same module also owns the GPS receiver, the accelerometer, the real-time clock, and the battery-voltage ADC, so no external sensors are needed. [Environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) flow back from Notehub on each inbound sync — a fleet manager can retune the geofence radius or the after-hours window from a browser, and the firmware automatically reissues `hub.set` and `card.location.mode` so all three Notecard cadences stay aligned with the new wake interval. +**Notecard responsibilities.** Notecard for Skylo is doing most of the connectivity work behind the scenes. It buffers queued [Notes](https://dev.blues.io/api-reference/glossary/#note) in on-device flash, opens a cellular or satellite session on the [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence, and treats any `sync:true` alert Note as an immediate uplink — the difference between an alert reaching the operator in seconds and the equipment crossing a county line. The same module also owns the GPS receiver, the accelerometer, the real-time clock, and the battery-voltage ADC, so no external sensors are needed. [Environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) flow back from Notehub on each inbound sync — a fleet manager can retune the geofence radius or the after-hours window from a browser, and the firmware automatically reissues `hub.set` and `card.location.mode` so all three Notecard cadences stay aligned with the new wake interval. **Notehub responsibilities.** [Notehub](https://notehub.io) ingests every event from every device — whether it arrived over cellular or Skylo — stores it, and applies the project's [routes](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub). Alert Notes (`alert.qo`) and tracker heartbeats (`tracker.qo`) land in separate Notefiles, so the security platform that needs alerts the moment they happen and the fleet-management store that needs position history can be served from the same device with no filter logic in between. Operators stage an `immobilize` or `release` command by posting a Note to the device's `immobilize.qi` inbound queue from the Notehub UI or via the [Notehub REST API](https://dev.blues.io/api-reference/notehub-api/api-introduction/). [Smart Fleets](https://dev.blues.io/notehub/notehub-walkthrough/#using-smart-fleet-rules) push site-level geofence and after-hours defaults to every machine on a job site at once. @@ -126,8 +126,8 @@ Here is a sample Note this device emits: | 10 kΩ resistor, ¼ W | 1 | Gate-to-source pulldown on the BSS138. Ensures the MOSFET stays off if the Cygnet GPIO is high-impedance during reset or power-on. | | 33 kΩ + 10 kΩ resistors, ¼ W, 1% tolerance | 2 | Resistive voltage divider for ignition sense: 33 kΩ high-side (to 12 V rail) + 10 kΩ low-side (to GND) → 12 V × 10 / (33 + 10) ≈ 2.79 V at A2 — safely within the Cygnet's 3.3 V GPIO absolute maximum. 1% tolerance for a consistent threshold. **POC-only front end** — this bare divider provides no protection against automotive load-dump or starter transients; see §5 and §11 for production protection guidance. | | NEMA 4X weatherproof enclosure, ~150×100×75 mm (e.g. [Polycase WC-31](https://www.polycase.com/wc-31) or Hammond 1554N2GYCL) | 1 | Rated for outdoor hose-down environments. Mount inside the equipment housing where it is not visible from outside. | -| Skylo-certified cellular/satellite antenna — **use the antenna included in the NOTE-NBGLWX kit** | 1 | Connects to the `MAIN` u.FL on the Notecard for Skylo. The NOTE-NBGLWX is certified on Skylo's network exclusively with the included antenna; substituting a different antenna voids Skylo network certification and may result in network blocking. See the [antenna guide](https://dev.blues.io/datasheets/application-notes/antenna-guide/) for placement requirements. | -| Passive GNSS antenna, GPS L1 1575 MHz, u.FL connector, outdoor-rated (e.g. [Taoglas FXP611 (Cloud)](https://www.taoglas.com/product/cloud-fxp611-gps-glonass-compass-flexible-pcb-2/) flexible PCB GPS/GLONASS antenna with u.FL lead, or equivalent passive GPS patch) | 1 | Connects to the `GPS` u.FL on the Notecard for Skylo. Must be a passive antenna (the `GPS` port does not supply bias voltage). Mount outdoors with clear sky view alongside the MAIN antenna. | +| Skylo-certified cellular/satellite antenna — **use the antenna included in the NOTE-NBGLWX kit** | 1 | Connects to the `MAIN` u.FL on Notecard for Skylo. The NOTE-NBGLWX is certified on Skylo's network exclusively with the included antenna; substituting a different antenna voids Skylo network certification and may result in network blocking. See the [antenna guide](https://dev.blues.io/datasheets/application-notes/antenna-guide/) for placement requirements. | +| Passive GNSS antenna, GPS L1 1575 MHz, u.FL connector, outdoor-rated (e.g. [Taoglas FXP611 (Cloud)](https://www.taoglas.com/product/cloud-fxp611-gps-glonass-compass-flexible-pcb-2/) flexible PCB GPS/GLONASS antenna with u.FL lead, or equivalent passive GPS patch) | 1 | Connects to the `GPS` u.FL on Notecard for Skylo. Must be a passive antenna (the `GPS` port does not supply bias voltage). Mount outdoors with clear sky view alongside the MAIN antenna. | All Blues hardware ships with an active SIM including 500 MB of cellular data and 10 years of service — no activation fee, no monthly commitment. @@ -145,7 +145,7 @@ All Blues hardware ships with an active SIM including 500 MB of cellular data an -The whole assembly has to disappear inside the equipment chassis — behind a panel, under a seat, in an equipment bay where a thief won't find it — so the build is small and the antennas are the only parts that need to see the sky. The Notecard for Skylo seats into the Notecarrier CX's M.2 slot; route the **`MAIN` u.FL** lead to the Skylo-certified antenna that came with the kit and the **`GPS` u.FL** lead to the separate passive GNSS antenna. Leave both leads slack until the final enclosure mounting location is set — antenna placement and clear sky view matter significantly for Skylo lock. +The whole assembly has to disappear inside the equipment chassis — behind a panel, under a seat, in an equipment bay where a thief won't find it — so the build is small and the antennas are the only parts that need to see the sky. Notecard for Skylo seats into the Notecarrier CX's M.2 slot; route the **`MAIN` u.FL** lead to the Skylo-certified antenna that came with the kit and the **`GPS` u.FL** lead to the separate passive GNSS antenna. Leave both leads slack until the final enclosure mounting location is set — antenna placement and clear sky view matter significantly for Skylo lock. During bench validation the Mojo coulomb counter splices inline on the +VBAT wire to measure phase-by-phase current draw; see the [Mojo datasheet](https://dev.blues.io/datasheets/mojo-datasheet/) for wiring. It comes out before the unit ships to the field (or stays in circuit only if you add the Qwiic telemetry extension — see §11). @@ -235,7 +235,7 @@ Every wake runs the same compact cycle: sense, evaluate, queue any Notes, save s **Ignition sense.** A voltage divider on the equipment's 12 V ignition rail presents ~2.79 V to the Cygnet's A2 pin when the ignition key is ON — within the 3.3 V safe limit. The high-side resistor (33 kΩ, to the 12 V rail) and low-side resistor (10 kΩ, to GND) set the divider ratio: 12 V × 10 / (33 + 10) ≈ 2.79 V. On each wake the Cygnet reads A2 with `analogRead()` at 12-bit resolution, averaging 4 samples to filter automotive line noise and battery-sag transients during engine crank. State changes are governed by hysteresis thresholds: the averaged reading must exceed ~2.50 V (3103 counts on a 12-bit / 3.3 V ADC) to declare ignition ON, and must fall below ~2.00 V (2482 counts) to declare ignition OFF. Within the ~0.5 V hysteresis band the firmware holds the previous state, preventing chatter at the logic boundary and spanning the typical battery-sag floor (~10.5 V → ~2.44 V at the divider) during cold cranks. -**Motion.** The Notecard for Skylo's built-in accelerometer runs continuously in low-power mode. `card.motion.mode` configures it for 25Hz, ±4G sensitivity with a 60-second bucket. The firmware calls `card.motion` on each wake; when the bucket contains at least 3 events, the Notecard reports `"mode":"moving"`. This approach detects both equipment being driven away (sustained multi-axis motion) and equipment being loaded onto a trailer (tilt, vibration). +**Motion.** Notecard for Skylo's built-in accelerometer runs continuously in low-power mode. `card.motion.mode` configures it for 25Hz, ±4G sensitivity with a 60-second bucket. The firmware calls `card.motion` on each wake; when the bucket contains at least 3 events, the Notecard reports `"mode":"moving"`. This approach detects both equipment being driven away (sustained multi-axis motion) and equipment being loaded onto a trailer (tilt, vibration). **GPS.** `card.location.mode` is set to `periodic` with a motion threshold of 4 events, so the Notecard only spins up the GNSS module when the accelerometer confirms the unit is actually moving — avoiding the multi-second GNSS warm-up penalty on every stationary wake. The firmware calls `card.location` to read the most recent fix; the Notecard caches the last valid location so the call returns quickly even when GNSS is not active. @@ -330,7 +330,7 @@ The GPS module is motion-gated at the Notecard level — it only activates after ### Key code snippet 1: compact Note template definition -The `format:"compact"` and `port:50` arguments are required for the Notecard for Skylo. Without them, Notes destined for the satellite path may be dropped. The numeric type hints (`14.1` = 4-byte float, `12` = 2-byte signed int) define the binary record layout. +The `format:"compact"` and `port:50` arguments are required for Notecard for Skylo. Without them, Notes destined for the satellite path may be dropped. The numeric type hints (`14.1` = 4-byte float, `12` = 2-byte signed int) define the binary record layout. ```cpp J *req = notecard.newRequest("note.template"); @@ -398,7 +398,7 @@ NotePayloadSaveAndSleep(&save, sleep_sec, NULL); ![Data flow: ignition/motion/GPS/battery → Cygnet edge rules → alert.qo (sync:true, immediate) and tracker.qo (queued, batch outbound) → Notehub → routes; immobilize.qi inbound from Notehub to Cygnet → relay](diagrams/03-data-flow.svg) -**Collected every wake cycle.** Ignition state (12V voltage divider), motion status (Notecard accelerometer, read via `card.motion`), GPS fix (Notecard GNSS, read via `card.location`), battery voltage (`card.voltage`), UTC epoch (`card.time`). No I²C sensors external to the Notecard are used — all sensing is built into the Notecard for Skylo module. +**Collected every wake cycle.** Ignition state (12V voltage divider), motion status (Notecard accelerometer, read via `card.motion`), GPS fix (Notecard GNSS, read via `card.location`), battery voltage (`card.voltage`), UTC epoch (`card.time`). No I²C sensors external to the Notecard are used — all sensing is built into Notecard for Skylo module. **Transmitted:** @@ -496,7 +496,7 @@ Satellite session validation requires outdoor antenna placement with clear sky v - Skylo satellites are in geostationary orbit (GEO) over the equator. Antenna must have a clear southern sky view. From northern hemisphere, satellite is low on the southern horizon — objects above 15° south-of-horizon elevation may block the link. - First satellite acquisition can take 2–5 minutes. Antenna orientation and sky clarity are critical. See [Satellite Best Practices](https://dev.blues.io/starnote/satellite-best-practices/) for detailed placement guidance. - If Skylo is the fallback and cellular is available, the device will prefer cellular and never trigger satellite. To test satellite, disconnect cellular or move the device to an area with no cellular coverage (e.g., rural location, underground bunker after the charger has been removed so it cannot fall back to USB). -- Verify that the Notecard for Skylo (NOTE-NBGLWX) antenna is the Skylo-certified antenna included with the kit. A substituted antenna may not lock onto the Skylo network. See datasheet for antenna part number. +- Verify that Notecard for Skylo (NOTE-NBGLWX) antenna is the Skylo-certified antenna included with the kit. A substituted antenna may not lock onto the Skylo network. See datasheet for antenna part number. ## 11. Limitations and Next Steps @@ -512,7 +512,7 @@ This POC demonstrates the control path, the data path, and the satellite fallbac - **Geofence is a circle.** The firmware uses a Haversine-computed circle around a single center point. Irregular job-site boundaries (L-shaped lots, equipment lots separated by roads) would require multiple overlapping circles or a polygon geofence, neither of which is implemented here. - **Single geofence.** The device stores one home location. Equipment that legitimately moves between job sites (morning deliveries, weekend staging) will generate false geofence breach alerts unless the operator updates `fence_lat` / `fence_lon` in Notehub ahead of each move. - **No tamper detection.** The firmware does not detect cable cutting, enclosure intrusion, or GPS jamming. A motivated thief who locates and removes the tracker, jams the antenna, or removes the equipment battery before the solar reserve is depleted will defeat this POC design. -- **Satellite data budget.** The Notecard for Skylo includes 10 KB of Skylo data per month. Compact record sizes derived from the actual template field types are **26 bytes** per `tracker.qo` heartbeat (4 floats × 4 bytes + 5 int16 × 2 bytes) and **47 bytes** per `alert.qo` event (4 floats × 4 bytes + 3 int16 × 2 bytes + 24-char string field at 25 bytes). The payload-only budget therefore supports roughly **390 heartbeat-sized Notes** (10,240 ÷ 26 bytes) or **215 alert-sized Notes** (10,240 ÷ 47 bytes) per month. Actual usable counts are lower after satellite-session protocol and framing overhead — validate against Notehub usage metrics and field measurements rather than relying on payload-only arithmetic. Under normal stationary operation, heartbeats queue every hour and batch-transmit every 4 hours (~6 outbound sessions/day), so the heartbeat budget is well within limits. **Alert storm risk:** if the equipment is under active pursuit and cellular coverage is lost, repeated `sync:true` alerts every `alert_cooldown_min` (default 5 minutes) can consume the Skylo budget quickly — 47 bytes × 288 alerts/day (5-min cadence) = 13.5 KB, exceeding the monthly satellite allowance in a single day. If satellite-only operation during a pursuit event is expected, raise `alert_cooldown_min` to 15–30 minutes via the Notehub fleet env var to protect the monthly budget. In production, consider gating satellite transmission to alerts only and enforcing a per-Note minimum satellite interval. +- **Satellite data budget.** Notecard for Skylo includes 10 KB of Skylo data per month. Compact record sizes derived from the actual template field types are **26 bytes** per `tracker.qo` heartbeat (4 floats × 4 bytes + 5 int16 × 2 bytes) and **47 bytes** per `alert.qo` event (4 floats × 4 bytes + 3 int16 × 2 bytes + 24-char string field at 25 bytes). The payload-only budget therefore supports roughly **390 heartbeat-sized Notes** (10,240 ÷ 26 bytes) or **215 alert-sized Notes** (10,240 ÷ 47 bytes) per month. Actual usable counts are lower after satellite-session protocol and framing overhead — validate against Notehub usage metrics and field measurements rather than relying on payload-only arithmetic. Under normal stationary operation, heartbeats queue every hour and batch-transmit every 4 hours (~6 outbound sessions/day), so the heartbeat budget is well within limits. **Alert storm risk:** if the equipment is under active pursuit and cellular coverage is lost, repeated `sync:true` alerts every `alert_cooldown_min` (default 5 minutes) can consume the Skylo budget quickly — 47 bytes × 288 alerts/day (5-min cadence) = 13.5 KB, exceeding the monthly satellite allowance in a single day. If satellite-only operation during a pursuit event is expected, raise `alert_cooldown_min` to 15–30 minutes via the Notehub fleet env var to protect the monthly budget. In production, consider gating satellite transmission to alerts only and enforcing a per-Note minimum satellite interval. - **Mojo is bench-only in this POC.** The firmware does not read Mojo's LTC2959 coulomb counter over the Qwiic bus. Mojo is used only as a bench measurement instrument during validation. **Production next steps:** diff --git a/65-off-grid-livestock-water-tank-monitor/README.md b/65-off-grid-livestock-water-tank-monitor/README.md index 9deb84df..49754e9a 100644 --- a/65-off-grid-livestock-water-tank-monitor/README.md +++ b/65-off-grid-livestock-water-tank-monitor/README.md @@ -27,7 +27,7 @@ Expected data consumption: ~6 KB/month on the 500 MB included prepaid Blues data The failure modes are simple and repeatable. Tanks go dry because a float valve sticks or fails and the tank drains down, because the pump's supply well drops below the intake (the pump keeps running but moves no water), or because the pump motor fails entirely and nothing moves even when the float calls for it. None of these require sophisticated modeling — they are observable conditions that nobody happens to be watching. The sensor suite here measures exactly the two signals a rancher or hired hand would check on a physical inspection: how high is the water, and is the pump drawing current? The third measurement — solar battery voltage — tells you whether the monitoring system itself is healthy and likely to keep reporting through a run of cloudy days. -**Why Notecard.** Stock tanks sit miles from the ranch house, beyond WiFi range, beyond LoRa range, and frequently beyond the reach of any terrestrial infrastructure. The [Notecard for Skylo](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) addresses both halves of the connectivity problem in a single module: it uses cellular (LTE-M/NB-IoT) where a tower is reachable and falls back to the Skylo NTN satellite network where terrestrial coverage ends. Many ranch pastures sit in mixed coverage — a cellular signal may be available across most of a property, but valleys and remote corners go dark. A tank in a covered valley reports over cellular while a tank on a ridge beyond any tower still reports via satellite; the rancher sees both without understanding which network carried the data. No SIM activation, no carrier contract, no per-site configuration required. The Notecard also handles the low-power half: in periodic mode with a 15-minute sampling interval, the radio is active for tens of seconds every few hours and silent the rest of the time, making it possible to run this device indefinitely on a modest solar panel and a single battery even through overcast weeks in a northern winter. +**Why Notecard.** Stock tanks sit miles from the ranch house, beyond WiFi range, beyond LoRa range, and frequently beyond the reach of any terrestrial infrastructure. [Notecard for Skylo](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) addresses both halves of the connectivity problem in a single module: it uses cellular (LTE-M/NB-IoT) where a tower is reachable and falls back to the Skylo NTN satellite network where terrestrial coverage ends. Many ranch pastures sit in mixed coverage — a cellular signal may be available across most of a property, but valleys and remote corners go dark. A tank in a covered valley reports over cellular while a tank on a ridge beyond any tower still reports via satellite; the rancher sees both without understanding which network carried the data. No SIM activation, no carrier contract, no per-site configuration required. The Notecard also handles the low-power half: in periodic mode with a 15-minute sampling interval, the radio is active for tens of seconds every few hours and silent the rest of the time, making it possible to run this device indefinitely on a modest solar panel and a single battery even through overcast weeks in a northern winter. @@ -39,7 +39,7 @@ The failure modes are simple and repeatable. Tanks go dry because a float valve **Device-side responsibilities.** The onboard Cygnet STM32L433 host on the Notecarrier CX wakes on a 15-minute interval driven by [`card.attn`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-attn), reads three sensors (ultrasonic level, pump RMS current, solar battery voltage), evaluates alert thresholds, accumulates readings into a rolling window for the next summary, and returns to sleep. All Notecard interaction happens over I²C — no AT commands, no serial buffers, no JSON hand-rolling. -**Notecard responsibilities.** The Notecard for Skylo stores [Notes](https://dev.blues.io/api-reference/glossary/#note) in its on-device queue, selects the best available transport (cellular or Skylo satellite), manages the session on the configured [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence (default 4 hours), and flushes `sync:true` alert Notes immediately regardless of that cadence. Transport selection is transparent to the host firmware — the same `note.add` JSON that queues a Note over cellular also queues it over satellite. The Notecard also distributes [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) from Notehub on each inbound sync — alert thresholds, tank calibration values, and sampling intervals are all operator-tunable from the Notehub console without re-flashing the device. +**Notecard responsibilities.** Notecard for Skylo stores [Notes](https://dev.blues.io/api-reference/glossary/#note) in its on-device queue, selects the best available transport (cellular or Skylo satellite), manages the session on the configured [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence (default 4 hours), and flushes `sync:true` alert Notes immediately regardless of that cadence. Transport selection is transparent to the host firmware — the same `note.add` JSON that queues a Note over cellular also queues it over satellite. The Notecard also distributes [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) from Notehub on each inbound sync — alert thresholds, tank calibration values, and sampling intervals are all operator-tunable from the Notehub console without re-flashing the device. **Notehub responsibilities.** [Notehub](https://notehub.io) receives and stores every event — whether it arrived via the cellular or satellite transport, and applies project-level routes. Periodic summaries and alerts land in separate [Notefiles](https://dev.blues.io/api-reference/glossary/#notefile), so routes can fan them to different destinations: alerts to an SMS gateway or push-notification service, summaries to a long-term time-series store for trend analysis. [Smart Fleets](https://dev.blues.io/notehub/notehub-walkthrough/#using-smart-fleet-rules) can classify devices automatically by pasture name or tank ID so that fleet-level environment variables encode site-specific calibration values without touching the firmware. @@ -108,7 +108,7 @@ All Blues hardware ships with an active SIM including 500 MB of cellular data an ![Wiring: MB7389 ultrasonic to A0; SCT-013 CT with V/2 bias to A1; battery divider to A2 with PMOS gated by A3; Skylo MAIN antenna via u.FL to SMA bulkhead; solar 20 W → charge controller → 12 V battery → 5 V step-down → +VBAT](diagrams/02-wiring-assembly.svg) -All host I/O lands on the [Notecarrier CX](https://dev.blues.io/datasheets/notecarrier-datasheet/notecarrier-cx-v1-3/) dual 16-pin header. The Notecard for Skylo seats into the M.2 slot. The Mojo is a bench power-measurement instrument spliced inline between the step-down regulator output and the Notecarrier's `+VBAT` pad during commissioning; it is not read by the deployed firmware and is removed before field installation. +All host I/O lands on the [Notecarrier CX](https://dev.blues.io/datasheets/notecarrier-datasheet/notecarrier-cx-v1-3/) dual 16-pin header. Notecard for Skylo seats into the M.2 slot. The Mojo is a bench power-measurement instrument spliced inline between the step-down regulator output and the Notecarrier's `+VBAT` pad during commissioning; it is not read by the deployed firmware and is removed before field installation. @@ -479,4 +479,4 @@ This reference design is a single-tank monitor that works on a pole next to a st ## 12. Summary -A Notecarrier CX and Notecard for Skylo — paired with a weatherproof ultrasonic level sensor, a clamp-on current transformer, and a handful of passive components — give a rancher continuous visibility into every stock tank on the property without driving the pasture roads. The Notecard for Skylo uses cellular where a tower is reachable and falls back to the Skylo satellite network where terrestrial coverage ends, so tanks in covered valleys and tanks on remote ridges both report through the same firmware and the same Notehub project. Sampling happens locally every 15 minutes with the host MCU asleep between measurements; the radio wakes only for the 4-hour summary or an immediate alert. That duty cycle makes the system comfortable running indefinitely on a modest solar setup, with built-in power-aware sleep extension to handle extended overcast stretches in northern winters. Dry-tank alerts and solar fault alerts reach the rancher's phone before cattle suffer from dehydration; pump current is captured as observational telemetry in every summary and alert payload so operators can correlate it with tank levels after the fact. It's a simple problem — know when the tank is low, and the Blues stack is a proportionately simple solution: a sensor, a Notecard, and a network path that follows the asset wherever it lives. +A Notecarrier CX and Notecard for Skylo — paired with a weatherproof ultrasonic level sensor, a clamp-on current transformer, and a handful of passive components — give a rancher continuous visibility into every stock tank on the property without driving the pasture roads. Notecard for Skylo uses cellular where a tower is reachable and falls back to the Skylo satellite network where terrestrial coverage ends, so tanks in covered valleys and tanks on remote ridges both report through the same firmware and the same Notehub project. Sampling happens locally every 15 minutes with the host MCU asleep between measurements; the radio wakes only for the 4-hour summary or an immediate alert. That duty cycle makes the system comfortable running indefinitely on a modest solar setup, with built-in power-aware sleep extension to handle extended overcast stretches in northern winters. Dry-tank alerts and solar fault alerts reach the rancher's phone before cattle suffer from dehydration; pump current is captured as observational telemetry in every summary and alert payload so operators can correlate it with tank levels after the fact. It's a simple problem — know when the tank is low, and the Blues stack is a proportionately simple solution: a sensor, a Notecard, and a network path that follows the asset wherever it lives. diff --git a/66-remote-apiary-hive-health-monitor/README.md b/66-remote-apiary-hive-health-monitor/README.md index 0511441f..4862562e 100644 --- a/66-remote-apiary-hive-health-monitor/README.md +++ b/66-remote-apiary-hive-health-monitor/README.md @@ -15,7 +15,7 @@ This project is a solar-powered hive monitor that turns each hive into a [remote **The problem.** Commercial beekeepers run apiary yards in orchards, fields, and forest edges where there is no electrical infrastructure and no cellular signal worth depending on. A full-sized Langstroth hive in production can weigh 40–80 kg, and the difference between a thriving colony and a dead one, or a hive that has just swarmed and taken 10,000 bees with it — is measured in kilograms, degrees, and the subtle shift in pitch of the colony's acoustic hum. None of those signals are observable from a distance without instrumentation, and traditional hive inspection — opening the box, smoking the bees, physically weighing the stand — takes time, disturbs the colony, and simply can't happen every 15 minutes. The result is that hive collapse, swarm departure, and queen loss are routinely discovered days after the fact, when the economic damage is already done. -This project is the remote set of eyes and ears that a beekeeper wants but cannot afford to physically station at every yard. A single weatherproof enclosure mounted on the hive stand reads three independent signals: weight (colony biomass and honey stores), temperature and humidity inside the brood box (brood viability), and acoustic features sampled from an analog microphone inside the hive (behavioral state). Those three signals are processed locally — weight and temperature sampled every 15 minutes, audio captured once per day — aggregated into a daily summary, and pushed to Notehub over cellular where a tower is in reach, and over the [Skylo](https://www.skylo.tech/) satellite network where one isn't — the Notecard for Skylo selects the path automatically. The beekeeper gets one notification per day in steady state and an immediate alert when any signal crosses a threshold. +This project is the remote set of eyes and ears that a beekeeper wants but cannot afford to physically station at every yard. A single weatherproof enclosure mounted on the hive stand reads three independent signals: weight (colony biomass and honey stores), temperature and humidity inside the brood box (brood viability), and acoustic features sampled from an analog microphone inside the hive (behavioral state). Those three signals are processed locally — weight and temperature sampled every 15 minutes, audio captured once per day — aggregated into a daily summary, and pushed to Notehub over cellular where a tower is in reach, and over the [Skylo](https://www.skylo.tech/) satellite network where one isn't — Notecard for Skylo selects the path automatically. The beekeeper gets one notification per day in steady state and an immediate alert when any signal crosses a threshold. @@ -23,7 +23,7 @@ This project is the remote set of eyes and ears that a beekeeper wants but canno -**Why Notecard for Skylo.** Apiaries are deliberately sited away from human infrastructure — the whole point is to place bees near crops, meadows, or forest edges where forage is available and human disturbance is minimal. Those sites have no AC power and often marginal or absent cellular coverage. Every one of those constraints rules out the conventional IoT stack: a gateway-plus-cloud-SIM architecture requires months of site negotiation per yard, and a device that only works in strong cellular signal will fail at exactly the locations where bees are most productive. The [Notecard for Skylo](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) (NOTE-NBGLWX) carries three radios on one M.2 module — cellular (LTE-M / NB-IoT / GPRS) with its own prepaid global SIM, WiFi, and satellite over the [Skylo](https://www.skylo.tech/) non-terrestrial network (**NTN**) — and selects among them automatically. There is no per-site IT negotiation and no carrier contract, and no second device or part-number decision for the yards that sit in coverage gaps: the firmware sets a single [`card.transport`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-transport) preference of `wifi-cell-ntn` (prefer WiFi, fall back to cellular, fall back again to Skylo satellite) and the failover is handled inside the Notecard — the host firmware never branches on which network is live. Skylo's geostationary (GEO) network provides good coverage across open-sky terrain, which is exactly what a hive stand in an open orchard or meadow provides. **Skylo coverage is geography- and service-region-dependent; verify current coverage for your deployment region and review the [satellite best practices guide](https://dev.blues.io/starnote/satellite-best-practices/) before relying on satellite as the sole backhaul.** The combination of low-power cellular with automatic satellite fallover is not a belt-and-suspenders add-on here; it is the architecture that makes this deployable in the real operating environment of commercial apiculture. +**Why Notecard for Skylo.** Apiaries are deliberately sited away from human infrastructure — the whole point is to place bees near crops, meadows, or forest edges where forage is available and human disturbance is minimal. Those sites have no AC power and often marginal or absent cellular coverage. Every one of those constraints rules out the conventional IoT stack: a gateway-plus-cloud-SIM architecture requires months of site negotiation per yard, and a device that only works in strong cellular signal will fail at exactly the locations where bees are most productive. [Notecard for Skylo](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) (NOTE-NBGLWX) carries three radios on one M.2 module — cellular (LTE-M / NB-IoT / GPRS) with its own prepaid global SIM, WiFi, and satellite over the [Skylo](https://www.skylo.tech/) non-terrestrial network (**NTN**) — and selects among them automatically. There is no per-site IT negotiation and no carrier contract, and no second device or part-number decision for the yards that sit in coverage gaps: the firmware sets a single [`card.transport`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-transport) preference of `wifi-cell-ntn` (prefer WiFi, fall back to cellular, fall back again to Skylo satellite) and the failover is handled inside the Notecard — the host firmware never branches on which network is live. Skylo's geostationary (GEO) network provides good coverage across open-sky terrain, which is exactly what a hive stand in an open orchard or meadow provides. **Skylo coverage is geography- and service-region-dependent; verify current coverage for your deployment region and review the [satellite best practices guide](https://dev.blues.io/starnote/satellite-best-practices/) before relying on satellite as the sole backhaul.** The combination of low-power cellular with automatic satellite fallover is not a belt-and-suspenders add-on here; it is the architecture that makes this deployable in the real operating environment of commercial apiculture. @@ -36,7 +36,7 @@ This project is the remote set of eyes and ears that a beekeeper wants but canno **Device-side responsibilities.** Every 15 minutes the onboard Cygnet STM32L433 host on the Notecarrier CX wakes via [`card.attn`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-attn), reads hive weight and brood-box temperature and humidity, evaluates three independent threshold rules, and folds the result into a running summary in RAM. Audio is a once-a-day affair, not a once-every-15-minutes affair — colony acoustic state evolves on the scale of hours, so the firmware captures a ~0.75-second snippet on the rollover wake itself, computes the ZCR, RMS, and peak amplitude on-device, and discards the raw samples. A tripped threshold queues an alert Note immediately; a normal day's summary goes to the Notecard for the next outbound sync. Between wakes the host is fully powered off — the Notecard's ATTN pin cuts the supply, and the battery sees essentially zero draw. Raw audio never leaves the device. -**Notecard responsibilities.** The Notecard for Skylo buffers each [Note](https://dev.blues.io/api-reference/glossary/#note) on its on-device flash queue and opens a network session on the configured [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) outbound cadence. The `card.transport` `wifi-cell-ntn` preference set at boot decides the path automatically — cellular where a tower is in reach, Skylo satellite where the orchard sits beyond terrestrial coverage — so the beekeeper's daily summary still reaches Notehub whether the apiary has cellular bars or not, with no firmware branching on which radio is live. Alert Notes carry `sync:true` to bypass the outbound timer; the beekeeper hears about a weight-drop event in the same minute it crosses the threshold (minutes, when the unit is on satellite), not at the next scheduled flush. [Environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) pushed from Notehub retune thresholds and cadences in the field without anyone driving out to reflash firmware. +**Notecard responsibilities.** Notecard for Skylo buffers each [Note](https://dev.blues.io/api-reference/glossary/#note) on its on-device flash queue and opens a network session on the configured [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) outbound cadence. The `card.transport` `wifi-cell-ntn` preference set at boot decides the path automatically — cellular where a tower is in reach, Skylo satellite where the orchard sits beyond terrestrial coverage — so the beekeeper's daily summary still reaches Notehub whether the apiary has cellular bars or not, with no firmware branching on which radio is live. Alert Notes carry `sync:true` to bypass the outbound timer; the beekeeper hears about a weight-drop event in the same minute it crosses the threshold (minutes, when the unit is on satellite), not at the next scheduled flush. [Environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) pushed from Notehub retune thresholds and cadences in the field without anyone driving out to reflash firmware. **Notehub responsibilities.** Each unit's embedded global SIM gets the Notecard onto carrier cellular worldwide and delivers data to [Notehub](https://notehub.io) over the Internet, which ingests every event and applies the project's [routes](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub). Hive summaries and alerts arrive in separate [Notefiles](https://dev.blues.io/api-reference/glossary/#notefile), so the beekeeper's SMS endpoint and the long-term weight-trend store can be served from the same device without any filter logic in between. @@ -47,7 +47,7 @@ This project is the remote set of eyes and ears that a beekeeper wants but canno 1. **Flash the firmware.** Open `firmware/apiary_hive_monitor/apiary_hive_monitor.ino` in Arduino IDE. Install dependencies: Blues Wireless Notecard, HX711 Arduino Library, Adafruit SHT31 (all via Library Manager). Replace `PRODUCT_UID` with your [Notehub](https://notehub.io) ProjectUID. Build with `arduino-cli compile --fqbn STMicroelectronics:stm32:Blues:pnum=CYGNET firmware/apiary_hive_monitor/apiary_hive_monitor.ino` and upload (the FQBN matches `firmware/apiary_hive_monitor/sketch.yaml`, so omitting `--fqbn` also works when invoked from the sketch directory). -2. **Wire sensors.** Connect HX711 (D5, D6), SHT31-D (SDA, SCL), and MAX9814 (A0) to Notecarrier CX per §5. Seat the Notecard for Skylo in the M.2 slot and connect its `MAIN` and `GPS` antennas (§5). +2. **Wire sensors.** Connect HX711 (D5, D6), SHT31-D (SDA, SCL), and MAX9814 (A0) to Notecarrier CX per §5. Seat Notecard for Skylo in the M.2 slot and connect its `MAIN` and `GPS` antennas (§5). 3. **Validate power.** Use Mojo (bench only) to confirm ~15–40 mA active, ~100–400 µA asleep. Confirm temperature/humidity readings and audio ZCR in summaries before field deployment. @@ -120,7 +120,7 @@ Here is a sample Note this device emits: | [Hammond 1554F2GY polycarbonate enclosure (IP66, 120 × 90 × 60 mm)](https://www.hammfg.com/product/1554F2GY) | 1 | IP66 polycarbonate enclosure with opaque lid, sized to house the Notecarrier CX, Sunny Buddy, and Li-ion pack. Drill two M16 cable-gland holes: one for the sensor cable bundle, one for the SMA antenna pigtail. The antenna mounts outside the enclosure (see antenna rows below), so the opaque lid does not affect the satellite or cellular link. Available from Hammond and authorized distributors. | | 4× female-to-female jumper wires, 150–200 mm (e.g. [Adafruit #266](https://www.adafruit.com/product/266)) | 1 set | Connect the SHT31-D breakout's 0.1″ header pins (VIN, GND, SDA, SCL) to the matching pins on the Notecarrier CX dual 16-pin header. | | STEMMA QT / Qwiic cable, 100 mm | 1 | Connects Mojo's Qwiic port to the Notecarrier CX Qwiic connector during bench commissioning so the coulomb-counter tally is readable from the blues.dev In-Browser Terminal; remove this cable before field deployment. | -| Skylo-certified LTE/satellite antenna included with the Notecard for Skylo (u.FL) | 1 | Connects to the `MAIN` u.FL port and carries **both** the terrestrial cellular signal and the Skylo satellite link — a single antenna for both networks. Use only the Skylo-certified antenna supplied with the Notecard for Skylo; substituting an uncertified antenna risks regulatory non-compliance and link failure. Mount it outdoors on the enclosure lid or hive-stand upright with an unobstructed view of the sky (northern hemisphere: the southern sky toward the equator, where Skylo's GEO satellites sit), routed through a liquid-tight fitting. For an external SMA mount instead of the bare u.FL antenna, add a u.FL-to-SMA-F bulkhead pigtail (e.g. [Adafruit #851](https://www.adafruit.com/product/851)) through the enclosure wall. | +| Skylo-certified LTE/satellite antenna included with Notecard for Skylo (u.FL) | 1 | Connects to the `MAIN` u.FL port and carries **both** the terrestrial cellular signal and the Skylo satellite link — a single antenna for both networks. Use only the Skylo-certified antenna supplied with Notecard for Skylo; substituting an uncertified antenna risks regulatory non-compliance and link failure. Mount it outdoors on the enclosure lid or hive-stand upright with an unobstructed view of the sky (northern hemisphere: the southern sky toward the equator, where Skylo's GEO satellites sit), routed through a liquid-tight fitting. For an external SMA mount instead of the bare u.FL antenna, add a u.FL-to-SMA-F bulkhead pigtail (e.g. [Adafruit #851](https://www.adafruit.com/product/851)) through the enclosure wall. | | Passive GPS/GNSS antenna (u.FL) per the [Notecard for Skylo datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) | 1 | Connects to the `GPS` u.FL port for GNSS time/ephemeris used internally by the satellite stack. Mount outdoors with a clear sky view alongside the main antenna; route through a liquid-tight fitting. | **Bundled connectivity (Notecard for Skylo):** Ships with an active global SIM including 500 MB of cellular data and 10 years of service, **plus** 10 KB of bundled Skylo satellite data — no activation fees, no monthly subscription, and no separate satellite provider subscription. Minimizing inbound sync frequency conserves the bundled satellite allocation; see §2 and §7 for guidance. @@ -130,7 +130,7 @@ Here is a sample Note this device emits: ![Wiring diagram: HX711 on D5/D6, SHT31-D via 4-wire jumpers on SDA/SCL, MAX9814 on A0, Skylo-certified antenna on MAIN u.FL plus GPS antenna, power chain: solar → Sunny Buddy (Li-ion at BATT) → LOAD → Mojo → Notecarrier +VBAT](diagrams/02-wiring-assembly.svg) -The enclosure mounts on the hive stand and the bees never know it's there — three sensor leads thread through existing seams, the antenna lives outside on the lid, and a small solar panel feeds the whole thing from a gooseneck bracket nearby. Every host I/O lands on the [Notecarrier CX](https://dev.blues.io/datasheets/notecarrier-datasheet/notecarrier-cx-v1-3/) dual 16-pin headers, and the Notecard for Skylo seats into the M.2 slot. Its `MAIN` u.FL port connects to the included Skylo-certified antenna — which carries both the cellular and satellite signals — and its `GPS` u.FL port connects to the passive GPS/GNSS antenna; both mount outside the box with an unobstructed view of the sky. +The enclosure mounts on the hive stand and the bees never know it's there — three sensor leads thread through existing seams, the antenna lives outside on the lid, and a small solar panel feeds the whole thing from a gooseneck bracket nearby. Every host I/O lands on the [Notecarrier CX](https://dev.blues.io/datasheets/notecarrier-datasheet/notecarrier-cx-v1-3/) dual 16-pin headers, and Notecard for Skylo seats into the M.2 slot. Its `MAIN` u.FL port connects to the included Skylo-certified antenna — which carries both the cellular and satellite signals — and its `GPS` u.FL port connects to the passive GPS/GNSS antenna; both mount outside the box with an unobstructed view of the sky. **Power chain.** The Sunny Buddy MPPT charger sits between the solar panel and the Li-ion battery. The Li-ion pack connects to the Sunny Buddy's `BATT` JST connector (or `BAT+`/`GND` screw terminals). The system load is drawn from the Sunny Buddy's `LOAD+`/`GND` screw terminals; the Notecarrier CX `+VBAT` pad connects to `LOAD+` and `GND` connects to the common ground rail. During bench commissioning, Mojo sits inline on the positive load rail to measure downstream device current: @@ -181,7 +181,7 @@ The SHT31-D address defaults to 0x44; it coexists on the I2C bus with the Noteca **Antennas (single board, cellular + satellite + GPS):** -The Notecard for Skylo's `MAIN` u.FL antenna carries **both** the cellular and the Skylo satellite signal — one antenna replaces what used to be a separate cellular whip and an external satellite module's antenna. +Notecard for Skylo's `MAIN` u.FL antenna carries **both** the cellular and the Skylo satellite signal — one antenna replaces what used to be a separate cellular whip and an external satellite module's antenna. 1. Connect the included Skylo-certified antenna's u.FL connector to the Notecard's `MAIN` u.FL port. The connector orients with the cable center-pin facing the port — it clicks firmly when fully seated. Use only the Skylo-certified antenna supplied with the board; an uncertified substitute risks regulatory non-compliance and link failure. 2. Connect the passive GPS/GNSS antenna's u.FL connector to the Notecard's `GPS` u.FL port. @@ -196,7 +196,7 @@ Because the satellite link uses the same `MAIN` antenna as cellular, the placeme 1. **Create a project.** Sign up at [notehub.io](https://notehub.io) and create a project. Copy the [ProductUID](https://dev.blues.io/notehub/notehub-walkthrough/#finding-a-productuid) and paste it into `firmware/apiary_hive_monitor/apiary_hive_monitor.ino` as `PRODUCT_UID`. -2. **Claim the Notecard.** Power up the unit at a location with cellular (or WiFi) coverage. The Notecard for Skylo associates with your project on its first non-NTN sync. **This initial cellular/WiFi sync is mandatory before satellite works:** it registers the device with Notehub, registers the Notefile templates, downloads the current satellite ephemeris, and sets device time — all required before any NTN transmission will succeed. Commission each unit where it has terrestrial coverage even if it will routinely operate over satellite. See the [satellite best practices guide](https://dev.blues.io/starnote/satellite-best-practices/). +2. **Claim the Notecard.** Power up the unit at a location with cellular (or WiFi) coverage. Notecard for Skylo associates with your project on its first non-NTN sync. **This initial cellular/WiFi sync is mandatory before satellite works:** it registers the device with Notehub, registers the Notefile templates, downloads the current satellite ephemeris, and sets device time — all required before any NTN transmission will succeed. Commission each unit where it has terrestrial coverage even if it will routinely operate over satellite. See the [satellite best practices guide](https://dev.blues.io/starnote/satellite-best-practices/). **First-boot timing Note.** The firmware anchors the summary window to the first successful `card.time` response — the moment the Notecard returns a valid epoch rather than an error. Any sensor readings accumulated before that time anchor are discarded, and the window clock starts from that point. The first `hive_summary.qo` Note therefore arrives after a full `report_interval_hr` window has elapsed **from the first successful time sync** (default: 24 hours from that anchor), which may be later than first power-up if the unit is commissioned indoors or in a weak-signal location before cellular or satellite lock is achieved. This is intentional — a summary sent before a valid time reference would contain at most a single sensor reading and no meaningful weight delta. @@ -312,7 +312,7 @@ The `value1` and `value2` fields carry alert-specific data: for `weight_drop`, t After each 15-minute sample cycle, the host issues `NotePayloadSaveAndSleep()`, which serializes the runtime state (`HiveState` struct containing summary-window accumulators, last-alert timestamps, the weight baseline, and the `audio_sampled` flag) into the Notecard's flash memory, then arms [`card.attn`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-attn) to cut host power entirely for `sample_interval_min × 60` seconds. Between cellular sessions the Notecard enters its published low-power idle state (~8–20 µA per the Notecard datasheet). The HX711 is put to sleep via its PD_SCK pin after each weight reading. The microphone's AGC circuit draws from the 3.3 V rail only while the Cygnet host is awake (~5–8 seconds per cycle), and audio sampling itself occurs on only one of the 96 daily wake cycles. -`notecardConfigure()` also issues a one-time [`card.transport`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-transport) `{"method":"wifi-cell-ntn"}` on first boot so the Notecard for Skylo prefers WiFi, then cellular, then Skylo satellite — the fallback is enabled at the Notecard, with no firmware branching on which radio is live (NTN is not enabled by default, so this call is what makes satellite fallback possible). The Notecard persists the setting in its own flash, so issuing it once is sufficient. +`notecardConfigure()` also issues a one-time [`card.transport`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-transport) `{"method":"wifi-cell-ntn"}` on first boot so Notecard for Skylo prefers WiFi, then cellular, then Skylo satellite — the fallback is enabled at the Notecard, with no firmware branching on which radio is live (NTN is not enabled by default, so this call is what makes satellite fallback possible). The Notecard persists the setting in its own flash, so issuing it once is sufficient. The initial sync cadence is set to `outbound: 1440` (daily) to minimize satellite transmission costs at sites that operate over NTN; `sync:true` on alert Notes bypasses this timer and forces an immediate cellular or NTN session. `inbound` is set to `10080` (one week) per the [satellite best practices guide](https://dev.blues.io/starnote/satellite-best-practices/), since each inbound satellite ping costs approximately 50 bytes of the bundled 10 KB satellite allocation. Environment variable changes are applied on the next scheduled inbound sync. @@ -490,7 +490,7 @@ delay((uint32_t)sampleMin * 60000UL); | Skylo NTN satellite session | ~250 mA avg (same magnitude as a cellular session) | Notecard datasheet | | Host cut via ATTN, Notecard low-power idle + Sunny Buddy quiescent | ~100–400 µA typical | Whole-device estimate | -Notecard-published figures come from the [Notecard for Skylo datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/); whole-device estimates include the Notecarrier CX regulator and Sunny Buddy quiescent draw and should be validated with Mojo on your specific assembly. +Notecard-published figures come from [Notecard for Skylo datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/); whole-device estimates include the Notecarrier CX regulator and Sunny Buddy quiescent draw and should be validated with Mojo on your specific assembly. The expected Mojo pattern for a correctly sleeping unit: a brief 5–8 second active spike every 15 minutes, and a longer cellular spike once every 24 hours. If instead you see continuous > 20 mA draw, the host is not sleeping — check that the `ATTN` pin is connected between the Notecard and the host (the Notecarrier CX routes this internally). If you see no cellular spike in 25 hours, confirm `hub.set` outbound cadence and that the device has associated with a Notehub project. diff --git a/70-trailer-manufacturer-connected-trailer-platform/README.md b/70-trailer-manufacturer-connected-trailer-platform/README.md index 51ce668f..b2fd6dbc 100644 --- a/70-trailer-manufacturer-connected-trailer-platform/README.md +++ b/70-trailer-manufacturer-connected-trailer-platform/README.md @@ -16,11 +16,11 @@ This project is a connected-trailer platform for trailer OEM integration, target A trailer OEM that wants to own the connectivity layer — rather than ceding it to the reefer OEM — needs a hardware-and-software platform that's on the trailer from day one. That platform has to read everything the fleet operator actually cares about: the reefer setpoint and actual temperature from the refrigeration unit itself, body-air temperature at two points in the cargo space (the data the shipper trusts at delivery time, not the reefer unit's own sensor), tire pressure on every axle, rear-door events that tell the cold-chain story, and GPS for asset location and route compliance. It has to survive 10–15 years of operation across regions, carriers, and signal environments, including long rural hauls, intermodal drayage moves, and multi-day DC (**distribution center**) dwells where the trailer sits disconnected from the tractor for days at a stretch, often in areas where cellular coverage is unreliable. -**Why Notecard.** A trailer OEM cannot commit to a modem they might have to re-source in year four of a ten-year program. The Notecard for Skylo solves this at the module level: it combines LTE-M/NB-IoT cellular and Skylo satellite (via **NTN**, Non-Terrestrial Network, meaning communication through geostationary satellites rather than cell towers) in a single pre-certified M.2 form-factor module with an embedded SIM, 500 MB of cellular data, and 10 years of service included. The OEM installs one hardware SKU, flashes one firmware image, and ships trailers into any regional market without per-unit carrier activation, without SIM swaps, and without a per-site recurring data-plan negotiation. When a trailer crosses into a cellular dead zone — a mountain pass, a rural cold-storage depot, a remote intermodal rail yard — the Notecard for Skylo transitions transparently to the Skylo satellite network, so the cold-chain record and the TPMS safety log stay continuous. Notehub gives the OEM's cloud a single API endpoint regardless of which radio delivered any given message. That's the connectivity bundle a trailer manufacturer needs to compete on the data layer rather than concede it to the reefer OEM by default. Pre-certified global cellular plus satellite plus included data, all in one module with a credible long-term roadmap, is exactly the program-level assurance a trailer OEM needs. +**Why Notecard.** A trailer OEM cannot commit to a modem they might have to re-source in year four of a ten-year program. Notecard for Skylo solves this at the module level: it combines LTE-M/NB-IoT cellular and Skylo satellite (via **NTN**, Non-Terrestrial Network, meaning communication through geostationary satellites rather than cell towers) in a single pre-certified M.2 form-factor module with an embedded SIM, 500 MB of cellular data, and 10 years of service included. The OEM installs one hardware SKU, flashes one firmware image, and ships trailers into any regional market without per-unit carrier activation, without SIM swaps, and without a per-site recurring data-plan negotiation. When a trailer crosses into a cellular dead zone — a mountain pass, a rural cold-storage depot, a remote intermodal rail yard — Notecard for Skylo transitions transparently to the Skylo satellite network, so the cold-chain record and the TPMS safety log stay continuous. Notehub gives the OEM's cloud a single API endpoint regardless of which radio delivered any given message. That's the connectivity bundle a trailer manufacturer needs to compete on the data layer rather than concede it to the reefer OEM by default. Pre-certified global cellular plus satellite plus included data, all in one module with a credible long-term roadmap, is exactly the program-level assurance a trailer OEM needs. -**Deployment scenario.** A weatherproof enclosure mounted on the trailer's nose wall (the forward interior wall, adjacent to the reefer unit). The Notecard for Skylo's Skylo-certified flat-patch antenna is exterior-mounted on the trailer roof with a clear sky view; the GPS antenna is also exterior on the roof. **SAE J2497** (also marketed as **PLC4TRUCKS**) is the SAE standard for power-line communications over the existing power conductors of commercial-vehicle trailer wiring; the J2497 PLC signal rides on the **J560 pin 6 circuit** — the always-hot auxiliary/battery feed on the SAE J560 North American seven-pin trailer connector; not a stop-lamp or brake circuit. The reference build includes a documented integration point for a future J2497 coupling interface on that circuit, and the firmware scaffolding routes a POC placeholder through the data pipeline, but this is not a delivered sensor path. A practical caveat: J2497's dominant production use is trailer ABS warning-lamp telemetry, not reefer data. Most reefer-OEM telemetry in the field is delivered over vendor-proprietary serial diagnostic ports (Carrier Transicold DataLink, Thermo King DSR/DSR2) or J1939 over CAN, not over J2497. The firmware UART (`Serial1`) is the same interface either way — only the decode function changes, so the reference assumption can be re-targeted to a different transport without rearchitecting the platform. See [§10 Limitations](#10-limitations-and-next-steps) for the alternative-transport comparison and the engineering required to activate any of them. **Regional Note:** SAE J560 is the North American 7-pin standard; European trailers use ISO 1185 (7-pin) or ISO 3731 (13-pin) connectors with different pinouts — J2497 PLC is deployed on the equivalent auxiliary circuit in those standards. Two encapsulated NTC thermistors hang inside the cargo space, front and rear, providing the independent body-air readings shippers use to verify cold-chain integrity at delivery. A documented integration point for a future TPMS (**Tire Pressure Monitoring System**) gateway receiver is included; the firmware scaffolding and note-template fields for four tire positions are in place, but this is not a delivered sensor path — real tire pressure data requires the vendor-specific engineering described in [§10 Limitations](#10-limitations-and-next-steps). A magnetic reed switch on the rear door reports open/close state. The Notecarrier CX and its onboard Cygnet STM32 host run the trailer state machine; the Notecard for Skylo handles all radio management, GNSS positioning, and Notehub data delivery. Power during tractor-connected operation comes from the trailer's 12 V auxiliary/battery circuit — **J560 pin 6** (the always-hot auxiliary feed, distinct from the stop-lamp and brake circuits); during DC dwells when the tractor is disconnected, a power-priority switching circuit transfers automatically to the reefer unit's own 12 V battery — integral to every refrigerated trailer — keeping the power path alive during DC dwells. The host uses `NotePayloadSaveAndSleep` / `card.attn` to sleep at zero current between sample cycles, making multi-day DC-dwell operation within a practical reefer battery budget achievable; see [§7](#7-firmware-design) for the power architecture detail. +**Deployment scenario.** A weatherproof enclosure mounted on the trailer's nose wall (the forward interior wall, adjacent to the reefer unit). Notecard for Skylo's Skylo-certified flat-patch antenna is exterior-mounted on the trailer roof with a clear sky view; the GPS antenna is also exterior on the roof. **SAE J2497** (also marketed as **PLC4TRUCKS**) is the SAE standard for power-line communications over the existing power conductors of commercial-vehicle trailer wiring; the J2497 PLC signal rides on the **J560 pin 6 circuit** — the always-hot auxiliary/battery feed on the SAE J560 North American seven-pin trailer connector; not a stop-lamp or brake circuit. The reference build includes a documented integration point for a future J2497 coupling interface on that circuit, and the firmware scaffolding routes a POC placeholder through the data pipeline, but this is not a delivered sensor path. A practical caveat: J2497's dominant production use is trailer ABS warning-lamp telemetry, not reefer data. Most reefer-OEM telemetry in the field is delivered over vendor-proprietary serial diagnostic ports (Carrier Transicold DataLink, Thermo King DSR/DSR2) or J1939 over CAN, not over J2497. The firmware UART (`Serial1`) is the same interface either way — only the decode function changes, so the reference assumption can be re-targeted to a different transport without rearchitecting the platform. See [§10 Limitations](#10-limitations-and-next-steps) for the alternative-transport comparison and the engineering required to activate any of them. **Regional Note:** SAE J560 is the North American 7-pin standard; European trailers use ISO 1185 (7-pin) or ISO 3731 (13-pin) connectors with different pinouts — J2497 PLC is deployed on the equivalent auxiliary circuit in those standards. Two encapsulated NTC thermistors hang inside the cargo space, front and rear, providing the independent body-air readings shippers use to verify cold-chain integrity at delivery. A documented integration point for a future TPMS (**Tire Pressure Monitoring System**) gateway receiver is included; the firmware scaffolding and note-template fields for four tire positions are in place, but this is not a delivered sensor path — real tire pressure data requires the vendor-specific engineering described in [§10 Limitations](#10-limitations-and-next-steps). A magnetic reed switch on the rear door reports open/close state. The Notecarrier CX and its onboard Cygnet STM32 host run the trailer state machine; Notecard for Skylo handles all radio management, GNSS positioning, and Notehub data delivery. Power during tractor-connected operation comes from the trailer's 12 V auxiliary/battery circuit — **J560 pin 6** (the always-hot auxiliary feed, distinct from the stop-lamp and brake circuits); during DC dwells when the tractor is disconnected, a power-priority switching circuit transfers automatically to the reefer unit's own 12 V battery — integral to every refrigerated trailer — keeping the power path alive during DC dwells. The host uses `NotePayloadSaveAndSleep` / `card.attn` to sleep at zero current between sample cycles, making multi-day DC-dwell operation within a practical reefer battery budget achievable; see [§7](#7-firmware-design) for the power architecture detail. @@ -49,7 +49,7 @@ A trailer OEM that wants to own the connectivity layer — rather than ceding it **Device-side responsibilities.** Each time the Notecard's ATTN signal brings the Cygnet STM32L433 back to life, the host walks the three fully-implemented sensor inputs — both cargo-air thermistors (12-bit ADC with β-equation conversion), the rear-door reed switch, and the GPS position from the Notecard's built-in GNSS — and then services the two UART stub channels: `Serial1` for the J2497 reefer path and `tpmsSerial` for the TPMS path. Both UART parsers handle simplified POC frame formats; neither produces real trailer data without the additional engineering described in §10. With every sample the host runs the threshold rules locally and decides whether the cycle warrants an immediate alert or just feeds the running summary accumulator. Between cycles the host is powered off entirely via the Notecard's ATTN signal (see [§7 Low-power strategy](#7-firmware-design)) — every byte of accumulated window state rides through the sleep in a serialised `PersistState` payload stored in the Notecard. On each wakeup, before the sample cycle starts, the host gives both UART channels a 250 ms drain to mop up frames that arrived during sleep, then drains again between each blocking Notecard I²C transaction so a long radio call doesn't shadow an incoming UART frame. All Notecard communication rides I²C over the Notecarrier CX's internal routing; the host never touches the radio or the cellular session. -**Notecard responsibilities.** From there the Notecard for Skylo takes over. It keeps [Notes](https://dev.blues.io/api-reference/glossary/#note) in its on-device queue, picks between cellular and satellite radios automatically, and flushes the queue on the [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) outbound cadence the firmware sets for the current trailer state — shorter in transit, longer during DC dwells. Alert Notes marked `sync:true` skip the outbound timer entirely and bring up a radio session right away. GNSS is also the Notecard's job, and every Note that leaves the device is automatically tagged with the last known position. The same channel runs the other direction for [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) pushed from Notehub, so fleet operators can retune thresholds and sync cadences across an entire customer's trailers without anyone touching firmware. +**Notecard responsibilities.** From there Notecard for Skylo takes over. It keeps [Notes](https://dev.blues.io/api-reference/glossary/#note) in its on-device queue, picks between cellular and satellite radios automatically, and flushes the queue on the [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) outbound cadence the firmware sets for the current trailer state — shorter in transit, longer during DC dwells. Alert Notes marked `sync:true` skip the outbound timer entirely and bring up a radio session right away. GNSS is also the Notecard's job, and every Note that leaves the device is automatically tagged with the last known position. The same channel runs the other direction for [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) pushed from Notehub, so fleet operators can retune thresholds and sync cadences across an entire customer's trailers without anyone touching firmware. **Notehub responsibilities.** [Notehub](https://dev.blues.io/notehub/notehub-walkthrough/) is where the data lands. Notes arrive over the Internet, every event is stored, and project-level [routes](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub) fan them out to wherever the OEM's cloud needs them. The same firmware image adapts to wildly different cargo types through fleet-level [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) — a frozen-goods customer and a produce customer differ only in the reefer temperature bands their fleet encodes, not in their device build. [Smart Fleets](https://dev.blues.io/notehub/notehub-walkthrough/#using-smart-fleet-rules) let the OEM slice the installed base by customer, cargo class, or route region without ever forking the firmware. @@ -84,7 +84,7 @@ A trailer OEM that wants to own the connectivity layer — rather than ceding it 5. **Wire the three sensors (optional for bench demo).** - Two 10 kΩ NTC thermistors with 10 kΩ 1% series resistors on ADC pins A0 and A1 (see [§5 Wiring](#5-wiring-and-assembly) for voltage-divider schematic). - A magnetic door reed switch on GPIO D9 (pull-up enabled in firmware). - - GPS and cellular/satellite antennas: already included with the Notecard for Skylo. + - GPS and cellular/satellite antennas: already included with Notecard for Skylo. With sensors wired, `trailer_summary.qo` reports real `air_t1_*` and `air_t2_*` fields and tracks `door_open_min` and `door_event_count`. @@ -127,14 +127,14 @@ Here is a sample Note this device emits: | Part | Qty | Rationale | |------|-----|-----------| -| [Notecarrier CX](https://shop.blues.com/products/notecarrier-cx?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Integrated carrier with embedded Cygnet STM32L433 host — no separate MCU needed. M.2 slot seats the Notecard for Skylo. | +| [Notecarrier CX](https://shop.blues.com/products/notecarrier-cx?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Integrated carrier with embedded Cygnet STM32L433 host — no separate MCU needed. M.2 slot seats Notecard for Skylo. | | [Notecard for Skylo (NOTE-NBGLWX)](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) | 1 | LTE-M/NB-IoT cellular + Skylo NTN satellite + integrated GNSS in one pre-certified module. Single SKU for any region; automatic cellular-to-satellite fallback with no host-firmware involvement. | | [Blues Mojo](https://shop.blues.com/products/mojo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Coulomb counter for power-envelope validation during bench commissioning. | | 10 kΩ NTC thermistor, β≈3950, encapsulated probe ([Adafruit 372](https://www.adafruit.com/product/372)) | 2 | Cargo-air temperature at two points — front and rear of the trailer. These are the independent readings shippers use to verify cold-chain integrity at delivery, separate from the reefer unit's own sensor. | | 10 kΩ 1% resistor | 2 | Voltage-divider series resistor for each thermistor on A0 and A1. | | Magnetic door sensor, N.C., panel-mount ([Adafruit 375](https://www.adafruit.com/product/375)) | 1 | Rear door open/close state on D9. When the door is **closed** the magnet holds the N.C. contact open, leaving the pull-up to drive the pin HIGH (`doorOpen = false`). When the door **opens** the magnet moves away; the N.C. contact closes to GND and pulls the pin LOW (`doorOpen = true`). | -| Skylo-certified flat-patch antenna with u.FL lead (included with Notecard for Skylo) | 1 | Connects to the **`MAIN`** u.FL port on the Notecard for Skylo. This single included antenna covers both LTE-M/NB-IoT cellular and Skylo NTN satellite (S-Band/L-Band, B23/B255/B256) — no separate cellular antenna is needed or installed. Exterior roof-mount, flat face toward the sky with ≥11 mm clearance on all edges. Replacing or modifying this antenna, or inserting additional RF connectors into the antenna lead, voids the Skylo network certification and may cause Skylo to block the device. Route the included lead through an IP68-rated cable gland (see §5) — **not** through an added RF connector or bulkhead adapter. | -| Passive GPS/GNSS antenna, u.FL, exterior-mount ([**Taoglas AA.162**](https://www.taoglas.com/product/ulysses-aa-162-miniature-magnetic-mount-gps-glonass-antenna/) passive patch, −40 to +85 °C) | 1 | Connects to the **`GPS`** u.FL port on the Notecard for Skylo. The NOTE-NBGLWX GPS port requires a **passive** (un-amplified) antenna — the port does not supply DC bias for an active antenna's LNA. Roof-mount with clear sky view; route the coax through a weatherproof u.FL-to-SMA bulkhead feedthrough. | +| Skylo-certified flat-patch antenna with u.FL lead (included with Notecard for Skylo) | 1 | Connects to the **`MAIN`** u.FL port on Notecard for Skylo. This single included antenna covers both LTE-M/NB-IoT cellular and Skylo NTN satellite (S-Band/L-Band, B23/B255/B256) — no separate cellular antenna is needed or installed. Exterior roof-mount, flat face toward the sky with ≥11 mm clearance on all edges. Replacing or modifying this antenna, or inserting additional RF connectors into the antenna lead, voids the Skylo network certification and may cause Skylo to block the device. Route the included lead through an IP68-rated cable gland (see §5) — **not** through an added RF connector or bulkhead adapter. | +| Passive GPS/GNSS antenna, u.FL, exterior-mount ([**Taoglas AA.162**](https://www.taoglas.com/product/ulysses-aa-162-miniature-magnetic-mount-gps-glonass-antenna/) passive patch, −40 to +85 °C) | 1 | Connects to the **`GPS`** u.FL port on Notecard for Skylo. The NOTE-NBGLWX GPS port requires a **passive** (un-amplified) antenna — the port does not supply DC bias for an active antenna's LNA. Roof-mount with clear sky view; route the coax through a weatherproof u.FL-to-SMA bulkhead feedthrough. | | DC-DC converter, 9–36 V input, 5 V/3 A output ([Mean Well SD-15A-5](https://www.meanwell.com/Upload/PDF/SD-15/SD-15-SPEC.PDF)) | 1 | Steps down the 12 V supply (from tractor auxiliary line when connected, or reefer battery during DC dwells) to the 5 V rail powering the Notecarrier CX. The SD-15A-5's 36 V maximum input provides margin against the trailer's normal transient envelope above 12 V nominal. | | Power-priority OR circuit: **ON Semi MBRS340T3G** automotive Schottky diode, 3 A / 40 V | 2 | One diode per 12 V input leg (tractor aux and reefer battery), anodes to their respective inputs, cathodes joined to a common output node feeding the DC-DC converter VIN. Automatically passes the higher-voltage source with no host involvement; the Schottky's reverse-blocking inherently protects against polarity reversal on each input. Forward drop ~0.4 V at full load — acceptable for a 12 V rail. For production a low-drop ideal-diode controller (e.g., TI LM74700-Q1, AEC-Q100) cuts forward drop to millivolts but adds FETs and layout complexity. **Do not use low-voltage power mux ICs** (e.g., TPS2116, max 5.5 V) — trailer supply and load-dump transients far exceed their rating. | | IP68 polycarbonate enclosure, ≥160×120×60 mm ([**Hammond 1555H2GY**](https://www.hammfg.com/part/1555H2GY), 180×120×60 mm, light gray, IP68) | 1 | Nose-wall mount; rated against refrigeration condensation and high-pressure washing during trailer cleaning. Key selection criteria: IP67 or better, polycarbonate or ABS body (survives trailer wash-down chemicals), continuous service to −40 °C, ≥160 mm internal length to accommodate the Notecarrier CX with antenna feedthrough headers, cable-gland knockouts on at least one long face. | @@ -160,7 +160,7 @@ The following items are **not part of this reference build** and should not be p ![Wiring: 2 NTC thermistors to A0/A1, rear-door reed to D9 INPUT_PULLUP, MAIN antenna to u.FL (cell + Skylo sat), passive GPS antenna to GPS u.FL; dual 12 V input through OR-circuit and transient protection → DC-DC 5 V → +VBAT](diagrams/02-wiring-assembly.svg) -Inside the nose-wall enclosure, everything traces back to the [Notecarrier CX](https://dev.blues.io/datasheets/notecarrier-datasheet/notecarrier-cx-v1-3/) and its dual 16-pin headers. The Notecard for Skylo seats into the carrier's M.2 slot, and the rest of the trailer-side wiring — thermistor leads, door reed, J560-pin-6 supply, antenna pigtails — comes back to that header from the rest of the box. Two routing rules are worth calling out upfront because they're easy to get wrong: the GPS antenna coax exits the enclosure through the weatherproof u.FL-to-SMA bulkhead feedthrough, while the Skylo MAIN antenna lead must pass through an IP68 cable gland only — never through a bulkhead adapter or any additional RF connector (see BOM and the MAIN u.FL bullet below). The Mojo sits inline between the DC-DC converter's 5V output and the Notecarrier's +VBAT pad during bench power validation (remove it from the field unit once commissioning is complete, or leave it in place if fleet-level energy telemetry is desired). In field installations the DC-DC converter's VIN is fed from the power-priority switching module described in the power chain below, not directly from J560 pin 6. +Inside the nose-wall enclosure, everything traces back to the [Notecarrier CX](https://dev.blues.io/datasheets/notecarrier-datasheet/notecarrier-cx-v1-3/) and its dual 16-pin headers. Notecard for Skylo seats into the carrier's M.2 slot, and the rest of the trailer-side wiring — thermistor leads, door reed, J560-pin-6 supply, antenna pigtails — comes back to that header from the rest of the box. Two routing rules are worth calling out upfront because they're easy to get wrong: the GPS antenna coax exits the enclosure through the weatherproof u.FL-to-SMA bulkhead feedthrough, while the Skylo MAIN antenna lead must pass through an IP68 cable gland only — never through a bulkhead adapter or any additional RF connector (see BOM and the MAIN u.FL bullet below). The Mojo sits inline between the DC-DC converter's 5V output and the Notecarrier's +VBAT pad during bench power validation (remove it from the field unit once commissioning is complete, or leave it in place if fleet-level energy telemetry is desired). In field installations the DC-DC converter's VIN is fed from the power-priority switching module described in the power chain below, not directly from J560 pin 6. Pin-by-pin: @@ -418,7 +418,7 @@ DC-dwell battery sizing should be based on bench-measured Mojo data, not on comp **Fallback — no ATTN host-power control.** If ATTN is not wired for host power control (bench commissioning without the ATTN connection), `NotePayloadSaveAndSleep()` returns without cutting host power and `loop()` falls through to a `delay()` that mimics the sample cadence. The host draws continuous active current (~5–15 mA, bench-measure) in this mode. The USB debug output indicates which path is active: look for `[sleep] ATTN not cutting host power — using delay fallback` on the serial console. -The Notecard for Skylo manages its own radio sleep independently: in [`periodic`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) mode it idles at ~8–18 µA between sessions, then wakes briefly for a cellular or satellite burst on the configured outbound cadence. The sync cadence switches automatically on every trailer state transition: `outbound_transit_min` (default 60 minutes) while moving, `outbound_parked_min` (default 240 minutes) during DC dwells. The host re-issues `hub.set` each time the cadence changes so the Notecard tracks the current schedule exactly. +Notecard for Skylo manages its own radio sleep independently: in [`periodic`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) mode it idles at ~8–18 µA between sessions, then wakes briefly for a cellular or satellite burst on the configured outbound cadence. The sync cadence switches automatically on every trailer state transition: `outbound_transit_min` (default 60 minutes) while moving, `outbound_parked_min` (default 240 minutes) during DC dwells. The host re-issues `hub.set` each time the cadence changes so the Notecard tracks the current schedule exactly. Operators can extend `sample_interval_sec` via environment variable during long-dwell parked periods (for example, from 300 seconds to 900 seconds) to reduce the host's active-duty cycle when cargo temperature is stable. @@ -661,7 +661,7 @@ The Notecard's `card.attn` wakes the host every `sample_interval_sec` (default 3 **Power validation with Mojo.** -**Measurement point.** Splice the [Mojo](https://shop.blues.com/products/mojo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) inline on the Notecarrier CX **+VBAT** rail. This captures the Notecard for Skylo, the Cygnet STM32 host, and any 3.3 V-railed peripherals (including, when eventually built, the J2497 custom board's IT700 logic VCC, sourced from the Notecarrier +3V3). The TPMS gateway is powered directly from the 12 V trailer rail — upstream of the DC-DC converter, and **does not appear in the Mojo trace**. For a complete DC-dwell energy budget, add a second measurement at the DC-DC converter's 12 V input rail using a bench current probe or dedicated meter. +**Measurement point.** Splice the [Mojo](https://shop.blues.com/products/mojo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) inline on the Notecarrier CX **+VBAT** rail. This captures Notecard for Skylo, the Cygnet STM32 host, and any 3.3 V-railed peripherals (including, when eventually built, the J2497 custom board's IT700 logic VCC, sourced from the Notecarrier +3V3). The TPMS gateway is powered directly from the 12 V trailer rail — upstream of the DC-DC converter, and **does not appear in the Mojo trace**. For a complete DC-dwell energy budget, add a second measurement at the DC-DC converter's 12 V input rail using a bench current probe or dedicated meter. **Blues-published reference figures for the NOTE-NBGLWX on +VBAT.** @@ -688,7 +688,7 @@ The Notecard idle figure is the only Blues-published power specification for the **Threshold simulation — integration stubs.** The reefer and TPMS alert paths evaluate against the stub parsers, not real hardware. Without a device injecting POC-format frames over Serial1 or D6, `g_sensors.reeferActualF` and `g_sensors.tpmsPsi[]` remain at −9999 and no reefer or TPMS alerts fire regardless of threshold settings. To exercise those code paths on the bench: (a) set `reefer_max_f` in Notehub to a value above −9999 (any positive threshold will suffice since the stub-received values, if injected, would be real-looking numbers), then (b) connect a USB-to-serial adapter to Serial1 and transmit a valid 8-byte POC frame (`0xAA 0x55` header, big-endian signed 16-bit setpoint and actual temp in 0.1 °F units, status byte, XOR checksum of bytes 2–6) at 9600 baud. The next sample cycle that latches the frame will evaluate the threshold and fire `reefer_temp_high` if the injected actual temperature exceeds `reefer_max_f`. This exercises the firmware's threshold-evaluation and `note.add` path but does not validate any J2497 physical-layer or protocol-layer behavior. -**Satellite fallback validation.** Move the powered unit — with **all antennas properly attached** — to an **outdoor location** with confirmed no LTE-M cellular coverage but a **clear, unobstructed sky view**. A rural field, open parking area, or rooftop site with verified weak/no LTE-M coverage (confirm against the carrier's coverage map before the trip) is ideal. **Do not use a basement, building interior, or enclosed metal container** — these structures block the satellite signal in addition to cellular, giving the Notecard no radio path at all; no delivery will occur. Do not disconnect a u.FL connector while the unit is powered; doing so creates an open-circuit impedance mismatch that can damage the modem front end. With all antennas connected and no cell signal available, the Notecard for Skylo will exhaust its cellular registration attempts and transition automatically to the Skylo NTN satellite path. A pending summary Note should eventually appear in Notehub — allow several minutes for initial satellite acquisition; subsequent sessions are faster once the modem has acquired the satellite ephemeris. **To confirm satellite delivery:** in Notehub navigate to **Events**, filter on your device, and open the `_session.qo` system Note created for the same session as your delivered event (see the [system notefiles reference](https://dev.blues.io/api-reference/system-notefiles/)). For a **cellular session**, the `_session.qo` body includes populated `tower_id`, `tower_lat`, and `tower_lon` fields identifying the cell tower that carried the session. For a **Skylo NTN satellite session**, those tower fields are absent — no cell tower was involved. This tower-field presence/absence is the reliable, documented indicator of transport type. +**Satellite fallback validation.** Move the powered unit — with **all antennas properly attached** — to an **outdoor location** with confirmed no LTE-M cellular coverage but a **clear, unobstructed sky view**. A rural field, open parking area, or rooftop site with verified weak/no LTE-M coverage (confirm against the carrier's coverage map before the trip) is ideal. **Do not use a basement, building interior, or enclosed metal container** — these structures block the satellite signal in addition to cellular, giving the Notecard no radio path at all; no delivery will occur. Do not disconnect a u.FL connector while the unit is powered; doing so creates an open-circuit impedance mismatch that can damage the modem front end. With all antennas connected and no cell signal available, Notecard for Skylo will exhaust its cellular registration attempts and transition automatically to the Skylo NTN satellite path. A pending summary Note should eventually appear in Notehub — allow several minutes for initial satellite acquisition; subsequent sessions are faster once the modem has acquired the satellite ephemeris. **To confirm satellite delivery:** in Notehub navigate to **Events**, filter on your device, and open the `_session.qo` system Note created for the same session as your delivered event (see the [system notefiles reference](https://dev.blues.io/api-reference/system-notefiles/)). For a **cellular session**, the `_session.qo` body includes populated `tower_id`, `tower_lat`, and `tower_lon` fields identifying the cell tower that carried the session. For a **Skylo NTN satellite session**, those tower fields are absent — no cell tower was involved. This tower-field presence/absence is the reliable, documented indicator of transport type. ## 10. Limitations and Next Steps @@ -709,7 +709,7 @@ This reference platform delivers the three sensor paths a trailer OEM can stand - **Four tire positions are tracked.** A 53-foot refrigerated trailer typically runs 10 or more tires on dual rear axles; the POC supports only four positions. Expanding to the full tire set requires a larger TPMS position array and a wider Note template. - **GPS-position-delta state detection is approximate.** Comparing GPS positions at 5-minute intervals can be ambiguous in poor-sky conditions or during slow dock maneuvering. A production implementation should combine GPS position delta with the Notecard's built-in accelerometer (`card.motion.mode`) for reliable motion detection that doesn't depend on GNSS fix quality. - **No J1939/CAN integration.** Modern reefer units expose richer telemetry — fault codes, fuel consumption, run hours, setpoint history — over J1939 CAN, not just temperature. Adding CAN to this platform requires more than a transceiver: (a) confirm that the STM32L433's CAN peripheral pins (CAN_TX/CAN_RX) are accessible on the Notecarrier CX/Cygnet headers — if not, a board redesign or an alternate host with CAN pins broken out is required; (b) once a host with accessible CAN pins is established, add an automotive-qualified CAN transceiver (e.g., TJA1051T/3/1J, AEC-Q100-qualified) between the host CAN controller and the J1939 bus; and (c) implement J1939 PGN (**Parameter Group Number**, the J1939 message identifier) decode in firmware (e.g., using an mcp_can-style library or a raw CAN driver targeting the host's bxCAN peripheral). A transceiver alone is not sufficient without a host that exposes a compatible CAN controller. -- **Skylo NTN satellite latency.** Satellite session establishment can take several minutes on initial power-up, and the Skylo NTN network imposes message-size and throughput constraints smaller than typical cellular sessions. Alert Notes sent via satellite will arrive in Notehub with higher latency than cellular. Plan monitoring workflows accordingly; the Notecard for Skylo prefers cellular and falls back to satellite automatically, so this latency applies only in genuine coverage gaps. +- **Skylo NTN satellite latency.** Satellite session establishment can take several minutes on initial power-up, and the Skylo NTN network imposes message-size and throughput constraints smaller than typical cellular sessions. Alert Notes sent via satellite will arrive in Notehub with higher latency than cellular. Plan monitoring workflows accordingly; Notecard for Skylo prefers cellular and falls back to satellite automatically, so this latency applies only in genuine coverage gaps. - **No host over-the-air firmware update.** [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) requires SWD/BOOT pin access that is not exposed through the Notecarrier CX headers in this standard configuration. Production boards should route BOOT and NRST signals through a DFU header to enable fleet-wide host firmware updates without a service visit. - **Mojo is bench tooling.** The firmware does not read the Mojo's LTC2959 coulomb counter over Qwiic. Adding a cumulative-mAh field to the summary Note is a straightforward extension that enables fleet-level power telemetry for DC dwell energy auditing. diff --git a/75-heavy-equipment-hours-of-use-utilization-tracker/README.md b/75-heavy-equipment-hours-of-use-utilization-tracker/README.md index 4fb78d29..45db125b 100644 --- a/75-heavy-equipment-hours-of-use-utilization-tracker/README.md +++ b/75-heavy-equipment-hours-of-use-utilization-tracker/README.md @@ -16,7 +16,7 @@ This project is a retrofit [asset location tracking](https://blues.com/solutions Vibration-based hour detection solves the retrofit problem entirely. A small enclosure attached magnetically to the equipment frame asks one question on each sample: *is this equipment's engine currently running?* Getting the answer right is harder than it sounds. A rented excavator sitting in the back of a flatbed travels to a job site with its engine off, but the truck's diesel vibration and road shock look a lot like engine idle to a simple threshold-based accelerometer. This project addresses that with a two-parameter vibration signature algorithm: the root-mean-square (RMS) amplitude of the net acceleration residual measures activity level, and the coefficient of variation (CV, or σ/μ) discriminates steady periodic engine vibration from the irregular, bursty character of transport shock. Engine idle produces a low CV; road vibration produces a high one. Together they give three reliable states — **engine running**, **in transport**, and **idle/stopped** — without a single wire to the equipment. -**Why Notecard for Skylo.** The equipment is mobile by definition, moving among customer job sites with no WiFi and often in areas where cellular coverage is marginal or absent. Open-pit mine sites, remote pipeline corridors, and offshore wind-farm construction zones all fall into this category. The [Notecard for Skylo (NOTE-NBGLWX)](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) consolidates LTE-M, NB-IoT, GPRS, WiFi fallback, and Skylo satellite NTN (non-terrestrial network) on a single M.2 module — no separate satellite modem, no Starnote companion board required. When cellular is available, Notes flow over LTE-M with the low latency and high throughput you'd expect. When the equipment sits at the bottom of a quarry or behind a ridge where no tower reaches, the Notecard automatically falls back to satellite uplink through Skylo's NTN satellite service. The operator sees unbroken location and hours telemetry regardless of site topology, and the firmware never has to know which network was used. +**Why Notecard for Skylo.** The equipment is mobile by definition, moving among customer job sites with no WiFi and often in areas where cellular coverage is marginal or absent. Open-pit mine sites, remote pipeline corridors, and offshore wind-farm construction zones all fall into this category. [Notecard for Skylo (NOTE-NBGLWX)](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) consolidates LTE-M, NB-IoT, GPRS, WiFi fallback, and Skylo satellite NTN (non-terrestrial network) on a single M.2 module — no separate satellite modem, no Starnote companion board required. When cellular is available, Notes flow over LTE-M with the low latency and high throughput you'd expect. When the equipment sits at the bottom of a quarry or behind a ridge where no tower reaches, the Notecard automatically falls back to satellite uplink through Skylo's NTN satellite service. The operator sees unbroken location and hours telemetry regardless of site topology, and the firmware never has to know which network was used. @@ -28,7 +28,7 @@ Vibration-based hour detection solves the retrofit problem entirely. A small enc **Device-side responsibilities.** Three pieces of work happen on the equipment itself, and they all have to fit into a 30-second wake budget. The Cygnet STM32 host on the Notecarrier CX comes up via [`card.attn`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-attn) host power gating, initializes the Adafruit LSM6DSOX accelerometer over I2C, and grabs a 2-second burst of 3-axis samples at 104 Hz. The vibration classifier turns that burst into one of three states — IDLE, RUNNING, or TRANSPORT — feeds the hour-meter accumulator, and compares the result against the previous wake. A state change fires an immediate event; an elapsed summary window fires a summary Note. Between wakes the host is fully powered off, and the Notecard holds the persisted state struct in its internal flash until the `ATTN` timer reapplies host power. -**Notecard responsibilities.** Once the host hands off, the Notecard for Skylo takes over the network side. It queues [Notes](https://dev.blues.io/api-reference/glossary/#note) locally and opens cellular or satellite sessions on two cadences configured in [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set): a daily outbound sync that carries queued summaries and an 8-hour inbound check-in (`inbound: 480`) that pulls environment-variable updates from Notehub. After each state-change event lands in the queue, the firmware issues a separate `hub.sync` call so the billing record doesn't wait for the next scheduled outbound window. Periodic GPS location sampling (every 15 minutes) and geofence configuration both run through [`card.location.mode`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-location-mode), with a separate [`card.location.track`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-location-track) call enabling the 4-hour heartbeat `_track.qo` record. If a geofence is configured through [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/), the Notecard evaluates it autonomously and emits a `_track.qo` event the moment the equipment leaves the job site — no host involvement required after the fence parameters are applied. +**Notecard responsibilities.** Once the host hands off, Notecard for Skylo takes over the network side. It queues [Notes](https://dev.blues.io/api-reference/glossary/#note) locally and opens cellular or satellite sessions on two cadences configured in [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set): a daily outbound sync that carries queued summaries and an 8-hour inbound check-in (`inbound: 480`) that pulls environment-variable updates from Notehub. After each state-change event lands in the queue, the firmware issues a separate `hub.sync` call so the billing record doesn't wait for the next scheduled outbound window. Periodic GPS location sampling (every 15 minutes) and geofence configuration both run through [`card.location.mode`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-location-mode), with a separate [`card.location.track`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-location-track) call enabling the 4-hour heartbeat `_track.qo` record. If a geofence is configured through [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/), the Notecard evaluates it autonomously and emits a `_track.qo` event the moment the equipment leaves the job site — no host involvement required after the fence parameters are applied. **Notehub responsibilities.** The Notecard's embedded global SIM handles cellular and Skylo NTN satellite sessions against supported carriers worldwide, delivering events to [Notehub](https://notehub.io) over the Internet; Notehub ingests, stores, and applies project-level routes from there. The operator never touches firmware to retune the fleet — fleet-level [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) let you adjust vibration thresholds and geofence parameters from the web console without a truck roll. [Smart Fleets](https://dev.blues.io/notehub/notehub-walkthrough/#using-smart-fleet-rules) segment devices by rental customer, equipment class, or geographic territory so routing and alerting can differ by group. @@ -74,13 +74,13 @@ Here is a sample Note this device emits: | Passive GPS/GNSS patch antenna, u.FL connector (e.g. [Adafruit #2460](https://www.adafruit.com/product/2460)) | 1 | Attaches to the NOTE-NBGLWX `GPS` u.FL port. **Must be passive** — the GPS port does not supply DC bias, and the datasheet explicitly requires a passive antenna. The 50 mm pigtail is long enough to position the 9 mm × 9 mm ceramic patch against the inside face of the polycarbonate lid; GPS L1 signals penetrate the plastic without requiring a cable gland. For best fix rate, orient the patch toward the sky. | | u.FL-to-SMA female pigtail cable, ~150 mm (e.g. [Adafruit #851](https://www.adafruit.com/product/851)) | 1 | Routes the NOTE-NBGLWX `MAIN` u.FL port through the enclosure wall to the Skylo-certified MAIN antenna. The u.FL end (**female**, clips onto the Notecard's `MAIN` port) attaches inside the enclosure; the other end is an **SMA female jack (panel-mount style)** — pass it through a drilled or punched hole in the enclosure sidewall, secure with the hex nut, and apply a thin bead of silicone sealant under the nut face to maintain the enclosure's weatherproof rating at the penetration. The Skylo-certified MAIN antenna's **SMA male plug** screws directly onto this SMA female from outside the enclosure — no separate bulkhead adapter is needed. The `MAIN` port carries both LTE-M/NB-IoT/GPRS cellular **and** Skylo NTN satellite on a single antenna path (S-Band / L-Band, bands B23/B255/B256). **The Skylo-certified MAIN antenna included with the NOTE-NBGLWX must be used on this port** — substituting a different antenna removes Skylo certification and may result in network blocking by Skylo. Mount the MAIN antenna outside the enclosure with an unobstructed sky view. See the [NOTE-NBGLWX datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) for the full antenna requirements. | -The Notecard for Skylo ships with a factory-provisioned SIM, global cellular and satellite service, 500 MB of cellular data, 10 KB of satellite data, and 10 years of connectivity included in the device price — no activation fees, no monthly minimum. This entitlement applies to the Notecard for Skylo; the Notecarrier CX and Mojo are hardware-only items with no attached connectivity service. +Notecard for Skylo ships with a factory-provisioned SIM, global cellular and satellite service, 500 MB of cellular data, 10 KB of satellite data, and 10 years of connectivity included in the device price — no activation fees, no monthly minimum. This entitlement applies to Notecard for Skylo; the Notecarrier CX and Mojo are hardware-only items with no attached connectivity service. ## 5. Wiring and Assembly ![Wiring: LSM6DSOX accelerometer on I²C; ATTN→EN jumper required for sleep gating; MAIN antenna for cellular/satellite plus GPS antenna via Notecard u.FL; solar 2 W → LiPo 2 Ah → Mojo (bench) → +VBAT](diagrams/02-wiring-assembly.svg) -The Notecard for Skylo seats into the Notecarrier CX's M.2 Key E slot. The Adafruit LSM6DSOX connects via the Notecarrier CX's I2C header — a Qwiic/STEMMA QT cable makes this a single two-connector snap if you own the matching Qwiic cable, otherwise use four discrete wires. The Mojo sits inline on the main power feed during bench validation. +Notecard for Skylo seats into the Notecarrier CX's M.2 Key E slot. The Adafruit LSM6DSOX connects via the Notecarrier CX's I2C header — a Qwiic/STEMMA QT cable makes this a single two-connector snap if you own the matching Qwiic cable, otherwise use four discrete wires. The Mojo sits inline on the main power feed during bench validation. Pin-by-pin: @@ -295,7 +295,7 @@ Power efficiency matters for a solar-trickle-charged deployment. Three levers ar 4. **GPS fix cadence.** The firmware configures `card.location.mode` in `periodic` mode with a 900-second (15-minute) interval. In the typical deployment case, GNSS fix attempts occur on or around the 15-minute cadence when the Notecard determines a new fix is warranted. Each fix attempt typically draws 20–50 mA for 10–60 seconds; at up to 96 attempts per day this can contribute roughly **15–30 mAh/day** to the power budget — a meaningful fraction of the total. If solar input is marginal or the device is frequently stationary, increase `GPS_PERIOD_SECONDS` to reduce GNSS power consumption. -The Notecard for Skylo idles at approximately **8–18 µA @ 5V** between sessions (see the [low-power firmware design guide](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design/)). LTE-M sessions for a small queued payload run on the order of tens of seconds at ~100–300 mA peak. Satellite (Skylo NTN) sessions measured in the Blues low-power guide consume approximately **27 mAh per 12-hour period with hourly syncs** — daily sync cadence will be materially lower. Expect the bench-measured total for a device with default settings to be approximately **65–120 mAh per 24 hours** depending on network type, signal quality, state-change event frequency, and GNSS fix success rate. +Notecard for Skylo idles at approximately **8–18 µA @ 5V** between sessions (see the [low-power firmware design guide](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design/)). LTE-M sessions for a small queued payload run on the order of tens of seconds at ~100–300 mA peak. Satellite (Skylo NTN) sessions measured in the Blues low-power guide consume approximately **27 mAh per 12-hour period with hourly syncs** — daily sync cadence will be materially lower. Expect the bench-measured total for a device with default settings to be approximately **65–120 mAh per 24 hours** depending on network type, signal quality, state-change event frequency, and GNSS fix success rate. ### 7.6 Retry and error handling @@ -494,4 +494,4 @@ This is a reference build, not a finished fleet product — a few things are del ## 12. Summary -The rental excavator that started this story now reports its own hours. A magnetic enclosure slaps onto the frame rail in under ten minutes — no drilling, no harness, no OEM cooperation — and from that moment the machine streams engine hours, location, and work-session events to Notehub over whichever network it can reach. The two-parameter RMS + coefficient-of-variation classifier is the piece that makes vibration-only detection trustworthy: it tells a diesel idle apart from a flatbed delivery without any wiring to the engine, and the Notecard for Skylo keeps the data flowing whether the machine is at a regional yard or at the bottom of a quarry. For the rental company, the data pipeline is straightforward — any `equip_event.qo` with `session_min > 0` is the billing record, `run_h_total` drives maintenance scheduling, and a `transport_start` at 2 AM is the unauthorized-use alert. Same firmware, same hardware, same Notehub project, across the whole fleet. +The rental excavator that started this story now reports its own hours. A magnetic enclosure slaps onto the frame rail in under ten minutes — no drilling, no harness, no OEM cooperation — and from that moment the machine streams engine hours, location, and work-session events to Notehub over whichever network it can reach. The two-parameter RMS + coefficient-of-variation classifier is the piece that makes vibration-only detection trustworthy: it tells a diesel idle apart from a flatbed delivery without any wiring to the engine, and Notecard for Skylo keeps the data flowing whether the machine is at a regional yard or at the bottom of a quarry. For the rental company, the data pipeline is straightforward — any `equip_event.qo` with `session_min > 0` is the billing record, `run_h_total` drives maintenance scheduling, and a `transport_start` at 2 AM is the unauthorized-use alert. Same firmware, same hardware, same Notehub project, across the whole fleet. diff --git a/76-untethered-trailer-chassis-fleet-tracker/README.md b/76-untethered-trailer-chassis-fleet-tracker/README.md index 66a36dfc..2d7c2c55 100644 --- a/76-untethered-trailer-chassis-fleet-tracker/README.md +++ b/76-untethered-trailer-chassis-fleet-tracker/README.md @@ -576,7 +576,7 @@ A reference design has to draw the line somewhere, and this one draws it at the - **No DFU wired up.** [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) on the Swan is not configured in this POC. Field firmware updates currently require physical access to the Swan's USB-C port. -- **Alternative hardware path — [Skylo](https://www.skylo.tech/) NTN (land routes only).** For fleets confined to North American land-route corridors within Skylo's geostationary footprint, the [Notecard for Skylo (NOTE-NBGLWX)](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) on a [Notecarrier CX](https://shop.blues.com/products/notecarrier-cx?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) integrates cellular, Skylo NTN satellite, GPS, and the accelerometer in a single M.2 module with no Starnote or external MCU board required. The same Notefile schemas (`trailer_event.qo`, `trailer_location.qo`, `trailer_heartbeat.qo`) and the same Notehub project apply. **Skylo's service area covers defined land-route corridors only — no ocean-route or polar coverage.** See the [Choosing Between Skylo and Iridium](https://dev.blues.io/starnote/choosing-between-skylo-and-iridium/) guide for the full coverage comparison. +- **Alternative hardware path — [Skylo](https://www.skylo.tech/) NTN (land routes only).** For fleets confined to North American land-route corridors within Skylo's geostationary footprint, [Notecard for Skylo (NOTE-NBGLWX)](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) on a [Notecarrier CX](https://shop.blues.com/products/notecarrier-cx?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) integrates cellular, Skylo NTN satellite, GPS, and the accelerometer in a single M.2 module with no Starnote or external MCU board required. The same Notefile schemas (`trailer_event.qo`, `trailer_location.qo`, `trailer_heartbeat.qo`) and the same Notehub project apply. **Skylo's service area covers defined land-route corridors only — no ocean-route or polar coverage.** See the [Choosing Between Skylo and Iridium](https://dev.blues.io/starnote/choosing-between-skylo-and-iridium/) guide for the full coverage comparison. **Production next steps:** diff --git a/78-rail-car-condition-interchange-tracker/README.md b/78-rail-car-condition-interchange-tracker/README.md index 8d8c1742..07e9c533 100644 --- a/78-rail-car-condition-interchange-tracker/README.md +++ b/78-rail-car-condition-interchange-tracker/README.md @@ -20,11 +20,11 @@ Rail car lessors operate fleets worth hundreds of millions of dollars with essen -The Notecard for Skylo (NOTE-NBGLWX) solves the coverage gap with a single M.2 module that carries LTE-M/NB-IoT/GPRS for cellular coverage and [Skylo](https://www.skylo.tech/) NTN (Non-Terrestrial Network) satellite for everywhere else. The Notecard orchestrates the cellular-to-satellite fallback autonomously — the host firmware doesn't need to know which transport is in use. Notes accumulate in Notecard flash during the long dead zones between windows, then flush the moment any transport opens. For assets that might spend days out of cellular range and weeks in a yard, that queue-and-forward model is load-bearing, not a nice-to-have. +Notecard for Skylo (NOTE-NBGLWX) solves the coverage gap with a single M.2 module that carries LTE-M/NB-IoT/GPRS for cellular coverage and [Skylo](https://www.skylo.tech/) NTN (Non-Terrestrial Network) satellite for everywhere else. The Notecard orchestrates the cellular-to-satellite fallback autonomously — the host firmware doesn't need to know which transport is in use. Notes accumulate in Notecard flash during the long dead zones between windows, then flush the moment any transport opens. For assets that might spend days out of cellular range and weeks in a yard, that queue-and-forward model is load-bearing, not a nice-to-have. This architecture maps directly to Blues' [supply chain tracking](https://blues.com/solutions-supply-chain-tracking/) use case: mobile assets crossing connectivity boundaries unpredictably, with no fixed infrastructure to rely on. -**Deployment scenario.** A weatherproof NEMA 4X enclosure bolted to the car's end-sill or side-sill, powered by a small rooftop solar panel through a solar LiPo charge controller that safely charges a lithium-ion polymer battery. A [Blues Scoop](https://shop.blues.com/products/scoop?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) lithium-ion capacitor buffer sits inline between a 5 V regulated supply and the Notecarrier VBAT rail, smoothing out the high-current bursts that cellular and especially satellite transmission demand; without it, a modest LiPo under a weak winter sun can brown out the radio mid-session. The Skylo-certified LTE/NTN antenna (included with the Notecard for Skylo) and a passive GNSS antenna mount flush to the roof with a clear sky view. A magnetically actuated reed switch attaches near the coupler knuckle, with a matching magnet mounted to the adjacent coupler structure. On TANK_CAR builds, the MPRLS connects to a low-pressure vent or fitting port on the car body. +**Deployment scenario.** A weatherproof NEMA 4X enclosure bolted to the car's end-sill or side-sill, powered by a small rooftop solar panel through a solar LiPo charge controller that safely charges a lithium-ion polymer battery. A [Blues Scoop](https://shop.blues.com/products/scoop?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) lithium-ion capacitor buffer sits inline between a 5 V regulated supply and the Notecarrier VBAT rail, smoothing out the high-current bursts that cellular and especially satellite transmission demand; without it, a modest LiPo under a weak winter sun can brown out the radio mid-session. The Skylo-certified LTE/NTN antenna (included with Notecard for Skylo) and a passive GNSS antenna mount flush to the roof with a clear sky view. A magnetically actuated reed switch attaches near the coupler knuckle, with a matching magnet mounted to the adjacent coupler structure. On TANK_CAR builds, the MPRLS connects to a low-pressure vent or fitting port on the car body. ## 2. System Architecture @@ -70,7 +70,7 @@ Here is a sample Note this device emits: | Part | Qty | Rationale | |------|-----|-----------| | [Notecarrier CX](https://shop.blues.com/products/notecarrier-cx?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Integrated carrier with onboard Cygnet STM32L433 host — no separate MCU needed. I²C, six analog inputs, nine digital I/O, and M.2 Notecard slot. See the [Notecarrier CX datasheet](https://dev.blues.io/datasheets/notecarrier-datasheet/notecarrier-cx-v1-3/). | -| [Notecard for Skylo (NOTE-NBGLWX)](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Single M.2 module with LTE-M/NB-IoT/GPRS + Skylo NTN satellite. 500 MB cellular + 10 KB satellite bundled; no monthly fees. **Ships with its Skylo-certified LTE/NTN antenna — do not substitute another antenna** without a CTIA/OTA delta test report; Skylo may block uncertified devices. See the [Notecard for Skylo datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/). | +| [Notecard for Skylo (NOTE-NBGLWX)](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Single M.2 module with LTE-M/NB-IoT/GPRS + Skylo NTN satellite. 500 MB cellular + 10 KB satellite bundled; no monthly fees. **Ships with its Skylo-certified LTE/NTN antenna — do not substitute another antenna** without a CTIA/OTA delta test report; Skylo may block uncertified devices. See [Notecard for Skylo datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/). | | [Blues Mojo](https://shop.blues.com/products/mojo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Coulomb counter for bench power validation. See [§9](#9-validation-and-testing). Not deployed to the field. See the [Mojo datasheet](https://dev.blues.io/datasheets/mojo-datasheet/). | | [Blues Scoop](https://shop.blues.com/products/scoop?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Lithium-ion capacitor (250 F) peak-current buffer, wired **inline** between the 5 V boost module and the Notecarrier CX `+VBAT` rail. The Scoop has two connectors and two sets of header pins: **J1 (CHG)** JST input (4.8–24 V; headers **J3** are a through-hole alternative to J1) and **J2 (OUT)** JST output (2.5–3.8 V; headers **J4** are a through-hole alternative to J2). The 5 V boost module output connects to J1/J3; Scoop J2/J4 connects to Notecarrier CX `+VBAT`. The internal LiC charges from J1 between radio sessions and supplements the supply rail through J2 during high-current cellular and satellite bursts. **J1 requires ≥ 4.8 V — do not connect it directly to the LiPo (max 4.2 V) or to a raw solar panel.** It is **not** a LiPo charger and does not replace the solar charge controller. See the [Scoop datasheet](https://dev.blues.io/datasheets/scoop-datasheet/). | | 5 V boost regulator, 3.0–4.2 V input, 5 V regulated output, ≥ 500 mA (e.g., Pololu U1V11F5 or equivalent single-cell LiPo boost module) | 1 | Converts LiPo voltage (3.0–4.2 V) to the regulated 5 V that the Scoop J1 (CHG) input requires. Connect the LiPo JST to this module's input and the 5 V output to Scoop J1 (see [§5](#5-wiring-and-assembly)). A 500 mA output rating provides sufficient current to recharge the Scoop's internal LiC between radio sessions. | @@ -87,11 +87,11 @@ Here is a sample Note this device emits: | u.FL (IPEX/MHF1) to SMA female bulkhead pigtail cable, 100–200 mm, RG178 coaxial | 1 | Adapts the Notecard GPS u.FL port to the SMA GNSS antenna above. Route the cable inside the enclosure; the SMA female end mates to the antenna's SMA male connector through a panel-mount SMA bulkhead feedthrough in the enclosure wall. A 100 mm pigtail is typical; ensure routing clears sharp edges and the feedthrough is rated for the antenna's frequency range. | | NEMA 4X polycarbonate enclosure, ~8×6×3″ | 1 | Weatherproof housing for all electronics. Rated for outdoor rail-car use; cable glands for antenna leads, reed switch wire, pressure fitting, and power wiring. | -The Notecard for Skylo ships with bundled cellular and satellite connectivity — 500 MB cellular data and 10 KB satellite data included, with no activation fees and no monthly commitment. The Notecarrier CX is a carrier board and does not contain a SIM. +Notecard for Skylo ships with bundled cellular and satellite connectivity — 500 MB cellular data and 10 KB satellite data included, with no activation fees and no monthly commitment. The Notecarrier CX is a carrier board and does not contain a SIM. ## 5. Wiring and Assembly -All host I/O lands on the [Notecarrier CX](https://dev.blues.io/datasheets/notecarrier-datasheet/notecarrier-cx-v1-3/) dual 16-pin header. The Notecard for Skylo seats into the carrier's M.2 slot; its MAIN u.FL port connects to the included Skylo-certified LTE/NTN antenna, and its GPS u.FL port connects to the separate GNSS antenna via the u.FL-to-SMA pigtail adapter listed in the BOM. The Mojo sits inline between Scoop J2 and the Notecarrier `+VBAT` during bench testing (remove for field deployment). +All host I/O lands on the [Notecarrier CX](https://dev.blues.io/datasheets/notecarrier-datasheet/notecarrier-cx-v1-3/) dual 16-pin header. Notecard for Skylo seats into the carrier's M.2 slot; its MAIN u.FL port connects to the included Skylo-certified LTE/NTN antenna, and its GPS u.FL port connects to the separate GNSS antenna via the u.FL-to-SMA pigtail adapter listed in the BOM. The Mojo sits inline between Scoop J2 and the Notecarrier `+VBAT` during bench testing (remove for field deployment). ![Wiring diagram: ADXL345 and reed switch on I²C/D5, MPRLS and DS18B20 (TANK_CAR), antennas on u.FL ports, and the inline Scoop power path: solar → charge controller → LiPo → 5 V boost → Scoop J1 (CHG, ≥4.8 V) → Scoop J2 (OUT, 2.5–3.8 V) → Notecarrier CX +VBAT](diagrams/02-wiring-assembly.svg) @@ -149,7 +149,7 @@ The MPRLS breakout has a 1/8 NPT threaded port on the sensor body. For field dep -- **Certified antenna.** The Notecard for Skylo ships with a Skylo-certified LTE/NTN antenna. Using any other antenna invalidates the Skylo certification and may result in Skylo blocking the device from its NTN network. Do not substitute another antenna without obtaining a delta test lab report through a CTIA/OTA-authorized facility. Contact [Blues](https://blues.com/contact-sales/) for recommended test houses. +- **Certified antenna.** Notecard for Skylo ships with a Skylo-certified LTE/NTN antenna. Using any other antenna invalidates the Skylo certification and may result in Skylo blocking the device from its NTN network. Do not substitute another antenna without obtaining a delta test lab report through a CTIA/OTA-authorized facility. Contact [Blues](https://blues.com/contact-sales/) for recommended test houses. - **Pressure port safety.** The Adafruit MPRLS (product 3965) is a consumer-grade breakout with a 25 PSI absolute upper limit. It must **not** be plumbed into a pressurized cargo line, any fitting carrying hazardous or flammable contents, or any port that may exceed its 25 PSI absolute rating. Installation of any fitting or sensor on a regulated tank car must be performed by qualified personnel following all applicable DOT, AAR, and carrier/operator rules. For production cargo pressure sensing, replace the MPRLS with a certified industrial transducer rated for the lading and pressure class (see [§11](#11-limitations-and-next-steps)). @@ -161,7 +161,7 @@ The MPRLS breakout has a 1/8 NPT threaded port on the sensor body. For field dep 1. **Create a project.** Sign up at [notehub.io](https://notehub.io) and create a project. Copy the [ProductUID](https://dev.blues.io/notehub/notehub-walkthrough/#finding-a-productuid) (format: `com.your-company.your-name:rail-tracker`) and paste it into the `PRODUCT_UID` macro in `firmware/rail_car_tracker/rail_car_tracker_helpers.h`. -2. **Claim the Notecard.** Power the assembled unit. The Notecard for Skylo attempts cellular connection on first boot and associates itself with the project automatically. The device appears in the **Devices** tab within a few minutes. If cellular coverage is unavailable at the bench, wait until an antenna is connected and the unit has sky view. +2. **Claim the Notecard.** Power the assembled unit. Notecard for Skylo attempts cellular connection on first boot and associates itself with the project automatically. The device appears in the **Devices** tab within a few minutes. If cellular coverage is unavailable at the bench, wait until an antenna is connected and the unit has sky view. 3. **Set the device serial number.** In Notehub, open the device and set the **Serial Number** field to the car's reporting mark and number (e.g., `UTLX-123456`). This propagates through every event and makes it trivial to filter events by car in downstream analytics. @@ -366,7 +366,7 @@ Alert types and their `value` fields: The host Cygnet STM32L433 is fully powered off between samples via `card.attn` sleep mode. Following the pattern of the reference accelerators, all sensing and logic runs in `setup()`; `loop()` holds only the `NotePayloadSaveAndSleep` call and a fallback `delay`. `NotePayloadSaveAndSleep` serializes the `PersistState` struct into Notecard flash, then issues the `card.attn` sleep request that cuts the host power rail for `sample_interval_min × 60` seconds. On ATTN fire, the Notecarrier CX re-applies host power, the MCU enters `setup()` from cold, and `NotePayloadRetrieveAfterSleep` rehydrates the struct. The host is awake for only the few seconds needed to read sensors, evaluate rules, and queue Notes — on the order of 5–10 seconds per 15-minute interval. -The Notecard for Skylo idles at ~8–18 µA @ 5V between sessions (see the [low-power firmware design guide](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design/)). GPS is motion-gated: `card.location.mode` with `threshold: 1` keeps the GNSS radio off while the car sits in a yard, waking it only when the Notecard's internal accelerometer detects movement. Outbound sync cadence adapts to battery charge state via `voutbound`/`vinbound` voltage-variable strings: +Notecard for Skylo idles at ~8–18 µA @ 5V between sessions (see the [low-power firmware design guide](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design/)). GPS is motion-gated: `card.location.mode` with `threshold: 1` keeps the GNSS radio off while the car sits in a yard, waking it only when the Notecard's internal accelerometer detects movement. Outbound sync cadence adapts to battery charge state via `voutbound`/`vinbound` voltage-variable strings: | Voltage tier | `voutbound` interval | `vinbound` interval | |---|---|---| @@ -542,7 +542,7 @@ Mojo is a bench-validation and per-firmware-revision regression tool. Field unit | `railcar_status.qo` has `shock_peak_g: 0.0` always | ADXL345 is not connected or not responding on I²C. Check SDA/SCL wiring to header. The firmware logs `[adxl345Begin] OK` on startup if the sensor is found. If not present, shock is silently recorded as 0.0. | Verify Qwiic/STEMMA QT cable to ADXL345 breakout, or check 4-wire I²C connections (VCC/GND/SDA/SCL). Re-flash and watch serial output. | | `railcar_status.qo` has `pressure_psi: -9999` (TANK_CAR build) | MPRLS pressure sensor failed to initialize or returned an error on this wake. | Check SDA/SCL wiring to MPRLS breakout. Verify I²C address is 0x18 (default; no address pin jumpers on Adafruit 3965). Power-cycle the unit. If errors persist, check that TANK_CAR is enabled in `rail_car_tracker_helpers.h` and the MPRLS library is installed (`arduino-cli lib install "Adafruit MPRLS Library"`). | | `railcar_status.qo` has `tank_temp_c: -9999` (TANK_CAR build) | DS18B20 probe failed to initialize or wiring is broken. The firmware treats values below −100 °C as errors. | Verify the 4.7 kΩ pull-up resistor is connected between D6 and +3V3_OUT. Check the DS18B20 data (yellow) wire to D6, power (red) to +3V3_OUT, and GND (black) to GND. Power-cycle. If the probe has been run too long or the stainless-steel housing is corroded, replace the sensor. | -| Device claims but never syncs (no Notes flow to Notehub) | Cellular and satellite coverage both unavailable; Notes queue in Notecard flash and wait for a window. Also check `hub.set` configuration. | Verify antenna connections: the Notecard for Skylo's MAIN u.FL must connect to the Skylo-certified LTE/NTN antenna (included with the Notecard), and the GPS u.FL connects to the separate GNSS antenna via u.FL-to-SMA pigtail. Both antennas need clear sky view. If both are connected and sky-view is clear, check the Notecard console in Notehub (**Devices → [device] → Notecard Console**) for `[hub]` errors. | +| Device claims but never syncs (no Notes flow to Notehub) | Cellular and satellite coverage both unavailable; Notes queue in Notecard flash and wait for a window. Also check `hub.set` configuration. | Verify antenna connections: Notecard for Skylo's MAIN u.FL must connect to the Skylo-certified LTE/NTN antenna (included with the Notecard), and the GPS u.FL connects to the separate GNSS antenna via u.FL-to-SMA pigtail. Both antennas need clear sky view. If both are connected and sky-view is clear, check the Notecard console in Notehub (**Devices → [device] → Notecard Console**) for `[hub]` errors. | | Mojo shows high baseline current (30–50 mA continuously) | Host is not sleeping. The Notecarrier CX ATTN pin controls host power gating; it must be connected (internal on CX, no external wire needed). If something is holding the host awake, the baseline will not drop to sleep levels (~20–50 µA). | Check the serial log for `[loop]` — if it appears more frequently than once per 15 minutes, the host is looping instead of sleeping. Verify `NotePayloadSaveAndSleep` returns true and issues a `card.attn sleep` request in the log. A failed power-save will leave the host consuming ~30–50 mA continuously. | | Rapid satellite session bursts (1–4 minutes high-current events) | Cellular coverage is lost; the Notecard is falling back to Skylo NTN. This is expected and correct behavior. | No action needed — this is the reference design working as intended. Monitor satellite data consumption in Notehub to confirm you're within your NTN budget. Validate compact templates are being used before the first `note.add` call — a non-compact Note over NTN costs 3–10× more bytes. | @@ -573,4 +573,4 @@ A car-level tracker that has to live for years on solar power, ride out weeks in ## 12. Summary -The lessor who used to wait on an EDI interchange report now hears from the tank car itself. The same Texas-to-New-Jersey trip that used to spend three days in a Tennessee yard with nothing more than a paperwork acknowledgment is now a quarter-hourly health check, a continuous GPS track, a coupling-impact score for every hard hit, and an alert the moment fitting pressure drops or temperature drifts out of range. The continuous GPS track, coupler-state transitions, and motion events that reach Notehub are precisely the inputs a downstream geofencing service needs to detect railroad boundary crossings and generate interchange records; the geofencing and EDI integration steps that convert that telemetry into formal interchange events are production work outlined in [§11 Production Next Steps](#11-limitations-and-next-steps). Status Notes are generated every 4 hours and delivered on the next sync session — within 2–4 hours over cellular at good charge, or the next time the Notecard can establish an NTN session across the open Nebraska Sandhills. The key insight is that the Notecard for Skylo doesn't ask the firmware to choose a transport — it manages cellular and satellite autonomously, queues everything that can't transmit immediately, and flushes it the moment connectivity returns. For an asset class where "no news" has historically meant "no visibility," that queue-and-forward guarantee is the entire value proposition. +The lessor who used to wait on an EDI interchange report now hears from the tank car itself. The same Texas-to-New-Jersey trip that used to spend three days in a Tennessee yard with nothing more than a paperwork acknowledgment is now a quarter-hourly health check, a continuous GPS track, a coupling-impact score for every hard hit, and an alert the moment fitting pressure drops or temperature drifts out of range. The continuous GPS track, coupler-state transitions, and motion events that reach Notehub are precisely the inputs a downstream geofencing service needs to detect railroad boundary crossings and generate interchange records; the geofencing and EDI integration steps that convert that telemetry into formal interchange events are production work outlined in [§11 Production Next Steps](#11-limitations-and-next-steps). Status Notes are generated every 4 hours and delivered on the next sync session — within 2–4 hours over cellular at good charge, or the next time the Notecard can establish an NTN session across the open Nebraska Sandhills. The key insight is that Notecard for Skylo doesn't ask the firmware to choose a transport — it manages cellular and satellite autonomously, queues everything that can't transmit immediately, and flushes it the moment connectivity returns. For an asset class where "no news" has historically meant "no visibility," that queue-and-forward guarantee is the entire value proposition. diff --git a/82-aerial-lift-rental-equipment-battery-health-monitor/README.md b/82-aerial-lift-rental-equipment-battery-health-monitor/README.md index a2c7e2c4..1e8c9880 100644 --- a/82-aerial-lift-rental-equipment-battery-health-monitor/README.md +++ b/82-aerial-lift-rental-equipment-battery-health-monitor/README.md @@ -18,7 +18,7 @@ Rental fleets compound this. A machine might sit on a customer's site for three This project is the watcher. A small monitoring device clipped to the pack reads the pack bus voltage through a precision I²C power monitor (INA228) and, in field builds, pack current through either an external precision shunt wired to the INA228's differential inputs (the default, `ENABLE_ACS758 0`) or an ACS758 Hall-effect sensor on the traction conductor (the alternative, `ENABLE_ACS758 1`); records the pack temperature through a probe mounted to the battery housing; and — when the machine's **BMS** (battery management system) exposes individual cell-group voltages over **CAN** (Controller Area Network) bus — pulls those in too (see the CAN Note below). From these four data streams, it continuously estimates **SoC** (state of charge), accumulates a **cycle Ah throughput** total via a sampled Ah estimator, and maintains a rolling **SoH** (state of health) estimate updated whenever a heuristic charge-cycle threshold is crossed. Three of those numbers, plus temperature, show up on the rental company's fleet dashboard within seconds of a threshold trip, and in a single hourly telemetry Note the rest of the time. -**Why Notecard.** The lift is on a construction site that is unlikely to have public WiFi, and even if it does, the rental company's fleet app has to work identically at every job site — a residential project in rural Montana and a high-rise downtown. Cellular removes that dependency entirely: no network form, no AP to pair with, no IT ticket. But construction sites can also be in coverage gaps — in-building below grade, in mountain foothills, in rural areas where the crew has gone to break ground. That's where the [Skylo](https://www.skylo.tech/) satellite fallback earns its place: the same JSON Note that normally travels over LTE-M can, transparently to the firmware, use the Notecard for Skylo's NTN (Non-Terrestrial Network) radio when cellular isn't reachable. The satellite link isn't the primary path — it's the insurance policy that makes the system work the same way at every job. The Notecard for Skylo integrates cellular, WiFi, and Skylo satellite on a single M.2 SoM, so there's no companion board to wire up and no secondary UART to manage. +**Why Notecard.** The lift is on a construction site that is unlikely to have public WiFi, and even if it does, the rental company's fleet app has to work identically at every job site — a residential project in rural Montana and a high-rise downtown. Cellular removes that dependency entirely: no network form, no AP to pair with, no IT ticket. But construction sites can also be in coverage gaps — in-building below grade, in mountain foothills, in rural areas where the crew has gone to break ground. That's where the [Skylo](https://www.skylo.tech/) satellite fallback earns its place: the same JSON Note that normally travels over LTE-M can, transparently to the firmware, use Notecard for Skylo's NTN (Non-Terrestrial Network) radio when cellular isn't reachable. The satellite link isn't the primary path — it's the insurance policy that makes the system work the same way at every job. Notecard for Skylo integrates cellular, WiFi, and Skylo satellite on a single M.2 SoM, so there's no companion board to wire up and no secondary UART to manage. @@ -30,13 +30,13 @@ This project is the watcher. A small monitoring device clipped to the pack reads **Device-side responsibilities.** The host's job is to turn four raw signals into pack health numbers the rental company can act on. Every `sample_interval_s` seconds (default 300 seconds / 5 minutes), the Cygnet STM32 on the Notecarrier CX wakes and reads pack voltage from the INA228 over I²C, pack current from the right source for the build (INA228 `readCurrent()` through an external precision shunt in the default field build `ENABLE_ACS758 0`, the ACS758 Hall-effect sensor on A1 in the alternative `ENABLE_ACS758 1`, or the onboard INA228 shunt in bench builds `BENCH_ONLY 1`), and the pack temperature from the NTC thermistor. When the machine's BMS is CAN-accessible, the host also polls cell-group voltages over the SPI CAN interface. (**CAN BMS integration requires vendor-specific CAN ID and frame parser configuration before the feature will work with any real BMS** — the shipped firmware is a placeholder for this path; see §7.3 and §9.) From those four streams, the firmware updates SoC via a voltage-based OCV lookup, accumulates absolute current above a 0.5 A noise floor into a running cycle Ah throughput total (one sampled Ah estimate per wake), and updates a rolling SoH estimate whenever a heuristic pseudo-cycle completes (SoC dips below 30% then recovers above 90%). Threshold checks run after every sample, and any trip fires an immediate Note. Between wakes, [`card.attn`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-attn) cuts host power; the Notecard idles. The full assembly still draws quiescent current from the buck regulator, INA228, thermistor divider, and any optional CAN hardware — materially above the Notecard's own idle figure, so see [§9](#9-validation-and-testing) for Mojo-measured whole-device figures. -**Notecard responsibilities.** The Notecard for Skylo is the part that decides when those numbers actually leave the machine. It holds [Notes](https://dev.blues.io/api-reference/glossary/#note) in its onboard queue, manages the cellular or satellite session on the configured [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence, and flushes any `sync:true` alert the instant a threshold trips. It also distributes [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) from Notehub, so fleet-level threshold adjustments reach devices without a reflash. The built-in Skylo NTN radio activates automatically whenever terrestrial cellular is unavailable — the firmware doesn't manage the handoff, and the same alert reaches Notehub from a rural job site that it reaches from an urban yard. +**Notecard responsibilities.** Notecard for Skylo is the part that decides when those numbers actually leave the machine. It holds [Notes](https://dev.blues.io/api-reference/glossary/#note) in its onboard queue, manages the cellular or satellite session on the configured [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence, and flushes any `sync:true` alert the instant a threshold trips. It also distributes [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) from Notehub, so fleet-level threshold adjustments reach devices without a reflash. The built-in Skylo NTN radio activates automatically whenever terrestrial cellular is unavailable — the firmware doesn't manage the handoff, and the same alert reaches Notehub from a rural job site that it reaches from an urban yard. **Notehub responsibilities.** Once Notes leave the lift, the Notecard's embedded global SIM carries them over supported carriers worldwide and lands them in [Notehub](https://notehub.io), where every event is stored and project-level routes fan it out. Hourly telemetry summaries and immediate alerts use separate [Notefiles](https://dev.blues.io/api-reference/glossary/#notefile) so the rental company can route each one to where it belongs: alerts to an on-call or rental ERP system for immediate triage, summaries to a long-term analytics store for cycle-life trending. [Smart Fleets](https://dev.blues.io/notehub/notehub-walkthrough/#using-smart-fleet-rules) are how a single firmware image serves machines with different pack chemistries and rated capacities — fleet-level environment variables encode the pack specs, and per-device overrides handle the machines that deviate. **Routing to the cloud (high level).** Notehub supports HTTP, MQTT, AWS, Azure, GCP, and Snowflake, among other destinations; route setup is project-specific. See the [Notehub routing docs](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub) — this project ships no specific downstream endpoint or dashboard. -**Satellite data budget.** The Notecard for Skylo includes 10 KB of satellite data. Hourly summaries are suppressed over satellite (the `battery_status.qo` template sets `delete:true`, so any queued summaries are cleared when the Notecard establishes an NTN session rather than being routed over the expensive satellite link). Critical alerts — low SoC, thermal excursion, SoH degradation — carry no `delete` flag and travel over whatever link is available, including satellite. This ensures fleet operators are notified of dangerous pack conditions even on job sites with no cellular coverage. +**Satellite data budget.** Notecard for Skylo includes 10 KB of satellite data. Hourly summaries are suppressed over satellite (the `battery_status.qo` template sets `delete:true`, so any queued summaries are cleared when the Notecard establishes an NTN session rather than being routed over the expensive satellite link). Critical alerts — low SoC, thermal excursion, SoH degradation — carry no `delete` flag and travel over whatever link is available, including satellite. This ensures fleet operators are notified of dangerous pack conditions even on job sites with no cellular coverage. ## 3. Technical Summary @@ -96,7 +96,7 @@ All Blues hardware ships with an active SIM and no activation fees or monthly co ![Wiring: INA228 on I²C, NTC thermistor on ADC, optional ACS758 on A1 or CAN BMS on SPI; MAIN antenna for cellular + Skylo NTN; 12 V pack aux → buck regulator → Mojo (bench) → +VBAT](diagrams/02-wiring-assembly.svg) -All host I/O lands on the [Notecarrier CX](https://dev.blues.io/datasheets/notecarrier-datasheet/notecarrier-cx-v1-3/) dual 16-pin header. The Notecard for Skylo seats in the carrier's M.2 slot. The Mojo sits inline between the 5V supply output and the Notecarrier's VBAT+ pad during bench validation. +All host I/O lands on the [Notecarrier CX](https://dev.blues.io/datasheets/notecarrier-datasheet/notecarrier-cx-v1-3/) dual 16-pin header. Notecard for Skylo seats in the carrier's M.2 slot. The Mojo sits inline between the 5V supply output and the Notecarrier's VBAT+ pad during bench validation. @@ -424,7 +424,7 @@ notecard.sendRequest(req); ### 7.8 Key code snippet 2: immediate-sync alert -`sync: true` wakes the Notecard's radio immediately rather than waiting for the next hourly outbound window. If cellular isn't available, the Notecard for Skylo will establish a Skylo satellite session instead. +`sync: true` wakes the Notecard's radio immediately rather than waiting for the next hourly outbound window. If cellular isn't available, Notecard for Skylo will establish a Skylo satellite session instead. ```cpp J *req = notecard.newRequest("note.add"); @@ -573,7 +573,7 @@ A pack-health monitor has to make decisions about safety-critical equipment, so - **Aux-rail power dependency.** The design powers the monitor from the machine's 12 V auxiliary circuit. On machines where that rail drops when the key is turned off, the charger is disconnected, or the master disconnect is opened, the monitor goes blind during storage, transport, and between-job intervals — precisely when low SoC, deep discharge, and thermal excursions are most likely to develop undetected. The §4 commissioning check addresses this, but if the field team has not confirmed that the chosen aux rail is always-on, the monitor provides no coverage during machine storage. For full coverage, the power feed must come from the main traction pack terminals through an appropriately rated HV DC/DC stage. -- **Satellite data budget.** The Notecard for Skylo includes 10 KB of satellite data. Each compact alert Note is typically under 100 bytes on the wire; 10 KB covers roughly 100 satellite alert events per billing period. Deployments where sustained NTN operation is expected should monitor satellite usage in Notehub and consider upgrading the data plan. Skylo coverage also requires an unobstructed view of the equatorial sky — the antenna must be mounted on the machine exterior, not in an enclosed battery bay. +- **Satellite data budget.** Notecard for Skylo includes 10 KB of satellite data. Each compact alert Note is typically under 100 bytes on the wire; 10 KB covers roughly 100 satellite alert events per billing period. Deployments where sustained NTN operation is expected should monitor satellite usage in Notehub and consider upgrading the data plan. Skylo coverage also requires an unobstructed view of the equatorial sky — the antenna must be mounted on the machine exterior, not in an enclosed battery bay. - **Mojo does not read from the Notecard in firmware.** The sketch does not query the LTC2959 coulomb counter over Qwiic for runtime power telemetry. Adding a `mojo_mah` field to the summary is a straightforward extension. diff --git a/83-off-grid-solar-battery-site-controller/README.md b/83-off-grid-solar-battery-site-controller/README.md index a6e8c967..0ebcd59f 100644 --- a/83-off-grid-solar-battery-site-controller/README.md +++ b/83-off-grid-solar-battery-site-controller/README.md @@ -25,7 +25,7 @@ This project is a bank-level solar and battery monitoring solution — a Blues [ - **[Notecard Cell+WiFi (NOTE-MBGLW)](https://dev.blues.io/datasheets/notecard-datasheet/note-mbglw/)** — LTE Cat-1 bis cellular with opportunistic WiFi fallback. The practical choice for bench validation and sites with adequate terrestrial coverage. -- **[Notecard for Skylo (NOTE-NBGLWX)](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/)** — LTE-M cellular combined with [Skylo](https://www.skylo.tech/) Non-Terrestrial Network (NTN) satellite connectivity on a single card. The Notecard manages radio-mode selection internally; no firmware differences exist between the two SKUs. **Both antennas must be positioned outdoors with an unobstructed view of the sky**. See §4 and §5 for the mounting and enclosure-feedthrough requirements. The Notecard for Skylo is the primary production SKU for the truly remote towers, wilderness arrays, and high-altitude installations this use case targets. +- **[Notecard for Skylo (NOTE-NBGLWX)](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/)** — LTE-M cellular combined with [Skylo](https://www.skylo.tech/) Non-Terrestrial Network (NTN) satellite connectivity on a single card. The Notecard manages radio-mode selection internally; no firmware differences exist between the two SKUs. **Both antennas must be positioned outdoors with an unobstructed view of the sky**. See §4 and §5 for the mounting and enclosure-feedthrough requirements. Notecard for Skylo is the primary production SKU for the truly remote towers, wilderness arrays, and high-altitude installations this use case targets. **Deployment scenario.** A Notecarrier CX mounted inside the existing site enclosure or a weatherproof addon box, powered from the site's 5V regulation bus or a small DC-DC converter off the main battery bus. Two short VE.Direct cables run from the Notecarrier CX dual-row header to the SmartShunt (battery shunt, usually mounted near the battery bank negative terminal) and to the SmartSolar MPPT controller (typically mounted on the enclosure wall). No changes to the Victron equipment, no interruption to the solar system. @@ -89,7 +89,7 @@ Here is a sample Note this device emits: |------|-----|-----------| | [Notecarrier CX](https://shop.blues.com/products/notecarrier-cx?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Integrated carrier with an embedded Cygnet STM32L433 host — no separate MCU. Provides the UART (Serial1), analog, and SPI/I²C headers needed for this sensor mix. | | [Notecard Cell+WiFi (NOTE-MBGLW)](https://dev.blues.io/datasheets/notecard-datasheet/note-mbglw/) | 1 *(bench / sites with reliable cellular coverage)* | LTE Cat-1 bis cellular with opportunistic WiFi fallback. Prepaid global SIM, no monthly commitment. Use this SKU for bench validation and field sites where terrestrial cellular coverage is reliable. | -| [Notecard for Skylo (NOTE-NBGLWX)](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) | 1 *(sites with marginal or no terrestrial coverage)* | LTE-M cellular combined with Skylo NTN satellite on a single M.2 card — the production SKU for remote towers, backcountry arrays, and high-altitude installations where terrestrial cellular is unreliable. The Notecard-certified satellite/LTE antenna and a passive GPS/GNSS antenna are both required and **must be mounted outdoors with an unobstructed view of the sky** (see §5 for enclosure feedthrough guidance). No firmware changes vs. the NOTE-MBGLW. See the [Notecard for Skylo datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) and [antenna guide](https://dev.blues.io/datasheets/application-notes/antenna-guide/) before deploying. | +| [Notecard for Skylo (NOTE-NBGLWX)](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) | 1 *(sites with marginal or no terrestrial coverage)* | LTE-M cellular combined with Skylo NTN satellite on a single M.2 card — the production SKU for remote towers, backcountry arrays, and high-altitude installations where terrestrial cellular is unreliable. The Notecard-certified satellite/LTE antenna and a passive GPS/GNSS antenna are both required and **must be mounted outdoors with an unobstructed view of the sky** (see §5 for enclosure feedthrough guidance). No firmware changes vs. the NOTE-MBGLW. See [Notecard for Skylo datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) and [antenna guide](https://dev.blues.io/datasheets/application-notes/antenna-guide/) before deploying. | | [Blues Mojo](https://shop.blues.com/products/mojo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Coulomb counter on the +VBAT rail for validating the sleep/wake current profile during commissioning and bench bring-up. See [§9](#9-validation-and-testing). | | [Victron SmartShunt 500A/50mV](https://www.victronenergy.com/battery-monitors/smart-battery-shunt) | 1 | Industry-standard battery shunt monitor. Measures battery voltage, current, SoC, and optional temperature via VE.Direct UART. The 500A variant covers the vast majority of off-grid installations from small cabins to telecom sites; a 1000A variant is available for high-current systems. Includes a VE.Direct cable. | | [Victron SmartSolar MPPT 75/15](https://www.victronenergy.com/solar-charge-controllers/smartsolar-mppt-75-10-75-15-100-15-100-20) | 1 *(or existing)* | Solar charge controller. Exposes panel voltage, instantaneous panel power, daily yield, and charge state over VE.Direct. Select the MPPT SKU that matches your array size; the VE.Direct protocol and field names are the same across the SmartSolar family. Includes a VE.Direct cable. | @@ -182,11 +182,11 @@ The Notecarrier CX routes the NOTE-MBGLW's `MAIN` u.FL port to a u.FL pigtail le The NOTE-MBGLW includes a GNSS receiver, but GNSS is not used in this project — the design operates in cellular mode only and no GPS/GNSS antenna is required. If site geolocation is needed in a future enhancement, the Notecard's onboard GNSS can be enabled without firmware changes. **Satellite antenna feedthrough (NOTE-NBGLWX only):** -- The Notecard for Skylo has two u.FL connectors: `MAIN` for the Skylo-certified satellite/LTE antenna (included in the kit) and `GPS` for the passive GNSS antenna (Quectel YCA001BA). Both antennas must be mounted **outside the enclosure** with an unobstructed view of the sky — satellite signals cannot penetrate a metal enclosure wall. +- Notecard for Skylo has two u.FL connectors: `MAIN` for the Skylo-certified satellite/LTE antenna (included in the kit) and `GPS` for the passive GNSS antenna (Quectel YCA001BA). Both antennas must be mounted **outside the enclosure** with an unobstructed view of the sky — satellite signals cannot penetrate a metal enclosure wall. - **MAIN antenna:** Connect the included Skylo antenna to the `MAIN` u.FL port via the SparkFun WRL-09145 (or equivalent RG316/RG178) pigtail. The pigtail's SMA female end connects to an IP67-rated SMA bulkhead connector threaded through the enclosure wall; the antenna mounts on the bulkhead's external SMA port. The bulkhead provides its own weather seal. - **GPS antenna (Quectel YCA001BA):** Plug the antenna's u.FL connector into the `GPS` u.FL port on the Notecard. Route the flexible cable lead through an M16 IP67 cable gland in the enclosure wall and mount the flexible patch flat on the exterior of the enclosure. - Maintain gentle cable curves throughout; avoid sharp bends that kink the coax feed lines. Keep runs as short as practical to minimise insertion loss, especially on the satellite band. -- Use only the Skylo-certified antenna supplied with the Notecard for Skylo kit on the MAIN port. Substituting a different antenna voids Skylo network certification and may result in the device being blocked from the network. See the [Blues antenna guide](https://dev.blues.io/datasheets/application-notes/antenna-guide/) for full certification and placement requirements. +- Use only the Skylo-certified antenna supplied with Notecard for Skylo kit on the MAIN port. Substituting a different antenna voids Skylo network certification and may result in the device being blocked from the network. See the [Blues antenna guide](https://dev.blues.io/datasheets/application-notes/antenna-guide/) for full certification and placement requirements. @@ -491,7 +491,7 @@ Mojo is a **bench bring-up tool**, not a production sensor. Once a firmware revi A Notecarrier CX and Notecard pair with two Victron VE.Direct devices to turn an opaque off-grid power system into a continuously-monitored, remotely-observable asset. The device wakes every 15 minutes, reads battery SoC, current, temperature, and solar harvest in a few seconds, and goes back to sleep — accumulating a window of averages that flush to Notehub every four hours. A site going dark gets a warning Note via cellular before the battery drops too far to communicate, giving the operations team a fighting chance to dispatch before the outage. None of this requires any site networking, IT coordination, or infrastructure that wasn't already there — just a 5V supply and two short VE.Direct cables. -For the truly remote sites where terrestrial cellular coverage is marginal or absent, the [Notecard for Skylo (NOTE-NBGLWX)](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) slots into the same M.2 carrier with no firmware changes — the same API the Notecard Cell+WiFi uses. Deploying the Skylo variant requires mounting both antennas outdoors with an unobstructed sky view, as documented in §3 and §4. The pattern scales from a single off-grid cabin to a fleet of hundreds of remote towers, with per-fleet threshold management and per-device overrides handled entirely from Notehub. +For the truly remote sites where terrestrial cellular coverage is marginal or absent, [Notecard for Skylo (NOTE-NBGLWX)](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) slots into the same M.2 carrier with no firmware changes — the same API the Notecard Cell+WiFi uses. Deploying the Skylo variant requires mounting both antennas outdoors with an unobstructed sky view, as documented in §3 and §4. The pattern scales from a single off-grid cabin to a fleet of hundreds of remote towers, with per-fleet threshold management and per-device overrides handled entirely from Notehub. ## 10. Troubleshooting and Common Issues diff --git a/88-reefer-trailer-cold-chain-door-event-monitor/README.md b/88-reefer-trailer-cold-chain-door-event-monitor/README.md index 61c0a885..4ec88d1f 100644 --- a/88-reefer-trailer-cold-chain-door-event-monitor/README.md +++ b/88-reefer-trailer-cold-chain-door-event-monitor/README.md @@ -30,7 +30,7 @@ Both failure modes have a common root: nobody can see inside the trailer while i -The [Notecard for Skylo (NOTE-NBGLWX)](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link). See the [datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) — addresses this in a single 30 × 42 mm module: LTE-M, NB-IoT, and GPRS for terrestrial cellular, Skylo **NTN** (non-terrestrial network) satellite as an automatic fallback, and WiFi via an onboard antenna. The firmware enables this multi-RAT behavior with a single one-time [`card.transport`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-transport) request (`method:"wifi-cell-ntn"`); from then on the Notecard manages network selection itself, and the application never needs to know which radio carried a given message. An alert triggered by a door opening at a rural rest stop will use cellular if a tower is within range and satellite if it isn't — with no radio-selection logic required in the application. For a mobile asset that can't self-select its coverage environment, this multi-RAT (radio access technology) automatic failover is the whole value proposition. +[Notecard for Skylo (NOTE-NBGLWX)](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link). See the [datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) — addresses this in a single 30 × 42 mm module: LTE-M, NB-IoT, and GPRS for terrestrial cellular, Skylo **NTN** (non-terrestrial network) satellite as an automatic fallback, and WiFi via an onboard antenna. The firmware enables this multi-RAT behavior with a single one-time [`card.transport`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-transport) request (`method:"wifi-cell-ntn"`); from then on the Notecard manages network selection itself, and the application never needs to know which radio carried a given message. An alert triggered by a door opening at a rural rest stop will use cellular if a tower is within range and satellite if it isn't — with no radio-selection logic required in the application. For a mobile asset that can't self-select its coverage environment, this multi-RAT (radio access technology) automatic failover is the whole value proposition. **Deployment scenario.** The electronics mount in a weatherproof NEMA 4X enclosure strapped or screwed to the interior trailer wall or exterior chassis rail, powered from the trailer's 12 V DC supply (or the nose-box connector if available). Two DS18B20 stainless steel probes thread through grommets into the cargo compartment — one near the front (forward air) and one near the rear return-air panel, and the reed switch mounts on the door frame with its matching magnet on the door itself. @@ -41,7 +41,7 @@ The [Notecard for Skylo (NOTE-NBGLWX)](https://shop.blues.com/products/notecard- **Device-side responsibilities.** Down the road at 65 mph, the Cygnet STM32 host on the [Notecarrier CX](https://dev.blues.io/datasheets/notecarrier-datasheet/notecarrier-cx-v1-3/) is off — power-gated by [`card.attn`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-attn). Every 60 seconds it wakes long enough to read both DS18B20 probes and the door pin, evaluate the threshold rules locally, and hand any resulting Notes to the Notecard over I²C. Because the host loses power between samples, the accumulating state — running temperature averages, the door open/close timestamp, the alert deduplication epoch — is serialized into Notecard flash by `NotePayloadSaveAndSleep` and restored on the next wake via `NotePayloadRetrieveAfterSleep`. Nothing is lost across sleep cycles, and the trailer's 12 V supply sees only a few seconds of MCU draw per minute. -**Notecard responsibilities.** The Notecard for Skylo handles every part of "getting the message off the trailer." It queues [Notes](https://dev.blues.io/api-reference/glossary/#note) locally, runs the WiFi → cellular → NTN fallback policy that the firmware sets up once at first boot via [`card.transport`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-transport) (`method:"wifi-cell-ntn"`), opens a session on the configured [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence (default 60 minutes), and flushes pending alerts immediately when the host calls [`hub.sync`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-sync) over whatever network happens to be available. It pulls [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) down from Notehub so dispatch can retune thresholds without reflashing. And because the Notecard for Skylo has an integrated GNSS radio, the firmware turns on [`card.location.mode`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-location-mode) `periodic` (600-second interval, motion-gated per the API docs) so every `trailer_alert.qo` carries the last known latitude and longitude — answering "where was this trailer when the alert fired?" without any extra hardware. +**Notecard responsibilities.** Notecard for Skylo handles every part of "getting the message off the trailer." It queues [Notes](https://dev.blues.io/api-reference/glossary/#note) locally, runs the WiFi → cellular → NTN fallback policy that the firmware sets up once at first boot via [`card.transport`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-transport) (`method:"wifi-cell-ntn"`), opens a session on the configured [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence (default 60 minutes), and flushes pending alerts immediately when the host calls [`hub.sync`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-sync) over whatever network happens to be available. It pulls [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) down from Notehub so dispatch can retune thresholds without reflashing. And because Notecard for Skylo has an integrated GNSS radio, the firmware turns on [`card.location.mode`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-location-mode) `periodic` (600-second interval, motion-gated per the API docs) so every `trailer_alert.qo` carries the last known latitude and longitude — answering "where was this trailer when the alert fired?" without any extra hardware. **Notehub responsibilities.** Whatever the Notecard sends — cellular, WiFi, or satellite — lands in [Notehub](https://notehub.io), which ingests, stores, and applies project [routes](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub). Alerts, per-sample logs, and hourly summaries live in separate [Notefiles](https://dev.blues.io/api-reference/glossary/#notefile), so dispatch routes can take immediate alerts to the TMS or on-call channel while the per-sample and summary streams flow into a long-term cold-chain compliance store. The `trailer_alert.qo` payload format is compact+port-encoded so it works identically over cellular and NTN, and Notehub session metadata records which transport carried each event. [Smart Fleets](https://dev.blues.io/notehub/notehub-walkthrough/#using-smart-fleet-rules) group trailers by lane, customer, or cargo type and push fleet-specific threshold overrides without touching individual device configs. @@ -97,7 +97,7 @@ All Blues hardware ships with an active SIM; no separate SIM purchase or activat ![Wiring and Assembly](diagrams/02-wiring-assembly.svg) -All host I/O lands on the [Notecarrier CX](https://dev.blues.io/datasheets/notecarrier-datasheet/notecarrier-cx-v1-3/) dual 16-pin header. The Notecard for Skylo seats into the M.2 slot; cellular, satellite, and GNSS antennas connect via u.FL leads to externally-mounted antennas. If bench-validating with the Mojo, it sits inline between the 5 V supply and the Notecarrier's `+VBAT` pad, reporting cumulative mAh to the Notecard over Qwiic (I²C). +All host I/O lands on the [Notecarrier CX](https://dev.blues.io/datasheets/notecarrier-datasheet/notecarrier-cx-v1-3/) dual 16-pin header. Notecard for Skylo seats into the M.2 slot; cellular, satellite, and GNSS antennas connect via u.FL leads to externally-mounted antennas. If bench-validating with the Mojo, it sits inline between the 5 V supply and the Notecarrier's `+VBAT` pad, reporting cumulative mAh to the Notecard over Qwiic (I²C). **Power (production, no Mojo):** - Pololu D24V22F5 `VIN` → inline fuse holder (3 A ATO blade fuse fitted; see BOM) → trailer 12 V DC positive. Mount the fuse holder on the positive lead as close to the 12 V source as practical. See the field installation caution below. @@ -450,7 +450,7 @@ Every 60 seconds the firmware wakes, reads both temperature probes and the door - **Threshold tuning:** lower `temp_max_c` to `0.0` in the Fleet's environment variables; the next inbound sync pulls the new value, and the next sample cycle with any probe above 0 °C fires the alert. - **Location:** confirm the GNSS antenna has a clear sky view outdoors. After at least one full `card.location.mode` fix interval (≤ 10 minutes on a moving or recently-moved unit), trigger a door or temperature alert and verify `lat` and `lon` are non-zero in the resulting `trailer_alert.qo` Note body in Notehub. A `(0.0, 0.0)` pair means no fix has been acquired yet — allow more time or confirm the GPS antenna cable and connector are seated. -**Power validation with Mojo.** The Notecard for Skylo's published figures: ~8–18 µA idle (radio off between syncs); ~250 mA average with peaks approaching 2 A during cellular transmit; satellite sessions are similar in current envelope but longer in duration. +**Power validation with Mojo.** Notecard for Skylo's published figures: ~8–18 µA idle (radio off between syncs); ~250 mA average with peaks approaching 2 A during cellular transmit; satellite sessions are similar in current envelope but longer in duration. Place the [Mojo](https://dev.blues.io/datasheets/mojo-datasheet/) inline between the 5 V supply and the Notecarrier CX `+VBAT` pad. The expected trace in steady state: @@ -522,6 +522,6 @@ The design hits the two failure modes that account for most refrigerated cargo l ## 12. Summary -The fleet dispatcher now has the two signals that matter most: a geo-stamped alert within roughly a minute when a door opens at an unexpected location, and a temperature excursion caught while the load can still be re-routed. The Notecard for Skylo picks cellular, WiFi, or NTN satellite at every moment of a haul without any firmware logic — keeping the bundled satellite data budget intact by discarding the per-sample and hourly summary Notefiles at sync time when NTN is the active transport, while alerts ride the satellite link regardless. For shippers under FSMA Sanitary Transportation rules or HACCP records, and for pharmaceutical cold-chain operators on GDP terms, those same per-sample logs and hourly summaries become the independent condition record that audits and freight claims demand. +The fleet dispatcher now has the two signals that matter most: a geo-stamped alert within roughly a minute when a door opens at an unexpected location, and a temperature excursion caught while the load can still be re-routed. Notecard for Skylo picks cellular, WiFi, or NTN satellite at every moment of a haul without any firmware logic — keeping the bundled satellite data budget intact by discarding the per-sample and hourly summary Notefiles at sync time when NTN is the active transport, while alerts ride the satellite link regardless. For shippers under FSMA Sanitary Transportation rules or HACCP records, and for pharmaceutical cold-chain operators on GDP terms, those same per-sample logs and hourly summaries become the independent condition record that audits and freight claims demand. The same skeleton carries to pharma cold chain, cross-border intermodal containers, frozen-food long-haul, or any mobile insulated enclosure where a temperature log and a door audit trail have regulatory or financial weight. diff --git a/89-pallet-attached-cold-chain-logger/README.md b/89-pallet-attached-cold-chain-logger/README.md index f7737556..bb0ec105 100644 --- a/89-pallet-attached-cold-chain-logger/README.md +++ b/89-pallet-attached-cold-chain-logger/README.md @@ -25,7 +25,7 @@ This project builds on the dedicated temperature logger concept: a pallet-attach > **Note on reefer standards:** This project does **not** implement J2497, J1939, or proprietary reefer protocols (Carrier DataLink, Thermo King DSR). It is a shipper-owned, independent cold-chain monitor that operates alongside or in parallel with carrier telematics, not as a reefer integration. The design is intentionally isolated: the logger measures cargo-bay conditions, not reefer controller state, and routes data to shipper systems (TMS, quality, analytics), not carrier networks. -This project uses the [Notecard for Skylo (NOTE-NBGLWX)](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) ([datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/)), an all-in-one module that packs cellular (LTE-M, 2G/3G), WiFi (2.4 GHz), and satellite ([Skylo](https://www.skylo.tech/resources/geographical-coverage) NTN, non-terrestrial network) into a single M.2 form-factor Notecard. The device selects the best available radio automatically: WiFi in a connected DC where credentials have been provisioned on the Notecard (see [§6 WiFi provisioning](#6-notehub-setup)), cellular over road and rail, satellite where neither is available and the antenna has sky exposure. Queued Notes in Notecard flash carry their original timestamps and are transmitted intact when any radio comes back — coverage gaps produce store-and-forward gaps, not data loss. No SIM provisioning, no per-country certification cycle (Blues ships pre-certified globally), and no site network credentials to manage at every waypoint. +This project uses [Notecard for Skylo (NOTE-NBGLWX)](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) ([datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/)), an all-in-one module that packs cellular (LTE-M, 2G/3G), WiFi (2.4 GHz), and satellite ([Skylo](https://www.skylo.tech/resources/geographical-coverage) NTN, non-terrestrial network) into a single M.2 form-factor Notecard. The device selects the best available radio automatically: WiFi in a connected DC where credentials have been provisioned on the Notecard (see [§6 WiFi provisioning](#6-notehub-setup)), cellular over road and rail, satellite where neither is available and the antenna has sky exposure. Queued Notes in Notecard flash carry their original timestamps and are transmitted intact when any radio comes back — coverage gaps produce store-and-forward gaps, not data loss. No SIM provisioning, no per-country certification cycle (Blues ships pre-certified globally), and no site network credentials to manage at every waypoint. **Deployment scenario.** The logger is housed in an IP67 enclosure attached to the pallet exterior. Three sealed openings: a PTFE breathable vent on the pallet-facing side wall so the SHT41 can sample the surrounding cargo-bay air; a separate 3/8-18 NPT threaded opening on the same pallet-facing wall so the PT100 probe's 150 mm sensing tip extends into the cargo airstream; and a clear polycarbonate lens window on the cargo-bay-facing wall so the inward-facing VEML7700 can detect when the cargo compartment is opened and light enters the interior. The Skylo-certified multi-band antenna (included with the NOTE-NBGLWX) is mounted inside the ABS enclosure — ABS is transparent to LTE-M and L-band NTN frequencies — with the antenna face pointing upward through the lid. @@ -47,7 +47,7 @@ When the state changes, a `cargo_state.qo` note is dispatched immediately via `s **Tamper-evident local log.** Every sample cycle appends one compact-templated entry to the `cargo_log.qo` Notefile. Each entry includes a monotonic sequence number (`seq`, incremented before every note.add), a rolling integrity hash (`chain_crc`) computed over the previous hash, the sequence number, boot segment, and all sensor readings, and a `boot_seg` counter that increments on every cold boot. The boot-segment counter is persisted both in the Notecard sleep payload (planned-sleep resilience) and in a Notecard-local notefile `chain_boot.dbx` (power-loss resilience). Log entries are queued for the regular outbound window rather than synced immediately, batching with outbound sessions without consuming an extra satellite session per sample. The `_time` field is always included in each entry: the real epoch when the Notecard has obtained valid time from Notehub, or `0` as a documented pre-sync sentinel. Downstream consumers should treat `_time == 0` as pre-sync and use Notehub's event receive-time as the best available approximation for those records. A `motion_valid` flag (`1` = card.motion returned valid data; `0` = card.motion was unavailable) is also included in every entry so downstream consumers can distinguish "no motion occurred" (`motion = 0`, `motion_valid = 1`) from "motion data unavailable" (`motion = 0`, `motion_valid = 0`) — preserving the compliance semantics of the per-sample audit log even when the accelerometer interface is temporarily unreachable. A downstream verifier replays the chain **within each `boot_seg` group** from seq=1 (seed=0); a gap in `seq` within a segment indicates a dropped transmission; a `chain_crc` mismatch indicates a modified or inserted record; and a new `boot_seg` value marks the start of a new, independent chain segment caused by a device cold boot. -**Notecard responsibilities.** The Notecard for Skylo holds outbound [Notes](https://dev.blues.io/api-reference/glossary/#note) in its on-device flash queue and decides for itself which radio to use — cellular, WiFi, or NTN satellite — depending on what's reachable from wherever the pallet currently sits. It flushes the queue on the configured [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) outbound cadence (default 60 minutes), and any Note marked `sync:true` jumps the queue and opens a session immediately on whatever radio is available. Coming the other way, the Notecard distributes [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) from Notehub, so shipper operations can change threshold values, sample cadence, or summary cadence mid-route without reflashing firmware. +**Notecard responsibilities.** Notecard for Skylo holds outbound [Notes](https://dev.blues.io/api-reference/glossary/#note) in its on-device flash queue and decides for itself which radio to use — cellular, WiFi, or NTN satellite — depending on what's reachable from wherever the pallet currently sits. It flushes the queue on the configured [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) outbound cadence (default 60 minutes), and any Note marked `sync:true` jumps the queue and opens a session immediately on whatever radio is available. Coming the other way, the Notecard distributes [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) from Notehub, so shipper operations can change threshold values, sample cadence, or summary cadence mid-route without reflashing firmware. **Notehub responsibilities.** Whatever the Notecard sends — over cellular, WiFi, or NTN — lands in [Notehub](https://notehub.io), where it's stored with the original on-pallet timestamp and run through project [routes](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub). The four Notefiles (`cargo_alert.qo`, `cargo_state.qo`, `cargo_data.qo`, `cargo_log.qo`) stay separate so each stream can go to the system that wants it: alerts and state changes to the TMS or on-call channel, summaries to the cold-chain analytics platform, and the tamper-evident log entries to a compliance archive. @@ -107,7 +107,7 @@ All Blues hardware ships with an active SIM including 500 MB of data and 10 year ![Wiring and assembly](diagrams/02-wiring-assembly.svg) -All host I/O connects to the Notecarrier CX's dual 16-pin header. The Notecard for Skylo seats into the carrier's M.2 slot; the included Skylo-certified antenna attaches to the Notecard's `MAIN` u.FL port and remains inside the ABS enclosure. +All host I/O connects to the Notecarrier CX's dual 16-pin header. Notecard for Skylo seats into the carrier's M.2 slot; the included Skylo-certified antenna attaches to the Notecard's `MAIN` u.FL port and remains inside the ABS enclosure. **MAX31865 (SPI, temperature).** Connect via the Cygnet's hardware SPI bus: @@ -146,7 +146,7 @@ Drill an M12 through-hole in the pallet-facing side panel for the PTFE vent plug **Antenna placement (internal).** Attach the included Skylo-certified antenna to the Notecard's `MAIN` u.FL port. Mount the antenna inside the ABS enclosure with its face pointing upward toward the lid to maximize sky-facing aperture for Skylo NTN. **Do not substitute a different antenna on the MAIN port.** The `GPS` u.FL port is not connected in this project. -> **No external accelerometer required.** The Notecard for Skylo includes a built-in 3-axis accelerometer. Motion tracking is enabled via `card.motion.mode` with `start:true` and `sensitivity:2`; the firmware does not configure sample rate or G-range — those are managed internally by the Notecard. The `card.motion` stream provides per-bucket motion counts for shock detection and the `orientation` field for tilt detection. +> **No external accelerometer required.** Notecard for Skylo includes a built-in 3-axis accelerometer. Motion tracking is enabled via `card.motion.mode` with `start:true` and `sensitivity:2`; the firmware does not configure sample rate or G-range — those are managed internally by the Notecard. The `card.motion` stream provides per-bucket motion counts for shock detection and the `orientation` field for tilt detection. ## 6. Notehub Setup @@ -157,7 +157,7 @@ Drill an M12 through-hole in the pallet-facing side panel for the PTFE vent plug 3. **Claim the Notecard.** Power the assembled unit. The Notecard associates itself with your Notehub project on the **first successful radio session over any available RAT** — cellular, WiFi, or Skylo NTN. The device appears in your project's **Devices** tab after that first session completes. Over cellular or WiFi in good coverage, this typically happens within a minute or two of power-on. Over Skylo NTN, first contact requires a clear, unobstructed view toward the equatorial sky; session acquisition can take several minutes to establish, and is not possible inside enclosed metal structures or below grade. The Notecard MUST sync over cellular or WiFi once prior to NTN. -> **WiFi provisioning (optional).** The Notecard for Skylo treats WiFi as its highest-priority radio when credentials are present, but credentials are **not** provisioned automatically. To provision WiFi, send a [`card.wifi`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-wifi) request to the Notecard via the in-browser Notecard terminal or the [Notecard CLI](https://dev.blues.io/tools-and-sdks/notecard-cli/): +> **WiFi provisioning (optional).** Notecard for Skylo treats WiFi as its highest-priority radio when credentials are present, but credentials are **not** provisioned automatically. To provision WiFi, send a [`card.wifi`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-wifi) request to the Notecard via the in-browser Notecard terminal or the [Notecard CLI](https://dev.blues.io/tools-and-sdks/notecard-cli/): > ```json > { "req": "card.wifi", "ssid": "your-network-ssid", "password": "your-network-password" } > ``` @@ -524,7 +524,7 @@ The logger commits to a specific scope: independent, pallet-level evidence with - **PT100 calibration document must be sourced at procurement.** The MAX31865 hardware is capable of NIST-traceable accuracy, but traceability is only realized if the PT100 probe is accompanied by a calibration certificate from an accredited laboratory. The specified Omega PR-21C-3-100-A-1/8-0600-M12-2 must be ordered with the **CAL-3** NIST-traceable calibration option (performed per ISO 10012-1 / ANSI/NCSL Z540-1). Verify calibration documentation at the time of procurement — a probe shipped without it does not satisfy the traceability requirement regardless of accuracy class. -- **No GPS location.** The Notecard for Skylo includes GNSS for location, but this firmware does not request GPS fixes. Adding `card.location.mode` and including position in the summary and state-change Notes is a natural extension for multi-modal shipments where knowing *where* a temperature excursion or handling event occurred matters as much as *when*. +- **No GPS location.** Notecard for Skylo includes GNSS for location, but this firmware does not request GPS fixes. Adding `card.location.mode` and including position in the summary and state-change Notes is a natural extension for multi-modal shipments where knowing *where* a temperature excursion or handling event occurred matters as much as *when*. - **Lithium battery transport compliance.** The 3.7 V / 2 000 mAh Li-Po cell (7.4 Wh) is subject to transport safety regulations on every mode of carriage — UN 38.3 testing, IATA Section II (Packing Instruction 966/967) for air, IMDG Code Class 9 for ocean. Confirm compliance and sourcing of UN 38.3 documentation with your freight forwarder before the first shipment. For volume deployment, source cells from a manufacturer that supplies UN 38.3 test documentation on request. @@ -539,4 +539,4 @@ The logger commits to a specific scope: independent, pallet-level evidence with ## 12. Summary -The pharma quality manager (or food shipper's compliance lead) finally has the answer to "what actually happened to this pallet?" — independent of the carrier, tied to the BOL, and accurate enough to drive a real acceptance or rejection decision. A NIST-traceable PT100 probe gives ±0.15 °C readings; a tamper-evident chain in `cargo_log.qo` lets a downstream verifier replay every five-minute sample within each boot segment and confirm that nothing was inserted, deleted, or modified in transit. The Notecard for Skylo picks cellular, WiFi, or NTN satellite at every leg of the journey, queues through coverage gaps, and ships the original on-pallet timestamps when the radio comes back. Threshold values, sample cadence, summary cadence, and state-model parameters all retune from Notehub without a reflash — so the same logger generalizes from biologics on an ocean leg to fresh produce on a cross-country truck. +The pharma quality manager (or food shipper's compliance lead) finally has the answer to "what actually happened to this pallet?" — independent of the carrier, tied to the BOL, and accurate enough to drive a real acceptance or rejection decision. A NIST-traceable PT100 probe gives ±0.15 °C readings; a tamper-evident chain in `cargo_log.qo` lets a downstream verifier replay every five-minute sample within each boot segment and confirm that nothing was inserted, deleted, or modified in transit. Notecard for Skylo picks cellular, WiFi, or NTN satellite at every leg of the journey, queues through coverage gaps, and ships the original on-pallet timestamps when the radio comes back. Threshold values, sample cadence, summary cadence, and state-model parameters all retune from Notehub without a reflash — so the same logger generalizes from biologics on an ocean leg to fresh produce on a cross-country truck. From 0d1298b27304520b70507256dd6cb974d17136f4 Mon Sep 17 00:00:00 2001 From: Rob Lauer Date: Tue, 2 Jun 2026 14:10:13 -0500 Subject: [PATCH 5/6] improve formatting of the "limitations" sections --- .../README.md | 45 ++++++++----- .../README.md | 52 +++++++++------ .../README.md | 44 +++++++------ .../README.md | 40 ++++++----- .../README.md | 63 +++++++++++------- .../README.md | 50 +++++++++----- .../README.md | 48 +++++++++----- .../README.md | 52 +++++++++------ .../README.md | 52 ++++++++++----- .../README.md | 57 ++++++++++------ .../README.md | 53 ++++++++++----- .../README.md | 47 +++++++------ .../README.md | 38 ++++++----- .../README.md | 41 +++++++----- .../README.md | 39 ++++++----- .../README.md | 57 ++++++++++------ .../README.md | 66 ++++++++++++------- .../README.md | 38 ++++++----- .../README.md | 26 ++++++-- .../README.md | 48 ++++++++------ .../README.md | 48 +++++++++----- .../README.md | 57 ++++++++++------ .../README.md | 61 +++++++++++------ 87-post-discharge-vitals-relay-hub/README.md | 53 ++++++++++----- .../README.md | 51 +++++++++----- .../README.md | 36 ++++++---- 26 files changed, 792 insertions(+), 470 deletions(-) diff --git a/58-commercial-grease-interceptor-level-monitor/README.md b/58-commercial-grease-interceptor-level-monitor/README.md index 7417d670..457b89f5 100644 --- a/58-commercial-grease-interceptor-level-monitor/README.md +++ b/58-commercial-grease-interceptor-level-monitor/README.md @@ -356,36 +356,45 @@ The dominant daily energy consumer is likely the always-on sensor (~8 mA continu This reference design is scoped tightly to the indoor-utility-room HGI install and to geometries where the liquid surface rises with FOG accumulation. The simplifications below are deliberate — they keep the build buildable without a hazardous-location electrical review or a custom dual-sensor probe — and each has a clear extension path for a production rollout. -**Simplified for the POC:** +### Simplified for the POC -- **Scoped to HGI and batch-collection geometries, not validated for conventional constant-level interceptors.** This reference design is scoped to hydromechanical and batch-collection interceptors without a fixed outlet weir — geometries where the top liquid surface rises with FOG and wastewater accumulation, making the fill percentage a meaningful pump-out indicator. On a **conventional constant-level gravity interceptor** (outlet weir holds the liquid surface at a fixed height regardless of FOG thickness), the top surface stays nearly constant as grease accumulates, so `fill_pct` will not track FOG buildup and the 75% alert threshold will not map to regulatory pump-out criteria. **Do not deploy this reference design on a conventional constant-level interceptor for compliance purposes without independent empirical validation** that surface elevation correlates with FOG accumulation in that specific unit. For conventional interceptors, direct FOG-layer measurement (e.g., differential float pair, bottom conductivity probe, or matched top-and-bottom ultrasonic sensors) is required. +The simplifications below are deliberate scope choices — each keeps the build buildable without a hazardous-location review or a custom dual-sensor probe, and each carries a clear extension path for a production rollout. -- **Not rated for classified hazardous locations.** The A02YYUW probe, all associated wiring, and the electronics in this build are standard, non-intrinsically-safe (non-IS) components with no NEC Article 505/506 Class/Zone, ATEX, or IECEx certification. Whether a given interceptor installation constitutes a classified hazardous location is a site-specific determination that must be made by a qualified licensed electrician or AHJ before deployment — do not assume an installation is unclassified without a documented review. **This reference design is suitable only for non-classified installations following a completed code and site-safety review.** Classified hazardous-location installations require IS-rated sensors, certified IS barriers, explosion-proof (XP) or purged-and-pressurized (P) enclosures, and installation by personnel qualified for hazardous-area work. +**Scoped to HGI and batch-collection geometries, not validated for conventional constant-level interceptors.** This reference design is scoped to hydromechanical and batch-collection interceptors without a fixed outlet weir — geometries where the top liquid surface rises with FOG and wastewater accumulation, making the fill percentage a meaningful pump-out indicator. On a **conventional constant-level gravity interceptor** (outlet weir holds the liquid surface at a fixed height regardless of FOG thickness), the top surface stays nearly constant as grease accumulates, so `fill_pct` will not track FOG buildup and the 75% alert threshold will not map to regulatory pump-out criteria. **Do not deploy this reference design on a conventional constant-level interceptor for compliance purposes without independent empirical validation** that surface elevation correlates with FOG accumulation in that specific unit. For conventional interceptors, direct FOG-layer measurement (e.g., differential float pair, bottom conductivity probe, or matched top-and-bottom ultrasonic sensors) is required. -- **Indoor utility-room power architecture only.** The documented hardware build assumes a 120 VAC wall outlet within ~1.5 m of the interceptor access cover, powering a UL-listed 5 V DC wall adapter that supplies the enclosure. A large fraction of commercial HGI installations are in rear yards, buried below a parking lot, or set in a floor vault where no convenient outlet exists. Those sites require a solar panel plus a lithium battery pack or a long conduit power run — neither is covered by this reference design. See the battery backup Note in Production Next Steps below. +**Not rated for classified hazardous locations.** The A02YYUW probe, all associated wiring, and the electronics in this build are standard, non-intrinsically-safe (non-IS) components with no NEC Article 505/506 Class/Zone, ATEX, or IECEx certification. Whether a given interceptor installation constitutes a classified hazardous location is a site-specific determination that must be made by a qualified licensed electrician or AHJ before deployment — **do not assume an installation is unclassified without a documented review.** This reference design is suitable only for non-classified installations following a completed code and site-safety review. Classified hazardous-location installations require IS-rated sensors, certified IS barriers, explosion-proof (XP) or purged-and-pressurized (P) enclosures, and installation by personnel qualified for hazardous-area work. -- **Single-layer measurement only.** A grease interceptor has two distinct layers: a floating FOG layer at the top and a settled sludge layer at the bottom. Regulatory compliance in many jurisdictions is based on the *combined* FOG-plus-sludge depth relative to the overall liquid depth, not just the FOG surface distance. The firmware measures one distance (sensor to FOG surface) and derives a simple fill percentage from it. A production deployment targeting jurisdictions with explicit combined-depth regulations would need either a second sensor at the bottom or a different measurement method to account for sludge accumulation. +**Indoor utility-room power architecture only.** The documented hardware build assumes a 120 VAC wall outlet within ~1.5 m of the interceptor access cover, powering a UL-listed 5 V DC wall adapter that supplies the enclosure. A large fraction of commercial HGI installations are in rear yards, buried below a parking lot, or set in a floor vault where no convenient outlet exists. Those sites require a solar panel plus a lithium battery pack or a long conduit power run — neither is covered by this reference design. See the battery backup item in Production Next Steps below. -- **Fixed interceptor depth per device.** `interceptor_depth_mm` is a single scalar representing the sensor-to-reference-surface distance when the interceptor is at 0% fill. This must be measured and set manually per installation; there is no auto-calibration. If the probe mounting depth shifts (e.g., if someone repositions the cover), the calibration drifts silently. +**Single-layer measurement only.** A grease interceptor has two distinct layers: a floating FOG layer at the top and a settled sludge layer at the bottom. Regulatory compliance in many jurisdictions is based on the *combined* FOG-plus-sludge depth relative to the overall liquid depth, not just the FOG surface distance. The firmware measures one distance (sensor to FOG surface) and derives a simple fill percentage from it. A production deployment targeting jurisdictions with explicit combined-depth regulations would need either a second sensor at the bottom or a different measurement method to account for sludge accumulation. -- **No FOG layer thickness calculation.** The sensor reports the distance to the *surface* of the FOG layer, not its thickness. Thickness (a more directly actionable metric) would require knowing the bottom of the FOG layer, which is the top of the wastewater zone below — measuring that would require a second sensor or a conductivity probe. +**Fixed interceptor depth per device.** `interceptor_depth_mm` is a single scalar representing the sensor-to-reference-surface distance when the interceptor is at 0% fill. This must be measured and set manually per installation; there is no auto-calibration. If the probe mounting depth shifts (e.g., if someone repositions the cover), the calibration drifts silently. -- **Environmental fouling not detected.** The A02YYUW probe is IP67 and tolerates condensation and splash, but a heavy grease coating on the transducer face will attenuate the ultrasonic signal and produce erroneous long readings (sensor thinks the surface is farther away than it is, i.e., fill level appears lower than actual). The firmware has no mechanism to detect or correct for probe fouling. A valid-samples count well below the expected 96/day can be a symptom, but is not a reliable diagnostic. +**No FOG layer thickness calculation.** The sensor reports the distance to the *surface* of the FOG layer, not its thickness. Thickness (a more directly actionable metric) would require knowing the bottom of the FOG layer, which is the top of the wastewater zone below — measuring that would require a second sensor or a conductivity probe. -- **No temperature compensation beyond the sensor.** The A02YYUW has an internal temperature-compensation circuit for the speed of sound. The firmware does not read or log temperature separately — temperature is not transmitted to Notehub. +**Environmental fouling not detected.** The A02YYUW probe is IP67 and tolerates condensation and splash, but a heavy grease coating on the transducer face will attenuate the ultrasonic signal and produce erroneous long readings (sensor thinks the surface is farther away than it is, i.e., fill level appears lower than actual). The firmware has no mechanism to detect or correct for probe fouling. A valid-samples count well below the expected 96/day can be a symptom, but is not a reliable diagnostic. -- **Alert cooldown is per-device, not per-channel.** The 1-hour alert cooldown is enforced in firmware. If the downstream routing endpoint needs its own deduplication or escalation logic (e.g., "send a second alert if not acknowledged within 4 hours"), that must be implemented in the Notehub route or the receiving system. +**No temperature compensation beyond the sensor.** The A02YYUW has an internal temperature-compensation circuit for the speed of sound. The firmware does not read or log temperature separately — temperature is not transmitted to Notehub. -- **Mojo is bench-validation equipment here.** The firmware does not read the Mojo's LTC2959 coulomb counter over I²C. Adding a `mojo_mah` field to the daily summary is a one-function extension if fleet-level energy telemetry is useful in production. +**Alert cooldown is per-device, not per-channel.** The 1-hour alert cooldown is enforced in firmware. If the downstream routing endpoint needs its own deduplication or escalation logic (e.g., "send a second alert if not acknowledged within 4 hours"), that must be implemented in the Notehub route or the receiving system. -**Production next steps:** +**Mojo is bench-validation equipment here.** The firmware does not read the Mojo's LTC2959 coulomb counter over I²C. Adding a `mojo_mah` field to the daily summary is a one-function extension if fleet-level energy telemetry is useful in production. -- Per-installation commissioning flow: expose a `calibrate` environment variable that, when set, records the current sensor reading as the 0%-fill reference distance and stores it back as `interceptor_depth_mm`. This replaces the manual tape-measure step with a firmware-driven calibration gesture. -- Dual-layer measurement: add a conductivity or float probe near the bottom of the interceptor to detect sludge accumulation and report combined FOG+sludge fill depth. -- Probe-fouling detection: add a signal-quality metric derived from the standard deviation of the 5-reading median filter. A high std-dev or elevated rejection rate is a leading indicator of fouling or multipath before the readings go completely invalid. -- Over-the-air firmware updates via [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/), so threshold recipes and protocol updates can be pushed to the entire fleet without a site visit. -- Battery backup via Blues Scoop or a small sealed lead-acid for interceptors in locations prone to power outages, to ensure an overflow alert fires even during a kitchen's electrical fault. -- Per-device pump-out logging: add a `grease_service.qi` inbound Notefile that the dispatch system writes to when a pump-out event is completed, allowing the firmware to reset the fill accumulator on confirmed service and start fresh from a known-empty state. +### Production Next Steps + +Once the basic level monitor is running in the field, the following extensions are the natural progression — roughly from per-site usability to deeper measurement and fleet management. + +**A per-installation commissioning flow** removes the manual setup step: expose a `calibrate` environment variable that, when set, records the current sensor reading as the 0%-fill reference distance and stores it back as `interceptor_depth_mm`, replacing the manual tape-measure step with a firmware-driven calibration gesture. + +**Dual-layer measurement** addresses jurisdictions with combined-depth rules: add a conductivity or float probe near the bottom of the interceptor to detect sludge accumulation and report combined FOG+sludge fill depth. + +**Probe-fouling detection** turns an invisible failure into a leading indicator: add a signal-quality metric derived from the standard deviation of the 5-reading median filter. A high std-dev or elevated rejection rate is a leading indicator of fouling or multipath before the readings go completely invalid. + +**Over-the-air firmware updates** via [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) let threshold recipes and protocol updates be pushed to the entire fleet without a site visit. + +**Battery backup** via Blues Scoop or a small sealed lead-acid keeps interceptors in outage-prone locations protected, ensuring an overflow alert fires even during a kitchen's electrical fault. + +**Per-device pump-out logging** closes the service loop: add a `grease_service.qi` inbound Notefile that the dispatch system writes to when a pump-out event is completed, allowing the firmware to reset the fill accumulator on confirmed service and start fresh from a known-empty state. ## 11. Summary diff --git a/60-lone-worker-panic-fall-detection-beacon/README.md b/60-lone-worker-panic-fall-detection-beacon/README.md index db0c613d..d6824578 100644 --- a/60-lone-worker-panic-fall-detection-beacon/README.md +++ b/60-lone-worker-panic-fall-detection-beacon/README.md @@ -547,41 +547,51 @@ A productive bench exercise: run the device for 2 hours on a known-capacity LiPo This is a reference design, not a finished safety product. Several things a real lone-worker fleet would demand have been left for a production team to add — most notably a certified safety claim and a sleeping host MCU — and they are listed below as scope choices, not surprises. The forward-looking work that turns this into a deployable wearable follows the limitations. -**Simplified for the POC:** +### Simplified for the POC -- **Not a certified life-safety device.** This proof-of-concept has not been evaluated for fail-safe operation or certified under any personal-emergency-response or lone-worker protection standard. Validate all alert behaviors against your own safety requirements, and treat this design as a starting point rather than a production safety system. Supplement it with — do not use it to replace — mandatory check-in procedures, required PPE, and any regulated safety systems that apply to your operation. +The simplifications below are scope choices, not surprises — each names something a real lone-worker fleet would add before deployment. -- **Host MCU never sleeps.** The firmware runs a dual-cadence polling loop: the LIS3DH is sampled at ~100 Hz via a 10-sample inner loop (10 milliseconds between reads), and Notecard/GPS/haptic state advances at the outer ~10 Hz cadence. A production implementation should use STM32L433 STOP2 mode with GPIO interrupt wakeup from the LIS3DH INT1 pin and the panic button, dropping host idle draw from ~10+ mA to ~2–3 µA. The LIS3DH's hardware free-fall interrupt handles Stage 1 detection in silicon without host MCU involvement — the host only wakes when the interrupt fires. This is the single biggest power optimization available and the most important production change. +**Not a certified life-safety device.** This proof-of-concept has not been evaluated for fail-safe operation or certified under any personal-emergency-response or lone-worker protection standard. Validate all alert behaviors against your own safety requirements, and treat this design as a starting point rather than a production safety system. Supplement it with — **do not use it to replace** — mandatory check-in procedures, required PPE, and any regulated safety systems that apply to your operation. -- **Fall detection is software-sampled.** The LIS3DH is sampled at ~100 Hz via the inner loop (10 reads per outer pass, 10 milliseconds apart), matching the sensor ODR and reliably catching free-fall phases as short as 80 ms. The remaining limitation is that Stage 1 (free-fall detection) is implemented in host firmware rather than the LIS3DH hardware interrupt registers, so the host MCU must stay awake continuously. Using the LIS3DH INT1 free-fall interrupt (via `INT1_CFG`, `INT1_THS`, `INT1_DURATION` registers) is the production upgrade: it offloads Stage 1 entirely to the accelerometer silicon, allows the STM32L433 to sleep in STOP2 between events, and eliminates the polling overhead. +**Host MCU never sleeps.** The firmware runs a dual-cadence polling loop: the LIS3DH is sampled at ~100 Hz via a 10-sample inner loop (10 milliseconds between reads), and Notecard/GPS/haptic state advances at the outer ~10 Hz cadence. A production implementation should use STM32L433 STOP2 mode with GPIO interrupt wakeup from the LIS3DH INT1 pin and the panic button, dropping host idle draw from ~10+ mA to ~2–3 µA. The LIS3DH's hardware free-fall interrupt handles Stage 1 detection in silicon without host MCU involvement — the host only wakes when the interrupt fires. **This is the single biggest power optimization available and the most important production change.** -- **Fall detection thresholds are heuristic.** The default 0.55g free-fall / 2.5g impact thresholds cover textbook falls from standing height onto hard surfaces. They will produce false negatives for soft-surface landings (carpeted floors, mud) where the impact spike is attenuated, and may produce false positives during vigorous physical work involving overhead tool swings. Production deployments should run a calibration period with each worker activity profile before enabling real-time dispatch. +**Fall detection is software-sampled.** The LIS3DH is sampled at ~100 Hz via the inner loop (10 reads per outer pass, 10 milliseconds apart), matching the sensor ODR and reliably catching free-fall phases as short as 80 ms. The remaining limitation is that Stage 1 (free-fall detection) is implemented in host firmware rather than the LIS3DH hardware interrupt registers, so the host MCU must stay awake continuously. Using the LIS3DH INT1 free-fall interrupt (via `INT1_CFG`, `INT1_THS`, `INT1_DURATION` registers) is the production upgrade: it offloads Stage 1 entirely to the accelerometer silicon, allows the STM32L433 to sleep in STOP2 between events, and eliminates the polling overhead. -- **No cancel flow after panic.** The current firmware has no mechanism for a worker to cancel a panic alert once it's been confirmed and sent. A production device should include a multi-step cancel: button press within 60 seconds of a panic, haptic confirmation, and a `cancel` Note that the dispatch system can act on. +**Fall detection thresholds are heuristic.** The default 0.55g free-fall / 2.5g impact thresholds cover textbook falls from standing height onto hard surfaces. They will produce false negatives for soft-surface landings (carpeted floors, mud) where the impact spike is attenuated, and may produce false positives during vigorous physical work involving overhead tool swings. Production deployments should run a calibration period with each worker activity profile before enabling real-time dispatch. -- **GPS follow-up Note is optional and serialized.** When a fall or panic alert fires, the initial `beacon_alert.qo` Note is queued immediately with the Notecard's cached location. The background GPS search then runs for up to `DEFAULT_GPS_TIMEOUT_SEC` (90 seconds) without blocking the detection loop. If a fresh fix arrives, a `beacon_location.qo` Note is queued with the event-time coordinates and the same `event_id`. If GPS times out — because the device is indoors, under heavy tree cover, or the Notecard has no sky view — only the initial alert Note is delivered and its cached location (which may be stale or empty) stands. Dispatch should treat a missing `beacon_location.qo` (matching `event_id`) as an indication that the event-time position is unknown, not that the alert failed. Only one GPS enrichment window can run at a time — a second alert that fires during the 90-second window (the 60-second cooldown is shorter than the GPS timeout) receives its cached location only and does not get a `beacon_location.qo` follow-up. A production system that requires fresh GPS for every alert should serialize the alert cadence (e.g., extend the cooldown to match the GPS timeout) or implement a per-alert GPS job queue. +**No cancel flow after panic.** The current firmware has no mechanism for a worker to cancel a panic alert once it's been confirmed and sent. A production device should include a multi-step cancel: button press within 60 seconds of a panic, haptic confirmation, and a `cancel` Note that the dispatch system can act on. -- **No data encryption.** Notes travel over TLS between Notecard and Notehub; the Notefile body is not additionally encrypted. For sensitive safety applications with worker location data, consider using `beacon_alert.qos` (`.qos` suffix enables encrypted transport at the Notecard level). +**GPS follow-up Note is optional and serialized.** When a fall or panic alert fires, the initial `beacon_alert.qo` Note is queued immediately with the Notecard's cached location. The background GPS search then runs for up to `DEFAULT_GPS_TIMEOUT_SEC` (90 seconds) without blocking the detection loop. If a fresh fix arrives, a `beacon_location.qo` Note is queued with the event-time coordinates and the same `event_id`. If GPS times out — because the device is indoors, under heavy tree cover, or the Notecard has no sky view — only the initial alert Note is delivered and its cached location (which may be stale or empty) stands. Dispatch should treat a missing `beacon_location.qo` (matching `event_id`) as an indication that the event-time position is unknown, **not** that the alert failed. Only one GPS enrichment window can run at a time — a second alert that fires during the 90-second window (the 60-second cooldown is shorter than the GPS timeout) receives its cached location only and does not get a `beacon_location.qo` follow-up. A production system that requires fresh GPS for every alert should serialize the alert cadence (e.g., extend the cooldown to match the GPS timeout) or implement a per-alert GPS job queue. -- **Skylo NTN requires an initial non-NTN sync.** The Skylo satellite (NTN) path is not available until Notecard for Skylo has completed at least one successful cellular or WiFi session to associate with Notehub and register the Notefile templates. A device that ships directly into a no-cellular zone will be unable to send via satellite until it has found cellular (or WiFi) coverage at least once. Pre-provisioning during QA on a cellular-capable bench is the standard mitigation. +**No data encryption.** Notes travel over TLS between Notecard and Notehub; the Notefile body is not additionally encrypted. For sensitive safety applications with worker location data, consider using `beacon_alert.qos` (`.qos` suffix enables encrypted transport at the Notecard level). -- **Satellite payload budget.** Notecard for Skylo bundle includes 10 KB of Skylo satellite data, and the Skylo NTN link enforces a hard 256-byte maximum per Note. The compact alert template is well under that ceiling; frequent triggering in a no-cellular environment will consume the bundle faster. Monitor satellite usage via [Notehub billing/usage data](https://dev.blues.io/notehub/notehub-walkthrough/#configuring-your-billing-account). +**Skylo NTN requires an initial non-NTN sync.** The Skylo satellite (NTN) path is not available until Notecard for Skylo has completed at least one successful cellular or WiFi session to associate with Notehub and register the Notefile templates. A device that ships directly into a no-cellular zone will be unable to send via satellite until it has found cellular (or WiFi) coverage at least once. Pre-provisioning during QA on a cellular-capable bench is the standard mitigation. -- **Single I²C bus for all peripherals.** LIS3DH and DRV2605L share the bus with the internal Notecard connection. A severe I²C lockup (e.g., a partially-completed transaction interrupted by a reset) could block all communication. A production design should include bus-error recovery and a hardware watchdog. +**Satellite payload budget.** The Notecard for Skylo bundle includes 10 KB of Skylo satellite data, and the Skylo NTN link enforces a hard 256-byte maximum per Note. The compact alert template is well under that ceiling; frequent triggering in a no-cellular environment will consume the bundle faster. Monitor satellite usage via [Notehub billing/usage data](https://dev.blues.io/notehub/notehub-walkthrough/#configuring-your-billing-account). -- **No charging subsystem.** This POC documents a bare LiPo cell; no charger, dock, cradle, or inductive charging coil is included in the BOM or wiring. A production wearable needs an appropriate charging path, for example, a USB-C LiPo charging circuit integrated into the enclosure — plus overcharge and short-circuit protection if not already provided by the cell's built-in circuitry. Rechargeable operation is a natural next step but is out of scope for the POC. +**Single I²C bus for all peripherals.** The LIS3DH and DRV2605L share the bus with the internal Notecard connection. A severe I²C lockup (e.g., a partially-completed transaction interrupted by a reset) could block all communication. A production design should include bus-error recovery and a hardware watchdog. -- **Mojo is bench-only in this POC.** The firmware does not read the Mojo's charge accumulation register over Qwiic — the Mojo is a bench measurement instrument only. A production extension could include a `mah_consumed` field in `beacon_alert.qo` for fleet-level battery-health monitoring, read via the Mojo's Qwiic I²C link. +**No charging subsystem.** This POC documents a bare LiPo cell; no charger, dock, cradle, or inductive charging coil is included in the BOM or wiring. A production wearable needs an appropriate charging path, for example, a USB-C LiPo charging circuit integrated into the enclosure — plus overcharge and short-circuit protection if not already provided by the cell's built-in circuitry. Rechargeable operation is a natural next step but is out of scope for the POC. -**Production next steps:** +**Mojo is bench-only in this POC.** The firmware does not read the Mojo's charge accumulation register over Qwiic — the Mojo is a bench measurement instrument only. A production extension could include a `mah_consumed` field in `beacon_alert.qo` for fleet-level battery-health monitoring, read via the Mojo's Qwiic I²C link. -- STM32L433 STOP2 low-power mode with LIS3DH INT1 hardware interrupt wakeup — the single most impactful power optimization; drops host idle from ~10–15 mA to ~2–3 µA. -- LIS3DH hardware free-fall and shock detection configured via INT1_CFG, INT1_THS, INT1_DURATION registers — offloads Stage 1 entirely to the accelerometer silicon. -- Cancel-alert flow: post-panic confirmation cancel within N seconds, routed as a `cancel` event on `beacon_alert.qo` (carrying the same `event_id` as the alert being cancelled). -- Worker check-in acknowledgment: dispatcher can send a Notehub [Signal](https://dev.blues.io/api-reference/glossary/#signal) back to the device, triggering a distinctive haptic pattern so the worker knows their alert was received. -- Field-upgradeable firmware via [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) so threshold recipes can be pushed to the whole fleet without a physical re-flash. -- `.qos` encrypted Notefile for worker location data in privacy-sensitive jurisdictions. -- Per-worker baseline calibration: record each worker's typical activity vibration profile via a 24-hour learning period, then tune `impact_g` and `freefall_g` individually. +### Production Next Steps + +The forward-looking work that turns this into a deployable wearable follows, roughly from the most impactful power and safety changes to per-worker refinements. + +**STM32L433 STOP2 low-power mode** with LIS3DH INT1 hardware interrupt wakeup is the single most impactful power optimization, dropping host idle from ~10–15 mA to ~2–3 µA. + +**LIS3DH hardware free-fall and shock detection** configured via the `INT1_CFG`, `INT1_THS`, and `INT1_DURATION` registers offloads Stage 1 detection entirely to the accelerometer silicon. + +**A cancel-alert flow** gives the worker a way out of a false alarm: a post-panic confirmation cancel within N seconds, routed as a `cancel` event on `beacon_alert.qo` carrying the same `event_id` as the alert being cancelled. + +**Worker check-in acknowledgment** closes the loop back to the worker: a dispatcher can send a Notehub [Signal](https://dev.blues.io/api-reference/glossary/#signal) back to the device, triggering a distinctive haptic pattern so the worker knows their alert was received. + +**Field-upgradeable firmware** via [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) lets threshold recipes be pushed to the whole fleet without a physical re-flash. + +**A `.qos` encrypted Notefile** protects worker location data in privacy-sensitive jurisdictions. + +**Per-worker baseline calibration** records each worker's typical activity vibration profile via a 24-hour learning period, then tunes `impact_g` and `freefall_g` individually. ## 12. Summary diff --git a/61-regulatory-grade-pharmacy-lab-cold-storage-audit-monitor/README.md b/61-regulatory-grade-pharmacy-lab-cold-storage-audit-monitor/README.md index 552c82ec..ec56b01f 100644 --- a/61-regulatory-grade-pharmacy-lab-cold-storage-audit-monitor/README.md +++ b/61-regulatory-grade-pharmacy-lab-cold-storage-audit-monitor/README.md @@ -483,41 +483,45 @@ See the [MBGLW datasheet](https://dev.blues.io/datasheets/notecard-datasheet/not This reference design produces the measurement record and the cellular data path an auditor cares about, but several of the surrounding pieces of a regulated cold-chain program are explicitly out of scope — the calibration certificate that goes with each probe, the SOPs that govern the program, the multi-point mapping that a large freezer needs, and the ultra-cold (−80°C) hardware path. The list below names those boundaries so anyone evaluating this design against a real compliance program can see exactly what they still need to bring. -**Deployment considerations:** +### Deployment Considerations -- **Regulatory and compliance scope.** This reference design produces an audit-evidence record of temperature readings, door events, and excursion alerts, and transmits that record to Notehub via an independent cellular data path. It does not implement, and does not substitute for, site validation, SOP authorship, calibration program management, record-retention policy, electronic-record controls (e.g., 21 CFR Part 11 audit trails, access controls, and change management), or the broader quality-management framework required by any specific regulatory body. Deploying this design as part of a monitored, compliant storage program requires an exact calibrated probe assembly with a current NIST-traceable certificate, written commissioning and operating procedures, and validation documentation. Those are operator responsibilities, not firmware features. +The boundaries below are the surrounding pieces of a regulated cold-chain program that this design deliberately leaves to the operator — so anyone evaluating it against a real compliance program can see exactly what they still need to bring. -- **The production probe assembly is specified; obtain its NIST-traceable calibration certificate before deploying.** The firmware implements the Adafruit Platinum RTD Sensor PT1000 3-Wire 1 m (Product 3984) via the Adafruit MAX31865 PT1000 Amplifier (Product 3648). The PT1000 probe's 316L stainless-steel capsule routes into the refrigerated compartment; the MAX31865 amplifier board mounts inside the enclosure. This path provides the required cable-mounted, compartment-internal temperature measurement. **The probe does not ship with a NIST-traceable calibration certificate.** Before regulatory deployment, submit the specific probe assembly to an accredited calibration laboratory (e.g., Transcat, Tektronix Calibration, or a lab accredited under ILAC to ISO/IEC 17025) to receive a calibration certificate traceable to NIST for that individual unit. Keep the certificate on file with the unit's commissioning and IQ/OQ documentation, and enter the unit into a recertification schedule matching your calibration management program. The SparkFun TMP117 breakout (SEN-15805) is a bench substitute only. See [§4 Hardware Requirements](#4-hardware-requirements) for the library swap required to use it. +**Regulatory and compliance scope.** This reference design produces an audit-evidence record of temperature readings, door events, and excursion alerts, and transmits that record to Notehub via an independent cellular data path. It does not implement, and **does not substitute for**, site validation, SOP authorship, calibration program management, record-retention policy, electronic-record controls (e.g., 21 CFR Part 11 audit trails, access controls, and change management), or the broader quality-management framework required by any specific regulatory body. Deploying this design as part of a monitored, compliant storage program requires an exact calibrated probe assembly with a current NIST-traceable certificate, written commissioning and operating procedures, and validation documentation. Those are operator responsibilities, not firmware features. -- **Single-point temperature measurement.** One PT1000 probe measures a single location in the compartment. USP Chapter 659 and CDC guidelines recommend sensor placement at the geometric center of the unit, away from vents and walls. Units with high thermal gradients (e.g., large reach-in freezers) may need multiple probes. Adding a second MAX31865 on a different SPI chip-select pin (e.g., D9) with a second calibrated PT1000 probe, and a second `temp_c_2` template field, is a straightforward extension. +**The production probe assembly is specified; obtain its NIST-traceable calibration certificate before deploying.** The firmware implements the Adafruit Platinum RTD Sensor PT1000 3-Wire 1 m (Product 3984) via the Adafruit MAX31865 PT1000 Amplifier (Product 3648). The PT1000 probe's 316L stainless-steel capsule routes into the refrigerated compartment; the MAX31865 amplifier board mounts inside the enclosure. This path provides the required cable-mounted, compartment-internal temperature measurement. **The probe does not ship with a NIST-traceable calibration certificate.** Before regulatory deployment, submit the specific probe assembly to an accredited calibration laboratory (e.g., Transcat, Tektronix Calibration, or a lab accredited under ILAC to ISO/IEC 17025) to receive a calibration certificate traceable to NIST for that individual unit. Keep the certificate on file with the unit's commissioning and IQ/OQ documentation, and enter the unit into a recertification schedule matching your calibration management program. The SparkFun TMP117 breakout (SEN-15805) is a bench substitute only. See [§4 Hardware Requirements](#4-hardware-requirements) for the library swap required to use it. -- **No cryptographic Note signing.** The Notecard includes an STSAFE secure element. This design does not implement note-level signing — the `when` timestamps assigned by Notehub are server-side and cannot be altered after delivery, but the Note body itself is not signed on the device. On-device signing is out of scope for this reference design. +**Single-point temperature measurement.** One PT1000 probe measures a single location in the compartment. USP Chapter 659 and CDC guidelines recommend sensor placement at the geometric center of the unit, away from vents and walls. Units with high thermal gradients (e.g., large reach-in freezers) may need multiple probes. Adding a second MAX31865 on a different SPI chip-select pin (e.g., D9) with a second calibrated PT1000 probe, and a second `temp_c_2` template field, is a straightforward extension. -- **Alerting and door-duration tracking begin only after time is acquired.** All alert rules and door-duration timestamps are gated on the Notecard returning a valid UTC epoch (`now > 0`). During initial cellular registration and NTP sync, typically a few minutes on first power-on, potentially longer in marginal signal — the device samples sensors and enqueues reading Notes, but does not fire alerts and does not start the door-duration timer. If the door is open during this pre-time window, the firmware waits until a valid epoch is available before setting `door_open_since`; `door_open_sec` in those early reading Notes will read zero until time is valid and the door has been seen open with a known timestamp. Commission each unit in a known-good environment and verify alert delivery before treating the unit as fully operational. **Reading Notes enqueued during this pre-sync window carry unverified Notecard RTC timestamps** and should be flagged as commissioning data rather than audit-grade records in any downstream export. +**No cryptographic Note signing.** The Notecard includes an STSAFE secure element. This design does not implement note-level signing — the `when` timestamps assigned by Notehub are server-side and cannot be altered after delivery, but the Note body itself is not signed on the device. On-device signing is out of scope for this reference design. -- **Door-open duration tracking is sampled, not interrupt-driven.** A door that opens and closes entirely within one `sample_interval_sec` window will not be detected. At the default 5-minute interval, any access shorter than 5 minutes is invisible. For pharmacies with high access frequency (every few minutes), shortening `sample_interval_sec` to 60–120 seconds reduces the blind spot at the cost of more frequent Cygnet wakes. +**Alerting and door-duration tracking begin only after time is acquired.** All alert rules and door-duration timestamps are gated on the Notecard returning a valid UTC epoch (`now > 0`). During initial cellular registration and NTP sync, typically a few minutes on first power-on, potentially longer in marginal signal — the device samples sensors and enqueues reading Notes, but does not fire alerts and does not start the door-duration timer. If the door is open during this pre-time window, the firmware waits until a valid epoch is available before setting `door_open_since`; `door_open_sec` in those early reading Notes will read zero until time is valid and the door has been seen open with a known timestamp. Commission each unit in a known-good environment and verify alert delivery before treating the unit as fully operational. **Reading Notes enqueued during this pre-sync window carry unverified Notecard RTC timestamps** and should be flagged as commissioning data rather than audit-grade records in any downstream export. -- **`sensor_disagreement` requires a door-actuated interior lamp.** The light-based cross-check — ambient lux above `door_lux_threshold` while the reed switch reads closed — only catches a **stuck-closed or failed-closed reed switch** on units where the interior lamp turns on when the cabinet is opened and off when it closes. On **lamp-free** units, lux will never exceed the threshold from an interior light event, so the rule never fires — omit the VEML7700 or set `door_lux_threshold` to `120000.0` in Notehub. On **always-on-lamp** units (lamp stays lit regardless of door state), `lux > door_lux_threshold` is true whenever the door is closed (the normal closed-door state), so the rule fires persistently every cooldown period — a source of continuous false positives, not silence. Set `door_lux_threshold` to `120000.0` in Notehub to suppress the rule on always-on-lamp units without a firmware rebuild. Verify the lamp behavior of the specific unit before deploying this rule. +**Door-open duration tracking is sampled, not interrupt-driven.** A door that opens and closes entirely within one `sample_interval_sec` window will not be detected. At the default 5-minute interval, any access shorter than 5 minutes is invisible. For pharmacies with high access frequency (every few minutes), shortening `sample_interval_sec` to 60–120 seconds reduces the blind spot at the cost of more frequent Cygnet wakes. -- **VEML7700 placement is bench-only.** The bare Adafruit VEML7700 breakout PCB is not rated for sustained cold or condensing environments. Permanently mounting the unprotected PCB inside a refrigerated cabinet will eventually cause moisture-related corrosion and failure — the same risk that makes the document recommend keeping all other electronics outside the cold zone. For a production design: use a sealed or potted light sensor rated for the operating temperature range, mount the sensor on the exterior of the door frame where it detects light spillage when the door is ajar, or use a different secondary door-verification signal (such as a suitably packaged hall-effect sensor). The `sensor_disagreement` feature may be omitted from production builds where a robust cold-tolerant light-sensing solution has not been specified. +**`sensor_disagreement` requires a door-actuated interior lamp.** The light-based cross-check — ambient lux above `door_lux_threshold` while the reed switch reads closed — only catches a **stuck-closed or failed-closed reed switch** on units where the interior lamp turns on when the cabinet is opened and off when it closes. On **lamp-free** units, lux will never exceed the threshold from an interior light event, so the rule never fires — omit the VEML7700 or set `door_lux_threshold` to `120000.0` in Notehub. On **always-on-lamp** units (lamp stays lit regardless of door state), `lux > door_lux_threshold` is true whenever the door is closed (the normal closed-door state), so the rule fires persistently every cooldown period — a source of continuous false positives, not silence. Set `door_lux_threshold` to `120000.0` in Notehub to suppress the rule on always-on-lamp units without a firmware rebuild. Verify the lamp behavior of the specific unit before deploying this rule. -- **Two independent buffering layers with different depth and failure-mode guarantees.** It is important to distinguish these clearly for compliance purposes: +**VEML7700 placement is bench-only.** The bare Adafruit VEML7700 breakout PCB is not rated for sustained cold or condensing environments. Permanently mounting the unprotected PCB inside a refrigerated cabinet will eventually cause moisture-related corrosion and failure — the same risk that makes the document recommend keeping all other electronics outside the cold zone. For a production design: use a sealed or potted light sensor rated for the operating temperature range, mount the sensor on the exterior of the door frame where it detects light spillage when the door is ajar, or use a different secondary door-verification signal (such as a suitably packaged hall-effect sensor). The `sensor_disagreement` feature may be omitted from production builds where a robust cold-tolerant light-sensing solution has not been specified. - 1. **Notecard flash-backed queue** — handles cellular and WiFi outages transparently. Notes accumulate in the Notecard's on-device flash store and flush when connectivity returns, with UTC timestamps intact. At the default 5-minute sample interval this design enqueues 288 Notes per day; an extended cellular outage of several consecutive days can exhaust on-device flash storage, producing gaps in the audit-evidence record. Using a `note.template` for `storage_reading.qo` encodes each Note as a compact fixed-length binary record, reducing per-Note storage overhead and improving wire efficiency compared to variable-length JSON; however, on-device queue depth is still finite and bounded by the Notecard's total flash capacity. Configure a shorter `outbound` interval to keep the queue shallow under normal operation. +**Two independent buffering layers with different depth and failure-mode guarantees** protect the audit record, and it is important to distinguish them clearly for compliance purposes. The first is the **Notecard flash-backed queue**, which handles cellular and WiFi outages transparently: Notes accumulate in the Notecard's on-device flash store and flush when connectivity returns, with UTC timestamps intact. At the default 5-minute sample interval this design enqueues 288 Notes per day; an extended cellular outage of several consecutive days can exhaust on-device flash storage, producing gaps in the audit-evidence record. Using a `note.template` for `storage_reading.qo` encodes each Note as a compact fixed-length binary record, reducing per-Note storage overhead and improving wire efficiency compared to variable-length JSON; however, on-device queue depth is still finite and bounded by the Notecard's total flash capacity. Configure a shorter `outbound` interval to keep the queue shallow under normal operation. The second is the **host-side I²C retry ring (`PENDING_RING_CAP = 4`)**, which handles only the distinct case where the Cygnet host cannot enqueue into the Notecard over I²C (e.g., a transient bus fault or Notecard startup delay). This ring holds at most four undelivered readings and four undelivered alerts. If the host cannot reach the Notecard for more than four consecutive wakes (~20 minutes at the default interval), the oldest buffered entry is overwritten and its loss is counted in `dropped_readings` or `dropped_alerts` — the payload is **not** preserved beyond that window. Normal cellular outages never trigger this path. For a compliance use case where full sample lineage through an extended I²C-fault window is a hard requirement, supplement with a larger host-side spill buffer (FRAM, SD card, or SPI flash) on the Cygnet's SPI bus. - 2. **Host-side I²C retry ring (`PENDING_RING_CAP = 4`)** — handles only the distinct case where the Cygnet host cannot enqueue into the Notecard over I²C (e.g., a transient bus fault or Notecard startup delay). This ring holds at most four undelivered readings and four undelivered alerts. If the host cannot reach the Notecard for more than four consecutive wakes (~20 minutes at the default interval), the oldest buffered entry is overwritten and its loss is counted in `dropped_readings` or `dropped_alerts` — the payload is **not** preserved beyond that window. Normal cellular outages never trigger this path. For a compliance use case where full sample lineage through an extended I²C-fault window is a hard requirement, supplement with a larger host-side spill buffer (FRAM, SD card, or SPI flash) on the Cygnet's SPI bus. +**No power-fail event.** If the facility experiences a power outage and the monitor is not on UPS, both the Notecard and the Cygnet lose power. Any Notes queued but not yet synced remain in the Notecard's flash-backed queue and will be delivered on the next power-on and cellular session, but a gap in the reading series will be visible in Notehub, which is itself a useful signal for the audit-evidence record. Adding a small LiFePO4 backup cell on the +VBAT rail would allow the monitor to survive brief outages and log the power-loss event explicitly. -- **No power-fail event.** If the facility experiences a power outage and the monitor is not on UPS, both the Notecard and the Cygnet lose power. Any Notes queued but not yet synced remain in the Notecard's flash-backed queue and will be delivered on the next power-on and cellular session, but a gap in the reading series will be visible in Notehub, which is itself a useful signal for the audit-evidence record. Adding a small LiFePO4 backup cell on the +VBAT rail would allow the monitor to survive brief outages and log the power-loss event explicitly. +**Mojo is bench-only.** The firmware does not read the Mojo's LTC2959 coulomb counter via the Qwiic bus. Adding a runtime mAh field to the reading Note is a straightforward extension if fleet-level energy telemetry is valuable. -- **Mojo is bench-only.** The firmware does not read the Mojo's LTC2959 coulomb counter via the Qwiic bus. Adding a runtime mAh field to the reading Note is a straightforward extension if fleet-level energy telemetry is valuable. +### Production Next Steps -**Production next steps:** +Once the basic audit monitor is delivering records an auditor trusts, the following extensions are the natural progression — from multi-point coverage to fleet maintenance and the ultra-cold hardware path. -- Add a second MAX31865 + PT1000 probe on a different chip-select (e.g., D9) for multi-point mapping of larger units. The template and per-sample reading logic extend naturally — add a `temp_c_2` field to the template and read both sensors on each wake. Each probe assembly requires its own NIST-traceable calibration certificate. -- Implement [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) for over-the-air host firmware updates — essential for maintaining a fleet across regulatory-threshold changes without site visits. -- Add a `storage_calibration.db` inbound Notefile for per-unit temperature-offset correction delivered from Notehub — eliminates the need to reflash when calibration data changes after annual re-certification. -- Integrate Notehub-side webhook routing to a LIMS or compliance database. The per-sample reading Note body maps directly to a time-series schema; the alert Note maps to an excursion event record. -- **Ultra-cold storage (−80°C freezers) is not supported by this hardware.** The Adafruit PT1000 probe (Product 3984) is rated to −50°C; using it below that limit is outside the manufacturer's specification and is not appropriate for a regulatory-grade deployment. Ultra-cold monitoring requires a dedicated RTD probe and amplifier chain rated to −80°C or below (e.g., a PT100 probe specified for cryogenic service), a calibration certificate covering that lower temperature range, and validation of the full measurement chain at operating temperature. The firmware architecture (per-sample reading Notes, immediate-sync alert Notes, environment-variable thresholds) is compatible with that extension, but the sensor hardware must be replaced. +**A second MAX31865 + PT1000 probe** on a different chip-select (e.g., D9) enables multi-point mapping of larger units. The template and per-sample reading logic extend naturally — add a `temp_c_2` field to the template and read both sensors on each wake. Each probe assembly requires its own NIST-traceable calibration certificate. + +**[Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/)** provides over-the-air host firmware updates, essential for maintaining a fleet across regulatory-threshold changes without site visits. + +**A `storage_calibration.db` inbound Notefile** delivers per-unit temperature-offset correction from Notehub, eliminating the need to reflash when calibration data changes after annual re-certification. + +**Notehub-side webhook routing** integrates the device with a LIMS or compliance database: the per-sample reading Note body maps directly to a time-series schema, and the alert Note maps to an excursion event record. + +**Ultra-cold storage (−80°C freezers) is not supported by this hardware.** The Adafruit PT1000 probe (Product 3984) is rated to −50°C; using it below that limit is outside the manufacturer's specification and is not appropriate for a regulatory-grade deployment. Ultra-cold monitoring requires a dedicated RTD probe and amplifier chain rated to −80°C or below (e.g., a PT100 probe specified for cryogenic service), a calibration certificate covering that lower temperature range, and validation of the full measurement chain at operating temperature. The firmware architecture (per-sample reading Notes, immediate-sync alert Notes, environment-variable thresholds) is compatible with that extension, but the sensor hardware must be replaced. ## 12. Summary diff --git a/62-construction-site-environmental-noise-exposure-monitor/README.md b/62-construction-site-environmental-noise-exposure-monitor/README.md index a5fc96c1..7c786885 100644 --- a/62-construction-site-environmental-noise-exposure-monitor/README.md +++ b/62-construction-site-environmental-noise-exposure-monitor/README.md @@ -379,45 +379,43 @@ The *shape* of the Mojo trace depends on whether the Notecarrier CX's Qwiic/3.3V This reference design is an area monitor, deliberately — not a personal dosimeter, not a regulatory silica sampler, not a complete replacement for either. The list below names the boundaries that come with that choice so a GC evaluating it can see exactly where it complements existing compliance work and where a production deployment will need to bring more. Forward-looking work that turns this into a full site monitoring program follows the limitations. -**Simplified for the POC:** +### Simplified for the POC -- **PM sensor fan acoustic contamination.** The PMSA003I's fan runs whenever its Qwiic 3.3V supply is present. Whether that supply is cut during ATTN sleep is carrier-implementation-specific: if it is not cut, the fan runs continuously and contaminates the dB(A) channel throughout every measurement cycle. If it is cut, the fan restarts when the host wakes and has been running for the host boot + `setup()` time (~5–15 seconds) before the 15-second sound window begins. The firmware samples sound before `begin_I2C()` and the PM warm-up phase, minimising (but not eliminating) contamination in the gated-rail case. **Before deploying, measure the enclosure's self-noise floor with the PM sensor powered and spinning, using a calibrated reference sound-level meter placed at the acoustic vent opening. If the enclosure self-noise floor exceeds 5 dB(A) above the ambient floor, the enclosure design is contaminating the dB(A) channel.** The definitive fix — regardless of carrier topology — is to add a GPIO-controlled load switch to the PMSA003I's Qwiic power line so the fan is definitively off during the entire sound-sample window. A load switch also removes any PMSA003I fan current contribution from the ATTN sleep floor, making power budgeting unambiguous. +The boundaries below come with the choice to build an area monitor rather than a personal dosimeter — they show exactly where this design complements existing compliance work and where a production deployment will need to bring more. -- **5-minute sampling cadence can miss transient events.** The firmware wakes and samples once per `sample_interval_sec` (default 5 minutes). A high-dust burst or noise spike that begins and ends entirely between two consecutive sample windows is not captured — the sensor never sees it. During task-intensive operations such as concrete demolition, jackhammering, dry cutting, or grinding, consider reducing `sample_interval_sec` to 60–120 seconds via the Notehub environment variable to narrow the detection gap. Note that more frequent sampling reduces LiPo autonomy proportionally and increases data consumption. For tasks where any transient spike matters (e.g., a saw that only runs for 30 seconds), a wearable personal dosimeter worn by the worker is the only reliable capture method; the area monitor cannot substitute for it in those scenarios. +**PM sensor fan acoustic contamination.** The PMSA003I's fan runs whenever its Qwiic 3.3V supply is present. Whether that supply is cut during ATTN sleep is carrier-implementation-specific: if it is not cut, the fan runs continuously and contaminates the dB(A) channel throughout every measurement cycle. If it is cut, the fan restarts when the host wakes and has been running for the host boot + `setup()` time (~5–15 seconds) before the 15-second sound window begins. The firmware samples sound before `begin_I2C()` and the PM warm-up phase, minimising (but not eliminating) contamination in the gated-rail case. **Before deploying, measure the enclosure's self-noise floor with the PM sensor powered and spinning, using a calibrated reference sound-level meter placed at the acoustic vent opening. If the enclosure self-noise floor exceeds 5 dB(A) above the ambient floor, the enclosure design is contaminating the dB(A) channel.** The definitive fix — regardless of carrier topology — is to add a GPIO-controlled load switch to the PMSA003I's Qwiic power line so the fan is definitively off during the entire sound-sample window. A load switch also removes any PMSA003I fan current contribution from the ATTN sleep floor, making power budgeting unambiguous. -- **PM sensor ≠ direct silica monitor.** The PMSA003I is an optical particle counter measuring total PM2.5 and PM10 by mass concentration. It cannot speciate particles — it cannot tell crystalline silica from wood dust, cement dust, or urban background particulate. OSHA's silica standard (29 CFR 1926.1153) requires respirable crystalline silica sampling using NIOSH Method 7500 or equivalent, which involves filter-based personal samplers analyzed by X-ray diffraction. The PM2.5/PM10 readings from this device are a real-time proxy indicator for elevated dust conditions, not a substitute for OSHA-compliant silica exposure documentation. The alerts can prompt a safety officer to investigate and deploy personal monitoring; they cannot replace it. +**5-minute sampling cadence can miss transient events.** The firmware wakes and samples once per `sample_interval_sec` (default 5 minutes). A high-dust burst or noise spike that begins and ends entirely between two consecutive sample windows is not captured — the sensor never sees it. During task-intensive operations such as concrete demolition, jackhammering, dry cutting, or grinding, consider reducing `sample_interval_sec` to 60–120 seconds via the Notehub environment variable to narrow the detection gap. Note that more frequent sampling reduces LiPo autonomy proportionally and increases data consumption. For tasks where any transient spike matters (e.g., a saw that only runs for 30 seconds), a wearable personal dosimeter worn by the worker is the only reliable capture method; the area monitor cannot substitute for it in those scenarios. -- **Sound level is 15-second mean, not 8-hour TWA.** OSHA's noise standard uses TWA (time-weighted average) over a full work shift, integrated using a dosimeter that accounts for the full exposure curve including quiet and loud periods. This device reports a 15-second moving average every 5 minutes and flags when that average exceeds 85 dB(A). That is useful for identifying high-noise task windows but is not a substitute for a personal dosimeter worn by a worker throughout the shift. +**PM sensor ≠ direct silica monitor.** The PMSA003I is an optical particle counter measuring total PM2.5 and PM10 by mass concentration. It cannot speciate particles — it cannot tell crystalline silica from wood dust, cement dust, or urban background particulate. OSHA's silica standard (29 CFR 1926.1153) requires respirable crystalline silica sampling using NIOSH Method 7500 or equivalent, which involves filter-based personal samplers analyzed by X-ray diffraction. The PM2.5/PM10 readings from this device are a real-time proxy indicator for elevated dust conditions, **not** a substitute for OSHA-compliant silica exposure documentation. The alerts can prompt a safety officer to investigate and deploy personal monitoring; they cannot replace it. -- **SEN0232 calibration.** The DFRobot SEN0232 is rated for 3.3–5V operation, so powering it from the LiPo's V+ rail (~3.7–4.2V) is within spec. However, the sensor's published output mapping (0.6V → 30 dB, 2.6V → 130 dB) is factory-calibrated at 5V; readings at lower supply voltages may differ from a calibrated reference by a fixed offset. Use the `db_cal_offset` environment variable to null that offset against a calibrated reference sound-level meter at commissioning time. +**Sound level is 15-second mean, not 8-hour TWA.** OSHA's noise standard uses TWA (time-weighted average) over a full work shift, integrated using a dosimeter that accounts for the full exposure curve including quiet and loud periods. This device reports a 15-second moving average every 5 minutes and flags when that average exceeds 85 dB(A). That is useful for identifying high-noise task windows but is not a substitute for a personal dosimeter worn by a worker throughout the shift. -- **Single-point perimeter monitoring.** One sensor reflects conditions at one location on the site. Exposure varies significantly by trade, task, and proximity to the source — a concrete saw 3 meters from the sensor reads very differently from one 20 meters away. A production deployment would use multiple sensors distributed across the site's active work zones. +**SEN0232 calibration.** The DFRobot SEN0232 is rated for 3.3–5V operation, so powering it from the LiPo's V+ rail (~3.7–4.2V) is within spec. However, the sensor's published output mapping (0.6V → 30 dB, 2.6V → 130 dB) is factory-calibrated at 5V; readings at lower supply voltages may differ from a calibrated reference by a fixed offset. Use the `db_cal_offset` environment variable to null that offset against a calibrated reference sound-level meter at commissioning time. -- **Alert cooldown prevents rapid re-notification.** The 30-minute per-type alert cooldown stops alarm fatigue but also means a sustained, elevated exposure that persists for hours generates only two alerts per hour. For compliance documentation purposes, the `env_summary.qo` stream is the authoritative record, not the alert count. +**Single-point perimeter monitoring.** One sensor reflects conditions at one location on the site. Exposure varies significantly by trade, task, and proximity to the source — a concrete saw 3 meters from the sensor reads very differently from one 20 meters away. A production deployment would use multiple sensors distributed across the site's active work zones. -- **PM sensor failure emits `–9999.0` as an explicit sentinel.** If the PMSA003I is not detected on I²C for an entire reporting window, `pm25_avg` and `pm10_avg` are transmitted as `–9999.0` — an unambiguous invalid-data sentinel that no downstream consumer can mistake for genuinely particulate-free air (0.0 µg/m³). The companion `pm_samples` field confirms total failure when its value is `0`. A persistent `pm_samples = 0` across multiple successive windows indicates a sensor wiring, I²C, or power fault. +**Alert cooldown prevents rapid re-notification.** The 30-minute per-type alert cooldown stops alarm fatigue but also means a sustained, elevated exposure that persists for hours generates only two alerts per hour. For compliance documentation purposes, the `env_summary.qo` stream is the authoritative record, not the alert count. -- **GPS coordinates may be absent or stale until `location_valid` is `true`.** Two distinct scenarios can produce untrustworthy coordinates: +**PM sensor failure emits `–9999.0` as an explicit sentinel.** If the PMSA003I is not detected on I²C for an entire reporting window, `pm25_avg` and `pm10_avg` are transmitted as `–9999.0` — an unambiguous invalid-data sentinel that no downstream consumer can mistake for genuinely particulate-free air (0.0 µg/m³). The companion `pm_samples` field confirms total failure when its value is `0`. A persistent `pm_samples = 0` across multiple successive windows indicates a sensor wiring, I²C, or power fault. - 1. **No fix acquired yet (zero coordinates).** If the Notecard hasn't acquired any GPS fix before the first summary fires (e.g., the enclosure is set up briefly indoors), `siteLat` and `siteLon` are both 0.0 in the payload body, and Notehub's `where_lat`/`where_lon` metadata will also be absent. Both remain zero/absent until the first GNSS acquisition. +**GPS coordinates may be absent or stale until `location_valid` is `true`.** Two distinct scenarios can produce untrustworthy coordinates. The first is **no fix acquired yet (zero coordinates)**: if the Notecard hasn't acquired any GPS fix before the first summary fires (e.g., the enclosure is set up briefly indoors), `siteLat` and `siteLon` are both 0.0 in the payload body, and Notehub's `where_lat`/`where_lon` metadata will also be absent — both remain zero/absent until the first GNSS acquisition. The second is a **stale cached fix after redeployment**: the Notecard's GNSS hardware retains the last-known position across power cycles, so after the device is moved from one construction site to another and powered on fresh, `card.location` may immediately return the coordinates of the **previous** site — a non-zero, apparently valid position that is geographically wrong for the new site. The firmware guards against this by comparing GPS `time` timestamps: the first non-zero response after boot is treated as a baseline and `location_valid` is held `false`; only when a subsequent `card.location` response returns a newer timestamp — confirming the GNSS acquired a fresh fix at the current site — is `location_valid` set to `true` and `gpsCountdown` armed for the normal re-acquisition interval. In both cases `location_valid: false` in the Note body is the signal. Downstream consumers should **not** geo-stamp compliance records or evaluate geo-fenced alert rules on Notes where `location_valid` is `false`. In a typical outdoor deployment with clear sky view, the GNSS acquires a fresh fix within one or two sample cycles (~5–10 minutes), after which `location_valid` becomes `true` and remains `true` across sleep/wake cycles for the lifetime of the current site deployment. - 2. **Stale cached fix after redeployment.** The Notecard's GNSS hardware retains the last-known position across power cycles. After the device is moved from one construction site to another and powered on fresh, `card.location` may immediately return the coordinates of the **previous** site — a non-zero, apparently valid position that is geographically wrong for the new site. The firmware guards against this by comparing GPS `time` timestamps: the first non-zero response after boot is treated as a baseline and `location_valid` is held `false`; only when a subsequent `card.location` response returns a newer timestamp — confirming the GNSS acquired a fresh fix at the current site — is `location_valid` set to `true` and `gpsCountdown` armed for the normal re-acquisition interval. +**Mojo is bench-validation only.** The firmware does not call `card.power` to read the Mojo's LTC2959 coulomb counter. Adding a `mojo_mah` field to the summary is a straightforward extension — include a `card.power` request in `sendSummary()` and append the returned `milliamp_hours` value to the queued Note body. - In both cases `location_valid: false` in the Note body is the signal. Downstream consumers should not geo-stamp compliance records or evaluate geo-fenced alert rules on Notes where `location_valid` is `false`. In a typical outdoor deployment with clear sky view, the GNSS acquires a fresh fix within one or two sample cycles (~5–10 minutes), after which `location_valid` becomes `true` and remains `true` across sleep/wake cycles for the lifetime of the current site deployment. +### Production Next Steps -- **Mojo is bench-validation only.** The firmware does not call `card.power` to read the Mojo's LTC2959 coulomb counter. Adding a `mojo_mah` field to the summary is a straightforward extension — include a `card.power` request in `sendSummary()` and append the returned `milliamp_hours` value to the queued Note body. +Forward-looking work that turns this into a full site-monitoring program follows, roughly from site coverage to fleet maintenance and power sizing. -**Production next steps:** +**Multi-sensor deployments** spread coverage across the site: deploy two to four units per active site — one downwind of the primary dust-generating task (typically the saw or grinder), one at the site perimeter as a perimeter check, and one upwind near the site office as a baseline. Keep all devices on the same per-site fleet so they share site-wide threshold environment variables, and use [device-level environment variable overrides](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) for any per-unit calibration differences (e.g., `db_cal_offset`). -- **Multi-sensor deployments.** Deploy two to four units per active site — one downwind of the primary dust-generating task (typically the saw or grinder), one at the site perimeter as a perimeter check, and one upwind near the site office as a baseline. Keep all devices on the same per-site fleet so they share site-wide threshold environment variables. Use [device-level environment variable overrides](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) for any per-unit calibration differences (e.g., `db_cal_offset`). +**Shift-aware sampling cadence** matches data volume to activity: use the Notecard's on-device time (via `card.time`) to reduce sampling frequency outside of work hours (e.g., 9 PM to 5 AM) and extend it during peak-activity windows like concrete operations or demolition, reducing data volume and battery load during periods when no workers are on site. -- **Shift-aware sampling cadence.** Use the Notecard's on-device time (via `card.time`) to reduce sampling frequency outside of work hours (e.g., 9 PM to 5 AM) and extend it during peak-activity windows like concrete operations or demolition. This reduces data volume and battery load during periods when no workers are on site. +**Personal dosimeter integration** complements the area monitor: add a second, wearable Notecard + Cygnet variant as a personal dosimeter worn by a worker, with the site monitor acting as the reference station. Comparing personal vs. ambient readings lets the GC demonstrate that workers in a specific trade zone had lower exposure than the perimeter sensor suggested. -- **Personal dosimeter integration.** Add a second, wearable Notecard + Cygnet variant as a personal dosimeter worn by a worker, with the site monitor acting as the reference station. Comparing personal vs. ambient readings lets the GC demonstrate that workers in a specific trade zone had lower exposure than the perimeter sensor suggested. +**Field-upgradeable firmware** via [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) lets threshold changes, new alert types, or calibration-constant updates be pushed to the entire fleet from Notehub without a site visit. -- **Field-upgradeable firmware** via [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) so threshold changes, new alert types, or calibration-constant updates can be pushed to the entire fleet from Notehub without a site visit. - -- **Extended battery for winter/cloudy deployments.** After the Mojo bench exercise (§8) establishes the actual weighted-average system draw for your build, size the battery accordingly. In northern latitudes in December, available solar may be only 2–3 peak-sun hours per day. Moving to a 3000–5000 mAh LiPo pack and a higher-wattage panel (10W) provides several cloudy days of autonomy and recovers faster when the sun returns; confirm against at least one full 4-hour GNSS re-acquisition cycle in the Mojo trace before finalising battery sizing. +**Extended battery for winter/cloudy deployments** keeps the monitor alive through low-sun periods: after the Mojo bench exercise (§8) establishes the actual weighted-average system draw for your build, size the battery accordingly. In northern latitudes in December, available solar may be only 2–3 peak-sun hours per day. Moving to a 3000–5000 mAh LiPo pack and a higher-wattage panel (10W) provides several cloudy days of autonomy and recovers faster when the sun returns; confirm against at least one full 4-hour GNSS re-acquisition cycle in the Mojo trace before finalising battery sizing. ## 11. Summary diff --git a/63-construction-equipment-anti-theft-tracker-with-immobilizer/README.md b/63-construction-equipment-anti-theft-tracker-with-immobilizer/README.md index 2fbb1fee..9695d282 100644 --- a/63-construction-equipment-anti-theft-tracker-with-immobilizer/README.md +++ b/63-construction-equipment-anti-theft-tracker-with-immobilizer/README.md @@ -502,28 +502,47 @@ Satellite session validation requires outdoor antenna placement with clear sky v This POC demonstrates the control path, the data path, and the satellite fallback — but it deliberately stops short of being a production security device. A working immobilizer for a deployed fleet wants a latching relay that survives sleep gaps, a transient-protected ignition front end that can handle automotive load dump, and interrupt-driven wake that catches a key-on edge inside the next 100 ms rather than the next two minutes. Those are the items below, framed as the scope boundaries of the reference design and the engineering work that turns it into a production product. -**Simplified for the POC:** - -- **Staged, polled, edge-triggered immobilizer, not a continuously-held cut.** The immobilizer in this POC is a _next-wake / next-key-on-edge_ design. `NotePayloadSaveAndSleep` physically cuts the Cygnet's power during the sleep window, so the relay coil de-energizes on every sleep interval and the NC contact re-closes — briefly restoring the ignition circuit. The Cygnet re-asserts the relay only when it wakes and reads `immobilized = true`. For the default 2-minute after-hours cycle, the relay is active for only a few seconds every 2 minutes; a determined thief who turns the key during the sleep gap can crank the engine. Additionally, the relay only fires on an OFF→ON ignition edge — the previous wake must have observed ignition OFF and the current wake must observe ignition ON. If the equipment is already running when the immobilize command is staged, the firmware deliberately holds off until the next key cycle (this avoids cutting the starter circuit while the engine is actively running, per the safety guidance in §5). If the thief cycles the key fully between two Cygnet wakes (OFF→ON→OFF inside one sleep window), the firing edge is missed entirely until the next OFF→ON transition the Cygnet observes. This is a proof-of-concept staging mechanism. Production deployments require a **latching (bistable) relay** that holds its contact state with no continuous coil power and survives Cygnet sleep, power cuts, and wiring interruptions. See Production next steps below. -- **Ignition-sense front end is POC-only — no transient protection.** The bare 33 kΩ / 10 kΩ voltage divider provides no protection against automotive electrical transients. Load-dump events on generator sets can produce transients 40–200 V above nominal 12 V; starter-motor switching creates fast inductive spikes on the battery rail. Both can exceed the Cygnet GPIO absolute maximum and damage the MCU. A production design must add a TVS diode (e.g. 15 V unidirectional, placed before the high-side divider resistor) and an RC low-pass filter (e.g. 1 kΩ + 100 nF at the A2 node) as a minimum, or use a properly isolated sensing front end. The relay-side vehicle interface carries the same risk; the 1N4007 flyback diode protects the MOSFET drain from the relay coil's inductive spike, but does not protect the 12 V feed from upstream transients — the inline fuse in the BOM addresses overcurrent only. -- **No interrupt-driven ignition sense.** The firmware polls ignition state on each wake. A thief who turns the key and drives away within the 2-minute window between wakes will have a head start before the `ignition_on_immobilized` event fires. A hardware interrupt from the ATTN pin triggered by the ignition-sense line would wake the Cygnet instantly on key-on — the Notecarrier CX ATTN wiring and the `card.attn` `auxgpio` mode support this pattern but it is not implemented in this POC. -- **Inbound commands require cellular.** The Skylo satellite link provides primarily uplink (device-to-cloud) data. `immobilize.qi` commands from Notehub to the device require a cellular or WiFi connection to be delivered. If the equipment is already in a dead zone, the operator must wait for cellular to be restored before the command arrives. -- **Geofence decisions use cached location data, and daytime detection latency is bounded by `heartbeat_stopped_min`.** The firmware calls `card.location` to read the Notecard's most recently cached GNSS fix — it does not wait for a fresh acquisition. The cached fix age is bounded by the GNSS acquisition cadence (`card.location.mode seconds`, default `heartbeat_moving_s` = 5 minutes), so one or two after-hours wake cycles may evaluate the geofence against the same stale fix before GNSS re-acquires. A geofence breach alert will not appear until both (a) the host wakes and (b) the Notecard has a sufficiently fresh fix that places the device outside the radius. During business hours, when the host wakes every 60 minutes (default), the worst-case detection latency for a theft that starts from a parked state is approximately 60 minutes plus up to 5 minutes of GNSS fix lag. Every outbound Note includes `fix_age_s` (seconds ≥ 0, or `-1` when `card.time` is unavailable) so operators can assess the staleness of each geofence decision. -- **Geofence is a circle.** The firmware uses a Haversine-computed circle around a single center point. Irregular job-site boundaries (L-shaped lots, equipment lots separated by roads) would require multiple overlapping circles or a polygon geofence, neither of which is implemented here. -- **Single geofence.** The device stores one home location. Equipment that legitimately moves between job sites (morning deliveries, weekend staging) will generate false geofence breach alerts unless the operator updates `fence_lat` / `fence_lon` in Notehub ahead of each move. -- **No tamper detection.** The firmware does not detect cable cutting, enclosure intrusion, or GPS jamming. A motivated thief who locates and removes the tracker, jams the antenna, or removes the equipment battery before the solar reserve is depleted will defeat this POC design. -- **Satellite data budget.** Notecard for Skylo includes 10 KB of Skylo data per month. Compact record sizes derived from the actual template field types are **26 bytes** per `tracker.qo` heartbeat (4 floats × 4 bytes + 5 int16 × 2 bytes) and **47 bytes** per `alert.qo` event (4 floats × 4 bytes + 3 int16 × 2 bytes + 24-char string field at 25 bytes). The payload-only budget therefore supports roughly **390 heartbeat-sized Notes** (10,240 ÷ 26 bytes) or **215 alert-sized Notes** (10,240 ÷ 47 bytes) per month. Actual usable counts are lower after satellite-session protocol and framing overhead — validate against Notehub usage metrics and field measurements rather than relying on payload-only arithmetic. Under normal stationary operation, heartbeats queue every hour and batch-transmit every 4 hours (~6 outbound sessions/day), so the heartbeat budget is well within limits. **Alert storm risk:** if the equipment is under active pursuit and cellular coverage is lost, repeated `sync:true` alerts every `alert_cooldown_min` (default 5 minutes) can consume the Skylo budget quickly — 47 bytes × 288 alerts/day (5-min cadence) = 13.5 KB, exceeding the monthly satellite allowance in a single day. If satellite-only operation during a pursuit event is expected, raise `alert_cooldown_min` to 15–30 minutes via the Notehub fleet env var to protect the monthly budget. In production, consider gating satellite transmission to alerts only and enforcing a per-Note minimum satellite interval. -- **Mojo is bench-only in this POC.** The firmware does not read Mojo's LTC2959 coulomb counter over the Qwiic bus. Mojo is used only as a bench measurement instrument during validation. - -**Production next steps:** - -- Replace the standard relay with a **bistable (latching) relay** — a dual-coil type where one coil pulse sets the contact and a second pulse resets it, with no continuous coil current required to hold either state. Required characteristics: dual-coil bistable mechanism, 12 V set and reset coils, contact rating appropriate for the ignition/run-start control circuit, automotive-rated or equivalent environmental rating. Single-pulse `assertRelay` / `releaseRelay` from the Cygnet; relay contact state survives Cygnet sleep, power interruption, and wiring cuts. -- Wire the ignition-sense signal to the Notecarrier CX's ATTN-compatible AUX GPIO input and configure `card.attn` `auxgpio` mode to wake the Cygnet instantly on ignition-on without waiting for the next timer expire. -- Implement satellite data budgeting: track cumulative satellite Note count in state, suppress non-alert heartbeats from the satellite path, and enforce a minimum 15-minute satellite interval even during after-hours. -- Add GPS jamming detection: if `card.location` returns `err` repeatedly while the Notecard accelerometer shows motion, log a `gps_jamming_suspected` alert. -- Add multi-geofence support via multiple geofence Notes in a `.db` Notefile — each Note is one site with lat/lon/radius. The firmware queries all Notes and considers itself in-fence if it is within any of them. -- Consider a dedicated anti-tamper microswitch on the enclosure lid connected to an AUX GPIO, firing `enclosure_opened` as a Note if someone tries to physically remove the device. -- [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) enables wireless firmware updates to the Cygnet — essential for pushing updated geofence logic, new alert types, or threshold recipes to an entire fleet without any truck roll. +### Simplified for the POC + +The boundaries below are the scope choices of the reference design — each marks where the POC stops short of a production security device and points to the engineering work that closes the gap. + +**Staged, polled, edge-triggered immobilizer, not a continuously-held cut.** The immobilizer in this POC is a _next-wake / next-key-on-edge_ design. `NotePayloadSaveAndSleep` physically cuts the Cygnet's power during the sleep window, so the relay coil de-energizes on every sleep interval and the NC contact re-closes — briefly restoring the ignition circuit. The Cygnet re-asserts the relay only when it wakes and reads `immobilized = true`. For the default 2-minute after-hours cycle, the relay is active for only a few seconds every 2 minutes; a determined thief who turns the key during the sleep gap can crank the engine. Additionally, the relay only fires on an OFF→ON ignition edge — the previous wake must have observed ignition OFF and the current wake must observe ignition ON. If the equipment is already running when the immobilize command is staged, the firmware deliberately holds off until the next key cycle (this avoids cutting the starter circuit while the engine is actively running, per the safety guidance in §5). If the thief cycles the key fully between two Cygnet wakes (OFF→ON→OFF inside one sleep window), the firing edge is missed entirely until the next OFF→ON transition the Cygnet observes. This is a proof-of-concept staging mechanism. Production deployments require a **latching (bistable) relay** that holds its contact state with no continuous coil power and survives Cygnet sleep, power cuts, and wiring interruptions. See Production Next Steps below. + +**Ignition-sense front end is POC-only — no transient protection.** The bare 33 kΩ / 10 kΩ voltage divider provides no protection against automotive electrical transients. Load-dump events on generator sets can produce transients 40–200 V above nominal 12 V; starter-motor switching creates fast inductive spikes on the battery rail. Both can exceed the Cygnet GPIO absolute maximum and damage the MCU. A production design must add a TVS diode (e.g. 15 V unidirectional, placed before the high-side divider resistor) and an RC low-pass filter (e.g. 1 kΩ + 100 nF at the A2 node) as a minimum, or use a properly isolated sensing front end. The relay-side vehicle interface carries the same risk; the 1N4007 flyback diode protects the MOSFET drain from the relay coil's inductive spike, but does not protect the 12 V feed from upstream transients — the inline fuse in the BOM addresses overcurrent only. + +**No interrupt-driven ignition sense.** The firmware polls ignition state on each wake. A thief who turns the key and drives away within the 2-minute window between wakes will have a head start before the `ignition_on_immobilized` event fires. A hardware interrupt from the ATTN pin triggered by the ignition-sense line would wake the Cygnet instantly on key-on — the Notecarrier CX ATTN wiring and the `card.attn` `auxgpio` mode support this pattern but it is not implemented in this POC. + +**Inbound commands require cellular.** The Skylo satellite link provides primarily uplink (device-to-cloud) data. `immobilize.qi` commands from Notehub to the device require a cellular or WiFi connection to be delivered. If the equipment is already in a dead zone, the operator must wait for cellular to be restored before the command arrives. + +**Geofence decisions use cached location data, and daytime detection latency is bounded by `heartbeat_stopped_min`.** The firmware calls `card.location` to read the Notecard's most recently cached GNSS fix — it does not wait for a fresh acquisition. The cached fix age is bounded by the GNSS acquisition cadence (`card.location.mode seconds`, default `heartbeat_moving_s` = 5 minutes), so one or two after-hours wake cycles may evaluate the geofence against the same stale fix before GNSS re-acquires. A geofence breach alert will not appear until both (a) the host wakes and (b) the Notecard has a sufficiently fresh fix that places the device outside the radius. During business hours, when the host wakes every 60 minutes (default), the worst-case detection latency for a theft that starts from a parked state is approximately 60 minutes plus up to 5 minutes of GNSS fix lag. Every outbound Note includes `fix_age_s` (seconds ≥ 0, or `-1` when `card.time` is unavailable) so operators can assess the staleness of each geofence decision. + +**Geofence is a circle.** The firmware uses a Haversine-computed circle around a single center point. Irregular job-site boundaries (L-shaped lots, equipment lots separated by roads) would require multiple overlapping circles or a polygon geofence, neither of which is implemented here. + +**Single geofence.** The device stores one home location. Equipment that legitimately moves between job sites (morning deliveries, weekend staging) will generate false geofence breach alerts unless the operator updates `fence_lat` / `fence_lon` in Notehub ahead of each move. + +**No tamper detection.** The firmware does not detect cable cutting, enclosure intrusion, or GPS jamming. A motivated thief who locates and removes the tracker, jams the antenna, or removes the equipment battery before the solar reserve is depleted will defeat this POC design. + +**Satellite data budget.** The Notecard for Skylo includes 10 KB of Skylo data per month. Compact record sizes derived from the actual template field types are **26 bytes** per `tracker.qo` heartbeat (4 floats × 4 bytes + 5 int16 × 2 bytes) and **47 bytes** per `alert.qo` event (4 floats × 4 bytes + 3 int16 × 2 bytes + 24-char string field at 25 bytes). The payload-only budget therefore supports roughly **390 heartbeat-sized Notes** (10,240 ÷ 26 bytes) or **215 alert-sized Notes** (10,240 ÷ 47 bytes) per month. Actual usable counts are lower after satellite-session protocol and framing overhead — validate against Notehub usage metrics and field measurements rather than relying on payload-only arithmetic. Under normal stationary operation, heartbeats queue every hour and batch-transmit every 4 hours (~6 outbound sessions/day), so the heartbeat budget is well within limits. **Alert storm risk:** if the equipment is under active pursuit and cellular coverage is lost, repeated `sync:true` alerts every `alert_cooldown_min` (default 5 minutes) can consume the Skylo budget quickly — 47 bytes × 288 alerts/day (5-min cadence) = 13.5 KB, exceeding the monthly satellite allowance in a single day. If satellite-only operation during a pursuit event is expected, raise `alert_cooldown_min` to 15–30 minutes via the Notehub fleet env var to protect the monthly budget. In production, consider gating satellite transmission to alerts only and enforcing a per-Note minimum satellite interval. + +**Mojo is bench-only in this POC.** The firmware does not read Mojo's LTC2959 coulomb counter over the Qwiic bus. Mojo is used only as a bench measurement instrument during validation. + +### Production Next Steps + +The engineering work that turns this into a production security device follows, roughly from the most critical hardware change to fleet management. + +**A bistable (latching) relay** replaces the standard relay: a dual-coil type where one coil pulse sets the contact and a second pulse resets it, with no continuous coil current required to hold either state. Required characteristics are a dual-coil bistable mechanism, 12 V set and reset coils, a contact rating appropriate for the ignition/run-start control circuit, and an automotive-rated or equivalent environmental rating. Single-pulse `assertRelay` / `releaseRelay` from the Cygnet drives it, and the relay contact state survives Cygnet sleep, power interruption, and wiring cuts. + +**Interrupt-driven ignition sense** eliminates the polling gap: wire the ignition-sense signal to the Notecarrier CX's ATTN-compatible AUX GPIO input and configure `card.attn` `auxgpio` mode to wake the Cygnet instantly on ignition-on without waiting for the next timer expire. + +**Satellite data budgeting** protects the monthly allowance: track cumulative satellite Note count in state, suppress non-alert heartbeats from the satellite path, and enforce a minimum 15-minute satellite interval even during after-hours. + +**GPS jamming detection** catches an active countermeasure: if `card.location` returns `err` repeatedly while the Notecard accelerometer shows motion, log a `gps_jamming_suspected` alert. + +**Multi-geofence support** handles equipment that legitimately moves: store multiple geofence Notes in a `.db` Notefile — each Note is one site with lat/lon/radius — and have the firmware query all Notes and consider itself in-fence if it is within any of them. + +**A dedicated anti-tamper microswitch** on the enclosure lid connected to an AUX GPIO fires `enclosure_opened` as a Note if someone tries to physically remove the device. + +**[Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/)** enables wireless firmware updates to the Cygnet — essential for pushing updated geofence logic, new alert types, or threshold recipes to an entire fleet without any truck roll. ## 12. Summary diff --git a/65-off-grid-livestock-water-tank-monitor/README.md b/65-off-grid-livestock-water-tank-monitor/README.md index 49754e9a..a67e3288 100644 --- a/65-off-grid-livestock-water-tank-monitor/README.md +++ b/65-off-grid-livestock-water-tank-monitor/README.md @@ -459,23 +459,39 @@ If the Mojo trace shows continuous multi-mA draw with no idle transitions, the h This reference design is a single-tank monitor that works on a pole next to a stock tank — not a multi-tank irrigation controller, not a herd-level analytics platform, not a polar-region satellite design. The list below names the boundaries that come with that scope so a rancher or integrator can see exactly where the design ends and where production work begins. -**Simplified for this reference design:** - -- **Satellite antenna siting is site-specific.** The NOTE-NBGLWX Skylo path requires a clear, unobstructed view of the equator-facing sky (southern sky in the northern hemisphere; northern sky in the southern hemisphere). Tank sites in valleys, near tree lines, or adjacent to structures that block the horizon toward the equator may have degraded satellite performance or no satellite link at all. Survey the site for equator-facing sky exposure before selecting this design for a satellite-dependent deployment. For sites that require Iridium coverage (polar regions, sites where Skylo GEO coverage does not reach), a different satellite module is needed. -- **Satellite data budget.** A deployment that is frequently on the satellite path should monitor satellite data consumption in the Notehub usage dashboard. Consult the [Blues pricing page](https://blues.com/pricing/) for current satellite data allotments and applicable usage terms. -- **Manual calibration.** `tank_depth_mm` and `sensor_min_mm` must be measured and entered in Notehub per installation. A production design would include a commissioning sequence that auto-measures and stores these values during the first fill cycle. -- **Single-phase current sensing.** The CT clamps around one conductor. Three-phase deep-well pump motors (common in high-volume agricultural wells) need three CTs and a firmware change to sum the three RMS values. -- **No pump fault-to-start detection.** The firmware detects when the pump IS running (current above threshold) but cannot determine whether the pump SHOULD be running. Adding a float-switch digital input on a Cygnet GPIO would enable a "pump failed to start" alert pattern — float says the tank needs water but no pump current is detected. -- **No local sample history.** The Notecard queues Notes for multi-day transmission if both cellular and satellite are unavailable, but the firmware keeps only the current summary window in RAM. A device reset (lightning strike, power interruption) clears the in-progress accumulator and loses the partial window's data. -- **Mojo is bench-validation equipment.** The firmware does not read the Mojo's LTC2959 coulomb counter over I²C at runtime; `alerts` is the only meta-field in the summary. Adding a `mojo_mah` field for fleet-level power telemetry is a straightforward extension. - -**Production next steps:** -- Float-switch input on a digital GPIO for "pump should be running but isn't" detection. -- Over-the-air firmware updates via [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) — critical for a device that lives in a pasture for years between physical access. -- Three-phase CT support (A1, A4, A5 for three CTs; A3 is occupied by the battery-divider PMOS enable; firmware sums three RMS values into a single `pump_amps` field). -- Per-device commissioning wizard: a "first-boot setup mode" that guides the installer through measuring and storing calibration values before entering normal operation. -- `env.get` with the `time` argument to fetch environment variables only when they have changed since the last sync, reducing I²C overhead on each wake. -- Satellite data usage monitoring: a Notehub route or environment variable feedback loop that alerts operators when satellite data consumption approaches the plan's included allotment. +### Simplified for this reference design + +Each of the simplifications below is a deliberate scope choice — a place where a production rancher or integrator will want to add a sensor, a calibration step, or an integration once the basic single-tank monitor is proven in the field. + +**Satellite antenna siting is site-specific.** The NOTE-NBGLWX Skylo path requires a clear, unobstructed view of the equator-facing sky (southern sky in the northern hemisphere; northern sky in the southern hemisphere). Tank sites in valleys, near tree lines, or adjacent to structures that block the horizon toward the equator may have degraded satellite performance or **no satellite link at all**. Survey the site for equator-facing sky exposure before selecting this design for a satellite-dependent deployment. For sites that require Iridium coverage (polar regions, sites where Skylo GEO coverage does not reach), a different satellite module is needed. + +**Satellite data budget** deserves attention on any deployment that is frequently on the satellite path: monitor satellite data consumption in the Notehub usage dashboard, and consult the [Blues pricing page](https://blues.com/pricing/) for current satellite data allotments and applicable usage terms. + +**Manual calibration** is required at commissioning. `tank_depth_mm` and `sensor_min_mm` must be measured and entered in Notehub per installation. A production design would include a commissioning sequence that auto-measures and stores these values during the first fill cycle. + +**Single-phase current sensing** is all the CT provides, since it clamps around one conductor. Three-phase deep-well pump motors (common in high-volume agricultural wells) need three CTs and a firmware change to sum the three RMS values. + +**No pump fault-to-start detection.** The firmware detects when the pump *is* running (current above threshold) but cannot determine whether the pump *should* be running. Adding a float-switch digital input on a Cygnet GPIO would enable a "pump failed to start" alert pattern — float says the tank needs water but no pump current is detected. + +**No local sample history.** The Notecard queues Notes for multi-day transmission if both cellular and satellite are unavailable, but the firmware keeps only the current summary window in RAM. A device reset (lightning strike, power interruption) clears the in-progress accumulator and loses the partial window's data. + +**Mojo is bench-validation equipment.** The firmware does not read the Mojo's LTC2959 coulomb counter over I²C at runtime; `alerts` is the only meta-field in the summary. Adding a `mojo_mah` field for fleet-level power telemetry is a straightforward extension. + +### Production Next Steps + +Once a rancher is running the basic tank monitor, the following extensions are the natural progression — from the most immediately useful detection improvements toward the deeper fleet-management integrations. + +**Float-switch input on a digital GPIO** adds "pump should be running but isn't" detection, closing the gap left by current-only sensing. + +**Over-the-air firmware updates** via [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) are critical for a device that lives in a pasture for years between physical access. + +**Three-phase CT support** brings high-volume wells into scope: A1, A4, A5 for three CTs (A3 is occupied by the battery-divider PMOS enable), with firmware summing three RMS values into a single `pump_amps` field. + +**A per-device commissioning wizard** — a "first-boot setup mode" — would guide the installer through measuring and storing calibration values before entering normal operation. + +**`env.get` with the `time` argument** fetches environment variables only when they have changed since the last sync, reducing I²C overhead on each wake. + +**Satellite data usage monitoring** — a Notehub route or environment variable feedback loop — would alert operators when satellite data consumption approaches the plan's included allotment. ## 12. Summary diff --git a/66-remote-apiary-hive-health-monitor/README.md b/66-remote-apiary-hive-health-monitor/README.md index 4862562e..10e96c68 100644 --- a/66-remote-apiary-hive-health-monitor/README.md +++ b/66-remote-apiary-hive-health-monitor/README.md @@ -515,29 +515,43 @@ Because the unit is solar-powered, the absolute mAh number matters less than the This reference design covers a single hive with a single load cell, exposed PCB-style sensors, and a heuristic acoustic threshold — appropriate for a POC, not yet ready for an unattended multi-year orchard deployment. The list below names the boundaries that come with that scope, starting with the Li-ion thermal limits that matter most for outdoor apiculture, and ending with the production paths that turn this into a fleet-grade hive scale. -**Simplified for the POC:** +### Simplified for the POC -- **Li-ion battery thermal limits — safety and reliability.** Lithium-ion cells (the chemistry of the Adafruit #354 18650 pack specified in §4) must not be charged below 0 °C (lithium plating can cause an internal short) or above approximately 45 °C (accelerated cycle-life degradation and, at extremes, thermal runaway). The SparkFun Sunny Buddy (LT3652) does not use a battery-thermistor input in the default board configuration and therefore does not gate charging based on temperature. In practice this means: +The simplifications below are deliberate scope choices, starting with the Li-ion thermal limits that matter most for outdoor apiculture and ending with the single-hive boundary — each a place where a production deployment will add a safer battery, a richer model, or another sensor. + +**Li-ion battery thermal limits — safety and reliability.** Lithium-ion cells (the chemistry of the Adafruit #354 18650 pack specified in §4) **must not be charged below 0 °C** (lithium plating can cause an internal short) **or above approximately 45 °C** (accelerated cycle-life degradation and, at extremes, thermal runaway). The SparkFun Sunny Buddy (LT3652) does not use a battery-thermistor input in the default board configuration and therefore does not gate charging based on temperature. In practice this means: - **Freezing mornings:** The solar panel will attempt to charge the battery at ambient temperature. In apiaries that see sub-zero nights in spring or autumn, the charger will push current into a cold cell. At minimum this degrades capacity; in severe cases it creates a safety risk. A production deployment should use a charger with NTC thermistor supervision or add a simple low-temperature charge-inhibit circuit. - **Sun-heated enclosures:** A polycarbonate enclosure mounted on a south-facing hive stand in direct sun can easily reach 50–60 °C interior temperature on a summer afternoon, well above the safe charging ceiling. In production, use a metal enclosure with thermal mass, a sun shield or white enclosure finish, and validate temperatures with a data logger before long-term deployment. - **Capacity in cold weather:** Li-ion usable capacity drops to 60–80 % at 0 °C and further below freezing. The 4400 mAh reserve calculations in §4 assume room-temperature performance; reduce the estimated reserve accordingly for cold-climate apiaries. - **Production alternatives:** For year-round outdoor apiary deployment, consider a LiFePO₄ pack and charger/BMS combination that is specifically rated for your deployment climate. LiFePO₄ is more tolerant of elevated temperatures than Li-ion, but safe charging temperature limits vary substantially by specific chemistry, cell construction, and BMS design — many packs still prohibit charging below 0 °C without an integrated heater or a low-temperature-rated BMS. Do not apply chemistry-wide temperature numbers as a substitute for reading the datasheet of the pack you intend to use: select a battery pack and charger whose **rated** charge and discharge temperature windows cover the full seasonal temperature swing at your deployment site, and verify those limits in the manufacturer's datasheet before committing to a production build. Alternatively, use a primary lithium cell bank for winter-dormant hives where solar recharge is not required. -- **Audio analysis is heuristic, not ML-based.** Zero-crossing rate and RMS energy are established acoustic features used in beehive research, but the firmware applies simple static thresholds rather than a learned colony baseline. The `audio_anomaly` alert indicates a measurable behavioral change from a typical settled-colony acoustic signature; it is not a diagnosis. Possible causes include defensive arousal, post-swarm disruption, environmental noise (nearby equipment, traffic), or other disturbances — all of which require physical inspection to identify and distinguish. A colony that is naturally more vocal (Carniolan vs. Italian strains, hot weather, nearby traffic) may fire false positives; a colony that is genuinely quieter than the default threshold may never fire an alert even if conditions warrant attention. The `audio_zcr_alert` env var exists to tune this per-hive, but doing it well requires a few weeks of observation. More specific hypotheses about queenlessness, swarming pressure, or defensive state require richer acoustic features, a colony-specific learned baseline, and physical verification before any conclusion can be drawn. -- **Load cell calibration is manual; absolute weight requires a tare step.** The `hx711_calibration` scale factor and `hx711_zero_offset_kg` platform tare must both be set experimentally (see §9 for the procedure). Without the tare step the `weight_kg` field includes the platform dead-load and does not represent true hive mass; the relative fields (`weight_delta` and `weight_drop` alert) remain valid in both calibrated and uncalibrated states. The firmware does not implement temperature-compensation for the load cell — alloy-steel shear-beam cells drift slightly with seasonal temperature swings, which can introduce a small systematic offset over the year. -- **Single load cell, single-end weighing.** The design weighs the hive from one end, which is accurate if the load cell is centered under the stand. An uneven hive body (tilted entrance board, added super on one side) can introduce a systematic reading offset. A proper hive scale uses 4 corner cells with a Wheatstone bridge; this POC uses one cell for simplicity. -- **Satellite (NTN) operation caveats.** The same Notecard for Skylo runs the same firmware everywhere, but when it falls back to the satellite link the NTN path has operational characteristics to plan for. The device must complete at least one successful Notehub sync over cellular or WiFi before NTN transmissions will work — the Notecard needs registered templates, time, and location data to find satellites efficiently, so a unit deployed directly in a cellular dead zone will not transmit until it can be briefly brought into terrestrial coverage. Over satellite, a `sync:true` alert is prioritized for the next Skylo session but locating a satellite and completing transmission takes several minutes (not seconds); each Note must stay within the NTN 256-byte maximum (the compact templates here do); and each inbound env-var sync consumes ~50 bytes of the bundled 10 KB satellite allocation, which is why `inbound` defaults to weekly. The `MAIN` antenna must be outdoors with an unobstructed sky view (northern hemisphere: southern sky toward the equator) for the satellite link to work. Skylo coverage is region-dependent — verify coverage for your deployment area (see [satellite best practices](https://dev.blues.io/starnote/satellite-best-practices/)). -- **No audio recording.** The firmware computes features only; no raw audio is stored or transmitted. Diagnosing a specific anomaly from the cloud requires a follow-up physical inspection. The feature scores narrow down the likely cause but do not replace the beekeeper's judgment. -- **Mojo is bench-only in this POC.** The firmware does not read the Mojo's LTC2959 coulomb counter over I2C; it is used only as a bench instrument to validate power draw during development. Adding a `batt_mah` field to the daily summary is straightforward. -- **Single hive per device.** One Notecarrier CX manages one hive. A yard with 50 hives needs 50 units; a multi-drop I2C bus with individually addressed sensors and a single Notecard handling an entire yard is a reasonable production extension. - -**Production next steps:** - -- Per-colony audio baseline learning: record a rolling 30-day ZCR distribution per hive and alert only on deviations beyond two standard deviations from that colony's own baseline, rather than a fixed threshold. -- Multi-cell weight platform: four corner cells in a full Wheatstone bridge for platform-grade accuracy and elimination of tilt errors. -- 4-wire cable waterproofing: pot the load cell cable exit and all external sensor penetrations with marine-grade epoxy for years-long outdoor service. -- Varroa mite proxy: some research groups have identified spectral signatures in the 100–300 Hz band correlated with high Varroa loads. Adding a narrow-band FFT bin to the audio features would surface this indicator without additional hardware. -- Outboard DFU: [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) enables shipping new host firmware images to an entire yard fleet over cellular — bug fixes, improved audio scoring algorithms, new threshold logic, or support for additional sensors — without a truck roll to each hive. Operational thresholds and calibration values are already handled today through Notehub environment variables; ODFU addresses the separate need to update the compiled firmware logic itself. +**Audio analysis is heuristic, not ML-based.** Zero-crossing rate and RMS energy are established acoustic features used in beehive research, but the firmware applies simple static thresholds rather than a learned colony baseline. The `audio_anomaly` alert indicates a measurable behavioral change from a typical settled-colony acoustic signature; **it is not a diagnosis.** Possible causes include defensive arousal, post-swarm disruption, environmental noise (nearby equipment, traffic), or other disturbances — all of which require physical inspection to identify and distinguish. A colony that is naturally more vocal (Carniolan vs. Italian strains, hot weather, nearby traffic) may fire false positives; a colony that is genuinely quieter than the default threshold may never fire an alert even if conditions warrant attention. The `audio_zcr_alert` env var exists to tune this per-hive, but doing it well requires a few weeks of observation. More specific hypotheses about queenlessness, swarming pressure, or defensive state require richer acoustic features, a colony-specific learned baseline, and physical verification before any conclusion can be drawn. + +**Load cell calibration is manual; absolute weight requires a tare step.** The `hx711_calibration` scale factor and `hx711_zero_offset_kg` platform tare must both be set experimentally (see §9 for the procedure). Without the tare step the `weight_kg` field includes the platform dead-load and does not represent true hive mass; the relative fields (`weight_delta` and `weight_drop` alert) remain valid in both calibrated and uncalibrated states. The firmware does not implement temperature-compensation for the load cell — alloy-steel shear-beam cells drift slightly with seasonal temperature swings, which can introduce a small systematic offset over the year. + +**Single load cell, single-end weighing.** The design weighs the hive from one end, which is accurate if the load cell is centered under the stand. An uneven hive body (tilted entrance board, added super on one side) can introduce a systematic reading offset. A proper hive scale uses 4 corner cells with a Wheatstone bridge; this POC uses one cell for simplicity. + +**Satellite (NTN) operation caveats.** The same Notecard for Skylo runs the same firmware everywhere, but when it falls back to the satellite link the NTN path has operational characteristics to plan for. The device must complete at least one successful Notehub sync over cellular or WiFi before NTN transmissions will work — the Notecard needs registered templates, time, and location data to find satellites efficiently, so a unit deployed directly in a cellular dead zone will not transmit until it can be briefly brought into terrestrial coverage. Over satellite, a `sync:true` alert is prioritized for the next Skylo session but locating a satellite and completing transmission takes several minutes (not seconds); each Note must stay within the **NTN 256-byte maximum** (the compact templates here do); and each inbound env-var sync consumes ~50 bytes of the bundled 10 KB satellite allocation, which is why `inbound` defaults to weekly. The `MAIN` antenna must be outdoors with an unobstructed sky view (northern hemisphere: southern sky toward the equator) for the satellite link to work. Skylo coverage is region-dependent — verify coverage for your deployment area (see [satellite best practices](https://dev.blues.io/starnote/satellite-best-practices/)). + +**No audio recording.** The firmware computes features only; no raw audio is stored or transmitted. Diagnosing a specific anomaly from the cloud requires a follow-up physical inspection. The feature scores narrow down the likely cause but do not replace the beekeeper's judgment. + +**Mojo is bench-only in this POC.** The firmware does not read the Mojo's LTC2959 coulomb counter over I2C; it is used only as a bench instrument to validate power draw during development. Adding a `batt_mah` field to the daily summary is straightforward. + +**Single hive per device.** One Notecarrier CX manages one hive. A yard with 50 hives needs 50 units; a multi-drop I2C bus with individually addressed sensors and a single Notecard handling an entire yard is a reasonable production extension. + +### Production Next Steps + +Once a yard is running the basic hive scale, the following extensions turn it into a fleet-grade instrument — roughly from the most immediately useful accuracy gains toward the deepest analytics and fleet-update capabilities. + +**Per-colony audio baseline learning** records a rolling 30-day ZCR distribution per hive and alerts only on deviations beyond two standard deviations from that colony's own baseline, rather than a fixed threshold. + +**A multi-cell weight platform** — four corner cells in a full Wheatstone bridge — delivers platform-grade accuracy and eliminates tilt errors. + +**4-wire cable waterproofing** pots the load cell cable exit and all external sensor penetrations with marine-grade epoxy for years-long outdoor service. + +**A Varroa mite proxy** is within reach: some research groups have identified spectral signatures in the 100–300 Hz band correlated with high Varroa loads. Adding a narrow-band FFT bin to the audio features would surface this indicator without additional hardware. + +**Outboard DFU** via [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) enables shipping new host firmware images to an entire yard fleet over cellular — bug fixes, improved audio scoring algorithms, new threshold logic, or support for additional sensors — without a truck roll to each hive. Operational thresholds and calibration values are already handled today through Notehub environment variables; ODFU addresses the separate need to update the compiled firmware logic itself. ## 12. Summary diff --git a/68-cnc-machine-spindle-load-cycle-time-tracker/README.md b/68-cnc-machine-spindle-load-cycle-time-tracker/README.md index 3443f097..1110f3d6 100644 --- a/68-cnc-machine-spindle-load-cycle-time-tracker/README.md +++ b/68-cnc-machine-spindle-load-cycle-time-tracker/README.md @@ -406,43 +406,53 @@ Confirm: (a) idle current between syncs is in the µA range (ensures the device This reference design is deliberately scoped to the moment the OEM's service technician needs most: from shipping crate to first usable telemetry on a single CNC, in an afternoon, without a single conversation with the shop's IT department. A few details were left simple to keep that path clean — each is documented below, along with what the production hardening looks like. -**Simplified for this reference design:** +### Simplified for this reference design -- **Active alarm register only; transient alarms between polls are invisible.** The firmware reads the CNC controller's *currently active* alarm-code holding register once per `sample_minutes` poll. It does **not** read a fault-history log, alarm queue, or event recorder — most controllers maintain such a log internally, but standard Modbus TCP interfaces rarely expose it. Any alarm that asserts and clears entirely within one poll interval is never observed, produces no `cnc_alarm.qo` Note, and is not counted in `alarm_count` in the hourly summary. The `alarm_count` field therefore reflects the number of *observed* active-alarm transitions during the window, not a complete record of every fault the controller encountered. This is not equivalent to reading the controller's internal fault history. For comprehensive fault logging, access the controller's native alarm log directly — via the operator panel, vendor software, or (where supported) a proprietary interface such as Fanuc FOCAS or Siemens OPC-UA. The practical consequence: increase `sample_minutes` and the probability of missing a brief alarm rises proportionally; keep the poll interval at 1 minute to minimize (but not eliminate) the gap. +Each of the simplifications below is a deliberate scope choice — a place where a production deployment will validate a vendor register map, add configurability, or harden a comms path once the basic single-CNC monitor is proven. -- **Feed-rate override as a proxy for feed rate.** The firmware reads register N+1 of the six-register block and interprets it as **feed-rate override percentage** — the operator-set multiplier applied to the programmed feed rate, typically 0–150 %. This is not the same as actual feed rate in engineering units (mm/min or in/min). Engineering-unit feed rate is rarely exposed over Modbus TCP on typical CNC controllers: most vendors reserve that value for internal NC interpolation and either do not map it to a Modbus register or require a proprietary protocol to access it (e.g., Fanuc FOCAS, Siemens OPC-UA). Feed-rate override is a useful production proxy — it surfaces the operator behavior described in §1 (over-riding the programmed rate on finishing passes) and is sufficient for the EaaS monitoring use case, but it is not a substitute for engineering-unit feed-rate telemetry in a rigorous Performance calculation. The `feed_override_pct_mean` field in `cnc_summary.qo` is named accordingly; downstream analytics should document this distinction. +**Active alarm register only; transient alarms between polls are invisible.** The firmware reads the CNC controller's *currently active* alarm-code holding register once per `sample_minutes` poll. It does **not** read a fault-history log, alarm queue, or event recorder — most controllers maintain such a log internally, but standard Modbus TCP interfaces rarely expose it. Any alarm that asserts and clears entirely within one poll interval is never observed, produces no `cnc_alarm.qo` Note, and is not counted in `alarm_count` in the hourly summary. The `alarm_count` field therefore reflects the number of *observed* active-alarm transitions during the window, not a complete record of every fault the controller encountered. This is not equivalent to reading the controller's internal fault history. For comprehensive fault logging, access the controller's native alarm log directly — via the operator panel, vendor software, or (where supported) a proprietary interface such as Fanuc FOCAS or Siemens OPC-UA. The practical consequence: increase `sample_minutes` and the probability of missing a brief alarm rises proportionally; keep the poll interval at 1 minute to minimize (but not eliminate) the gap. -- **`sample_minutes` must not exceed `report_minutes`, and ideally must divide it evenly.** `run_min` and `idle_min` in `cnc_summary.qo` are computed by adding `sample_minutes` to the appropriate accumulator on every successful poll. Two invariants must hold for those totals to be valid. First, `sample_minutes` ≤ `report_minutes` — otherwise a single poll adds more minutes than the entire report window, producing run/idle counts that exceed the window duration. Second, `report_minutes` should be a whole-number multiple of `sample_minutes` (e.g., `sample_minutes=5, report_minutes=60`) — otherwise the run+idle total will be less than the window duration even when the machine is continuously active, because the accumulator increments in fixed steps that do not land exactly on the report boundary. The firmware enforces the first invariant by clamping `sample_minutes` down to `report_minutes` in `fetchEnvOverrides()` and logging a warning to Serial. The second invariant is advisory: non-divisible combinations are accepted with a Serial warning but produce approximate run/idle totals. Configure fleet environment variables with divisible pairs. +**Feed-rate override as a proxy for feed rate.** The firmware reads register N+1 of the six-register block and interprets it as **feed-rate override percentage** — the operator-set multiplier applied to the programmed feed rate, typically 0–150 %. This is not the same as actual feed rate in engineering units (mm/min or in/min). Engineering-unit feed rate is rarely exposed over Modbus TCP on typical CNC controllers: most vendors reserve that value for internal NC interpolation and either do not map it to a Modbus register or require a proprietary protocol to access it (e.g., Fanuc FOCAS, Siemens OPC-UA). Feed-rate override is a useful production proxy — it surfaces the operator behavior described in §1 (over-riding the programmed rate on finishing passes) and is sufficient for the EaaS monitoring use case, but it is not a substitute for engineering-unit feed-rate telemetry in a rigorous Performance calculation. The `feed_override_pct_mean` field in `cnc_summary.qo` is named accordingly; downstream analytics should document this distinction. -- **Demo register map only.** The firmware reads six contiguous 16-bit holding registers starting at address 256, with fixed 0.1-unit scaling. Real CNC controllers differ on: addressing convention (0-based wire-level vs. Fanuc PLC notation vs. Siemens DBx addressing); per-register scaling; signedness; 32-bit cycle counters spanning two registers with vendor-specific word order; and which registers are even exposed over Modbus vs. proprietary protocol (Fanuc FOCAS, Siemens OPC-UA, Haas NGC). Each vendor requires a validated register map before this design can be deployed to production machines. +**`sample_minutes` must not exceed `report_minutes`, and ideally must divide it evenly.** `run_min` and `idle_min` in `cnc_summary.qo` are computed by adding `sample_minutes` to the appropriate accumulator on every successful poll. Two invariants must hold for those totals to be valid. First, `sample_minutes` ≤ `report_minutes` — otherwise a single poll adds more minutes than the entire report window, producing run/idle counts that exceed the window duration. Second, `report_minutes` should be a whole-number multiple of `sample_minutes` (e.g., `sample_minutes=5, report_minutes=60`) — otherwise the run+idle total will be less than the window duration even when the machine is continuously active, because the accumulator increments in fixed steps that do not land exactly on the report boundary. The firmware enforces the first invariant by clamping `sample_minutes` down to `report_minutes` in `fetchEnvOverrides()` and logging a warning to Serial. The second invariant is advisory: non-divisible combinations are accepted with a Serial warning but produce approximate run/idle totals. Configure fleet environment variables with divisible pairs. -- **IP addressing is hardcoded.** The CNC server IP and OPTA local IP are compile-time `#define`s. A production deployment needs either a web-based local configuration UI, an in-panel DIP-switch scheme, or env-var parsing of dotted-decimal IP strings — none of which are implemented here. +**Demo register map only.** The firmware reads six contiguous 16-bit holding registers starting at address 256, with fixed 0.1-unit scaling. Real CNC controllers differ on: addressing convention (0-based wire-level vs. Fanuc PLC notation vs. Siemens DBx addressing); per-register scaling; signedness; 32-bit cycle counters spanning two registers with vendor-specific word order; and which registers are even exposed over Modbus vs. proprietary protocol (Fanuc FOCAS, Siemens OPC-UA, Haas NGC). Each vendor requires a validated register map before this design can be deployed to production machines. -- **Operator-change events are best-effort, not guaranteed.** The firmware detects operator-ID transitions by comparing consecutive register reads and immediately emits a `cnc_operator.qo` Note on each change. Because `sendOperatorChange()` does not retry on failure, a transient I²C or cellular comms outage can drop an individual transition Note. The hourly `cnc_summary.qo` carries the most recently observed operator ID as a window-close snapshot — it does not capture all transitions that occurred during the window, and any transition that occurs and reverts between polls is never recorded. Per-operator session durations and cumulative utilization derived from summary Notes are therefore approximate and cannot substitute for durable session accounting. As with all register-based reads, the `operator_id` field is only as reliable as the controller's implementation: Fanuc 0i-MF exposes operator ID in the PMC area; Siemens SINUMERIK exposes it via OPC-UA rather than Modbus; some controllers have no external operator-identity interface at all. Where unavailable, `operator_id` will be 0 on every sample. +**IP addressing is hardcoded.** The CNC server IP and OPTA local IP are compile-time `#define`s. A production deployment needs either a web-based local configuration UI, an in-panel DIP-switch scheme, or env-var parsing of dotted-decimal IP strings — none of which are implemented here. -- **`cycle_count` is authoritative; `avg_cycle_sec` is a heuristic.** `cycle_count` in `cnc_summary.qo` is the per-window **delta** of the controller's own cumulative cycle-count holding register, computed with unsigned 16-bit subtraction of consecutive register reads. It captures every cycle that increments the controller's register, including cycles that complete entirely within a single poll interval, which edge detection alone cannot see. Counter wrap (65535 → 0) is handled correctly; a mid-session controller reset that drops the counter by more than 32767 cannot be distinguished from a natural wrap and would inflate one window's delta (an accepted corner case given the rarity of such resets). +**Operator-change events are best-effort, not guaranteed.** The firmware detects operator-ID transitions by comparing consecutive register reads and immediately emits a `cnc_operator.qo` Note on each change. Because `sendOperatorChange()` does not retry on failure, a transient I²C or cellular comms outage can drop an individual transition Note. The hourly `cnc_summary.qo` carries the most recently observed operator ID as a window-close snapshot — it does not capture all transitions that occurred during the window, and any transition that occurs and reverts between polls is never recorded. Per-operator session durations and cumulative utilization derived from summary Notes are therefore approximate and cannot substitute for durable session accounting. As with all register-based reads, the `operator_id` field is only as reliable as the controller's implementation: Fanuc 0i-MF exposes operator ID in the PMC area; Siemens SINUMERIK exposes it via OPC-UA rather than Modbus; some controllers have no external operator-identity interface at all. Where unavailable, `operator_id` will be 0 on every sample. + +**`cycle_count` is authoritative; `avg_cycle_sec` is a heuristic.** `cycle_count` in `cnc_summary.qo` is the per-window **delta** of the controller's own cumulative cycle-count holding register, computed with unsigned 16-bit subtraction of consecutive register reads. It captures every cycle that increments the controller's register, including cycles that complete entirely within a single poll interval, which edge detection alone cannot see. Counter wrap (65535 → 0) is handled correctly; a mid-session controller reset that drops the counter by more than 32767 cannot be distinguished from a natural wrap and would inflate one window's delta (an accepted corner case given the rarity of such resets). `avg_cycle_sec`, by contrast, is an edge-timing heuristic: the firmware watches `cycleState` transitions (1 → non-1) and measures elapsed wall-clock time between them using `millis()`. Two systematic limitations apply. **Missed short cycles:** any cycle that starts and finishes within a single poll interval is invisible to the edge detector; those cycles are excluded from `avg_cycle_sec` even though they are counted in `cycle_count`. On fast-cycle jobs (cycle time shorter than `sample_minutes`), `avg_cycle_sec` is biased toward the longer, observable cycles. **Timing granularity:** accuracy is bounded by the sample period (1 minutes by default), not the controller's internal timer. Treat `avg_cycle_sec` as a first-order estimate, not a certified measurement. The mapping of `cycleState == 1` to "program running" is vendor-specific and must be verified against each target CNC model before relying on `avg_cycle_sec`. -- **Quality component of OEE is absent.** OEE = Availability × Performance × Quality. This design provides the raw data for Availability (run/idle minutes) and the device-side inputs for Performance (cycle count and average cycle time, transmitted in `cnc_summary.qo`). However, the comparison of average cycle time against an expected target must be configured entirely in the downstream analytics layer today — `expected_cycle_sec` is stored in device config for future use but is not evaluated in firmware nor transmitted in any Note. Quality — the ratio of conforming parts to total parts — requires a downstream measurement (CMM output, vision inspection, or operator scrap entry) that Modbus cannot supply. +**Quality component of OEE is absent.** OEE = Availability × Performance × Quality. This design provides the raw data for Availability (run/idle minutes) and the device-side inputs for Performance (cycle count and average cycle time, transmitted in `cnc_summary.qo`). However, the comparison of average cycle time against an expected target must be configured entirely in the downstream analytics layer today — `expected_cycle_sec` is stored in device config for future use but is not evaluated in firmware nor transmitted in any Note. Quality — the ratio of conforming parts to total parts — requires a downstream measurement (CMM output, vision inspection, or operator scrap entry) that Modbus cannot supply. + +**Single CNC per OPTA.** The firmware polls one Modbus slave ID. A multi-machine cell with a shared Modbus gateway could support multiple IDs by round-robin polling, but that complicates the per-machine summary bookkeeping and is out of scope here. + +**No Modbus writes.** This is intentional and non-negotiable for this reference design. Writing setpoints to a CNC (feed override, spindle speed, program selection, M-codes) involves machine safety, interlocks, and functional safety certification that are entirely outside the scope of a monitoring-only device. + +**Modbus TCP reconnection is simple.** The firmware reconnects on every failed transaction. A production hardening would add exponential backoff, a connection health watchdog, and a per-session keep-alive to detect stale TCP connections before the next poll. + +**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. Host firmware updates are local-only via USB-C for the current Wireless for OPTA hardware. + +### Production Next Steps + +Taking this monitor toward a production fleet means validating vendor-specific register maps, adding field configurability, and closing the remaining OEE loop. The following extensions are the natural progression, roughly from the most immediately useful toward the most integration-dependent. + +**Vendor-specific register-map builds** are what most deployments will need first: Fanuc 30i/31i/32i (Series 30), Siemens SINUMERIK 840D sl (via OPC-UA adapter), Mitsubishi M80/M800, Haas NGC — each with correct addressing, scaling, and protocol translation where Modbus TCP is not natively available. -- **Single CNC per OPTA.** The firmware polls one Modbus slave ID. A multi-machine cell with a shared Modbus gateway could support multiple IDs by round-robin polling, but that complicates the per-machine summary bookkeeping and is out of scope here. +**IP addressing via Notehub environment variables** (string dotted-decimal parsing) or a local web configurator served from the OPTA on first-boot removes the compile-time `#define` constraint. -- **No Modbus writes.** This is intentional and non-negotiable for this reference design. Writing setpoints to a CNC (feed override, spindle speed, program selection, M-codes) involves machine safety, interlocks, and functional safety certification that are entirely outside the scope of a monitoring-only device. +**32-bit cycle counter support** reads two consecutive registers and assembles them with correct vendor byte order. -- **Modbus TCP reconnection is simple.** The firmware reconnects on every failed transaction. A production hardening would add exponential backoff, a connection health watchdog, and a per-session keep-alive to detect stale TCP connections before the next poll. +**Native elapsed-cycle-timer reads** replace the heuristic `cycleState` edge-detection used for `avg_cycle_sec` with a read of the controller's own elapsed-cycle-timer register (where exposed by the vendor). This removes the timing bias introduced by poll-interval granularity and the dependency on vendor-specific `cycleState` semantics. `cycle_count` already uses the controller's cumulative register; this step completes the transition for the average timing field. -- **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. Host firmware updates are local-only via USB-C for the current Wireless for OPTA hardware. +**OEE Quality component integration** via an inbound Notefile (`cnc_quality.qi`) that receives scrap/conforming counts from a CMM or vision system closes the OEE loop on the device. -**Production next steps:** +**Per-machine baseline learning** accumulates a 30-day spindle-load-vs-feed-rate operating envelope and triggers `spindle_overload` against the machine's own learned curve rather than a static percentage. -- Vendor-specific register-map builds: Fanuc 30i/31i/32i (Series 30), Siemens SINUMERIK 840D sl (via OPC-UA adapter), Mitsubishi M80/M800, Haas NGC — each with correct addressing, scaling, and protocol translation where Modbus TCP is not natively available. -- IP addressing via Notehub environment variables (string dotted-decimal parsing) or a local web configurator served from the OPTA on first-boot. -- 32-bit cycle counter support: read two consecutive registers and assemble with correct vendor byte order. -- Native elapsed-cycle-timer reads: replace the heuristic `cycleState` edge-detection used for `avg_cycle_sec` with a read of the controller's own elapsed-cycle-timer register (where exposed by the vendor). This removes the timing bias introduced by poll-interval granularity and the dependency on vendor-specific `cycleState` semantics. `cycle_count` already uses the controller's cumulative register; this step completes the transition for the average timing field. -- OEE Quality component integration via an inbound Notefile (`cnc_quality.qi`) that receives scrap/conforming counts from a CMM or vision system, closing the OEE loop on the device. -- Per-machine baseline learning: accumulate a 30-day spindle-load-vs-feed-rate operating envelope and trigger `spindle_overload` against the machine's own learned curve rather than a static percentage. -- Wire ODFU to the OPTA's BOOT/RESET pins for over-the-air host updates once the AUX path is available. +**Wiring ODFU to the OPTA's BOOT/RESET pins** enables over-the-air host updates once the AUX path is available. ## 13. Summary diff --git a/69-injection-molding-shot-to-shot-process-monitor/README.md b/69-injection-molding-shot-to-shot-process-monitor/README.md index 9bd9091e..007a8142 100644 --- a/69-injection-molding-shot-to-shot-process-monitor/README.md +++ b/69-injection-molding-shot-to-shot-process-monitor/README.md @@ -446,29 +446,45 @@ The Mojo reports cumulative mAh to the Notecard at 1% accuracy over the Qwiic bu This reference design optimizes for a retrofit that a process engineer can install in an afternoon — no mold modification, no controller modification, no plant-network conversation. A few details were intentionally left simple so that path stays clean; each is documented below alongside the production hardening that closes the gap. -**Simplified for this reference design:** +### Simplified for this reference design -- **Hydraulic injection pressure, not in-cavity pressure.** This design measures hydraulic injection pressure at the injection cylinder's manifold block using a standard 4–20 mA strain-gauge transducer. It does not measure in-cavity pressure, which requires a mold-mounted piezoelectric transducer installed through a dedicated sensor port in the mold (either an existing port or one machined for that purpose). Hydraulic pressure is the upstream forcing function applied by the injection unit; cavity pressure is the actual polymer pressure inside the mold cavity. The two differ by nozzle, gate, and runner losses that vary with resin, temperature, and wear. For shot-to-shot consistency monitoring and trend detection where the hydraulic-to-cavity relationship is reasonably stable, hydraulic pressure is a practical and accessible signal. For applications that require direct cavity pressure (closed-loop pack control, high-precision medical or optical parts), a mold-mounted piezoelectric transducer with appropriate charge amplifier and signal conditioning is required. See the scope note at the top of this document. +Each of the simplifications below is a deliberate scope choice — a place where a production deployment will add a persistent counter, a faster sampler, per-cavity tracking, or richer process logic once the basic single-sensor retrofit is proven. -- **Cycle counter resets on power loss.** `g_cycle_count` is a RAM-only variable. The `cycle` field in every Note is a per-boot-session shot sequence number — it resets to zero on every power loss or reboot. It is not a persistent lifetime part counter. For cumulative production counting in a downstream system, use Notehub event timestamps as the canonical ordering key. A production enhancement would persist `g_cycle_count` to the STM32's internal flash (using HAL_FLASH_Program) or to a small external EEPROM, with writes batched (e.g. every 100 shots) to stay well within flash endurance limits. +**Hydraulic injection pressure, not in-cavity pressure.** This design measures hydraulic injection pressure at the injection cylinder's manifold block using a standard 4–20 mA strain-gauge transducer. It does not measure in-cavity pressure, which requires a mold-mounted piezoelectric transducer installed through a dedicated sensor port in the mold (either an existing port or one machined for that purpose). Hydraulic pressure is the upstream forcing function applied by the injection unit; cavity pressure is the actual polymer pressure inside the mold cavity. The two differ by nozzle, gate, and runner losses that vary with resin, temperature, and wear. For shot-to-shot consistency monitoring and trend detection where the hydraulic-to-cavity relationship is reasonably stable, hydraulic pressure is a practical and accessible signal. For applications that require direct cavity pressure (closed-loop pack control, high-precision medical or optical parts), a mold-mounted piezoelectric transducer with appropriate charge amplifier and signal conditioning is required. See the scope note at the top of this document. -- **Pressure range is POC-level.** The default 0–2,000 PSI range suits benchtop and lab hydraulic circuits but may be insufficient for production injection machines, where hydraulic injection pressures often exceed this range. Deploying on a higher-pressure circuit requires a transducer rated for the actual maximum hydraulic pressure — update `max_pressure_psi` to match and confirm the manifold fitting and transducer pressure ratings before installation. -- **20 Hz shot capture is POC-level.** The firmware samples at 20 Hz (50 milliseconds per sample), which is sufficient for extracting the five summary features used here but is too coarse to capture the fine structure of the fill waveform. Fast injection molding machines — particularly those with fill times under 200 milliseconds or rapid gate-seal transients — may require 100–1000 Hz sampling to faithfully characterize fill dynamics and detect peak-pressure spikes. Achieving higher rates on the Cygnet would require SPI DMA, double-buffering, and a deeper profile buffer. -- **Profile waveform is not transmitted.** The firmware captures the pressure and temperature profile in RAM and extracts features from it, but only the five features are sent to Notehub. The raw profile arrays are discarded after each shot. A production system that needs SPC waveform analysis or golden-sample comparison would need to transmit the profile itself, but at 2,048 samples × 8 bytes × 2,880 shots per day, transmitting raw profiles is a very different data volume problem. -- **Single sensor per shot.** One pressure transducer and one thermocouple. Multi-cavity molds (two-cavity, four-cavity, family molds) would need one transducer per cavity plus a firmware extension to track per-cavity features independently. -- **Gate-seal detection is heuristic.** Pack-phase end is detected when pressure drops to 50% of peak. Real-world molds may have a different ratio depending on gate geometry and resin rheology. The `GATE_SEAL_FRAC` constant in firmware is the tuning point for this. -- **Shot trigger is pressure-only.** Some machine controllers output a digital shot-in-progress signal on their I/O board. Wiring that signal to a digital input pin and using it as the primary trigger (rather than the pressure threshold) would give more precise shot-boundary timing. The firmware's pressure-threshold approach is a practical alternative for installations where the machine's I/O is not accessible. -- **No shot-to-shot baseline tracking.** The alert thresholds are static (set by env var). A production quality system would maintain a rolling baseline for each feature and alert on *deviation from the process baseline* rather than fixed limits, automatically adapting after intentional process changes. -- **Mojo is bench-validation only.** The firmware does not read the Mojo's coulomb counter over Qwiic at runtime. Adding a mAh field to the periodic `shot.qo` Note is a straightforward extension if fleet-level energy telemetry becomes valuable. +**Cycle counter resets on power loss.** `g_cycle_count` is a RAM-only variable. The `cycle` field in every Note is a per-boot-session shot sequence number — **it resets to zero on every power loss or reboot.** It is not a persistent lifetime part counter. For cumulative production counting in a downstream system, use Notehub event timestamps as the canonical ordering key. A production enhancement would persist `g_cycle_count` to the STM32's internal flash (using HAL_FLASH_Program) or to a small external EEPROM, with writes batched (e.g. every 100 shots) to stay well within flash endurance limits. -**Production next steps:** +**Pressure range is POC-level.** The default 0–2,000 PSI range suits benchtop and lab hydraulic circuits but may be insufficient for production injection machines, where hydraulic injection pressures often exceed this range. Deploying on a higher-pressure circuit requires a transducer rated for the actual maximum hydraulic pressure — update `max_pressure_psi` to match and confirm the manifold fitting and transducer pressure ratings before installation. -- Persistent cycle counter: batch-write `g_cycle_count` to STM32 internal flash or an external EEPROM every 100 shots so the lifetime shot tally survives power cycling; expose the persisted count as a separate `total_cycle` field in the `shot.qo` Note body. -- Per-cavity monitoring: extend the data model to carry a `cavity_id` field and wire one transducer per cavity; the Notecarrier CX has A0–A5 available for expansion. -- Waveform capture for golden-sample comparison: implement a `TRANSMIT_WAVEFORM` mode (triggered once per N shots or on command from a `_cmd.qi` Notefile) that sends a base64-encoded mini-profile for offline SPC. -- Process change detection: compute an exponentially weighted moving average (EWMA) baseline for `peak_psi` and `fill_ms` on-device and alert only when a feature deviates from its EWMA by more than a configurable sigma band. -- Field-upgradeable firmware via [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) so the OEM can push threshold-logic updates across the fleet without a site visit. -- Thermocouple fault-bit handling and internal-reference validation: the MAX31855 32-bit SPI word contains three fault flags (open-circuit, short-to-GND, short-to-VCC) in bits 2:0 and 12 bits of cold-junction (board-level) reference temperature in bits 15:4 (0.0625 °C per LSB). The firmware checks the fault flags and **excludes faulted temperature samples from the shot averages**, but the shot Note is still emitted regardless — when no valid temperature samples were collected across an entire shot (e.g. a disconnected or shorted probe), `temp_avg_c` and `cool_c_s` both appear as `0.0` in the payload. As noted in §7, this sentinel is ambiguous: it cannot be distinguished from a mold legitimately near ambient temperature. A production improvement would either suppress the shot Note when the probe is entirely faulted, or replace the zero-valued sentinel with a value outside the physical temperature range (e.g. `-999.0`) so downstream analytics can tell a faulted probe from a cold mold. The internal-reference temperature bits are read and discarded — sanity-checking that value against the expected ambient range (e.g. 15–55 °C for a machine room) can catch board wiring faults and cold-junction compensation anomalies before they produce incorrect thermocouple readings. +**20 Hz shot capture is POC-level.** The firmware samples at 20 Hz (50 milliseconds per sample), which is sufficient for extracting the five summary features used here but is too coarse to capture the fine structure of the fill waveform. Fast injection molding machines — particularly those with fill times under 200 milliseconds or rapid gate-seal transients — may require 100–1000 Hz sampling to faithfully characterize fill dynamics and detect peak-pressure spikes. Achieving higher rates on the Cygnet would require SPI DMA, double-buffering, and a deeper profile buffer. + +**Profile waveform is not transmitted.** The firmware captures the pressure and temperature profile in RAM and extracts features from it, but only the five features are sent to Notehub. The raw profile arrays are discarded after each shot. A production system that needs SPC waveform analysis or golden-sample comparison would need to transmit the profile itself, but at 2,048 samples × 8 bytes × 2,880 shots per day, transmitting raw profiles is a very different data volume problem. + +**Single sensor per shot.** One pressure transducer and one thermocouple. Multi-cavity molds (two-cavity, four-cavity, family molds) would need one transducer per cavity plus a firmware extension to track per-cavity features independently. + +**Gate-seal detection is heuristic.** Pack-phase end is detected when pressure drops to 50% of peak. Real-world molds may have a different ratio depending on gate geometry and resin rheology. The `GATE_SEAL_FRAC` constant in firmware is the tuning point for this. + +**Shot trigger is pressure-only.** Some machine controllers output a digital shot-in-progress signal on their I/O board. Wiring that signal to a digital input pin and using it as the primary trigger (rather than the pressure threshold) would give more precise shot-boundary timing. The firmware's pressure-threshold approach is a practical alternative for installations where the machine's I/O is not accessible. + +**No shot-to-shot baseline tracking.** The alert thresholds are static (set by env var). A production quality system would maintain a rolling baseline for each feature and alert on *deviation from the process baseline* rather than fixed limits, automatically adapting after intentional process changes. + +**Mojo is bench-validation only.** The firmware does not read the Mojo's coulomb counter over Qwiic at runtime. Adding a mAh field to the periodic `shot.qo` Note is a straightforward extension if fleet-level energy telemetry becomes valuable. + +### Production Next Steps + +Once a process engineer is running the basic shot monitor, the following extensions harden it into a production quality tool — roughly from the most immediately useful toward the most analytics-dependent. + +**A persistent cycle counter** batch-writes `g_cycle_count` to STM32 internal flash or an external EEPROM every 100 shots so the lifetime shot tally survives power cycling; expose the persisted count as a separate `total_cycle` field in the `shot.qo` Note body. + +**Per-cavity monitoring** extends the data model to carry a `cavity_id` field and wires one transducer per cavity; the Notecarrier CX has A0–A5 available for expansion. + +**Waveform capture for golden-sample comparison** implements a `TRANSMIT_WAVEFORM` mode (triggered once per N shots or on command from a `_cmd.qi` Notefile) that sends a base64-encoded mini-profile for offline SPC. + +**Process change detection** computes an exponentially weighted moving average (EWMA) baseline for `peak_psi` and `fill_ms` on-device and alerts only when a feature deviates from its EWMA by more than a configurable sigma band. + +**Field-upgradeable firmware** via [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) lets the OEM push threshold-logic updates across the fleet without a site visit. + +**Thermocouple fault-bit handling and internal-reference validation** closes a known gap: the MAX31855 32-bit SPI word contains three fault flags (open-circuit, short-to-GND, short-to-VCC) in bits 2:0 and 12 bits of cold-junction (board-level) reference temperature in bits 15:4 (0.0625 °C per LSB). The firmware checks the fault flags and **excludes faulted temperature samples from the shot averages**, but the shot Note is still emitted regardless — when no valid temperature samples were collected across an entire shot (e.g. a disconnected or shorted probe), `temp_avg_c` and `cool_c_s` both appear as `0.0` in the payload. As noted in §7, this sentinel is ambiguous: it cannot be distinguished from a mold legitimately near ambient temperature. A production improvement would either suppress the shot Note when the probe is entirely faulted, or replace the zero-valued sentinel with a value outside the physical temperature range (e.g. `-999.0`) so downstream analytics can tell a faulted probe from a cold mold. The internal-reference temperature bits are read and discarded — sanity-checking that value against the expected ambient range (e.g. 15–55 °C for a machine room) can catch board wiring faults and cold-junction compensation anomalies before they produce incorrect thermocouple readings. ## 12. Summary diff --git a/70-trailer-manufacturer-connected-trailer-platform/README.md b/70-trailer-manufacturer-connected-trailer-platform/README.md index b2fd6dbc..8419e6e0 100644 --- a/70-trailer-manufacturer-connected-trailer-platform/README.md +++ b/70-trailer-manufacturer-connected-trailer-platform/README.md @@ -694,9 +694,11 @@ The Notecard idle figure is the only Blues-published power specification for the This reference platform delivers the three sensor paths a trailer OEM can stand up against real hardware on day one — cargo-air temperature, door, and GPS — plus firmware scaffolding for the two paths whose engineering work is genuinely outside the scope of a reference design. The list below is the honest accounting of what's still in front of any OEM that wants to ship this as a commercial product, framed by transport and protocol choice rather than apologized for. -**Outside this reference build's scope:** +### Outside This Reference Build's Scope -- **Reefer telemetry transport: pick one of three, then implement.** The firmware reserves `Serial1` for a reefer-telemetry source and ships with a simplified POC decode in `drainReeferUart()`. The reference assumption is J2497 PLC, but in practice three transports are realistic, and the choice changes the engineering effort substantially. The firmware's `note.add` pipeline is identical for all three; only the decode function in `drainReeferUart()` and the upstream physical interface differ. +The items below are the honest accounting of what's still in front of any OEM that wants to ship this as a commercial product — framed by transport and protocol choice rather than apologized for. + +**Reefer telemetry transport: pick one of three, then implement.** The firmware reserves `Serial1` for a reefer-telemetry source and ships with a simplified POC decode in `drainReeferUart()`. The reference assumption is J2497 PLC, but in practice three transports are realistic, and the choice changes the engineering effort substantially. The firmware's `note.add` pipeline is identical for all three; only the decode function in `drainReeferUart()` and the upstream physical interface differ. | Transport | Physical interface | Pros | Cons | Engineering required | |---|---|---|---|---| @@ -705,23 +707,40 @@ This reference platform delivers the three sensor paths a trailer OEM can stand | **J1939 over CAN** | CAN bus on the reefer unit (where exposed) | Standardized PGN-based message structure; richer telemetry (fault codes, run hours, fuel) than serial diagnostics; same bus standard widely used elsewhere on the vehicle | Requires a host with an accessible CAN controller (the STM32L433 in this build does not break out CAN on the Notecarrier CX headers. See the dedicated J1939/CAN limitation below); automotive-qualified CAN transceiver; J1939 PGN decode | Confirm host CAN pin availability or change host; add AEC-Q100 transceiver (e.g., TJA1051T/3/1J); implement J1939 PGN decode for the reefer's message set | For a first prototype against an actual reefer unit, the **vendor-proprietary serial** path is the lowest-risk first milestone — it lands on the same `Serial1` UART the reference build already exercises, and most modern reefers (Thermo King SLXe, Carrier X4 7700) expose it. The J2497 path is a credible long-term option if power-line carrier is a strategic constraint (no chassis-side connector, multi-OEM unification on a single physical interface), but expect to fund a multi-quarter effort across coupling-board hardware, stack licensing, and OEM message mapping before producing any real data. -- **TPMS protocol is vendor-specific.** The firmware models four tire positions with a simplified generic packet format. Commercial trailer TPMS systems (PressurePro, Doran 360, Continental VDO, TST 507) each use proprietary 315/433 MHz message structures with different tire ID encoding, pressure scaling, and checksum algorithms. Production firmware needs to implement the chosen vendor's message decode library. -- **Four tire positions are tracked.** A 53-foot refrigerated trailer typically runs 10 or more tires on dual rear axles; the POC supports only four positions. Expanding to the full tire set requires a larger TPMS position array and a wider Note template. -- **GPS-position-delta state detection is approximate.** Comparing GPS positions at 5-minute intervals can be ambiguous in poor-sky conditions or during slow dock maneuvering. A production implementation should combine GPS position delta with the Notecard's built-in accelerometer (`card.motion.mode`) for reliable motion detection that doesn't depend on GNSS fix quality. -- **No J1939/CAN integration.** Modern reefer units expose richer telemetry — fault codes, fuel consumption, run hours, setpoint history — over J1939 CAN, not just temperature. Adding CAN to this platform requires more than a transceiver: (a) confirm that the STM32L433's CAN peripheral pins (CAN_TX/CAN_RX) are accessible on the Notecarrier CX/Cygnet headers — if not, a board redesign or an alternate host with CAN pins broken out is required; (b) once a host with accessible CAN pins is established, add an automotive-qualified CAN transceiver (e.g., TJA1051T/3/1J, AEC-Q100-qualified) between the host CAN controller and the J1939 bus; and (c) implement J1939 PGN (**Parameter Group Number**, the J1939 message identifier) decode in firmware (e.g., using an mcp_can-style library or a raw CAN driver targeting the host's bxCAN peripheral). A transceiver alone is not sufficient without a host that exposes a compatible CAN controller. -- **Skylo NTN satellite latency.** Satellite session establishment can take several minutes on initial power-up, and the Skylo NTN network imposes message-size and throughput constraints smaller than typical cellular sessions. Alert Notes sent via satellite will arrive in Notehub with higher latency than cellular. Plan monitoring workflows accordingly; Notecard for Skylo prefers cellular and falls back to satellite automatically, so this latency applies only in genuine coverage gaps. -- **No host over-the-air firmware update.** [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) requires SWD/BOOT pin access that is not exposed through the Notecarrier CX headers in this standard configuration. Production boards should route BOOT and NRST signals through a DFU header to enable fleet-wide host firmware updates without a service visit. -- **Mojo is bench tooling.** The firmware does not read the Mojo's LTC2959 coulomb counter over Qwiic. Adding a cumulative-mAh field to the summary Note is a straightforward extension that enables fleet-level power telemetry for DC dwell energy auditing. - -**Production next steps:** -- Full J2497 integration: (1) coupling board hardware (IT700, Bourns bus-coupling transformer, bus protection), (2) J2497 application-layer protocol stack from Microchip/Yitran or equivalent, (3) reefer-OEM message mapping per target reefer model under an integration agreement, and (4) field validation on target reefer-unit hardware to confirm J560 bus data availability. -- Vendor-specific TPMS decode libraries covering all tire positions on the OEM's chosen sensor brand. -- J1939 CAN interface: verify CAN_TX/CAN_RX pin accessibility on the Notecarrier CX/Cygnet (or redesign to a host with CAN pins exposed), add an AEC-Q100 automotive CAN transceiver (e.g., TJA1051T/3/1J), and implement J1939 PGN decode — for comprehensive reefer-unit telemetry (fault codes, fuel, hours). -- Accelerometer-augmented (`card.motion.mode`) motion detection for reliable parked/transit classification. -- Full 10-tire TPMS coverage for 53-foot dual-rear-axle configuration. -- USDA and FDA FSMA-compliant temperature logging: cryptographically signed records with chain-of-custody audit trail. -- Host ODFU wiring for fleet-wide firmware updates from Notehub without a truck roll. -- Humidity and CO₂ sensors for high-value perishable loads (fresh produce, pharmaceutical). + +**TPMS protocol is vendor-specific.** The firmware models four tire positions with a simplified generic packet format. Commercial trailer TPMS systems (PressurePro, Doran 360, Continental VDO, TST 507) each use proprietary 315/433 MHz message structures with different tire ID encoding, pressure scaling, and checksum algorithms, so production firmware needs to implement the chosen vendor's message decode library. + +**Four tire positions are tracked.** A 53-foot refrigerated trailer typically runs 10 or more tires on dual rear axles, but the POC supports only four positions. Expanding to the full tire set requires a larger TPMS position array and a wider Note template. + +**GPS-position-delta state detection is approximate.** Comparing GPS positions at 5-minute intervals can be ambiguous in poor-sky conditions or during slow dock maneuvering. A production implementation should combine GPS position delta with the Notecard's built-in accelerometer (`card.motion.mode`) for reliable motion detection that doesn't depend on GNSS fix quality. + +**No J1939/CAN integration.** Modern reefer units expose richer telemetry — fault codes, fuel consumption, run hours, setpoint history — over J1939 CAN, not just temperature. Adding CAN to this platform requires more than a transceiver: (a) confirm that the STM32L433's CAN peripheral pins (CAN_TX/CAN_RX) are accessible on the Notecarrier CX/Cygnet headers — if not, a board redesign or an alternate host with CAN pins broken out is required; (b) once a host with accessible CAN pins is established, add an automotive-qualified CAN transceiver (e.g., TJA1051T/3/1J, AEC-Q100-qualified) between the host CAN controller and the J1939 bus; and (c) implement J1939 PGN (**Parameter Group Number**, the J1939 message identifier) decode in firmware (e.g., using an mcp_can-style library or a raw CAN driver targeting the host's bxCAN peripheral). **A transceiver alone is not sufficient without a host that exposes a compatible CAN controller.** + +**Skylo NTN satellite latency.** Satellite session establishment can take several minutes on initial power-up, and the Skylo NTN network imposes message-size and throughput constraints smaller than typical cellular sessions, so **alert Notes sent via satellite will arrive in Notehub with higher latency than cellular.** Plan monitoring workflows accordingly; Notecard for Skylo prefers cellular and falls back to satellite automatically, so this latency applies only in genuine coverage gaps. + +**No host over-the-air firmware update.** [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) requires SWD/BOOT pin access that is not exposed through the Notecarrier CX headers in this standard configuration. Production boards should route BOOT and NRST signals through a DFU header to enable fleet-wide host firmware updates without a service visit. + +**Mojo is bench tooling.** The firmware does not read the Mojo's LTC2959 coulomb counter over Qwiic. Adding a cumulative-mAh field to the summary Note is a straightforward extension that enables fleet-level power telemetry for DC dwell energy auditing. + +### Production Next Steps + +Once the three day-one sensor paths are running against real hardware, the following extensions carry the platform toward a shippable commercial product. + +**Full J2497 integration** comprises (1) coupling board hardware (IT700, Bourns bus-coupling transformer, bus protection), (2) a J2497 application-layer protocol stack from Microchip/Yitran or equivalent, (3) reefer-OEM message mapping per target reefer model under an integration agreement, and (4) field validation on target reefer-unit hardware to confirm J560 bus data availability. + +**Vendor-specific TPMS decode libraries** cover all tire positions on the OEM's chosen sensor brand. + +**A J1939 CAN interface** requires verifying CAN_TX/CAN_RX pin accessibility on the Notecarrier CX/Cygnet (or redesigning to a host with CAN pins exposed), adding an AEC-Q100 automotive CAN transceiver (e.g., TJA1051T/3/1J), and implementing J1939 PGN decode — for comprehensive reefer-unit telemetry (fault codes, fuel, hours). + +**Accelerometer-augmented motion detection** (`card.motion.mode`) provides reliable parked/transit classification. + +**Full 10-tire TPMS coverage** supports the 53-foot dual-rear-axle configuration. + +**USDA and FDA FSMA-compliant temperature logging** adds cryptographically signed records with a chain-of-custody audit trail. + +**Host ODFU wiring** enables fleet-wide firmware updates from Notehub without a truck roll. + +**Humidity and CO₂ sensors** serve high-value perishable loads (fresh produce, pharmaceutical). ## 11. Summary diff --git a/71-legacy-diesel-generator-fleet-performance-uplift/README.md b/71-legacy-diesel-generator-fleet-performance-uplift/README.md index 41745635..27a0b6a6 100644 --- a/71-legacy-diesel-generator-fleet-performance-uplift/README.md +++ b/71-legacy-diesel-generator-fleet-performance-uplift/README.md @@ -492,24 +492,41 @@ In the field, the generator's start battery sustains the control bus through a m This reference design is deliberately scoped to the path that takes a facility manager from a generator with a Modbus port to a generator with a live cellular uplink, in well under a day, without writing anything back to the controller. A handful of details were left simple so that path stays clean; each is documented below with the production extension that closes the gap. -**Simplified for this reference design:** - -- **Register addresses, scaling, and signedness.** The defaults are illustrative for a fictional contiguous map. Each controller vendor publishes its own Modbus map; commissioning a real site means looking up actual addresses, scaling factors (oil pressure may be in 0.1 bar, hundredths of kPa, or raw integer psi), signedness (coolant temperature is already read as signed `int16_t` in the demo; oil pressure and other fields on some controllers may also be signed and require case-by-case handling), word counts (run hours on DeepSea 7000-series is a 32-bit value spanning two consecutive registers), and addressing convention (0-based wire-level vs 1-based / Modicon "40001" notation). The shipped firmware reads seven individually-addressed 16-bit registers with no scaling — production builds need vendor-specific handling. -- **Firmware-observed alarm history, not controller-internal log.** The firmware tracks its own alarm-history log: every alarm assertion and clearance it detects is appended to an 8-slot ring buffer and flushed as `gen_alarm_log.qo` at each report boundary (see §6 and §7). What remains a future enhancement is reading the controller's own internal timestamped fault log — most production controllers maintain a multi-register circular buffer of events that can include faults that pre-date the monitor's installation. Extracting that log requires a vendor-specific read sequence; see Production next steps below. -- **Sampled alarm detection, not latched.** The alarm word is polled once per `sample_minutes` (default 1 minutes). A transient fault that asserts and clears entirely between two consecutive polls will be invisible to the firmware. Controllers that do not latch faults internally require a short enough polling cadence to catch the briefest expected fault pulse; for controllers that do latch faults, reading the alarm history log (above) is the robust alternative. -- **Failure-to-start detection requires operator configuration.** The `alarm_mask_fts` variable is `0` (disabled) by default because bit positions differ across controller families. A DeepSea 7000-series uses different alarm bits than a Woodward EasyGen. The operator must look up their controller's alarm register map and set the appropriate mask. Until configured, failure-to-start events are caught by the generic `controller_alarm` alert. -- **Single controller per OPTA.** The firmware reads one Modbus slave ID. A facility with multiple generators requires one OPTA + Wireless for OPTA per generator, or a firmware extension to round-robin across slave IDs on the same bus (with per-slave stat tracking). -- **Weekly test coverage.** Hourly summaries may straddle a short weekly exercise test. A 30-minute test that starts and finishes within a single 60-minute summary window will appear in that window's data, but the start event and any transient fault that clears during the test will be visible only via the event Notefile. Production deployments could add logic to emit a summary at engine stop (end of each run event) for complete run-level granularity. -- **No Modbus writes.** The firmware is read-only. Sending remote start commands to the generator is out of scope — that requires safety analysis, E-stop wiring, and potentially functional-safety certification. -- **Continuous OPTA host draw on the start battery.** The firmware runs no sleep state — the OPTA's Cortex-M7 stays continuously awake, drawing 0.6–2.2 W on the battery-backed control bus. Panel trickle chargers handle this load under normal operation, but a site that experiences extended utility outages without generator exercise or charger input should measure the actual OPTA supply current during commissioning and verify that the site's battery capacity provides acceptable autonomy. At 12 V and worst-case 2.2 W draw (~183 mA), a 40 Ah battery sustains the monitor alone for roughly 9 days; at best-case draw the same battery extends to ~33 days. Larger batteries and 24 V systems extend autonomy proportionally. - -**Production next steps:** -- Vendor-specific register-map builds: DeepSea 7000/8000, Woodward EasyGen 3000, Kohler RDC, Caterpillar EMCP 4, Cummins PowerCommand — each with the correct addresses, scaling, signedness, and 32-bit run-hour handling for that family. -- Controller-internal alarm log readout per vendor spec (DeepSea Event Log registers, Woodward EasyGen fault record, Kohler RDC history block, etc.), supplementing the firmware-observed history with timestamped events that pre-date the monitor's installation or that occurred while the firmware was offline. -- Per-controller baseline learning: track run hours and load history per device to detect drift toward scheduled service intervals rather than waiting for a threshold breach. -- Over-the-air firmware updates via [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) so a service company can push a new register-map build to an entire fleet without a truck roll. (Note: ODFU on the OPTA requires AUX wiring that Wireless for OPTA does not currently break out; local USB-C update is the current path for host firmware changes.) -- Fuel consumption rate: derive from the rate of change in fuel level across run events. Combined with load data, this gives a fuel-per-kWh efficiency figure that accumulates across the maintenance history. -- Automatic weekly test verification: flag a `test_not_detected` event if no engine start is observed in a configurable rolling window, catching test skips before an audit or inspection. +### Simplified for this reference design + +Each item below is a place where the reference firmware keeps things deliberately generic, with the production extension that a real fleet deployment will reach for once it is running against actual controllers. + +**Register addresses, scaling, and signedness** are illustrative for a fictional contiguous map. Each controller vendor publishes its own Modbus map, so commissioning a real site means looking up actual addresses, scaling factors (oil pressure may be in 0.1 bar, hundredths of kPa, or raw integer psi), signedness (coolant temperature is already read as signed `int16_t` in the demo; oil pressure and other fields on some controllers may also be signed and require case-by-case handling), word counts (run hours on DeepSea 7000-series is a 32-bit value spanning two consecutive registers), and addressing convention (0-based wire-level vs 1-based / Modicon "40001" notation). The shipped firmware reads seven individually-addressed 16-bit registers with no scaling — **production builds need vendor-specific handling.** + +**Firmware-observed alarm history, not controller-internal log.** The firmware tracks its own alarm-history log: every alarm assertion and clearance it detects is appended to an 8-slot ring buffer and flushed as `gen_alarm_log.qo` at each report boundary (see §6 and §7). What remains a future enhancement is reading the controller's own internal timestamped fault log — most production controllers maintain a multi-register circular buffer of events that can include faults that pre-date the monitor's installation. Extracting that log requires a vendor-specific read sequence; see Production Next Steps below. + +**Sampled alarm detection, not latched.** The alarm word is polled once per `sample_minutes` (default 1 minutes), so **a transient fault that asserts and clears entirely between two consecutive polls will be invisible to the firmware.** Controllers that do not latch faults internally require a short enough polling cadence to catch the briefest expected fault pulse; for controllers that do latch faults, reading the alarm history log (above) is the robust alternative. + +**Failure-to-start detection requires operator configuration.** The `alarm_mask_fts` variable is `0` (disabled) by default because bit positions differ across controller families — a DeepSea 7000-series uses different alarm bits than a Woodward EasyGen. The operator must look up their controller's alarm register map and set the appropriate mask. Until configured, failure-to-start events are caught by the generic `controller_alarm` alert. + +**Single controller per OPTA.** The firmware reads one Modbus slave ID, so a facility with multiple generators requires one OPTA + Wireless for OPTA per generator, or a firmware extension to round-robin across slave IDs on the same bus (with per-slave stat tracking). + +**Weekly test coverage** can be straddled by an hourly summary. A 30-minute test that starts and finishes within a single 60-minute summary window will appear in that window's data, but the start event and any transient fault that clears during the test will be visible only via the event Notefile. Production deployments could add logic to emit a summary at engine stop (end of each run event) for complete run-level granularity. + +**No Modbus writes.** The firmware is read-only. Sending remote start commands to the generator is **out of scope** — that requires safety analysis, E-stop wiring, and potentially functional-safety certification. + +**Continuous OPTA host draw on the start battery** is a consequence of running no sleep state — the OPTA's Cortex-M7 stays continuously awake, drawing 0.6–2.2 W on the battery-backed control bus. Panel trickle chargers handle this load under normal operation, but a site that experiences extended utility outages without generator exercise or charger input should measure the actual OPTA supply current during commissioning and verify that the site's battery capacity provides acceptable autonomy. At 12 V and worst-case 2.2 W draw (~183 mA), a 40 Ah battery sustains the monitor alone for roughly 9 days; at best-case draw the same battery extends to ~33 days. Larger batteries and 24 V systems extend autonomy proportionally. + +### Production Next Steps + +Once a real fleet is reporting in, the following extensions are the natural progression toward a commercial-grade monitoring product. + +**Vendor-specific register-map builds** cover DeepSea 7000/8000, Woodward EasyGen 3000, Kohler RDC, Caterpillar EMCP 4, and Cummins PowerCommand — each with the correct addresses, scaling, signedness, and 32-bit run-hour handling for that family. + +**Controller-internal alarm log readout** per vendor spec (DeepSea Event Log registers, Woodward EasyGen fault record, Kohler RDC history block, etc.) supplements the firmware-observed history with timestamped events that pre-date the monitor's installation or that occurred while the firmware was offline. + +**Per-controller baseline learning** tracks run hours and load history per device to detect drift toward scheduled service intervals rather than waiting for a threshold breach. + +**Over-the-air firmware updates** via [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) let a service company push a new register-map build to an entire fleet without a truck roll. (Note: ODFU on the OPTA requires AUX wiring that Wireless for OPTA does not currently break out; local USB-C update is the current path for host firmware changes.) + +**Fuel consumption rate** can be derived from the rate of change in fuel level across run events. Combined with load data, this gives a fuel-per-kWh efficiency figure that accumulates across the maintenance history. + +**Automatic weekly test verification** flags a `test_not_detected` event if no engine start is observed in a configurable rolling window, catching test skips before an audit or inspection. ## 12. Summary diff --git a/72-solar-array-string-level-performance-dashboard/README.md b/72-solar-array-string-level-performance-dashboard/README.md index 41ebf7ad..07eba751 100644 --- a/72-solar-array-string-level-performance-dashboard/README.md +++ b/72-solar-array-string-level-performance-dashboard/README.md @@ -452,38 +452,47 @@ With the default cadence (5-minute samples, hourly sync), a healthy trace shows This reference design targets the moment a portfolio operator wants real per-string visibility on an array — soiling, shading, and bad-module signals delivered to an off-site dashboard within a single sample interval. A handful of details were left simple so the path from BOM to first event stays inside a single afternoon; each is documented below alongside the production hardening that closes the gap. -**Simplified for this reference design:** +### Simplified for this reference design -- **Per-string voltage required for full root-cause classification.** The firmware reads a `[V, I]` register pair for each string and uses the per-string voltage signature to classify root causes. This is the signal model provided by multi-MPPT string inverters where each MPPT input tracks one string, such as those implementing the [SunSpec Model 160 Multiple MPPT](https://sunspec.org/sunspec-modbus-specifications/) register model, which exposes per-MPPT voltage (DCV) and current (DCA) via Modbus RTU. Traditional string combiner boxes aggregate multiple strings onto a shared DC bus and typically expose only per-string current at the combiner's Modbus port; independent per-string voltages are not available in that topology. Against a combiner-only source the `shading` root-cause hypothesis — which classifies by operating voltage significantly lower than the fleet mean — will never fire, because every string reads the same shared bus voltage and all per-string voltage ratios equal 1.0. In that configuration all PR-threshold trips will resolve as `soiling`, `string_fault`, or `degraded` depending on the current magnitude, and the `shading` classification can never be reached. If the monitored device provides only per-string current and a single bus voltage, document this constraint for O&M personnel so that a `soiling` or `string_fault` alert is understood to also encompass undetected shading. +Each item below is a place where the reference build keeps the signal model or the hardware deliberately simple, with the production hardening that closes the gap. -- **Register-map demo only.** The firmware reads N contiguous 16-bit holding-register pairs `[V, I, V, I, …]` with fixed scaling from `reg_base`. Real string combiners and inverters from SMA, Fronius, Huawei, SolarEdge, and ABB all publish their own Modbus register maps with vendor-specific addressing conventions, scaling factors, signed/unsigned handling, and sometimes 32-bit register pairs for accumulated energy. Production deployments need a vendor-specific firmware build that implements the correct map. The environment-variable scaling factors (`string_v_scale_x100`, `string_a_scale_x1000`, `reg_base`) let a single firmware binary cover multiple sites with the same vendor, but they are not a substitute for correct implementation of the register map. +**Per-string voltage is required for full root-cause classification.** The firmware reads a `[V, I]` register pair for each string and uses the per-string voltage signature to classify root causes. This is the signal model provided by multi-MPPT string inverters where each MPPT input tracks one string, such as those implementing the [SunSpec Model 160 Multiple MPPT](https://sunspec.org/sunspec-modbus-specifications/) register model, which exposes per-MPPT voltage (DCV) and current (DCA) via Modbus RTU. Traditional string combiner boxes aggregate multiple strings onto a shared DC bus and typically expose only per-string current at the combiner's Modbus port; **independent per-string voltages are not available in that topology.** Against a combiner-only source the `shading` root-cause hypothesis — which classifies by operating voltage significantly lower than the fleet mean — will never fire, because every string reads the same shared bus voltage and all per-string voltage ratios equal 1.0. In that configuration all PR-threshold trips will resolve as `soiling`, `string_fault`, or `degraded` depending on the current magnitude, and the `shading` classification can never be reached. If the monitored device provides only per-string current and a single bus voltage, document this constraint for O&M personnel so that a `soiling` or `string_fault` alert is understood to also encompass undetected shading. -- **All monitored strings must be electrically comparable.** One device should monitor only peer strings on the same array geometry: equal module count, equal STC rating, and the same orientation, tilt, azimuth, and irradiance/temperature reference (same MPPT group and microclimate). The PR model uses `string_stc_w` as a single reference power for every monitored string, and the V/I root-cause hypothesis (shading/soiling/string_fault) uses the fleet mean of all monitored strings as its reference. On a device monitoring strings across different orientations, different MPPT groups, or unequal-length strings, normal production differences between groups will be misclassified as faults. For mixed-geometry arrays, deploy one device per homogeneous string group. +**Register-map demo only.** The firmware reads N contiguous 16-bit holding-register pairs `[V, I, V, I, …]` with fixed scaling from `reg_base`. Real string combiners and inverters from SMA, Fronius, Huawei, SolarEdge, and ABB all publish their own Modbus register maps with vendor-specific addressing conventions, scaling factors, signed/unsigned handling, and sometimes 32-bit register pairs for accumulated energy, so production deployments need a vendor-specific firmware build that implements the correct map. The environment-variable scaling factors (`string_v_scale_x100`, `string_a_scale_x1000`, `reg_base`) let a single firmware binary cover multiple sites with the same vendor, but **they are not a substitute for correct implementation of the register map.** -- **Maximum 4 strings.** `MAX_STRINGS = 4` is a compile-time constant. Utility-scale installations can have 20–30 strings per combiner. Increasing `MAX_STRINGS` grows `sizeof(AppState)` — the state blob serialised to Notecard flash each sleep cycle, and expands the `note.template` payload definition sent on first boot. The binding constraint is the STM32L433's 64 KB SRAM: `AppState`, the per-Notefile template JSON construction buffers, and the Modbus response buffer must all coexist in static and stack memory. Because the implementation uses no dynamic allocation, the risk is not heap fragmentation but a growing static footprint that leaves too little headroom for library stack frames. Scaling `MAX_STRINGS` beyond 4 requires revalidating that the combined static footprint fits within the 64 KB SRAM budget — no measured ceiling has been established for this implementation, so validate at each increment before field deployment. +**All monitored strings must be electrically comparable.** One device should monitor only peer strings on the same array geometry: equal module count, equal STC rating, and the same orientation, tilt, azimuth, and irradiance/temperature reference (same MPPT group and microclimate). The PR model uses `string_stc_w` as a single reference power for every monitored string, and the V/I root-cause hypothesis (shading/soiling/string_fault) uses the fleet mean of all monitored strings as its reference. On a device monitoring strings across different orientations, different MPPT groups, or unequal-length strings, **normal production differences between groups will be misclassified as faults.** For mixed-geometry arrays, deploy one device per homogeneous string group. -- **RS-485 interface is POC-grade only.** The SparkFun BOB-10124 (SP3485) is a non-isolated, non-surge-hardened breakout board suitable for bench and prototype use. Solar PV combiner and inverter RS-485 ports are exposed to the outdoor environment and share a ground reference with high-voltage DC bus equipment; lightning-induced transients and ground-fault currents are a realistic field hazard. Production hardware should replace the BOB-10124 with an isolated RS-485 transceiver (e.g. Analog Devices ADM2587E or similar) that provides galvanic isolation between the Cygnet UART and the RS-485 bus, and should add appropriate surge protection (TVS diodes rated for the bus, IEC 61000-4-5 Class 4 or better) on the A/B lines. The cable shield must remain single-ended bonded at the combiner/inverter chassis; proper bonding and grounding practices per IEC 62548 or NEC Article 690 are essential for outdoor PV installations. +**Maximum 4 strings.** `MAX_STRINGS = 4` is a compile-time constant, while utility-scale installations can have 20–30 strings per combiner. Increasing `MAX_STRINGS` grows `sizeof(AppState)` — the state blob serialised to Notecard flash each sleep cycle — and expands the `note.template` payload definition sent on first boot. The binding constraint is the STM32L433's 64 KB SRAM: `AppState`, the per-Notefile template JSON construction buffers, and the Modbus response buffer must all coexist in static and stack memory. Because the implementation uses no dynamic allocation, the risk is not heap fragmentation but a growing static footprint that leaves too little headroom for library stack frames. Scaling `MAX_STRINGS` beyond 4 requires revalidating that the combined static footprint fits within the 64 KB SRAM budget — no measured ceiling has been established for this implementation, so **validate at each increment before field deployment.** -- **Analog pyranometer resolution.** The Apogee SP-110-SS directly connected to A0 provides approximately 4 W/m² per ADC count at the Cygnet's 12-bit / 3.3V reference. This is adequate for coarse threshold comparisons but limits PR accuracy. Adding a single-supply rail-to-rail op-amp in a 10× non-inverting configuration between the sensor and A0 improves effective resolution to about 0.4 W/m² per count and is recommended for production deployments. Alternatively, pyranometers with Modbus RTU output (such as the IMT Si-RS485TC-T-MB, which also includes a Pt1000 module temperature channel) can replace both the SP-110-SS and the DS18B20 with a single RS-485 device on the same bus. +**RS-485 interface is POC-grade only.** The SparkFun BOB-10124 (SP3485) is a non-isolated, non-surge-hardened breakout board suitable for bench and prototype use. Solar PV combiner and inverter RS-485 ports are exposed to the outdoor environment and share a ground reference with high-voltage DC bus equipment; lightning-induced transients and ground-fault currents are a realistic field hazard. Production hardware should replace the BOB-10124 with an isolated RS-485 transceiver (e.g. Analog Devices ADM2587E or similar) that provides galvanic isolation between the Cygnet UART and the RS-485 bus, and should add appropriate surge protection (TVS diodes rated for the bus, IEC 61000-4-5 Class 4 or better) on the A/B lines. The cable shield must remain single-ended bonded at the combiner/inverter chassis; **proper bonding and grounding practices per IEC 62548 or NEC Article 690 are essential for outdoor PV installations.** -- **Single-axis temperature coefficient.** The firmware uses one `temp_coeff` value for the entire array. Bifacial modules, thin-film modules, and heterojunction (HJT) panels all have meaningfully different temperature coefficients from standard mono-PERC. The default (−0.0035 /°C) is representative for mono-PERC; adjust via `temp_coeff_per10000` for the actual module datasheet value. A per-string coefficient would require a more complex state structure. +**Analog pyranometer resolution** is adequate for coarse threshold comparisons but limits PR accuracy. The Apogee SP-110-SS directly connected to A0 provides approximately 4 W/m² per ADC count at the Cygnet's 12-bit / 3.3V reference. Adding a single-supply rail-to-rail op-amp in a 10× non-inverting configuration between the sensor and A0 improves effective resolution to about 0.4 W/m² per count and is recommended for production deployments. Alternatively, pyranometers with Modbus RTU output (such as the IMT Si-RS485TC-T-MB, which also includes a Pt1000 module temperature channel) can replace both the SP-110-SS and the DS18B20 with a single RS-485 device on the same bus. -- **No irradiance-sensor validation.** The pyranometer reading is used as-is with no cross-check. A bird dropping on the pyranometer lens or a shadow from a nearby object will cause the firmware to compute an artificially low expected power, making the PR appear high and suppressing real underperformance alerts. A second reference pyranometer or a model-based irradiance estimate (from a local weather API via a Notehub route) would catch this. +**Single-axis temperature coefficient.** The firmware uses one `temp_coeff` value for the entire array, yet bifacial modules, thin-film modules, and heterojunction (HJT) panels all have meaningfully different temperature coefficients from standard mono-PERC. The default (−0.0035 /°C) is representative for mono-PERC; adjust via `temp_coeff_per10000` for the actual module datasheet value. A per-string coefficient would require a more complex state structure. -- **Heuristic root-cause hypothesis.** The shading/soiling/string-fault classification uses simple thresholds on the ratio of each string's V and I to the fleet mean. It will misclassify strings in certain multi-fault scenarios (e.g., one string with both shading and partial soiling), and the fleet-mean reference breaks down when the majority of strings are simultaneously underperforming. Treat the hypothesis as a first-pass maintenance triage signal, not a definitive diagnosis. +**No irradiance-sensor validation.** The pyranometer reading is used as-is with no cross-check, so a bird dropping on the pyranometer lens or a shadow from a nearby object will cause the firmware to compute an artificially low expected power, making the PR appear high and **suppressing real underperformance alerts.** A second reference pyranometer or a model-based irradiance estimate (from a local weather API via a Notehub route) would catch this. -- **Single-string deployments support PR alerts only.** When `n_strings = 1`, the comparative root-cause hypotheses (`shading`, `soiling`, `string_fault`) are unavailable — there are no peer strings to compare against, so all PR-threshold trips emit as `degraded`. The device still detects when the string's PR drops below `perf_thresh_pct` and fires an immediate alert; the maintenance team must determine the root cause manually from site inspection or additional data. If root-cause classification is required for a single-string installation, a Modbus-output pyranometer with a reference string (even a single extra string of the same geometry) provides the peer comparison needed. +**Heuristic root-cause hypothesis.** The shading/soiling/string-fault classification uses simple thresholds on the ratio of each string's V and I to the fleet mean. It will misclassify strings in certain multi-fault scenarios (e.g., one string with both shading and partial soiling), and the fleet-mean reference breaks down when the majority of strings are simultaneously underperforming. **Treat the hypothesis as a first-pass maintenance triage signal, not a definitive diagnosis.** -- **Mojo is bench-validation equipment only.** The Mojo is spliced into the 5V supply rail and connected to the Notecarrier CX via a Qwiic cable to bench-validate the sleep/wake current profile during commissioning. The Notecard reads Mojo's coulomb counter / power monitor over that Qwiic connection and exposes the data via `card.power`; the application firmware does not call `card.power` on each sample cycle. The Mojo and its Qwiic cable are not deployed to the field — remove both before enclosing the assembly. Adding a runtime mAh field to the summary Note by calling `card.power` in firmware and including the result in `solar_summary.qo` is a straightforward extension if fleet-level energy-consumption telemetry is useful. +**Single-string deployments support PR alerts only.** When `n_strings = 1`, the comparative root-cause hypotheses (`shading`, `soiling`, `string_fault`) are unavailable — there are no peer strings to compare against, so all PR-threshold trips emit as `degraded`. The device still detects when the string's PR drops below `perf_thresh_pct` and fires an immediate alert; the maintenance team must determine the root cause manually from site inspection or additional data. If root-cause classification is required for a single-string installation, a Modbus-output pyranometer with a reference string (even a single extra string of the same geometry) provides the peer comparison needed. -**Production next steps:** +**Mojo is bench-validation equipment only.** The Mojo is spliced into the 5V supply rail and connected to the Notecarrier CX via a Qwiic cable to bench-validate the sleep/wake current profile during commissioning. The Notecard reads Mojo's coulomb counter / power monitor over that Qwiic connection and exposes the data via `card.power`; the application firmware does not call `card.power` on each sample cycle. The Mojo and its Qwiic cable are **not deployed to the field** — remove both before enclosing the assembly. Adding a runtime mAh field to the summary Note by calling `card.power` in firmware and including the result in `solar_summary.qo` is a straightforward extension if fleet-level energy-consumption telemetry is useful. -- Vendor-specific Modbus register-map implementations for the major inverter/combiner families (SMA SunnyBoy, Fronius Symo, SolarEdge SetApp, Huawei SUN2000) using SunSpec Model 101 (single-phase/three-phase inverter) and Model 160 (Multiple MPPT) as the standard reference. -- Increase `MAX_STRINGS` to at least 12 and validate that total static memory (AppState + template JSON buffers + library stack frames) fits within the STM32L433's 64 KB SRAM budget. -- Add a Modbus-output pyranometer+temperature combo sensor (e.g. IMT Si-RS485TC-T-MB) to consolidate three separate interfaces into one RS-485 bus. -- Implement a shadow-mask calendar: suppress shading alerts between known shadow times (calculable from GPS coordinates and sun-position math) so seasonal early-morning or late-afternoon shadows don't flood the alert channel. -- Field-upgradeable firmware via [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) so register-map recipe updates can be pushed to the fleet without a site visit. -- Per-device commissioning: record a 7-day baseline PR per string immediately after installation so the alert threshold adapts to site-specific shading and soiling patterns rather than relying on a generic default. +### Production Next Steps + +Once the basic dashboard is live, the following extensions are the natural progression toward a portfolio-grade monitoring product. + +**Vendor-specific Modbus register-map implementations** for the major inverter/combiner families (SMA SunnyBoy, Fronius Symo, SolarEdge SetApp, Huawei SUN2000) use SunSpec Model 101 (single-phase/three-phase inverter) and Model 160 (Multiple MPPT) as the standard reference. + +**Increase `MAX_STRINGS` to at least 12** and validate that total static memory (AppState + template JSON buffers + library stack frames) fits within the STM32L433's 64 KB SRAM budget. + +**A Modbus-output pyranometer+temperature combo sensor** (e.g. IMT Si-RS485TC-T-MB) consolidates three separate interfaces into one RS-485 bus. + +**A shadow-mask calendar** suppresses shading alerts between known shadow times (calculable from GPS coordinates and sun-position math) so seasonal early-morning or late-afternoon shadows don't flood the alert channel. + +**Field-upgradeable firmware** via [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) lets register-map recipe updates be pushed to the fleet without a site visit. + +**Per-device commissioning** records a 7-day baseline PR per string immediately after installation so the alert threshold adapts to site-specific shading and soiling patterns rather than relying on a generic default. ## 12. Summary diff --git a/74-returnable-container-tote-pool-tracker/README.md b/74-returnable-container-tote-pool-tracker/README.md index ad8a9903..ab766eec 100644 --- a/74-returnable-container-tote-pool-tracker/README.md +++ b/74-returnable-container-tote-pool-tracker/README.md @@ -472,31 +472,39 @@ Useful Mojo bench validation: leave the assembly running for 24 h and confirm th This reference design is scoped to bench validation and limited field trials — the fastest path from "we should track these containers" to a live cellular uplink with site-level location. A few deliberate scope choices keep that path short; each is documented below alongside the production hardening that turns a 12–24 month LiPo prototype into a multi-year deployed fleet. -**Simplified for the POC:** +### Simplified for the POC -- **LiPo battery vs. Li-SOCl₂ — primary scope constraint.** This POC build uses a rechargeable 2 Ah LiPo on the Notecarrier CX's charge-enabled power path. As discussed in [§9](#9-validation-and-testing), LiPo self-discharge limits practical service life to 12–24 months regardless of the low active-drain budget — this is the principal reason this build is documented as a bench prototype rather than a production deployment. For genuinely multi-year deployments — 3 to 5+ years between swaps — the right chemistry is Li-SOCl₂ (e.g., a D-size Tadiran TL-5930 at 3.6 V / 14.5 Ah, under 1% annual self-discharge). However, the Notecarrier CX's onboard charge IC is designed for LiPo chemistry; connecting a Li-SOCl₂ primary cell directly to the JST `LIPO` port would engage the charge circuit against a non-rechargeable cell, which is unsafe. A production deployment with Li-SOCl₂ requires a purpose-designed carrier board with no charging circuitry and a direct +VBAT input matched to the primary cell chemistry — the power path must be engineered from the ground up, not adapted from a charge-enabled design. The Notecarrier CX documented here is the right platform for prototyping and limited field trials. +Each item below is a deliberate scope choice that keeps the prototype path short, paired with the production hardening that turns a bench build into a deployed fleet. -- **Not rated for classified or explosive atmospheres.** This build uses standard commercial electronics and a LiPo battery — none of which carry ATEX, IECEx, Class I Division 2, or intrinsically safe certification. Deployments in classified or explosive atmospheres (including certain gas-cylinder and industrial-gas environments where flammable gases or vapours may be present) require a purpose-certified assembly: enclosure, battery, antenna, and all electronics must carry the appropriate hazardous-location rating. That certification scope is well beyond this POC. +**LiPo battery vs. Li-SOCl₂ is the primary scope constraint.** This POC build uses a rechargeable 2 Ah LiPo on the Notecarrier CX's charge-enabled power path. As discussed in [§9](#9-validation-and-testing), LiPo self-discharge limits practical service life to 12–24 months regardless of the low active-drain budget — this is the principal reason this build is documented as a bench prototype rather than a production deployment. For genuinely multi-year deployments — 3 to 5+ years between swaps — the right chemistry is Li-SOCl₂ (e.g., a D-size Tadiran TL-5930 at 3.6 V / 14.5 Ah, under 1% annual self-discharge). However, the Notecarrier CX's onboard charge IC is designed for LiPo chemistry; **connecting a Li-SOCl₂ primary cell directly to the JST `LIPO` port would engage the charge circuit against a non-rechargeable cell, which is unsafe.** A production deployment with Li-SOCl₂ requires a purpose-designed carrier board with no charging circuitry and a direct +VBAT input matched to the primary cell chemistry — the power path must be engineered from the ground up, not adapted from a charge-enabled design. The Notecarrier CX documented here is the right platform for prototyping and limited field trials. -- **Enclosure fit and gland rating.** The main BOM specifies the Hammond 1554C2GY (NEMA 4X / IP67, polycarbonate) for field deployment; the Hammond 1591XXBSFLBK (IP54, ABS) is listed only for bench bring-up. When adapting to a different enclosure, verify the interior cavity against the Notecarrier CX footprint (76 × 38 mm board) and the flat LiPo pack before committing — inner dimensions tighter than ~95 × 50 mm will require the board and battery to be stacked rather than laid flat. Any cable gland through which a cellular antenna pigtail exits the enclosure must be rated to the same IP level as the enclosure body; the Essentra M16 IP68 gland in the BOM satisfies this for both the 1554C2GY and any IP68-rated replacement. +**Not rated for classified or explosive atmospheres.** This build uses standard commercial electronics and a LiPo battery — none of which carry ATEX, IECEx, Class I Division 2, or intrinsically safe certification. Deployments in classified or explosive atmospheres (including certain gas-cylinder and industrial-gas environments where flammable gases or vapours may be present) require a purpose-certified assembly: enclosure, battery, antenna, and all electronics must carry the appropriate hazardous-location rating. **That certification scope is well beyond this POC.** -- **Triangulation accuracy.** Cell-tower and WiFi AP triangulation (`mode:"wifi,cell"`) is the default in this build. In AP-dense environments — warehouses, distribution centers, port terminals — the combined mode can improve accuracy to 15–200 m, more than sufficient to identify individual customer sites. In rural or outdoor areas with few APs the device falls back to cell-only, which delivers roughly 300 m to 5 km accuracy depending on tower density — still adequate for site-level identification in most cases. For applications requiring sub-50 m precision (identifying a specific dock door rather than a facility), a GPS fix via [`card.location.mode`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-location-mode) `periodic` is the upgrade path, at the cost of a GPS antenna, cold-start latency of up to a few minutes, and additional power per fix. +**Enclosure fit and gland rating** need verification when adapting the design. The main BOM specifies the Hammond 1554C2GY (NEMA 4X / IP67, polycarbonate) for field deployment; the Hammond 1591XXBSFLBK (IP54, ABS) is listed only for bench bring-up. When adapting to a different enclosure, verify the interior cavity against the Notecarrier CX footprint (76 × 38 mm board) and the flat LiPo pack before committing — inner dimensions tighter than ~95 × 50 mm will require the board and battery to be stacked rather than laid flat. Any cable gland through which a cellular antenna pigtail exits the enclosure must be rated to the same IP level as the enclosure body; the Essentra M16 IP68 gland in the BOM satisfies this for both the 1554C2GY and any IP68-rated replacement. -- **No server-side geofencing.** The POC reports locations but does not evaluate them. Alerting when a container leaves an expected zone or appears at an unexpected site is best implemented as a [Notehub JSONata route transform](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub) — comparing `where_lat`/`where_lon` against fleet-level environment variables that define site polygons and firing a webhook when a container appears outside any known site, or in the downstream fleet application. Either approach allows site boundary data to change without a firmware update. +**Triangulation accuracy** varies with the surrounding environment. Cell-tower and WiFi AP triangulation (`mode:"wifi,cell"`) is the default in this build. In AP-dense environments — warehouses, distribution centers, port terminals — the combined mode can improve accuracy to 15–200 m, more than sufficient to identify individual customer sites. In rural or outdoor areas with few APs the device falls back to cell-only, which delivers roughly 300 m to 5 km accuracy depending on tower density — still adequate for site-level identification in most cases. For applications requiring sub-50 m precision (identifying a specific dock door rather than a facility), a GPS fix via [`card.location.mode`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-location-mode) `periodic` is the upgrade path, at the cost of a GPS antenna, cold-start latency of up to a few minutes, and additional power per fix. -- **No transit-leg pairing.** The firmware reports `"departed"` and `"arrived"` events independently; correlating them into origin-destination legs (Container #4712 left Supplier A at 08:15 and arrived at Customer B at 14:42) requires logic in the fleet application, which has the context to make the association. +**No server-side geofencing.** The POC reports locations but does not evaluate them. Alerting when a container leaves an expected zone or appears at an unexpected site is best implemented as a [Notehub JSONata route transform](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub) — comparing `where_lat`/`where_lon` against fleet-level environment variables that define site polygons and firing a webhook when a container appears outside any known site, or in the downstream fleet application. Either approach allows site boundary data to change without a firmware update. -- **Single wake reason.** On a timer wake the firmware does not distinguish between "timer fired because heartbeat_hours elapsed" and "timer fired because the device reset." Both result in a heartbeat Note. A `card.time` call could confirm elapsed wall-clock time and refine the `reason` field, but at the cost of an additional I²C round trip on every timer wake. +**No transit-leg pairing.** The firmware reports `"departed"` and `"arrived"` events independently; correlating them into origin-destination legs (Container #4712 left Supplier A at 08:15 and arrived at Customer B at 14:42) requires logic in the fleet application, which has the context to make the association. -- **No tamper or shock detection.** The accelerometer could detect sustained unusual orientations or sharp impact signatures. These are viable firmware extensions that this POC does not implement. +**Single wake reason.** On a timer wake the firmware does not distinguish between "timer fired because heartbeat_hours elapsed" and "timer fired because the device reset" — both result in a heartbeat Note. A `card.time` call could confirm elapsed wall-clock time and refine the `reason` field, but at the cost of an additional I²C round trip on every timer wake. -**Production next steps:** +**No tamper or shock detection.** The accelerometer could detect sustained unusual orientations or sharp impact signatures. These are viable firmware extensions that this POC does not implement. -- Custom carrier board with a direct +VBAT input (no charging circuitry) for a D-cell Li-SOCl₂ primary, with the Notecarrier CX form factor used only for prototyping. -- Voltage-variable sync via [`hub.set voutbound/vinbound`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) — the Notecard natively reduces cellular session frequency as the battery drains once `voutbound`/`vinbound` voltage thresholds are configured. The shipped firmware issues `hub.set` with fixed `outbound`/`inbound` only; enabling voltage-variable sync requires either (a) a small firmware change to add `voutbound`/`vinbound` fields to the `hub.set` call and verify those fields are not overwritten by the `hub.set` reissue that fires when `heartbeat_hours` changes, or (b) a one-time commissioning step in the blues.dev In-Browser Terminal to set the fields directly on each device. -- Server-side geofencing via Notehub JSONata: compare `where_lat`/`where_lon` against fleet-level environment variables defining site polygons; fire a route to a webhook when a container appears outside any known site. -- [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) for over-the-air host firmware updates to the entire fleet — essential for a tracker that may be affixed to a container for 5+ years without a hands-on service visit. -- Per-container asset metadata (container ID, type, tare weight, inspection due date) stored as Notehub device-level environment variables and appended to events by a JSONata route transform, so the fleet portal can display rich container profiles without requiring the tracker to store or transmit that data itself. +### Production Next Steps + +Taking this prototype toward a multi-year deployed fleet means re-engineering the power path and layering on the cloud-side intelligence a real tracking operation needs. + +**A custom carrier board** with a direct +VBAT input (no charging circuitry) supports a D-cell Li-SOCl₂ primary, with the Notecarrier CX form factor used only for prototyping. + +**Voltage-variable sync** via [`hub.set voutbound/vinbound`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) lets the Notecard natively reduce cellular session frequency as the battery drains once `voutbound`/`vinbound` voltage thresholds are configured. The shipped firmware issues `hub.set` with fixed `outbound`/`inbound` only; enabling voltage-variable sync requires either (a) a small firmware change to add `voutbound`/`vinbound` fields to the `hub.set` call and verify those fields are not overwritten by the `hub.set` reissue that fires when `heartbeat_hours` changes, or (b) a one-time commissioning step in the blues.dev In-Browser Terminal to set the fields directly on each device. + +**Server-side geofencing** via Notehub JSONata compares `where_lat`/`where_lon` against fleet-level environment variables defining site polygons, firing a route to a webhook when a container appears outside any known site. + +**[Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/)** provides over-the-air host firmware updates to the entire fleet — essential for a tracker that may be affixed to a container for 5+ years without a hands-on service visit. + +**Per-container asset metadata** (container ID, type, tare weight, inspection due date) stored as Notehub device-level environment variables and appended to events by a JSONata route transform lets the fleet portal display rich container profiles without requiring the tracker to store or transmit that data itself. ## 12. Summary diff --git a/75-heavy-equipment-hours-of-use-utilization-tracker/README.md b/75-heavy-equipment-hours-of-use-utilization-tracker/README.md index 45db125b..e5c50c62 100644 --- a/75-heavy-equipment-hours-of-use-utilization-tracker/README.md +++ b/75-heavy-equipment-hours-of-use-utilization-tracker/README.md @@ -465,32 +465,41 @@ If the baseline is continuously 10+ mA, the Cygnet is not sleeping — confirm t This is a reference build, not a finished fleet product — a few things are deliberately scoped down so the core idea (engine-hour billing from a magnetic stick-on with no wiring) can stay readable. The list below calls out where you'll want to harden the design before it goes on a thousand machines, then points at the natural production extensions. -**Simplified for this POC:** +### Simplified for this POC -- **Vibration classifier is heuristic, not trained.** The RMS + CV algorithm distinguishes engine idle from transport vibration well for diesel construction equipment at typical idle RPMs. On gasoline-powered equipment with smoother idle, CV can be lower and may overlap with transport characteristics at certain speeds. On very rough terrain, engine-running CV can creep above the default threshold. The `vib_run_mg` and `vib_cv_max` environment variables are the tuning knobs, but they require per-equipment-class calibration from logged data to dial in precisely. A production deployment would instrument a representative sample of each equipment type, log raw RMS/CV values over several shifts, and derive per-class threshold pairs. +Each of the following is a deliberate shortcut that keeps the reference build readable, with a note on what a production deployment would do instead. -- **Hour accumulation granularity is 30 seconds.** Each wake adds `SAMPLE_INTERVAL_SEC / 3600` hours to the running bucket if the previous state was RUNNING. A start event that occurs midway through a 30-second sleep interval will be captured on the *next* wake — worst-case rounding error is one sample interval (30 seconds). For billing purposes this is typically acceptable; for sub-minute precision, reduce `SAMPLE_INTERVAL_SEC` to 10 at the cost of ~3× higher host wake frequency. +**The vibration classifier is heuristic, not trained.** The RMS + CV algorithm distinguishes engine idle from transport vibration well for diesel construction equipment at typical idle RPMs. On gasoline-powered equipment with smoother idle, CV can be lower and may overlap with transport characteristics at certain speeds, and on very rough terrain engine-running CV can creep above the default threshold. The `vib_run_mg` and `vib_cv_max` environment variables are the tuning knobs, but they **require per-equipment-class calibration from logged data** to dial in precisely. A production deployment would instrument a representative sample of each equipment type, log raw RMS/CV values over several shifts, and derive per-class threshold pairs. -- **First run session after power-on may report `session_min: 0` if the Notecard has not yet acquired valid time.** `getEpoch()` returns 0 when `card.time` has no cellular or GPS sync. The firmware guards against recording a start timestamp of 0 — if the device transitions to RUNNING before time is valid, `run_session_start` is left at 0 and the closing `engine_stop` or `transport_start` event will carry `session_min: 0`, making it unusable as a standalone billing record. Subsequent sessions, once the Notecard has acquired time, compute correctly. For the affected cold-start window, the daily `equip_summary.qo` still accumulates run hours through the hour-meter buckets regardless of session boundaries — use the summary to reconcile any gap. Billing integrations should treat a `session_min: 0` on the first event after a device power-cycle as an incomplete record. +**Hour accumulation granularity is 30 seconds.** Each wake adds `SAMPLE_INTERVAL_SEC / 3600` hours to the running bucket if the previous state was RUNNING. A start event that occurs midway through a 30-second sleep interval will be captured on the *next* wake, so worst-case rounding error is one sample interval (30 seconds). For billing purposes this is typically acceptable; for sub-minute precision, reduce `SAMPLE_INTERVAL_SEC` to 10 at the cost of ~3× higher host wake frequency. -- **Persistent software hour counter, not hardware-backed.** The `run_h_total` field in `PersistState` is persisted to Notecard flash on each sleep. If the Notecard is replaced or factory-reset, the lifetime total is lost. A production implementation should store the authoritative total server-side in Notehub (e.g., as a device-level environment variable updated on each `engine_stop` event) so it survives hardware replacement. +**The first run session after power-on may report `session_min: 0`** if the Notecard has not yet acquired valid time. `getEpoch()` returns 0 when `card.time` has no cellular or GPS sync. The firmware guards against recording a start timestamp of 0 — if the device transitions to RUNNING before time is valid, `run_session_start` is left at 0 and the closing `engine_stop` or `transport_start` event will carry `session_min: 0`, making it unusable as a standalone billing record. Subsequent sessions, once the Notecard has acquired time, compute correctly. For the affected cold-start window, the daily `equip_summary.qo` still accumulates run hours through the hour-meter buckets regardless of session boundaries — use the summary to reconcile any gap. Billing integrations should treat a `session_min: 0` on the first event after a device power-cycle as an **incomplete record**. -- **No geofence alerting in application firmware.** Geofence exit is handled autonomously by the Notecard (`_track.qo`) — the application firmware only configures the fence center via `card.location.mode`. The resulting `_track.qo` Notes contain location data but no application-level label. A production deployment should add a Notehub route that triggers an alert when `_track.qo` appears outside the fence window. +**The persistent hour counter is software-based, not hardware-backed.** The `run_h_total` field in `PersistState` is persisted to Notecard flash on each sleep. If the Notecard is replaced or factory-reset, **the lifetime total is lost.** A production implementation should store the authoritative total server-side in Notehub (e.g., as a device-level environment variable updated on each `engine_stop` event) so it survives hardware replacement. -- **Geofence cannot be centered at the equator or prime meridian.** The firmware uses `geofence_lat = 0.0` and `geofence_lon = 0.0` as the "not configured" sentinel, and refuses to apply a fence if either coordinate is within ≈0.0001° of zero (the check is `fabsf(lat) > 0.0001f` and `fabsf(lon) > 0.0001f`). A deployment precisely on the equator (lat ≈ 0°) or the prime meridian (lon ≈ 0°), for example, sites in southern Ghana, the Republic of Congo, or the English Channel — cannot use the geofence feature as currently implemented. To lift this restriction, replace the 0,0 sentinel with an explicit enable flag (e.g., a `geofence_enable` environment variable set to `1`) and allow lat/lon to take any in-range value including zero. +**There is no geofence alerting in the application firmware.** Geofence exit is handled autonomously by the Notecard (`_track.qo`) — the application firmware only configures the fence center via `card.location.mode`. The resulting `_track.qo` Notes contain location data but no application-level label. A production deployment should add a Notehub route that triggers an alert when `_track.qo` appears outside the fence window. -- **Solar panel sizing is for temperate climates.** A 1W panel + 2000 mAh LiPo provides adequate runtime in most regions with ≥3 effective sun-hours per day. At higher latitudes in winter, or when the enclosure is mounted on a shaded chassis location, a larger panel (2–5W) or a higher-capacity LiPo (5000 mAh) may be needed. The `bat_v` field in `equip_summary.qo` is the early-warning indicator — a steadily declining voltage over multiple days indicates harvest deficit. +**The geofence cannot be centered at the equator or prime meridian.** The firmware uses `geofence_lat = 0.0` and `geofence_lon = 0.0` as the "not configured" sentinel, and refuses to apply a fence if either coordinate is within ≈0.0001° of zero (the check is `fabsf(lat) > 0.0001f` and `fabsf(lon) > 0.0001f`). A deployment precisely on the equator (lat ≈ 0°) or the prime meridian (lon ≈ 0°), for example, sites in southern Ghana, the Republic of Congo, or the English Channel — cannot use the geofence feature as currently implemented. To lift this restriction, replace the 0,0 sentinel with an explicit enable flag (e.g., a `geofence_enable` environment variable set to `1`) and allow lat/lon to take any in-range value including zero. -- **Mojo is not read in firmware.** The firmware does not poll the Mojo's LTC2959 coulomb counter over Qwiic. Adding a `mojo_mah` field to `equip_summary.qo` is a straightforward extension if fleet-level energy telemetry is valuable to the operator. +**Solar panel sizing is for temperate climates.** A 1W panel + 2000 mAh LiPo provides adequate runtime in most regions with ≥3 effective sun-hours per day. At higher latitudes in winter, or when the enclosure is mounted on a shaded chassis location, a larger panel (2–5W) or a higher-capacity LiPo (5000 mAh) may be needed. The `bat_v` field in `equip_summary.qo` is the early-warning indicator — a steadily declining voltage over multiple days indicates harvest deficit. -**Production next steps:** +**Mojo is not read in firmware.** The firmware does not poll the Mojo's LTC2959 coulomb counter over Qwiic. Adding a `mojo_mah` field to `equip_summary.qo` is a straightforward extension if fleet-level energy telemetry is valuable to the operator. -- Per-equipment-class threshold calibration: deploy a "learning mode" firmware build that logs raw RMS/CV data at 1-minute intervals for several shifts before switching to production classification. -- Lifetime hour counter persistence in Notehub environment variables to survive device replacement. -- Geofence-exit alert route in Notehub: a route that fires a webhook when a `_track.qo` Note appears with a location outside the configured fence, enabling unauthorized-move notifications. -- [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) for over-the-air firmware updates to the Cygnet host — allows threshold algorithm improvements and new features without a technician visit to each machine. -- Tamper detection: an abrupt, very high-amplitude single-axis spike (e.g., magnet base being removed) can be distinguished from equipment vibration and flagged as a `tamper` event. -- Multi-sensor fusion: pairing with an engine temperature sensor (NTC thermistor on the exhaust manifold) or a current clamp on the alternator output would provide a second independent confirmation of engine state, improving classifier reliability on unusual equipment types. +### Production Next Steps + +These are the natural extensions for hardening the tracker across a real fleet, from data-driven tuning through over-the-air updates and richer sensing. + +**Per-equipment-class threshold calibration** would deploy a "learning mode" firmware build that logs raw RMS/CV data at 1-minute intervals for several shifts before switching to production classification. + +**Lifetime hour counter persistence** in Notehub environment variables would let the running total survive device replacement. + +**A geofence-exit alert route in Notehub** would fire a webhook when a `_track.qo` Note appears with a location outside the configured fence, enabling unauthorized-move notifications. + +**Over-the-air firmware updates** via [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) to the Cygnet host would allow threshold algorithm improvements and new features without a technician visit to each machine. + +**Tamper detection** would distinguish an abrupt, very high-amplitude single-axis spike (e.g., the magnet base being removed) from equipment vibration and flag it as a `tamper` event. + +**Multi-sensor fusion** — pairing with an engine temperature sensor (NTC thermistor on the exhaust manifold) or a current clamp on the alternator output — would provide a second independent confirmation of engine state, improving classifier reliability on unusual equipment types. ## 12. Summary diff --git a/76-untethered-trailer-chassis-fleet-tracker/README.md b/76-untethered-trailer-chassis-fleet-tracker/README.md index 2d7c2c55..5e4629d0 100644 --- a/76-untethered-trailer-chassis-fleet-tracker/README.md +++ b/76-untethered-trailer-chassis-fleet-tracker/README.md @@ -556,34 +556,41 @@ For the arrival event, Note the **asymmetric detection latency**: once the track A reference design has to draw the line somewhere, and this one draws it at the core problem: tractor-independent visibility with global coverage on trickle solar. The items below are the deliberate trade-offs and the places where a production deployment will add hardening — none of them are bugs, but they're all worth knowing before scaling past a pilot. -**Simplified for this POC:** +### Simplified for this POC -- **Transition detection latency and GPS freshness.** The firmware samples motion only on wake boundaries — every `parked_check_mins` while parked (for departure detection) and every `moving_ping_mins` while moving (for arrival detection). Transition events are stamped with the wake time and the Notecard's cached GPS fix at that moment, not the exact physical instant of hookup or drop. For departure events after a long parked dwell, the GPS module has been off the entire time, so the cached fix may be from the trailer's last known pre-dwell location — potentially hours or days stale; `gps_valid` is still `1` because the fix is structurally valid, only its freshness is in question. Retried deliveries always carry the original detection-time capture (never re-stamped with the current state). If fresh departure coordinates are a hard requirement, the firmware can be extended to issue `card.location.mode {"mode":"on"}` and poll until a valid fix is available before enqueuing the departure event, at the cost of 30–90 seconds of additional GPS-on time per departure. +The following are the deliberate trade-offs in this build — each is something you should understand before scaling past a pilot. -- **Satellite sync latency.** Over Iridium NTN, `sync:true` event Notes are queued rather than transmitted immediately — the Notecard cannot interrupt a satellite orbital pass on demand the way it can wake a cellular modem. Departure and arrival events will be delivered at the next Iridium transmission opportunity; depending on LEO geometry, that window may be seconds to a few minutes away. This is a [documented Notecard behavior](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set). +**Transition detection latency and GPS freshness are wake-bound.** The firmware samples motion only on wake boundaries — every `parked_check_mins` while parked (for departure detection) and every `moving_ping_mins` while moving (for arrival detection). Transition events are stamped with the wake time and the Notecard's cached GPS fix at that moment, not the exact physical instant of hookup or drop. For departure events after a long parked dwell, the GPS module has been off the entire time, so the cached fix may be from the trailer's last known pre-dwell location — **potentially hours or days stale**; `gps_valid` is still `1` because the fix is structurally valid, only its freshness is in question. Retried deliveries always carry the original detection-time capture (never re-stamped with the current state). If fresh departure coordinates are a hard requirement, the firmware can be extended to issue `card.location.mode {"mode":"on"}` and poll until a valid fix is available before enqueuing the departure event, at the cost of 30–90 seconds of additional GPS-on time per departure. -- **First-boot dwell baseline.** On first boot (or after a reflash that invalidates the persisted payload), the firmware seeds `parked_since` with the current epoch if the Notecard's clock is available. For a brand-new unit, the Notecard needs to complete its first cellular session to sync its clock; if the trailer moves before that sync, the first departure reports `dwell_h: 0`. Allow the unit to reach a `_session.qo` in Notehub (confirming clock sync) before the first trip to ensure the first departure carries a meaningful dwell value. +**Satellite sync introduces latency.** Over Iridium NTN, `sync:true` event Notes are queued rather than transmitted immediately — the Notecard cannot interrupt a satellite orbital pass on demand the way it can wake a cellular modem. Departure and arrival events will be delivered at the next Iridium transmission opportunity; depending on LEO geometry, that window may be seconds to a few minutes away. This is a [documented Notecard behavior](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set). -- **No motion-event persistence check; short moves are a blind spot.** The Notecard's 60-second / 5-event motion bucket (`card.motion.mode motion:5, seconds:60`) is the only debounce layer: the modem declares a window "moving" only when five or more accelerometer events accumulate within 60 seconds, which filters brief impulses from dock impacts or adjacent-equipment vibration. However, **the host firmware acts on the first parked-state wake where `card.motion` reports `moving` — there is no second-sample persistence check at the host level.** A single `moving` read immediately enqueues a departure event. The direct corollary: **a move that begins and ends entirely within one `parked_check_mins` interval is invisible to this firmware** — the trailer can depart, travel, and re-park between two consecutive host wakes and the host never observes a `moving` reading. At the default 5-minute parked-check cadence, short yard moves and brief tractor hookup attempts that resolve before the next wake may be silently missed. Production deployments with short-move visibility requirements should reduce `parked_check_mins` (e.g., to 1–2 minutes via the env var) and/or extend the firmware to require two consecutive `moving` reads before enqueuing a departure event. The `motion` and `seconds` parameters in `card.motion.mode` can also be tuned per equipment type to adjust bucket sensitivity. +**The first-boot dwell baseline depends on clock sync.** On first boot (or after a reflash that invalidates the persisted payload), the firmware seeds `parked_since` with the current epoch if the Notecard's clock is available. For a brand-new unit, the Notecard needs to complete its first cellular session to sync its clock; if the trailer moves before that sync, the first departure reports `dwell_h: 0`. Allow the unit to reach a `_session.qo` in Notehub (confirming clock sync) before the first trip to ensure the first departure carries a meaningful dwell value. -- **Single GPS fix per position Note.** Location Notes embed the Notecard's most recent periodic GPS fix. On a fast highway run, the fix embedded in any given Note may be up to `moving_ping_mins` old. Reducing `moving_ping_mins` to 5 minutes via the env var gives more frequent fixes at the cost of more Notes per trip. +**There is no motion-event persistence check, so short moves are a blind spot.** The Notecard's 60-second / 5-event motion bucket (`card.motion.mode motion:5, seconds:60`) is the only debounce layer: the modem declares a window "moving" only when five or more accelerometer events accumulate within 60 seconds, which filters brief impulses from dock impacts or adjacent-equipment vibration. However, **the host firmware acts on the first parked-state wake where `card.motion` reports `moving` — there is no second-sample persistence check at the host level.** A single `moving` read immediately enqueues a departure event. The direct corollary: **a move that begins and ends entirely within one `parked_check_mins` interval is invisible to this firmware** — the trailer can depart, travel, and re-park between two consecutive host wakes and the host never observes a `moving` reading. At the default 5-minute parked-check cadence, short yard moves and brief tractor hookup attempts that resolve before the next wake may be silently missed. Production deployments with short-move visibility requirements should reduce `parked_check_mins` (e.g., to 1–2 minutes via the env var) and/or extend the firmware to require two consecutive `moving` reads before enqueuing a departure event. The `motion` and `seconds` parameters in `card.motion.mode` can also be tuned per equipment type to adjust bucket sensitivity. -- **Solar sizing is minimal.** The 0.6 W panel is sized for trickle charging a parked trailer in normal operating conditions. Extended cloudy weather, high-latitude winter deployments, or physically shaded mounting locations may not provide enough solar input to offset even the modest quiescent draw. For harsh environments, a 3–5 W panel and a larger LiPo (4 Ah or more) are more appropriate. +**Each position Note carries a single GPS fix.** Location Notes embed the Notecard's most recent periodic GPS fix. On a fast highway run, the fix embedded in any given Note may be up to `moving_ping_mins` old. Reducing `moving_ping_mins` to 5 minutes via the env var gives more frequent fixes at the cost of more Notes per trip. -- **No tamper or cargo detection.** The scope here is location and dwell. Sensor additions for door-open detection, cargo weight, temperature, or tire pressure are natural extensions but not implemented in this POC. +**Solar sizing is minimal.** The 0.6 W panel is sized for trickle charging a parked trailer in normal operating conditions. Extended cloudy weather, high-latitude winter deployments, or physically shaded mounting locations may not provide enough solar input to offset even the modest quiescent draw. For harsh environments, a 3–5 W panel and a larger LiPo (4 Ah or more) are more appropriate. -- **Mojo is bench-only.** The firmware does not read Mojo's coulomb counter registers — it just flows through the Mojo's power path. Adding a cumulative mAh field to the heartbeat Note is a straightforward extension. +**There is no tamper or cargo detection.** The scope here is location and dwell. Sensor additions for door-open detection, cargo weight, temperature, or tire pressure are natural extensions but not implemented in this POC. -- **No DFU wired up.** [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) on the Swan is not configured in this POC. Field firmware updates currently require physical access to the Swan's USB-C port. +**Mojo is bench-only.** The firmware does not read Mojo's coulomb counter registers — it just flows through the Mojo's power path. Adding a cumulative mAh field to the heartbeat Note is a straightforward extension. -- **Alternative hardware path — [Skylo](https://www.skylo.tech/) NTN (land routes only).** For fleets confined to North American land-route corridors within Skylo's geostationary footprint, [Notecard for Skylo (NOTE-NBGLWX)](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) on a [Notecarrier CX](https://shop.blues.com/products/notecarrier-cx?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) integrates cellular, Skylo NTN satellite, GPS, and the accelerometer in a single M.2 module with no Starnote or external MCU board required. The same Notefile schemas (`trailer_event.qo`, `trailer_location.qo`, `trailer_heartbeat.qo`) and the same Notehub project apply. **Skylo's service area covers defined land-route corridors only — no ocean-route or polar coverage.** See the [Choosing Between Skylo and Iridium](https://dev.blues.io/starnote/choosing-between-skylo-and-iridium/) guide for the full coverage comparison. +**DFU is not wired up.** [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) on the Swan is not configured in this POC. Field firmware updates currently require physical access to the Swan's USB-C port. -**Production next steps:** +**An alternative hardware path uses [Skylo](https://www.skylo.tech/) NTN for land routes only.** For fleets confined to North American land-route corridors within Skylo's geostationary footprint, [Notecard for Skylo (NOTE-NBGLWX)](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) on a [Notecarrier CX](https://shop.blues.com/products/notecarrier-cx?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) integrates cellular, Skylo NTN satellite, GPS, and the accelerometer in a single M.2 module with no Starnote or external MCU board required. The same Notefile schemas (`trailer_event.qo`, `trailer_location.qo`, `trailer_heartbeat.qo`) and the same Notehub project apply. **Skylo's service area covers defined land-route corridors only — no ocean-route or polar coverage.** See the [Choosing Between Skylo and Iridium](https://dev.blues.io/starnote/choosing-between-skylo-and-iridium/) guide for the full coverage comparison. -- **J1939 / trailer ABS hookup** via the 7-way trailer connector, reading brake and ABS status from the trailer's onboard systems when a tractor is connected. -- **Door sensor** (magnetic reed switch on the rear doors) for load/unload event detection, mapped to a `trailer_cargo.qo` Notefile. -- **Detention billing automation** — a Notehub route that fires a webhook into the TMS on every `trailer_event.qo` with `type:1` (departed), using the `dwell_h` field to auto-generate detention invoices for any dwell exceeding the contracted free-time allowance. -- **Outboard DFU** — wiring the Notecard's DFU GPIO to the Swan RESET/BOOT0 pins to enable over-the-air host firmware updates across the entire fleet via Notehub. +### Production Next Steps + +Beyond the location-and-dwell core, these extensions integrate the tracker with trailer systems and back-office workflows. + +**J1939 / trailer ABS hookup** via the 7-way trailer connector would read brake and ABS status from the trailer's onboard systems when a tractor is connected. + +**A door sensor** (magnetic reed switch on the rear doors) would add load/unload event detection, mapped to a `trailer_cargo.qo` Notefile. + +**Detention billing automation** would use a Notehub route that fires a webhook into the TMS on every `trailer_event.qo` with `type:1` (departed), using the `dwell_h` field to auto-generate detention invoices for any dwell exceeding the contracted free-time allowance. + +**Outboard DFU** — wiring the Notecard's DFU GPIO to the Swan RESET/BOOT0 pins — would enable over-the-air host firmware updates across the entire fleet via Notehub. ## 12. Summary diff --git a/78-rail-car-condition-interchange-tracker/README.md b/78-rail-car-condition-interchange-tracker/README.md index 07e9c533..0e5aa245 100644 --- a/78-rail-car-condition-interchange-tracker/README.md +++ b/78-rail-car-condition-interchange-tracker/README.md @@ -550,26 +550,43 @@ Mojo is a bench-validation and per-firmware-revision regression tool. Field unit A car-level tracker that has to live for years on solar power, ride out weeks in cellular-dark corridors, and report condition without false alarms is a deeply tunable problem. The list below is the deliberate scope boundary for this reference design — the places we kept the implementation simple so the queue-and-forward architecture is easy to read, plus the natural extensions for a fleet-grade deployment. -**Simplified for this POC:** - -- **Satellite data budget.** Compact Note templates substantially reduce per-Note payload — `railcar_status.qo` occupies approximately 28 bytes of body content per Note (add ~8 bytes for `pressure_psi` and `tank_temp_c` in TANK_CAR builds, totalling ~36 bytes), `railcar_alert.qo` approximately 24 bytes, and `railcar_location.qo` approximately 20 bytes. However, these are **body-only, template-only sizes**; they do not represent end-to-end satellite data consumption. Real Skylo NTN usage also includes session-establishment overhead, routing metadata, delivery receipts, and any retries, and session overhead can dominate the budget before raw body bytes become a concern, especially at frequent sync cadences or when alert traffic is high. **Do not use body-size arithmetic to project allowance endurance.** Validate actual satellite byte consumption in Notehub under your intended sync cadence and expected alert behavior before sizing a production satellite plan. In practice, a car on a US rail corridor spends much of its time in cellular range at yards and populated corridors, preserving most of the 10 KB bundled allowance for the truly remote stretches. -- **Shock threshold is total vector magnitude, not gravity-compensated.** The resultant magnitude at rest reads ~1.0 G (static gravity). The 2.5 G threshold applies to total `√(Gx²+Gy²+Gz²)` — because the firmware does not apply gravity compensation or high-pass filtering, this threshold cannot be converted to a "net impact" figure by simple subtraction; the relationship depends on the angle between the gravity vector and the impact direction. Gravity compensation or high-pass filtering would be required in firmware to make the threshold orientation-independent; alternatively, use empirical per-install calibration. For cars with active vibration (e.g., empty tank cars resonating on corrugated track), the threshold may need raising to 3–4 G to suppress nuisance alerts. Tune via the `shock_threshold_g` env var after observing baseline readings in `railcar_status.qo`. -- **Single-point cargo temperature only (TANK_CAR builds).** The DS18B20 probe provides a single temperature measurement at the probe tip. For ladings with large internal temperature gradients, or where regulatory compliance requires multi-point temperature verification, additional probes or a certified cargo temperature system are needed. The probe accuracy (±0.5 °C, −10 to +85 °C range) is sufficient for basic thermal monitoring of most common bulk liquid ladings but should be validated against the specific lading and temperature range. -- **Low-pressure fitting monitoring only; no tank gauge pressure.** The Adafruit MPRLS covers 0–25 PSI absolute (roughly 0–10 PSI above atmospheric at sea level). The `pressure_max_psi` env var is firmware-clamped to 25 PSI to match this absolute range. DOT-111 non-pressure cars can operate at up to ~100 PSI gauge; DOT-105 and pressure cars are higher still — all require a certified industrial pressure transducer of the appropriate type (gauge, absolute, or differential) with matching wetted-parts spec for the lading. -- **Solar power requires a charge controller.** The BOM includes a solar charge controller as a required component. Do not substitute a direct panel-to-LiPo connection. -- **Coupler state is sampled, not interrupt-driven.** A coupling or decoupling event that occurs and reverses entirely within a single 15-minute sample window will not be detected. Reducing `sample_interval_min` to 5 minutes narrows this gap at the cost of battery life. -- **Interchange detection is not implemented on-device.** Determining that a car has changed railroad custody — the core of interchange tracking — requires either on-device geofencing against railroad territory boundary polygons, or downstream processing against a geospatial database of those boundaries. This firmware does neither: it reports GPS location, motion state, coupler state, and sensor readings, but contains no handoff-detection logic. Production interchange tracking further requires feeding detected boundary crossings to the AAR's Umler or Railinc EDI platforms as structured interchange transactions. Both the geofencing step and the EDI integration step are production work outside the scope of this POC. See Production Next Steps below. -- **No GNSS in covered yards.** A car parked under an overhead conveyor structure or inside a building will lose GPS fix. The Notecard retains the last known position but location accuracy will degrade until sky view is restored. - -**Production next steps:** - -- Field-calibrate `shock_threshold_g` per car type. A tank car with a hand brake applied resonates differently than an empty flatcar; a single fleet-wide threshold is a starting point, not a final answer. -- Add additional DS18B20 probes on the same OneWire bus (up to ~10 devices per bus segment) for multi-point cargo temperature profiling; use `getDeviceCount()` and `getTempCByIndex(n)` in the DallasTemperature library to iterate all sensors. -- Replace the MPRLS with a 4–20 mA industrial pressure transmitter (e.g., Honeywell STS3000 series) rated for the lading and pressure class; read via a 250 Ω burden resistor on an analog input. -- Wire a second reed switch to a hatch or valve cover for tank cars to detect unauthorized access to the dome. -- Implement [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) so threshold recipe updates and new alert rules can be pushed to the fleet over the air without a truck roll. -- Connect Notehub location events to a geofencing service or location time-series store (via a [Notehub route](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub)) to detect railroad territory boundary crossings and generate interchange events for each custody handoff. -- Feed those interchange events to an AAR/Railinc EDI gateway (Umler or Railinc platforms) for automated interchange reporting. +### Simplified for this POC + +These are the spots where the implementation was kept simple to keep the queue-and-forward architecture readable — each comes with the consideration a production deployment should weigh. + +**The satellite data budget cannot be projected from body sizes.** Compact Note templates substantially reduce per-Note payload — `railcar_status.qo` occupies approximately 28 bytes of body content per Note (add ~8 bytes for `pressure_psi` and `tank_temp_c` in TANK_CAR builds, totalling ~36 bytes), `railcar_alert.qo` approximately 24 bytes, and `railcar_location.qo` approximately 20 bytes. However, these are **body-only, template-only sizes**; they do not represent end-to-end satellite data consumption. Real Skylo NTN usage also includes session-establishment overhead, routing metadata, delivery receipts, and any retries, and session overhead can dominate the budget before raw body bytes become a concern, especially at frequent sync cadences or when alert traffic is high. **Do not use body-size arithmetic to project allowance endurance.** Validate actual satellite byte consumption in Notehub under your intended sync cadence and expected alert behavior before sizing a production satellite plan. In practice, a car on a US rail corridor spends much of its time in cellular range at yards and populated corridors, preserving most of the 10 KB bundled allowance for the truly remote stretches. + +**The shock threshold is total vector magnitude, not gravity-compensated.** The resultant magnitude at rest reads ~1.0 G (static gravity). The 2.5 G threshold applies to total `√(Gx²+Gy²+Gz²)` — because the firmware does not apply gravity compensation or high-pass filtering, this threshold cannot be converted to a "net impact" figure by simple subtraction; the relationship depends on the angle between the gravity vector and the impact direction. Gravity compensation or high-pass filtering would be required in firmware to make the threshold orientation-independent; alternatively, use empirical per-install calibration. For cars with active vibration (e.g., empty tank cars resonating on corrugated track), the threshold may need raising to 3–4 G to suppress nuisance alerts. Tune via the `shock_threshold_g` env var after observing baseline readings in `railcar_status.qo`. + +**Cargo temperature is single-point only (TANK_CAR builds).** The DS18B20 probe provides a single temperature measurement at the probe tip. For ladings with large internal temperature gradients, or where regulatory compliance requires multi-point temperature verification, additional probes or a certified cargo temperature system are needed. The probe accuracy (±0.5 °C, −10 to +85 °C range) is sufficient for basic thermal monitoring of most common bulk liquid ladings but should be validated against the specific lading and temperature range. + +**Pressure monitoring is low-pressure fitting only; there is no tank gauge pressure.** The Adafruit MPRLS covers 0–25 PSI absolute (roughly 0–10 PSI above atmospheric at sea level). The `pressure_max_psi` env var is firmware-clamped to 25 PSI to match this absolute range. DOT-111 non-pressure cars can operate at up to ~100 PSI gauge; DOT-105 and pressure cars are higher still — all require a certified industrial pressure transducer of the appropriate type (gauge, absolute, or differential) with matching wetted-parts spec for the lading. + +**Solar power requires a charge controller.** The BOM includes a solar charge controller as a required component. **Do not substitute a direct panel-to-LiPo connection.** + +**Coupler state is sampled, not interrupt-driven.** A coupling or decoupling event that occurs and reverses entirely within a single 15-minute sample window will not be detected. Reducing `sample_interval_min` to 5 minutes narrows this gap at the cost of battery life. + +**Interchange detection is not implemented on-device.** Determining that a car has changed railroad custody — the core of interchange tracking — requires either on-device geofencing against railroad territory boundary polygons, or downstream processing against a geospatial database of those boundaries. This firmware does neither: it reports GPS location, motion state, coupler state, and sensor readings, but contains no handoff-detection logic. Production interchange tracking further requires feeding detected boundary crossings to the AAR's Umler or Railinc EDI platforms as structured interchange transactions. Both the geofencing step and the EDI integration step are production work outside the scope of this POC. See Production Next Steps below. + +**There is no GNSS in covered yards.** A car parked under an overhead conveyor structure or inside a building will lose GPS fix. The Notecard retains the last known position but location accuracy will degrade until sky view is restored. + +### Production Next Steps + +These extensions take the tracker from a readable reference build toward fleet-grade condition reporting and formal interchange integration. + +**Field-calibrate `shock_threshold_g` per car type.** A tank car with a hand brake applied resonates differently than an empty flatcar; a single fleet-wide threshold is a starting point, not a final answer. + +**Add additional DS18B20 probes** on the same OneWire bus (up to ~10 devices per bus segment) for multi-point cargo temperature profiling; use `getDeviceCount()` and `getTempCByIndex(n)` in the DallasTemperature library to iterate all sensors. + +**Replace the MPRLS with a 4–20 mA industrial pressure transmitter** (e.g., Honeywell STS3000 series) rated for the lading and pressure class; read via a 250 Ω burden resistor on an analog input. + +**Wire a second reed switch** to a hatch or valve cover for tank cars to detect unauthorized access to the dome. + +**Implement [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/)** so threshold recipe updates and new alert rules can be pushed to the fleet over the air without a truck roll. + +**Connect Notehub location events to a geofencing service** or location time-series store (via a [Notehub route](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub)) to detect railroad territory boundary crossings and generate interchange events for each custody handoff. + +**Feed those interchange events to an AAR/Railinc EDI gateway** (Umler or Railinc platforms) for automated interchange reporting. ## 12. Summary diff --git a/79-utility-distribution-transformer-load-monitor/README.md b/79-utility-distribution-transformer-load-monitor/README.md index 37fb94c7..c582bc5f 100644 --- a/79-utility-distribution-transformer-load-monitor/README.md +++ b/79-utility-distribution-transformer-load-monitor/README.md @@ -503,29 +503,49 @@ Mojo is a bench-validation and regression tool — it is not required in product A pole-mount monitor that drives operational decisions about live distribution equipment has a high bar to meet in production: surge protection, signed utility approvals, billing-grade accuracy where it matters, and survivable comms when the transformer itself fails. This POC keeps the implementation narrow on purpose — three signals (per-phase load, imbalance, enclosure thermal stress) over one cellular path — so the alerting and trending pieces stay readable. The items below mark both where that scope was drawn and the natural production additions. -**Simplified for this POC:** - -- **CT current range.** The SCT-013-000 (100A) suits transformers up to approximately 20 kVA at 240V (~83A full-load). Transformers at or above 25 kVA at 240V draw ~104A — beyond this CT's rating, and require a higher-range **current-output** CT (200A or 400A). Voltage-output CTs are not drop-in replacements; see §4. The firmware `CT_TURNS_RATIO` and `CT_BURDEN_OHMS` constants need to be updated to match the chosen CT; all downstream calculations scale automatically. -- **RMS accuracy.** The two-pass ADC algorithm covers approximately 20 mains cycles per channel (~330 milliseconds per channel, ~1 second total for three channels) at the Cygnet ADC's throughput rate. This gives adequate accuracy (~5–10%) for a load-threshold monitor, but is not suitable for billing-grade energy metering. Extending the sample count to cover ~200 mains cycles per channel would improve RMS accuracy at the cost of proportionally longer host-active time. -- **Summary averages reflect loaded intervals only.** `i_a_rms`, `i_b_rms`, `i_c_rms`, `i_total`, `loading_pct`, and `imbalance_pct` in `xfmr_summary.qo` are computed only over the sample intervals (`samples`) where at least one phase exceeded the 0.5 A noise floor. Sample intervals where no load is detectable are excluded from the denominator. This means a lightly-loaded or intermittently-loaded window reports average current *during the intervals when load was present*, not the true time-weighted average across the full window. For fault detection and threshold alerting this is the appropriate behavior — alert thresholds should be evaluated against actual load conditions, not diluted by idle time. For utilization reporting or transformer-life analytics, multiply `loading_pct` by `samples / total_wakes` (both fields are in the summary payload) to recover the time-weighted window average. -- **Power factor not measured.** The firmware reports apparent current (A RMS), not real power (watts) or reactive power (VAR). A transformer nameplate rating is in kVA (apparent power), so loading percentage is correct as stated. Measuring true power would require voltage sensing in addition to current sensing — a meaningful production enhancement for a billing or power-quality application. -- **Single-point temperature (enclosure proxy only; not a true ambient probe).** This implementation uses an MCP9808 mounted inside the enclosure. It measures internal enclosure temperature, not true outdoor ambient air temperature and not transformer core or winding temperature. Enclosure temperature tracks thermal stress directionally but can diverge significantly from outdoor ambient — especially on a sun-exposed pole, and lags winding temperature by minutes to hours under transient load changes. A true ambient probe (external housing, shielded from direct sun) or a winding-contact sensor (PT100 RTD or thermocouple on the transformer case) would provide more actionable data; see Production next steps below. -- **Conventional split-core CTs, not Rogowski coils.** This implementation uses conventional current-output split-core CTs (YHDC SCT-013-000) rather than flexible Rogowski-type coils. True Rogowski coils produce a signal proportional to d*i*/d*t*, requiring an external integrator board before the ADC; they offer no inherent accuracy advantage for power-frequency monitoring over calibrated current-output CTs and add meaningful cost and complexity. Flexible Rogowski coils (such as the Dent Instruments PowerScout or Magnelab RCT series) are the right choice for physically constrained installations where a rigid split-core jaw cannot open wide enough to encircle a large busbar or conductor bundle — that constraint does not apply to standard residential or commercial distribution transformer secondary leads, so this design uses the simpler current-output CT. -- **No inductive power harvest.** The project description mentions optional inductive energy harvesting from the transformer. It is omitted from this POC because the complexity and installation constraints of a validated inductive harvester are substantial relative to the simplicity of a direct 120VAC tap on the transformer secondary. For installations where tapping the secondary is impractical (sealed enclosures, third-party owned equipment), inductive harvesting is the right production next step, but it would require a separate, validated power-stage design and is out of scope here. -- **No backup power.** If the transformer fails (the scenario we're trying to detect early), the monitoring device also loses power and cannot report the outage itself. Adding a Blues Scoop with a small LiPo battery would allow the device to survive a brief outage and transmit a "power lost" event before the battery dies — a meaningful production addition for "last gasp" outage detection. -- **Alert cooldown is cycle-based.** The cooldown counter tracks sample cycles, not wall-clock time. If `sample_interval_sec` is changed via env var after an alert fires, the cooldown duration shifts proportionally. For most deployments this is acceptable; for strict SLA compliance, store the alert timestamp in persistent state instead. -- **No surge or transient protection.** The 2A slow-blow fuse on the 120VAC tap protects against a sustained overcurrent fault but provides no suppression of lightning-induced transients, switching surges, or capacitor-bank switching events — all of which are common on distribution transformer secondaries. A permanent pole-mount deployment requires: a surge protective device (SPD) rated for the site's overvoltage category (Category C / lightning-level, per IEC 61643-11 or UL 1449) installed on the Line/Neutral entry ahead of the fuse; enclosure grounding and bonding to the pole ground system per applicable NEC sections and utility rules; verified creepage and clearance in all mains-voltage wiring and connectors; UV and temperature qualification of all external cabling and the enclosure; and written utility approval before the secondary tap is permanently energized. This POC omits the SPD and grounding circuit as out of scope for a bench or controlled field-trial context; do not omit them in any design intended for permanent field deployment. - -**Production next steps:** - -- Surge protective device (SPD) on the AC mains entry (Category C rated, per IEC 61643-11 or UL 1449), enclosure grounding/bonding to the pole ground system per applicable NEC sections and utility rules, and written utility approval before permanent field deployment. -- Higher-range CTs (200A, 400A) for 50–167 kVA distribution transformers; update `CT_TURNS_RATIO` and `CT_BURDEN_OHMS` accordingly. -- Contact temperature probe on the transformer case for direct winding-temperature monitoring — a PT100 RTD via MAX31865 (SPI, requires three additional GPIO pins for SCLK/MISO/CS) or a thermocouple with a MAX31856 (also SPI). An I²C RTD option such as the Texas Instruments TMP117 (±0.1°C, I²C) avoids the extra SPI pins but is limited to –40°C to +125°C, which covers typical transformer enclosure ranges. -- Voltage measurement on the secondary (a resistor divider plus a precision analog input or an external ADC) to compute real power, power factor, and true apparent kVA loading. -- Inductive energy harvesting from a current-carrying secondary conductor as an alternative to the 120VAC tap — valuable for sealed enclosures where the tap is not accessible. -- Blues Scoop with LiPo for last-gasp outage reporting when the primary supply fails. -- Over-the-air host firmware updates across the deployed fleet — critical when physical re-flash of hundreds of pole-mount units is impractical. [Notecard Outboard Firmware Update (ODFU)](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) provides this capability; verify the specific wiring and bootloader support for the Notecarrier CX / Cygnet combination against Blues documentation before committing to a production design. -- Per-transformer commissioning: a one-time `rated_amps` calibration via env var at install time to account for field-measurement of the actual secondary current at known load. +### Simplified for this POC + +Each of these is a deliberate scope boundary that keeps the alerting and trending pieces readable, paired with what a production build would change. + +**The CT current range is bounded by the chosen sensor.** The SCT-013-000 (100A) suits transformers up to approximately 20 kVA at 240V (~83A full-load). Transformers at or above 25 kVA at 240V draw ~104A — beyond this CT's rating, and require a higher-range **current-output** CT (200A or 400A). **Voltage-output CTs are not drop-in replacements**; see §4. The firmware `CT_TURNS_RATIO` and `CT_BURDEN_OHMS` constants need to be updated to match the chosen CT; all downstream calculations scale automatically. + +**RMS accuracy is monitor-grade, not billing-grade.** The two-pass ADC algorithm covers approximately 20 mains cycles per channel (~330 milliseconds per channel, ~1 second total for three channels) at the Cygnet ADC's throughput rate. This gives adequate accuracy (~5–10%) for a load-threshold monitor, but is **not suitable for billing-grade energy metering**. Extending the sample count to cover ~200 mains cycles per channel would improve RMS accuracy at the cost of proportionally longer host-active time. + +**Summary averages reflect loaded intervals only.** `i_a_rms`, `i_b_rms`, `i_c_rms`, `i_total`, `loading_pct`, and `imbalance_pct` in `xfmr_summary.qo` are computed only over the sample intervals (`samples`) where at least one phase exceeded the 0.5 A noise floor. Sample intervals where no load is detectable are excluded from the denominator. This means a lightly-loaded or intermittently-loaded window reports average current *during the intervals when load was present*, not the true time-weighted average across the full window. For fault detection and threshold alerting this is the appropriate behavior — alert thresholds should be evaluated against actual load conditions, not diluted by idle time. For utilization reporting or transformer-life analytics, multiply `loading_pct` by `samples / total_wakes` (both fields are in the summary payload) to recover the time-weighted window average. + +**Power factor is not measured.** The firmware reports apparent current (A RMS), not real power (watts) or reactive power (VAR). A transformer nameplate rating is in kVA (apparent power), so loading percentage is correct as stated. Measuring true power would require voltage sensing in addition to current sensing — a meaningful production enhancement for a billing or power-quality application. + +**Temperature is single-point, an enclosure proxy and not a true ambient probe.** This implementation uses an MCP9808 mounted inside the enclosure. It measures internal enclosure temperature, not true outdoor ambient air temperature and not transformer core or winding temperature. Enclosure temperature tracks thermal stress directionally but can diverge significantly from outdoor ambient — especially on a sun-exposed pole, and lags winding temperature by minutes to hours under transient load changes. A true ambient probe (external housing, shielded from direct sun) or a winding-contact sensor (PT100 RTD or thermocouple on the transformer case) would provide more actionable data; see Production Next Steps below. + +**This design uses conventional split-core CTs, not Rogowski coils.** This implementation uses conventional current-output split-core CTs (YHDC SCT-013-000) rather than flexible Rogowski-type coils. True Rogowski coils produce a signal proportional to d*i*/d*t*, requiring an external integrator board before the ADC; they offer no inherent accuracy advantage for power-frequency monitoring over calibrated current-output CTs and add meaningful cost and complexity. Flexible Rogowski coils (such as the Dent Instruments PowerScout or Magnelab RCT series) are the right choice for physically constrained installations where a rigid split-core jaw cannot open wide enough to encircle a large busbar or conductor bundle — that constraint does not apply to standard residential or commercial distribution transformer secondary leads, so this design uses the simpler current-output CT. + +**There is no inductive power harvest.** The project description mentions optional inductive energy harvesting from the transformer. It is omitted from this POC because the complexity and installation constraints of a validated inductive harvester are substantial relative to the simplicity of a direct 120VAC tap on the transformer secondary. For installations where tapping the secondary is impractical (sealed enclosures, third-party owned equipment), inductive harvesting is the right production next step, but it would require a separate, validated power-stage design and is out of scope here. + +**There is no backup power.** If the transformer fails (the scenario we're trying to detect early), the monitoring device also loses power and cannot report the outage itself. Adding a Blues Scoop with a small LiPo battery would allow the device to survive a brief outage and transmit a "power lost" event before the battery dies — a meaningful production addition for "last gasp" outage detection. + +**Alert cooldown is cycle-based.** The cooldown counter tracks sample cycles, not wall-clock time. If `sample_interval_sec` is changed via env var after an alert fires, the cooldown duration shifts proportionally. For most deployments this is acceptable; for strict SLA compliance, store the alert timestamp in persistent state instead. + +**There is no surge or transient protection.** The 2A slow-blow fuse on the 120VAC tap protects against a sustained overcurrent fault but provides no suppression of lightning-induced transients, switching surges, or capacitor-bank switching events — all of which are common on distribution transformer secondaries. A permanent pole-mount deployment requires: a surge protective device (SPD) rated for the site's overvoltage category (Category C / lightning-level, per IEC 61643-11 or UL 1449) installed on the Line/Neutral entry ahead of the fuse; enclosure grounding and bonding to the pole ground system per applicable NEC sections and utility rules; verified creepage and clearance in all mains-voltage wiring and connectors; UV and temperature qualification of all external cabling and the enclosure; and written utility approval before the secondary tap is permanently energized. This POC omits the SPD and grounding circuit as out of scope for a bench or controlled field-trial context; **do not omit them in any design intended for permanent field deployment.** + +### Production Next Steps + +These additions take the monitor from a controlled trial toward a permanently energized, fleet-scale pole-mount deployment. + +**Surge and grounding protection** is mandatory before permanent field deployment: a surge protective device (SPD) on the AC mains entry (Category C rated, per IEC 61643-11 or UL 1449), enclosure grounding/bonding to the pole ground system per applicable NEC sections and utility rules, and written utility approval. + +**Higher-range CTs** (200A, 400A) cover 50–167 kVA distribution transformers; update `CT_TURNS_RATIO` and `CT_BURDEN_OHMS` accordingly. + +**A contact temperature probe** on the transformer case enables direct winding-temperature monitoring — a PT100 RTD via MAX31865 (SPI, requires three additional GPIO pins for SCLK/MISO/CS) or a thermocouple with a MAX31856 (also SPI). An I²C RTD option such as the Texas Instruments TMP117 (±0.1°C, I²C) avoids the extra SPI pins but is limited to –40°C to +125°C, which covers typical transformer enclosure ranges. + +**Voltage measurement on the secondary** (a resistor divider plus a precision analog input or an external ADC) would let the device compute real power, power factor, and true apparent kVA loading. + +**Inductive energy harvesting** from a current-carrying secondary conductor is an alternative to the 120VAC tap — valuable for sealed enclosures where the tap is not accessible. + +**A Blues Scoop with LiPo** enables last-gasp outage reporting when the primary supply fails. + +**Over-the-air host firmware updates** across the deployed fleet are critical when physical re-flash of hundreds of pole-mount units is impractical. [Notecard Outboard Firmware Update (ODFU)](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) provides this capability; verify the specific wiring and bootloader support for the Notecarrier CX / Cygnet combination against Blues documentation before committing to a production design. + +**Per-transformer commissioning** would add a one-time `rated_amps` calibration via env var at install time to account for field-measurement of the actual secondary current at known load. ## 12. Summary diff --git a/80-ev-charger-session-utilization-monitor/README.md b/80-ev-charger-session-utilization-monitor/README.md index 49272246..72dd2195 100644 --- a/80-ev-charger-session-utilization-monitor/README.md +++ b/80-ev-charger-session-utilization-monitor/README.md @@ -428,31 +428,39 @@ Mojo is bench-validation tooling — deployed units running from a panel supply A meter-based monitor and an OCPP-integrated monitor answer different questions, and this reference design deliberately answers the simpler one: how is the circuit being used, regardless of charger brand or network. The trade-offs that come with that choice — heuristic session boundaries, no per-driver records, single-phase coverage — are listed below, alongside the natural production extensions. -**Design boundaries:** +### Design Boundaries -- **Energy-meter integration: SDM120 Modbus RTU, not OCPP.** This project implements a hardware energy-meter integration on the charger's AC feed. It does not implement OCPP or direct charger-network integration and therefore does not provide per-driver, per-RFID, or charger-network session records. Session boundaries are power-threshold heuristics (`active_power_w ≥ session_threshold_w`), not authoritative OCPP `StartTransaction`/`StopTransaction` events. Sites that additionally require per-driver records or OCPP-correlated data should implement an OCPP back-end integration alongside this meter-based monitor. See the production next steps at the end of this section. +Each boundary below is a place where the meter-based approach trades authoritative session detail for brand-agnostic simplicity, and where a production deployment may want to add a meter, a phase, or an OCPP back-end. -- **SDM120 ampacity and neutral requirement.** The SDM120-Modbus direct-connect variant is rated 45 A continuous. It covers 32 A EVSE (40 A breaker) and 40 A EVSE (50 A breaker). For 48 A or 60 A EVSE circuits, substitute the **SDM120CT** variant (uses an external split-core CT; rated for any primary current, CT-dependent) or the **SDM230-Modbus** (100 A direct-connect). Additionally, the SDM120 requires a neutral connection for its internal voltage measurement. In a subpanel where only two line conductors are available (e.g., a 240 V line-to-line feed with no neutral), the SDM120 cannot measure voltage and will not operate correctly; use a single-phase meter that accepts a two-wire (L-L) supply voltage input instead, or run a neutral conductor from the main panel. +**Energy-meter integration is SDM120 Modbus RTU, not OCPP.** This project implements a hardware energy-meter integration on the charger's AC feed. It does not implement OCPP or direct charger-network integration and therefore does not provide per-driver, per-RFID, or charger-network session records. Session boundaries are power-threshold heuristics (`active_power_w ≥ session_threshold_w`), not authoritative OCPP `StartTransaction`/`StopTransaction` events. Sites that additionally require per-driver records or OCPP-correlated data should implement an OCPP back-end integration alongside this meter-based monitor. See the production next steps at the end of this section. -- **Availability from V_rms, not OCPP status.** `available_min` and `availability_pct` are derived from the SDM120's V_rms register. When V_rms ≥ `voltage_present_v`, the charger circuit is classified as energised. Wakes where the meter poll fails entirely — because mains is absent, wiring is faulted, or all Modbus retries fail — also count against availability: they contribute to the wall-clock `elapsed_min` denominator but not to `available_min`, so `availability_pct` correctly falls below 100 % whenever the circuit was offline for any reason. `sample_coverage_pct` distinguishes sustained meter faults from genuine mains absence: if `availability_pct` is low and `sample_coverage_pct` is also low, the charger was likely offline; if `availability_pct` is low but `sample_coverage_pct` is near 100, the V_rms readings were valid and indicate a prolonged low-voltage or brownout condition. This design does **not** detect an EVSE that is powered but internally faulted (e.g., a GFI trip within the EVSE, a J1772 pilot fault, or an EVSE error state) — those faults leave the circuit energised and appear as idle time (`charging_min = 0, available_min = elapsed_min`). Sites requiring per-charger EVSE fault detection should supplement this meter monitor with OCPP status-notification integration. Within those limits, `availability_pct` provides a useful signal: sustained `availability_pct < 100` in a summary window confirms a real mains interruption during that period, and `availability_pct = 100` with `utilization_pct = 0` indicates the charger was powered but unused. +**SDM120 ampacity and neutral requirement.** The SDM120-Modbus direct-connect variant is rated 45 A continuous. It covers 32 A EVSE (40 A breaker) and 40 A EVSE (50 A breaker). For 48 A or 60 A EVSE circuits, substitute the **SDM120CT** variant (uses an external split-core CT; rated for any primary current, CT-dependent) or the **SDM230-Modbus** (100 A direct-connect). Additionally, the SDM120 requires a neutral connection for its internal voltage measurement. In a subpanel where only two line conductors are available (e.g., a 240 V line-to-line feed with no neutral), the SDM120 cannot measure voltage and will not operate correctly; use a single-phase meter that accepts a two-wire (L-L) supply voltage input instead, or run a neutral conductor from the main panel. -- **Metered accuracy — Class 1, not revenue-grade.** The SDM120 is IEC 62053-21 Class 1, meaning ±1% accuracy under reference conditions. This is sufficient for utilization monitoring and tenant cost allocation, but falls short of revenue-grade Class 0.5 or 0.2 instruments required for utility billing. For billing applications, substitute a revenue-grade instrument. +**Availability is derived from V_rms, not OCPP status.** `available_min` and `availability_pct` are derived from the SDM120's V_rms register. When V_rms ≥ `voltage_present_v`, the charger circuit is classified as energised. Wakes where the meter poll fails entirely — because mains is absent, wiring is faulted, or all Modbus retries fail — also count against availability: they contribute to the wall-clock `elapsed_min` denominator but not to `available_min`, so `availability_pct` correctly falls below 100 % whenever the circuit was offline for any reason. `sample_coverage_pct` distinguishes sustained meter faults from genuine mains absence: if `availability_pct` is low and `sample_coverage_pct` is also low, the charger was likely offline; if `availability_pct` is low but `sample_coverage_pct` is near 100, the V_rms readings were valid and indicate a prolonged low-voltage or brownout condition. This design does **not** detect an EVSE that is powered but internally faulted (e.g., a GFI trip within the EVSE, a J1772 pilot fault, or an EVSE error state) — those faults leave the circuit energised and appear as idle time (`charging_min = 0, available_min = elapsed_min`). Sites requiring per-charger EVSE fault detection should supplement this meter monitor with OCPP status-notification integration. Within those limits, `availability_pct` provides a useful signal: sustained `availability_pct < 100` in a summary window confirms a real mains interruption during that period, and `availability_pct = 100` with `utilization_pct = 0` indicates the charger was powered but unused. -- **Single-phase monitoring only.** This design monitors one single-phase EVSE circuit. Three-phase 208 V or 480 V commercial charging installations (typically DCFC, DC fast chargers) require a three-phase energy meter and are not covered by this reference design. +**Metered accuracy is Class 1, not revenue-grade.** The SDM120 is IEC 62053-21 Class 1, meaning ±1% accuracy under reference conditions. This is sufficient for utilization monitoring and tenant cost allocation, but falls short of revenue-grade Class 0.5 or 0.2 instruments required for utility billing. For billing applications, substitute a revenue-grade instrument. -- **Session detection is power-threshold only.** The firmware does not distinguish between "EV actively charging at full rate," "EV plugged in but in top-off mode at reduced power," and "EV plugged in but the BMS has paused charging." All three produce above-threshold active power and appear as a single continuous session. An OCPP-integrated data source would provide the authoritative session state. +**Monitoring is single-phase only.** This design monitors one single-phase EVSE circuit. Three-phase 208 V or 480 V commercial charging installations (typically DCFC, DC fast chargers) require a three-phase energy meter and are not covered by this reference design. -- **Sessions spanning summary windows; retry-path attribution; single-slot data loss.** Window `total_kwh` uses the meter-register delta and captures all energy in the window period regardless of session boundaries. However, `window_sessions` counts only sessions that *close* in the window — a session still in progress when the summary fires will be counted in the window where it ends. On the retry path: if `emitSessionNote()` fails at session close and the pending retry only succeeds after the summary window has already reset, `window_sessions` and `window_completed_session_kwh` are attributed to the newer window. **Single-slot data loss:** the pending-session store holds exactly one completed-session payload. If a second session closes while the first Note has not yet been successfully queued (Notecard fault lasting longer than one complete charging session), the older session record is overwritten and permanently lost. A `[app] WARN: overwriting unconfirmed pending session Note` line is printed to serial. Production deployments requiring guaranteed per-session delivery should replace the single-slot pending store with a small ring buffer. See the code comment in `ev_charger_session_monitor_helpers.h`. +**Session detection is power-threshold only.** The firmware does not distinguish between "EV actively charging at full rate," "EV plugged in but in top-off mode at reduced power," and "EV plugged in but the BMS has paused charging." All three produce above-threshold active power and appear as a single continuous session. An OCPP-integrated data source would provide the authoritative session state. -- **No Notecard outboard firmware update wired.** The firmware does not configure [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) for over-the-air host firmware updates. Firmware updates require a physical USB connection. +**Sessions spanning summary windows, retry-path attribution, and single-slot data loss.** Window `total_kwh` uses the meter-register delta and captures all energy in the window period regardless of session boundaries. However, `window_sessions` counts only sessions that *close* in the window — a session still in progress when the summary fires will be counted in the window where it ends. On the retry path: if `emitSessionNote()` fails at session close and the pending retry only succeeds after the summary window has already reset, `window_sessions` and `window_completed_session_kwh` are attributed to the newer window. **Single-slot data loss:** the pending-session store holds exactly one completed-session payload. If a second session closes while the first Note has not yet been successfully queued (Notecard fault lasting longer than one complete charging session), the older session record is **overwritten and permanently lost**. A `[app] WARN: overwriting unconfirmed pending session Note` line is printed to serial. Production deployments requiring guaranteed per-session delivery should replace the single-slot pending store with a small ring buffer. See the code comment in `ev_charger_session_monitor_helpers.h`. -**Production next steps:** +**No Notecard outboard firmware update wired.** The firmware does not configure [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) for over-the-air host firmware updates. Firmware updates require a physical USB connection. -- Upgrade to a revenue-grade Class 0.5 or 0.2 DIN-rail energy meter (e.g., EASTRON SDM72D or equivalent) for utility-billing accuracy. -- For a two-port charger (two EVSE circuits in the same panel), add a second SDM120 on a shared RS-485 bus using a different Modbus slave ID; extend the firmware to poll both meters and emit per-port session and summary Notes. -- Implement OCPP session correlation: integrate with the charger's OCPP back-end via its WebSocket/HTTP interface or a network proxy to capture `StartTransaction` / `StopTransaction` events, then cross-reference those records with energy-meter session data to get per-driver, per-RFID, per-session energy records. -- Wire Notecard Outboard DFU to the Cygnet's boot/reset pins for over-the-air host firmware updates across the deployed fleet. -- Replace the single-slot pending-session store with a small ring buffer (4–8 slots) in the `State` struct to guarantee per-session delivery even during extended Notecard faults. See the extension Notes in `ev_charger_session_monitor_helpers.h`. +### Production Next Steps + +Once the basic meter monitor is running, these extensions move it toward billing-grade accuracy and multi-port, OCPP-correlated coverage — roughly from the most immediately useful to the most integration-dependent. + +**Upgrade to a revenue-grade meter.** Swap in a Class 0.5 or 0.2 DIN-rail energy meter (e.g., EASTRON SDM72D or equivalent) for utility-billing accuracy. + +**Add a second meter for two-port chargers.** For a two-port charger (two EVSE circuits in the same panel), add a second SDM120 on a shared RS-485 bus using a different Modbus slave ID; extend the firmware to poll both meters and emit per-port session and summary Notes. + +**Implement OCPP session correlation.** Integrate with the charger's OCPP back-end via its WebSocket/HTTP interface or a network proxy to capture `StartTransaction` / `StopTransaction` events, then cross-reference those records with energy-meter session data to get per-driver, per-RFID, per-session energy records. + +**Wire Notecard Outboard DFU.** Connect it to the Cygnet's boot/reset pins for over-the-air host firmware updates across the deployed fleet. + +**Replace the single-slot pending store with a ring buffer.** A small ring buffer (4–8 slots) in the `State` struct guarantees per-session delivery even during extended Notecard faults. See the extension Notes in `ev_charger_session_monitor_helpers.h`. ## 11. Summary diff --git a/81-commercial-tenant-sub-metering-bridge/README.md b/81-commercial-tenant-sub-metering-bridge/README.md index 8056d56d..a1f9b2e8 100644 --- a/81-commercial-tenant-sub-metering-bridge/README.md +++ b/81-commercial-tenant-sub-metering-bridge/README.md @@ -556,6 +556,10 @@ If a problem is not on this list, visit the [Blues community forum](https://disc This is a reference design for proportional tenant allocation, not a certified utility sub-meter — and that distinction is deliberate. The list below makes explicit where the design's measurement model, the agency-listing of the bench-grade voltage transducer, and the single-phase assumption draw the line, then points at the production paths for the cases that need more. +### Simplified for this Proof-of-Concept + +The simplifications below are deliberate scope choices — each marks where the measurement model, the bench-grade voltage transducer, or the single-phase assumption draws the line for a proportional allocation bridge rather than a certified meter. + **Allocation-grade estimation, not certified metering.** This design measures estimated interval energy by taking one ~200 milliseconds active-power snapshot per `sample_interval_sec` and multiplying it by the full interval duration. The firmware does not continuously integrate power between wakes. This approach is accurate for constant or slowly-varying loads but may over- or under-state energy on bursting or cycling loads. For internal bill-back between tenants in the same building it is an appropriate allocation method. It is **not** suitable for applications where accuracy is subject to regulatory oversight, for example, utility-tariff sub-metering subject to accuracy standards — without replacing the measurement front end with a dedicated simultaneous-sampling energy-metering IC or a certified pulse-output sub-meter interface. **Single-phase voltage reference shared across all channels.** The voltage transducer provides one voltage waveform used as the reference for all four current channels. This is accurate when all tenant circuits derive from the same phase leg of the building supply — common in small commercial buildings with a single-phase 120 V service. In a split-phase (120/240 V) building where tenants may be on different legs, or in a three-phase building where tenant feeds come from different phases, the phase relationship between the shared voltage reference and a tenant's actual line voltage introduces a power-factor error in the real-power calculation. For buildings with known multi-phase distribution, a dedicated voltage sensor per phase (and per-phase V×I pairs in the firmware) is required for accurate real-power metering across all tenants. @@ -574,9 +578,13 @@ This is a reference design for proportional tenant allocation, not a certified u **Mojo is bench equipment.** The firmware does not read the Mojo's coulomb-counter register over Qwiic. Adding a runtime mAh field to the summary Note is a straightforward extension if fleet-level power telemetry is valuable. -**Production next steps:** -- Per-channel calibration workflow: at commissioning, capture a reference reading alongside a calibrated clamp meter to establish the correct `rogowski_amps_per_volt` for each installed coil, then push the trimmed value as a per-device environment variable in Notehub. -- **Production voltage sensing (future revision).** The ZMPT101B module used in this design is bench/prototype only — it is not agency-listed for permanent installation inside a commercial panel enclosure. Before deploying to a live panel, replace it with an agency-listed isolated AC voltage transducer. Two substitution paths are available depending on the device chosen: +### Production Next Steps + +Taking the bridge toward a production rollout means calibrating each installed coil, replacing the bench-grade voltage front end with an agency-listed transducer, and wiring the hourly stream into a billing platform. The following extensions are the natural progression. + +**Per-channel calibration workflow** comes first: at commissioning, capture a reference reading alongside a calibrated clamp meter to establish the correct `rogowski_amps_per_volt` for each installed coil, then push the trimmed value as a per-device environment variable in Notehub. + +**Production voltage sensing (future revision).** The ZMPT101B module used in this design is bench/prototype only — it is **not agency-listed** for permanent installation inside a commercial panel enclosure. Before deploying to a live panel, replace it with an agency-listed isolated AC voltage transducer. Two substitution paths are available depending on the device chosen: **(a) AC waveform output** (e.g., a Yokogawa or Verivolt panel-mount PT with a 0–3 V AC output): wiring-only drop-in. The existing `measureChannel()` waveform-RMS algorithm works unchanged. Retain the 10 µF series AC-coupling capacitor and the 100 kΩ / 100 kΩ half-rail bias divider on A4 exactly as wired for the ZMPT101B. Calibrate `volt_scale` to the new transducer's rated output sensitivity (line V RMS ÷ ADC-pin V RMS at rated input). This is the simplest production upgrade path. @@ -586,10 +594,14 @@ This is a reference design for proportional tenant allocation, not a certified u - *150 Ω ±0.1% precision burden resistor* — wire from ADC A4 to GND. This converts the 4–20 mA loop current to 0.60–3.00 V DC, staying within the Cygnet's 3.3 V ADC limit. Remove the 10 µF AC-coupling capacitor and the 100 kΩ / 100 kΩ half-rail bias divider from A4; the signal is DC and needs neither AC coupling nor a bias network. - *Loop wiring*: connect the 24 V supply (+) → transducer VIN; transducer IOUT → burden resistor (+) → ADC A4; burden resistor (−) → GND → 24 V supply (−). Verify transducer polarity against the device datasheet. - *Firmware adaptation*: `measureChannel()` must be updated to replace the 2000-sample AC waveform loop with a single DC ADC read, compute instantaneous line voltage as `(adc_v - 0.60) / (3.00 - 0.60) × V_rated_full_scale` (where 0.60 V corresponds to 4 mA and 3.00 V to 20 mA), and pass that DC voltage value through the power and fault checks in place of `v_rms_adc`. The voltage-path bias and saturation checks must also be adapted — DC offset is no longer meaningful on A4, and the plausibility check should compare the derived line-voltage value directly against `VOLTAGE_MIN_V_RMS`. Implement the 4–20 mA path as a `#define`-gated alternative to the existing waveform path so both options can be compiled and bench-tested without modifying the core algorithm. -- Per-phase voltage sensing: for buildings with multi-phase distribution, replace the single voltage transducer with one per phase and extend the firmware to pair each current channel with its corresponding phase voltage. -- Implement [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) so firmware can be updated across the entire fleet without a truck roll to each panel. -- Integrate with a billing platform: configure a Notehub HTTP route that POSTs each `meter_summary.qo` to the analytics and billing database. Configure the downstream system to reject or quarantine any `meter_summary.qo` where `fault_mask != 0` and fall back to manual estimation for the affected period. Monthly totals are derived by querying the [Notehub Event Query API](https://dev.blues.io/api-reference/notehub-api/api-introduction/) and summing `t*_wh` for each device over the billing period. -- Commissioning baseline: on first installation, record the ADC DC offset for each channel with all loads off and store the values in Notehub device metadata. The downstream system can compare `fault_mask` flags against these baselines to distinguish genuine zero-load readings from sensor faults. + +**Per-phase voltage sensing** extends the design to buildings with multi-phase distribution: replace the single voltage transducer with one per phase and extend the firmware to pair each current channel with its corresponding phase voltage. + +**Notecard Outboard DFU** lets [firmware be updated](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) across the entire fleet without a truck roll to each panel. + +**Integrate with a billing platform** by configuring a Notehub HTTP route that POSTs each `meter_summary.qo` to the analytics and billing database. Configure the downstream system to reject or quarantine any `meter_summary.qo` where `fault_mask != 0` and fall back to manual estimation for the affected period. Monthly totals are derived by querying the [Notehub Event Query API](https://dev.blues.io/api-reference/notehub-api/api-introduction/) and summing `t*_wh` for each device over the billing period. + +**Capture a commissioning baseline** on first installation by recording the ADC DC offset for each channel with all loads off and storing the values in Notehub device metadata. The downstream system can compare `fault_mask` flags against these baselines to distinguish genuine zero-load readings from sensor faults. ## 12. Summary diff --git a/82-aerial-lift-rental-equipment-battery-health-monitor/README.md b/82-aerial-lift-rental-equipment-battery-health-monitor/README.md index 1e8c9880..f3af69e6 100644 --- a/82-aerial-lift-rental-equipment-battery-health-monitor/README.md +++ b/82-aerial-lift-rental-equipment-battery-health-monitor/README.md @@ -555,37 +555,47 @@ Mojo is not deployed to the field unit; its role ends when a firmware revision p A pack-health monitor has to make decisions about safety-critical equipment, so the boundary between this reference build and a production fleet rollout is well-defined: shunt sizing has to match real traction currents, SoC needs both OCV and Coulomb counting to be trustworthy under load, CAN integration is per-vendor work, and the device has to stay powered when the machine is in storage — the very interval where dead-on-arrival problems develop. The list below names each of those boundaries and points at the natural production path for each. -**Simplified for this proof-of-concept:** +### Simplified for this Proof-of-Concept -- **INA228 onboard shunt is bench-only; the default production path uses an external precision shunt.** Electric aerial lifts commonly draw 50–200 A during lift operation; the INA228's onboard 15 mΩ shunt is rated to ~10 A continuous and must not be placed inline on a traction-pack conductor at those currents. The firmware ships with `ENABLE_ACS758 0` as the default: `readPackVI()` reads pack current via INA228 `readCurrent()` through an external precision shunt wired to `VIN+`/`VIN–` (see §4 and §5). Update `DEFAULT_SHUNT_MOHM` and `DEFAULT_SHUNT_MAX_A` to match the installed shunt before building. The alternative field path (`ENABLE_ACS758 1`) uses an ACS758 Hall-effect sensor on A1 instead; use this path when galvanic isolation or inline shunt installation is impractical. For bench testing only, set `ENABLE_ACS758 0` and `BENCH_ONLY 1` to use the onboard 15 mΩ shunt at ≤10 A. The INA228's bus-voltage path (up to 85 V common-mode) is unaffected by shunt configuration in all cases. +The simplifications below are scope choices — each names a boundary where a production fleet rollout will want a different shunt, a blended SoC estimate, vendor-specific CAN work, or an always-on power feed. -- **OCV-based SoC is inaccurate under load.** Open-circuit voltage corresponds to SoC only when the pack is at rest (no load or charge current) for at least several minutes. During operation the terminal voltage is depressed by the internal resistance drop; the firmware's SoC estimate will read lower than actual SoC while the lift is in motion. For production, blend the OCV lookup with a Coulomb-counting depth-of-discharge estimate — Coulomb counting is accurate during dynamic operation, OCV is accurate at rest. The `throughput_ah` field is a bidirectional accumulator, not a true DoD value; a production Coulomb counter must separately track the net discharged deficit below full charge. +**The INA228 onboard shunt is bench-only; the default production path uses an external precision shunt.** Electric aerial lifts commonly draw 50–200 A during lift operation; the INA228's onboard 15 mΩ shunt is rated to ~10 A continuous and **must not** be placed inline on a traction-pack conductor at those currents. The firmware ships with `ENABLE_ACS758 0` as the default: `readPackVI()` reads pack current via INA228 `readCurrent()` through an external precision shunt wired to `VIN+`/`VIN–` (see §4 and §5). Update `DEFAULT_SHUNT_MOHM` and `DEFAULT_SHUNT_MAX_A` to match the installed shunt before building. The alternative field path (`ENABLE_ACS758 1`) uses an ACS758 Hall-effect sensor on A1 instead; use this path when galvanic isolation or inline shunt installation is impractical. For bench testing only, set `ENABLE_ACS758 0` and `BENCH_ONLY 1` to use the onboard 15 mΩ shunt at ≤10 A. The INA228's bus-voltage path (up to 85 V common-mode) is unaffected by shunt configuration in all cases. -- **SoC tables are sized for 48V packs.** The lookup tables in the firmware assume a 16S LiFePO4 or 24-cell lead-acid 48V pack. Machines with 24V, 36V, 72V, or 80V packs need tables scaled to their cell count. A `rated_voltage_v` environment variable and a scaling pass on the OCV table entries is the clean production extension. **Note: 72V and 80V packs also require verifying the INA228 common-mode limit before deployment. See below.** +**OCV-based SoC is inaccurate under load.** Open-circuit voltage corresponds to SoC only when the pack is at rest (no load or charge current) for at least several minutes. During operation the terminal voltage is depressed by the internal resistance drop; the firmware's SoC estimate will read lower than actual SoC while the lift is in motion. For production, blend the OCV lookup with a Coulomb-counting depth-of-discharge estimate — Coulomb counting is accurate during dynamic operation, OCV is accurate at rest. The `throughput_ah` field is a bidirectional accumulator, not a true DoD value; a production Coulomb counter must separately track the net discharged deficit below full charge. -- **INA228 bus-voltage input is limited to 85 V common-mode.** The Adafruit INA228 breakout used for bus-voltage sensing has an 85 V common-mode input limit. This is comfortably above the full-charge voltage of the 48 V-class packs the firmware defaults target (16S LiFePO4 full charge ≈ 58.4 V; 24-cell lead-acid ≈ 51.8 V). However, higher-voltage packs leave materially less headroom: a 20S LiFePO4 72 V-nominal pack can reach up to 73 V fully charged, still within limits; but a 22S or 24S LiFePO4 pack marketed as "72 V" may reach 80–87.6 V fully charged depending on cell count. Many 80 V-class packs (e.g. 24S LiFePO4 at 3.65 V/cell = 87.6 V) will **exceed** the 85 V INA228 limit when fully charged, which could damage the device. **Before deploying this design on any pack above 60 V nominal, measure or calculate the full-charge bus voltage and confirm it remains below 85 V.** For packs that cannot meet this constraint, substitute a voltage-sensing front end with a higher common-mode rating (such as an isolated bus-voltage monitor) in place of the INA228 for the pack-voltage measurement; the rest of the architecture is unaffected. +**SoC tables are sized for 48V packs.** The lookup tables in the firmware assume a 16S LiFePO4 or 24-cell lead-acid 48V pack. Machines with 24V, 36V, 72V, or 80V packs need tables scaled to their cell count. A `rated_voltage_v` environment variable and a scaling pass on the OCV table entries is the clean production extension. **Note: 72V and 80V packs also require verifying the INA228 common-mode limit before deployment. See below.** -- **CAN BMS integration is a placeholder, not deployable without vendor-specific work.** The CAN frame parser ships with a hardcoded example `BMS_CELL_GROUP_ID` of `0x18FF50E5` (a 29-bit extended J1939-style ID), a fixed 250 kbps bitrate, single-frame parsing only, and a simple layout that reads however many 2-byte groups fit in one frame. This placeholder will not match any real BMS without customization. Real BMS vendors use proprietary CAN IDs, scaling factors, multi-frame protocols, and message formats. The developer must obtain the BMS vendor's CAN DBC file or protocol documentation, update `BMS_CELL_GROUP_ID` and `parseCellGroupFrame()` to match, and verify the bitrate against the machine's CAN bus configuration. Some rental-equipment BMS implementations use SAE J1939 PGNs; others use entirely proprietary protocols with no public documentation. Do not deploy `ENABLE_CAN_BMS 1` to a machine without first capturing and decoding the machine's actual CAN traffic with an analyzer. +**INA228 bus-voltage input is limited to 85 V common-mode.** The Adafruit INA228 breakout used for bus-voltage sensing has an 85 V common-mode input limit. This is comfortably above the full-charge voltage of the 48 V-class packs the firmware defaults target (16S LiFePO4 full charge ≈ 58.4 V; 24-cell lead-acid ≈ 51.8 V). However, higher-voltage packs leave materially less headroom: a 20S LiFePO4 72 V-nominal pack can reach up to 73 V fully charged, still within limits; but a 22S or 24S LiFePO4 pack marketed as "72 V" may reach 80–87.6 V fully charged depending on cell count. Many 80 V-class packs (e.g. 24S LiFePO4 at 3.65 V/cell = 87.6 V) will **exceed** the 85 V INA228 limit when fully charged, which could damage the device. **Before deploying this design on any pack above 60 V nominal, measure or calculate the full-charge bus voltage and confirm it remains below 85 V.** For packs that cannot meet this constraint, substitute a voltage-sensing front end with a higher common-mode rating (such as an isolated bus-voltage monitor) in place of the INA228 for the pack-voltage measurement; the rest of the architecture is unaffected. -- **SoH requires a full discharge cycle to calibrate.** On first power-on, SoH initializes at 100%. The first meaningful SoH reading arrives after the device has observed one complete discharge cycle down below 30% SoC followed by a charge to above 90% SoC. Until then, the field is present in summaries but may be misleading. +**CAN BMS integration is a placeholder, not deployable without vendor-specific work.** The CAN frame parser ships with a hardcoded example `BMS_CELL_GROUP_ID` of `0x18FF50E5` (a 29-bit extended J1939-style ID), a fixed 250 kbps bitrate, single-frame parsing only, and a simple layout that reads however many 2-byte groups fit in one frame. This placeholder will not match any real BMS without customization. Real BMS vendors use proprietary CAN IDs, scaling factors, multi-frame protocols, and message formats. The developer must obtain the BMS vendor's CAN DBC file or protocol documentation, update `BMS_CELL_GROUP_ID` and `parseCellGroupFrame()` to match, and verify the bitrate against the machine's CAN bus configuration. Some rental-equipment BMS implementations use SAE J1939 PGNs; others use entirely proprietary protocols with no public documentation. **Do not deploy `ENABLE_CAN_BMS 1` to a machine without first capturing and decoding the machine's actual CAN traffic with an analyzer.** -- **No temperature compensation on OCV.** Battery OCV shifts with temperature — a cold lead-acid pack at 0°C reads several tenths of a volt lower at the same SoC as at 25°C. The firmware does not apply a temperature correction to the OCV lookup. For accurate low-temperature SoC on lead-acid packs, add a ΔV/ΔT correction factor; the pack temperature is already available in firmware. +**SoH requires a full discharge cycle to calibrate.** On first power-on, SoH initializes at 100%. The first meaningful SoH reading arrives after the device has observed one complete discharge cycle down below 30% SoC followed by a charge to above 90% SoC. Until then, the field is present in summaries but may be misleading. -- **Aux-rail power dependency.** The design powers the monitor from the machine's 12 V auxiliary circuit. On machines where that rail drops when the key is turned off, the charger is disconnected, or the master disconnect is opened, the monitor goes blind during storage, transport, and between-job intervals — precisely when low SoC, deep discharge, and thermal excursions are most likely to develop undetected. The §4 commissioning check addresses this, but if the field team has not confirmed that the chosen aux rail is always-on, the monitor provides no coverage during machine storage. For full coverage, the power feed must come from the main traction pack terminals through an appropriately rated HV DC/DC stage. +**No temperature compensation on OCV.** Battery OCV shifts with temperature — a cold lead-acid pack at 0°C reads several tenths of a volt lower at the same SoC as at 25°C. The firmware does not apply a temperature correction to the OCV lookup. For accurate low-temperature SoC on lead-acid packs, add a ΔV/ΔT correction factor; the pack temperature is already available in firmware. -- **Satellite data budget.** Notecard for Skylo includes 10 KB of satellite data. Each compact alert Note is typically under 100 bytes on the wire; 10 KB covers roughly 100 satellite alert events per billing period. Deployments where sustained NTN operation is expected should monitor satellite usage in Notehub and consider upgrading the data plan. Skylo coverage also requires an unobstructed view of the equatorial sky — the antenna must be mounted on the machine exterior, not in an enclosed battery bay. +**Aux-rail power dependency.** The design powers the monitor from the machine's 12 V auxiliary circuit. On machines where that rail drops when the key is turned off, the charger is disconnected, or the master disconnect is opened, the monitor goes blind during storage, transport, and between-job intervals — precisely when low SoC, deep discharge, and thermal excursions are most likely to develop undetected. The §4 commissioning check addresses this, but if the field team has not confirmed that the chosen aux rail is always-on, the monitor provides no coverage during machine storage. For full coverage, the power feed must come from the main traction pack terminals through an appropriately rated HV DC/DC stage. -- **Mojo does not read from the Notecard in firmware.** The sketch does not query the LTC2959 coulomb counter over Qwiic for runtime power telemetry. Adding a `mojo_mah` field to the summary is a straightforward extension. +**Satellite data budget.** Notecard for Skylo includes 10 KB of satellite data. Each compact alert Note is typically under 100 bytes on the wire; 10 KB covers roughly 100 satellite alert events per billing period. Deployments where sustained NTN operation is expected should monitor satellite usage in Notehub and consider upgrading the data plan. Skylo coverage also requires an unobstructed view of the equatorial sky — the antenna must be mounted on the machine exterior, not in an enclosed battery bay. -**Production next steps:** +**Mojo does not read from the Notecard in firmware.** The sketch does not query the LTC2959 coulomb counter over Qwiic for runtime power telemetry. Adding a `mojo_mah` field to the summary is a straightforward extension. -- **Commission the current sensor on each deployed unit.** For the default external-shunt field path (`ENABLE_ACS758 0`): confirm `DEFAULT_SHUNT_MOHM` and `DEFAULT_SHUNT_MAX_A` in the firmware match the installed shunt before flashing. After installation with the machine powered but the main contactor open, check the `[meas] i=` line in the serial output — it should read near 0 A. For the ACS758 alternative path (`ENABLE_ACS758 1`): the firmware ships with nominal datasheet values (`acs758_zero_v` = 2.5 V, `acs758_mv_per_a` = 10.0 mV/A), but Hall-sensor zero-offset error can bias the Ah accumulator by several amps and corrupt throughput and SoH over time. After installation with zero traction current flowing: check the `[meas] i=` line and, if the offset is significant, calculate the true zero-current `VOUT = analogRead(A1) × 3.3/4095 × 1.5` and set the `acs758_zero_v` Notehub environment variable to that measured value. If the installed sensor variant differs from ACS758LCB-200B (10 mV/A), update `acs758_mv_per_a` accordingly. -- Add temperature compensation to the OCV lookup table and to the Coulomb counting (charge efficiency degrades at low temperature). -- Expand the SoC table to cover all common pack voltages (24V, 36V, 48V); for 72V and 80V packs, first verify or replace the INA228 voltage-sensing front end (see the INA228 common-mode limit Note above), then add the higher-voltage table entries and drive selection from a `rated_voltage_v` environment variable. -- Implement vendor-specific CAN BMS parsers for the top rental-fleet BMS manufacturers (e.g., Zivan, Delta-Q, Enersys). -- Add a `battery_command.qi` inbound Notefile for fleet-triggered actions such as "reset SoH accumulator after a pack swap" or "clear alert cooldowns after a maintenance visit." -- Deploy [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) so the rental company can push OCV table updates, threshold recipes, and new BMS parsers across the fleet without a service visit. -- Store a rolling history of the last N cycle SoH measurements in the summary Note to give the fleet dashboard a degradation trend rather than a single current value. +### Production Next Steps + +Once the basic monitor is on a machine, the following extensions harden it for a real rental fleet — roughly from the most immediately useful to the most integration-dependent. + +**Commission the current sensor on each deployed unit.** For the default external-shunt field path (`ENABLE_ACS758 0`): confirm `DEFAULT_SHUNT_MOHM` and `DEFAULT_SHUNT_MAX_A` in the firmware match the installed shunt before flashing. After installation with the machine powered but the main contactor open, check the `[meas] i=` line in the serial output — it should read near 0 A. For the ACS758 alternative path (`ENABLE_ACS758 1`): the firmware ships with nominal datasheet values (`acs758_zero_v` = 2.5 V, `acs758_mv_per_a` = 10.0 mV/A), but Hall-sensor zero-offset error can bias the Ah accumulator by several amps and corrupt throughput and SoH over time. After installation with zero traction current flowing: check the `[meas] i=` line and, if the offset is significant, calculate the true zero-current `VOUT = analogRead(A1) × 3.3/4095 × 1.5` and set the `acs758_zero_v` Notehub environment variable to that measured value. If the installed sensor variant differs from ACS758LCB-200B (10 mV/A), update `acs758_mv_per_a` accordingly. + +**Add temperature compensation** to the OCV lookup table and to the Coulomb counting (charge efficiency degrades at low temperature). + +**Expand the SoC table** to cover all common pack voltages (24V, 36V, 48V); for 72V and 80V packs, first verify or replace the INA228 voltage-sensing front end (see the INA228 common-mode limit Note above), then add the higher-voltage table entries and drive selection from a `rated_voltage_v` environment variable. + +**Implement vendor-specific CAN BMS parsers** for the top rental-fleet BMS manufacturers (e.g., Zivan, Delta-Q, Enersys). + +**Add a `battery_command.qi` inbound Notefile** for fleet-triggered actions such as "reset SoH accumulator after a pack swap" or "clear alert cooldowns after a maintenance visit." + +**Deploy [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/)** so the rental company can push OCV table updates, threshold recipes, and new BMS parsers across the fleet without a service visit. + +**Store a rolling history** of the last N cycle SoH measurements in the summary Note to give the fleet dashboard a degradation trend rather than a single current value. ## 11. Summary diff --git a/83-off-grid-solar-battery-site-controller/README.md b/83-off-grid-solar-battery-site-controller/README.md index 0ebcd59f..da9e2c93 100644 --- a/83-off-grid-solar-battery-site-controller/README.md +++ b/83-off-grid-solar-battery-site-controller/README.md @@ -514,23 +514,37 @@ If you encounter an issue not covered above, the [Blues community forum](https:/ This reference design intentionally stays narrow: it answers the site-uptime question — "is this off-grid site healthy enough that I don't need to send a truck?" — and leaves the harder problems (cell-level diagnostics, MPPT control, multi-bank aggregation) to companion designs where they belong. -**Simplified for the POC:** - -- **Read-only over VE.Direct.** The firmware listens to the broadcast text protocol but never writes a command back to either Victron device. Setting parameters on the SmartShunt or MPPT (battery capacity, absorption voltage, equalization schedule) is done with the Victron VictronConnect app at commissioning, not from Notehub. Adding write support would mean tracking the proprietary VE.Direct HEX framing on top of the text protocol covered here. -- **Single battery bank, single MPPT.** The reference design assumes one SmartShunt watching one battery bank and one SmartSolar MPPT watching one solar array. Sites with parallel banks or multiple charge controllers require either a Victron Cerbo GX (which aggregates over Victron's CAN bus) or a firmware extension that opens additional VE.Direct serial ports on the Cygnet host. -- **No MPPT control.** The firmware reports what the MPPT is doing but cannot command a different absorption voltage, force a manual equalize, or disable charging. Remote control of the charge algorithm is a different problem class with safety implications and is intentionally out of scope. -- **Bank-level signal scope only.** Per-cell voltages and cell imbalance are not exposed on the VE.Direct wire — they travel over CAN bus and require dedicated hardware, as called out in §1. This design targets the bank-level uptime failure modes and explicitly defers cell-level telemetry to a companion design. -- **Sensor selection is fixed at the firmware level.** The two VE.Direct ports are hard-coded to a SmartShunt on Serial1 and an MPPT on the SoftwareSerial pin. Swapping in a different VE.Direct device family (such as a Phoenix inverter) requires extending the parser to recognise its label set. -- **No local sample history.** The host accumulates the current summary window in the persistent state struct between sleeps, but a power interruption that drains the Notecard backup capacitor clears the in-progress accumulator. Long-term storage lives in Notehub, not on the device. - -**Production next steps:** - -- **Multi-bank support.** Open additional SoftwareSerial ports on free Cygnet GPIO pins and parse a second SmartShunt and MPPT pair, adding a per-bank index to each Note so downstream analytics can attribute readings correctly. -- **Alarm output relays.** Drive a Cygnet GPIO to a small SSR or low-side switch, so a `harvest_deficit` or `soc_low` alert can trigger a local audible or visual indicator at the site for technicians on the ground. -- **Weather-data overlay.** Route `solar_summary.qo` events into a server-side process that joins each window's `yield_kwh` against a weather feed (cloud cover, GHI) for the site coordinates. A real recharge-deficit problem looks very different from a stretch of cloudy weather, and the overlay separates the two automatically. -- **BLE-based field provisioning.** A Bluetooth provisioning page on the Notecarrier CX would let a technician set the site identifier, fixed GPS coordinates, and initial thresholds from a phone in the field, with no laptop or USB cable required. The Notecard supports BLE on supported SKUs. -- **Notecard Outboard DFU for fleet firmware updates.** [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) lets Notehub push a new STM32 firmware image to every device in a fleet over the air. This is essential for a device that may live on a remote tower or backcountry array for years between physical visits. -- **Multi-phase or DC-coupled load shunting.** Sites that include AC inverter loads (Victron MultiPlus or similar) can add a Quattro or MultiPlus VE.Bus integration to capture inverter input, output, and inverter-internal alarms — a richer picture of total site load than the algebraic `pv_w - bat_w` computation used here. +### Simplified for the POC + +The simplifications below are deliberate scope choices — each marks where this site-uptime monitor stops and a companion design or firmware extension picks up. + +**Read-only over VE.Direct.** The firmware listens to the broadcast text protocol but never writes a command back to either Victron device. Setting parameters on the SmartShunt or MPPT (battery capacity, absorption voltage, equalization schedule) is done with the Victron VictronConnect app at commissioning, not from Notehub. Adding write support would mean tracking the proprietary VE.Direct HEX framing on top of the text protocol covered here. + +**Single battery bank, single MPPT.** The reference design assumes one SmartShunt watching one battery bank and one SmartSolar MPPT watching one solar array. Sites with parallel banks or multiple charge controllers require either a Victron Cerbo GX (which aggregates over Victron's CAN bus) or a firmware extension that opens additional VE.Direct serial ports on the Cygnet host. + +**No MPPT control.** The firmware reports what the MPPT is doing but cannot command a different absorption voltage, force a manual equalize, or disable charging. Remote control of the charge algorithm is a different problem class with safety implications and is intentionally out of scope. + +**Bank-level signal scope only.** Per-cell voltages and cell imbalance are not exposed on the VE.Direct wire — they travel over CAN bus and require dedicated hardware, as called out in §1. This design targets the bank-level uptime failure modes and explicitly defers cell-level telemetry to a companion design. + +**Sensor selection is fixed at the firmware level.** The two VE.Direct ports are hard-coded to a SmartShunt on Serial1 and an MPPT on the SoftwareSerial pin. Swapping in a different VE.Direct device family (such as a Phoenix inverter) requires extending the parser to recognise its label set. + +**No local sample history.** The host accumulates the current summary window in the persistent state struct between sleeps, but a power interruption that drains the Notecard backup capacitor clears the in-progress accumulator. Long-term storage lives in Notehub, not on the device. + +### Production Next Steps + +Taking this monitor toward a production fleet rollout means scaling to multi-bank sites, adding local alerting and field provisioning, and supporting over-the-air updates for devices that may go years between physical visits. The following extensions are the natural progression. + +**Multi-bank support.** Open additional SoftwareSerial ports on free Cygnet GPIO pins and parse a second SmartShunt and MPPT pair, adding a per-bank index to each Note so downstream analytics can attribute readings correctly. + +**Alarm output relays.** Drive a Cygnet GPIO to a small SSR or low-side switch, so a `harvest_deficit` or `soc_low` alert can trigger a local audible or visual indicator at the site for technicians on the ground. + +**Weather-data overlay.** Route `solar_summary.qo` events into a server-side process that joins each window's `yield_kwh` against a weather feed (cloud cover, GHI) for the site coordinates. A real recharge-deficit problem looks very different from a stretch of cloudy weather, and the overlay separates the two automatically. + +**BLE-based field provisioning.** A Bluetooth provisioning page on the Notecarrier CX would let a technician set the site identifier, fixed GPS coordinates, and initial thresholds from a phone in the field, with no laptop or USB cable required. The Notecard supports BLE on supported SKUs. + +**Notecard Outboard DFU for fleet firmware updates.** [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) lets Notehub push a new STM32 firmware image to every device in a fleet over the air. This is essential for a device that may live on a remote tower or backcountry array for years between physical visits. + +**Multi-phase or DC-coupled load shunting.** Sites that include AC inverter loads (Victron MultiPlus or similar) can add a Quattro or MultiPlus VE.Bus integration to capture inverter input, output, and inverter-internal alarms — a richer picture of total site load than the algebraic `pv_w - bat_w` computation used here. ## 12. Summary diff --git a/84-remote-cabinet-backup-battery-sentinel/README.md b/84-remote-cabinet-backup-battery-sentinel/README.md index 0fa814a6..abd2ccf5 100644 --- a/84-remote-cabinet-backup-battery-sentinel/README.md +++ b/84-remote-cabinet-backup-battery-sentinel/README.md @@ -476,26 +476,43 @@ If a symptom does not appear above, post a description (with the relevant `[sent This design targets one pack on one bus and the pack-level signal that catches the most common cabinet failure modes. Cell-level diagnostics, multi-bus shelters, and full state-of-health modeling are deliberate scope choices left to companion designs — the goal here is to get the simplest defensible cabinet sentinel into the field, then layer on richer telemetry where the site warrants it. -**Simplified for the POC:** - -- **Single pack, single bus.** The firmware monitors one pack on one positive-referenced DC bus. Cabinets with a primary bank and a parallel reserve, or multi-bus telecom shelters with separate −48 V plant and 12 V auxiliary loads, need one sentinel per bus or a multi-channel front end. -- **One INA228 with a single shunt.** The default 15 mΩ onboard shunt covers up to roughly 8 A continuous. Higher-current installations require an external busbar shunt (see §4 and §5); the firmware exposes `INA228_SHUNT_OHMS` and `INA228_MAX_CURRENT_A` for that case but does not auto-detect. -- **Pack-level signals only — no cell-level visibility.** Per-cell voltage and per-cell imbalance detection are out of scope. Float-current trending identifies that the string as a whole is degrading, not which cell is failing. -- **No state-of-health (SoH) modeling.** SoC is tracked by coulomb counting against a commissioned `usable_capacity_ah`, but the firmware does not estimate capacity fade over time. Re-commissioning `usable_capacity_ah` after a measured discharge cycle is a manual step. -- **No temperature compensation on voltage thresholds.** VRLA float voltage drifts with battery temperature (typically −3 to −5 mV per cell per °C). The fixed `volt_min_v` and `volt_max_v` thresholds do not adjust automatically; in a cabinet that swings 30 °C across seasons, set thresholds with margin or split the fleet by climate zone. -- **One thermistor on the case surface.** A single surface probe near the geometric center of the pack flags gross thermal events but cannot distinguish a hot cell from charger-induced bulk heating, and it cannot resolve internal cell temperature. -- **OCV-based SoC is approximate, especially under load.** Coulomb counting against the nameplate capacity is the only state estimator; the firmware does not blend in OCV at rest, does not detect a full-charge event automatically, and will drift between manual recalibrations. -- **No inbound command channel.** Operators tune behavior via Notehub environment variables — there is no `battery_command.qi` for fleet-triggered actions such as "clear alert cooldowns" or "reset SoC after a pack swap." - -**Production next steps:** - -- **Add a temperature probe on the pack interior or terminal post** for a more accurate read of the chemistry's thermal state, and apply temperature compensation to the float-voltage thresholds and to the coulomb-counting charge efficiency factor. -- **Blend OCV at rest with coulomb counting** for a self-correcting SoC estimate that recovers from drift after a long quiescent period, and add an automatic full-charge detector to re-anchor SoC to 100 percent without operator intervention. -- **Layer in cell-level monitoring** via a dedicated cell-monitor IC (TI BQ76940 or equivalent), CAN, or Bluetooth into a pack-resident BMS. A cell-level channel transforms the float-current signal from a string-level aggregate into a per-cell diagnostic. -- **Integrate with the site's existing BMS** when one is present: many telecom-grade VRLA strings ship with a CAN or RS-485 BMS that already exposes per-cell voltages and SoH. Adding a CAN front end and a vendor-specific frame parser turns this design into a redundant cellular uplink for that BMS rather than a parallel measurement. -- **Aggregate across a fleet** in a downstream time-series store. Float-current trends per cabinet, ranked against the fleet median, surface the outlier cabinets weeks before any one of them trips an absolute threshold. -- **Deploy [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/)** so threshold recipes, OCV blends, and chemistry-specific calibrations can be pushed across the fleet without a truck roll. -- **Add an inbound `battery_command.qi` Notefile** for fleet operators to reset SoH accumulators after a pack swap, clear alert cooldowns following a planned maintenance visit, or trigger an immediate ad-hoc sample-and-report. +### Simplified for the POC + +The simplifications below are deliberate scope choices — each is a place where a production deployment will reach for another channel, another sensor, or a richer state estimator once a specific site demands it. + +**Single pack, single bus.** The firmware monitors one pack on one positive-referenced DC bus. Cabinets with a primary bank and a parallel reserve, or multi-bus telecom shelters with separate −48 V plant and 12 V auxiliary loads, need one sentinel per bus or a multi-channel front end. + +**One INA228 with a single shunt.** The default 15 mΩ onboard shunt covers up to roughly 8 A continuous. Higher-current installations require an external busbar shunt (see §4 and §5); the firmware exposes `INA228_SHUNT_OHMS` and `INA228_MAX_CURRENT_A` for that case but does not auto-detect. + +**Pack-level signals only — no cell-level visibility.** Per-cell voltage and per-cell imbalance detection are out of scope. Float-current trending identifies that the string as a whole is degrading, not which cell is failing. + +**No state-of-health (SoH) modeling.** SoC is tracked by coulomb counting against a commissioned `usable_capacity_ah`, but the firmware does not estimate capacity fade over time. Re-commissioning `usable_capacity_ah` after a measured discharge cycle is a manual step. + +**No temperature compensation on voltage thresholds.** VRLA float voltage drifts with battery temperature (typically −3 to −5 mV per cell per °C). The fixed `volt_min_v` and `volt_max_v` thresholds do not adjust automatically; in a cabinet that swings 30 °C across seasons, set thresholds with margin or split the fleet by climate zone. + +**One thermistor on the case surface.** A single surface probe near the geometric center of the pack flags gross thermal events but cannot distinguish a hot cell from charger-induced bulk heating, and it cannot resolve internal cell temperature. + +**OCV-based SoC is approximate, especially under load.** Coulomb counting against the nameplate capacity is the only state estimator; the firmware does not blend in OCV at rest, does not detect a full-charge event automatically, and will drift between manual recalibrations. + +**No inbound command channel.** Operators tune behavior via Notehub environment variables — there is no `battery_command.qi` for fleet-triggered actions such as "clear alert cooldowns" or "reset SoC after a pack swap." + +### Production Next Steps + +Once a real cabinet fleet is running the basic sentinel, the following extensions are the natural progression — roughly from the most immediately useful to the most integration-dependent. + +**Add a temperature probe on the pack interior or terminal post** for a more accurate read of the chemistry's thermal state, and apply temperature compensation to the float-voltage thresholds and to the coulomb-counting charge efficiency factor. + +**Blend OCV at rest with coulomb counting** for a self-correcting SoC estimate that recovers from drift after a long quiescent period, and add an automatic full-charge detector to re-anchor SoC to 100 percent without operator intervention. + +**Layer in cell-level monitoring** via a dedicated cell-monitor IC (TI BQ76940 or equivalent), CAN, or Bluetooth into a pack-resident BMS. A cell-level channel transforms the float-current signal from a string-level aggregate into a per-cell diagnostic. + +**Integrate with the site's existing BMS** when one is present: many telecom-grade VRLA strings ship with a CAN or RS-485 BMS that already exposes per-cell voltages and SoH. Adding a CAN front end and a vendor-specific frame parser turns this design into a redundant cellular uplink for that BMS rather than a parallel measurement. + +**Aggregate across a fleet** in a downstream time-series store. Float-current trends per cabinet, ranked against the fleet median, surface the outlier cabinets weeks before any one of them trips an absolute threshold. + +**Deploy [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/)** so threshold recipes, OCV blends, and chemistry-specific calibrations can be pushed across the fleet without a truck roll. + +**Add an inbound `battery_command.qi` Notefile** for fleet operators to reset SoH accumulators after a pack swap, clear alert cooldowns following a planned maintenance visit, or trigger an immediate ad-hoc sample-and-report. ## 12. Summary diff --git a/85-cellular-medication-adherence-pillbox/README.md b/85-cellular-medication-adherence-pillbox/README.md index 128f9851..c1893e25 100644 --- a/85-cellular-medication-adherence-pillbox/README.md +++ b/85-cellular-medication-adherence-pillbox/README.md @@ -411,31 +411,50 @@ If a problem isn't on this list, the [Blues community forum](https://discuss.blu The design deliberately stops at "did a lid open?" — the most reliable signal that survives the realities of an elderly patient's home network, a caregiver's weekly refill routine, and a Bluetooth-fatigued smartphone. Confirmed ingestion, AM/PM trays, and local reminder UX are real product features, but they belong in a follow-on design rather than diluting the cellular-first sensor this POC is proving out. -**Simplified for the POC:** +### Simplified for the POC -- **Cannot confirm a dose was actually taken.** The device reports each detected compartment lid open, but it cannot distinguish "opened and took the pill" from "opened and closed without taking it." Confirming a dose requires a weight sensor on the tray or patient self-report — both are straightforward extensions but add hardware or UX complexity outside the scope of this POC. -- **Caregiver and pharmacist refill sessions are indistinguishable from patient dose-taking opens.** When the weekly tray is loaded — whether by the patient, a caregiver, or a pharmacist — opening each compartment lid to place pills generates `pill_open.qo` events and sets bitmask bits that are identical to genuine dose-taking opens. A single loading session can set all seven bits in `daily_opens` and produce up to seven events within one or two polling intervals, creating a false picture of perfect adherence for that day. This is a more active distortion than the dose-confirmation limitation above: it inflates the adherence record rather than leaving it ambiguous. Downstream systems and clinical workflows must account for this in at least one of the following ways: +The simplifications below are deliberate scope choices — each is a place where a production deployment will add a sensor, a downstream workflow, or a tighter data-handling control once a real RPM program starts running it. **This is a proof-of-concept reference design, not a medical device.** + +**Cannot confirm a dose was actually taken.** The device reports each detected compartment lid open, but it cannot distinguish "opened and took the pill" from "opened and closed without taking it." Confirming a dose requires a weight sensor on the tray or patient self-report — both are straightforward extensions but add hardware or UX complexity outside the scope of this POC. + +**Caregiver and pharmacist refill sessions are indistinguishable from patient dose-taking opens.** When the weekly tray is loaded — whether by the patient, a caregiver, or a pharmacist — opening each compartment lid to place pills generates `pill_open.qo` events and sets bitmask bits that are identical to genuine dose-taking opens. A single loading session can set all seven bits in `daily_opens` and produce up to seven events within one or two polling intervals, **creating a false picture of perfect adherence for that day.** This is a more active distortion than the dose-confirmation limitation above: it inflates the adherence record rather than leaving it ambiguous. Downstream systems and clinical workflows must account for this in at least one of the following ways: - **Fill outside the monitored window.** If the tray is loaded at a predictable time (e.g., Sunday evening before the monitoring week begins), configure downstream routes to flag or suppress clustered multi-lid opens during that window. - **Use a clinician-side refill flag.** The care coordinator logs refill sessions in the downstream covered system; the patient-record view excludes or tags those event clusters from adherence calculations. - **Filter simultaneous multi-lid opens downstream.** Multiple bits set in a single 30-second poll (`newly_opened` containing ≥ 3 compartments at once) is a strong operational signal of a refill rather than individual dose-taking. A downstream route rule or dashboard filter can flag clusters above a configurable threshold for manual review rather than counting them as adherence events. -- **Brief opens between polls are missed.** The firmware detects lid-open events by comparing pin state at each poll boundary (default every 30 seconds). A lid that is opened and fully re-closed within a single poll interval generates no event and is not counted in the daily summary. For the intended use case — a patient opening a compartment to take a pill — the lid will naturally remain open long enough to be detected. Caregiver testing, brief accidental knocks, or other sub-30-second interactions will not be recorded. Reducing `poll_interval_sec` to the firmware-enforced minimum of 15 seconds halves the exposure window; interrupt-driven or latch-based hardware would eliminate it entirely. -- **Pending retry queue has a finite depth.** If the Notecard is unable to accept `note.add` requests across more than four consecutive worst-case polling wakes (28 buffered events), the oldest queued dose-open records are evicted and permanently lost. The device emits a `pill_diag.qo` Note with `error: "pending_overflow"` and a `dropped` count when overflow first occurs, and a matching `error: "pending_overflow_cleared"` Note when the queue drains — providing cloud-visible evidence of data loss. A Notecard outage long enough to exhaust the buffer is uncommon on a battery-backed Notecard Cell+WiFi, but in the worst case downstream adherence calculations will undercount dose-opens for the affected interval without an explicit correction signal. Route `pill_diag.qo` to your alert channel alongside `pill_open.qo` so these episodes are not missed. -- **7-compartment design only.** The Notecarrier CX exposes exactly seven digital I/O pins (D5, D6, D9–D13), which maps cleanly to a standard 7-day tray. A 14-compartment tray (AM/PM per day) would require an I2C GPIO expander such as the MCP23017, adding one part and a library dependency. -- **No on-device time zone awareness.** The daily summary rolls over at UTC midnight. In practice, a care coordinator should set `summary_hour_utc` to match the patient's local midnight (e.g., `5` for Eastern Standard Time), which is tunable via environment variable without a reflash. -- **Micro-switch placement is manual.** Mounting the micro-switches inside a commercial pillbox requires drilling, adhesive, or 3D-printed brackets. A production design would integrate the switches into a purpose-built tray PCB. -- **No tamper or battery-low reporting.** The device does not currently alert if someone removes the Notecard, cuts power, or if the LiPo voltage drops below a safe threshold. Battery voltage monitoring via `card.voltage` and a `sync:true` low-battery event would be a straightforward addition. -- **No local visual or audible reminder.** The device is purely a reporting platform; it does not buzz or light up to remind the patient to take their medication. Adding a piezo buzzer on a PWM-capable pin would require a scheduled inbound event from Notehub to trigger it. -- **Pre-time-sync opens carry no calendar date.** On first boot, the device may accumulate opens before the Notecard acquires valid UTC time. Those opens remain in `daily_opens` and are associated with the first valid UTC day once time becomes available, then move into `prev_day_opens` at the next actual day rollover to feed the subsequent summary, with the correct bitmask. However, the summary's timestamp reflects when it was sent, not the (unknown) calendar day when the lids were opened. If accurate calendar-day attribution of pre-sync opens is required, wait for a `_session.qo` event in Notehub (confirming time-sync) before placing the device with the patient. -- **Firmware state holds only one pending day's summary data.** The `PillboxState` struct contains a single `prev_day_opens` slot. If two consecutive UTC-day boundaries pass while a pending summary has not yet been emitted, for example, because the device is powered off spanning an entire day, or because total power loss causes `NotePayloadRetrieveAfterSleep` to fail on the next boot — the slot is overwritten and the earlier day's adherence data is unrecoverable. Note that a lack of cellular connectivity alone does *not* cause this: the Notecard stores queued Notes locally in its on-device flash and delivers them automatically once connectivity is restored. The risk is power loss before `emitDailySummary()` executes. Size the LiPo for the intended deployment duration to minimize exposure. -- **Patient identity must stay out of Note payloads and Notehub metadata.** Note bodies are stored and routed as plaintext through Notehub and any downstream systems. Notehub device metadata (tags, serial-number field) is not designed as a covered system for protected health information. For an RPM deployment, never embed a patient name, MRN, date of birth, or any other PHI in a Note body or in Notehub device metadata. Assign only an opaque, non-PHI deployment identifier (for example, a random UUID or clinic-assigned device code) to the Notehub device tag or serial-number field. Maintain the mapping from device UID to patient record exclusively in your downstream covered system. If your deployment architecture requires routing PHI through any cloud component, engage qualified counsel to review the complete data path before go-live. - -**Production next steps:** - -- 14-slot tray support via an MCP23017 I2C GPIO expander (adds AM/PM per day); the firmware's bitmask and event structure extend naturally to 16 bits. -- Opaque deployment-ID assignment (a random UUID or clinic-assigned device code) in the Notehub device tag or serial-number field so downstream routes can correlate events to the correct caregiver via a patient-record lookup in the downstream covered system, keyed on device UID. -- Voltage-variable sync behavior via `hub.set` `voutbound` — automatically extend the outbound cadence as the LiPo voltage drops, maximizing runtime without manual intervention. -- [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) for over-the-air host firmware updates so new features (buzzer support, new alert rules) can be pushed to deployed devices without a pharmacy recall. -- A scheduled inbound Notefile (`pill_reminder.qi`) that the Notecard can trigger a local buzzer or LED on, turning the device from a passive sensor into an active reminder system. + +**Brief opens between polls are missed.** The firmware detects lid-open events by comparing pin state at each poll boundary (default every 30 seconds). A lid that is opened and fully re-closed within a single poll interval generates no event and is not counted in the daily summary. For the intended use case — a patient opening a compartment to take a pill — the lid will naturally remain open long enough to be detected. Caregiver testing, brief accidental knocks, or other sub-30-second interactions will not be recorded. Reducing `poll_interval_sec` to the firmware-enforced minimum of 15 seconds halves the exposure window; interrupt-driven or latch-based hardware would eliminate it entirely. + +**Pending retry queue has a finite depth.** If the Notecard is unable to accept `note.add` requests across more than four consecutive worst-case polling wakes (28 buffered events), the oldest queued dose-open records are evicted and **permanently lost.** The device emits a `pill_diag.qo` Note with `error: "pending_overflow"` and a `dropped` count when overflow first occurs, and a matching `error: "pending_overflow_cleared"` Note when the queue drains — providing cloud-visible evidence of data loss. A Notecard outage long enough to exhaust the buffer is uncommon on a battery-backed Notecard Cell+WiFi, but in the worst case downstream adherence calculations will undercount dose-opens for the affected interval without an explicit correction signal. Route `pill_diag.qo` to your alert channel alongside `pill_open.qo` so these episodes are not missed. + +**7-compartment design only.** The Notecarrier CX exposes exactly seven digital I/O pins (D5, D6, D9–D13), which maps cleanly to a standard 7-day tray. A 14-compartment tray (AM/PM per day) would require an I2C GPIO expander such as the MCP23017, adding one part and a library dependency. + +**No on-device time zone awareness.** The daily summary rolls over at UTC midnight. In practice, a care coordinator should set `summary_hour_utc` to match the patient's local midnight (e.g., `5` for Eastern Standard Time), which is tunable via environment variable without a reflash. + +**Micro-switch placement is manual.** Mounting the micro-switches inside a commercial pillbox requires drilling, adhesive, or 3D-printed brackets. A production design would integrate the switches into a purpose-built tray PCB. + +**No tamper or battery-low reporting.** The device does not currently alert if someone removes the Notecard, cuts power, or if the LiPo voltage drops below a safe threshold. Battery voltage monitoring via `card.voltage` and a `sync:true` low-battery event would be a straightforward addition. + +**No local visual or audible reminder.** The device is purely a reporting platform; it does not buzz or light up to remind the patient to take their medication. Adding a piezo buzzer on a PWM-capable pin would require a scheduled inbound event from Notehub to trigger it. + +**Pre-time-sync opens carry no calendar date.** On first boot, the device may accumulate opens before the Notecard acquires valid UTC time. Those opens remain in `daily_opens` and are associated with the first valid UTC day once time becomes available, then move into `prev_day_opens` at the next actual day rollover to feed the subsequent summary, with the correct bitmask. However, the summary's timestamp reflects when it was sent, not the (unknown) calendar day when the lids were opened. If accurate calendar-day attribution of pre-sync opens is required, wait for a `_session.qo` event in Notehub (confirming time-sync) before placing the device with the patient. + +**Firmware state holds only one pending day's summary data.** The `PillboxState` struct contains a single `prev_day_opens` slot. If two consecutive UTC-day boundaries pass while a pending summary has not yet been emitted, for example, because the device is powered off spanning an entire day, or because total power loss causes `NotePayloadRetrieveAfterSleep` to fail on the next boot — the slot is overwritten and the earlier day's adherence data is unrecoverable. Note that a lack of cellular connectivity alone does *not* cause this: the Notecard stores queued Notes locally in its on-device flash and delivers them automatically once connectivity is restored. The risk is power loss before `emitDailySummary()` executes. Size the LiPo for the intended deployment duration to minimize exposure. + +**Patient identity must stay out of Note payloads and Notehub metadata.** Note bodies are stored and routed as plaintext through Notehub and any downstream systems. Notehub device metadata (tags, serial-number field) is not designed as a covered system for protected health information. For an RPM deployment, **never embed a patient name, MRN, date of birth, or any other PHI in a Note body or in Notehub device metadata.** Assign only an opaque, non-PHI deployment identifier (for example, a random UUID or clinic-assigned device code) to the Notehub device tag or serial-number field. Maintain the mapping from device UID to patient record exclusively in your downstream covered system. If your deployment architecture requires routing PHI through any cloud component, engage qualified counsel to review the complete data path before go-live. + +### Production Next Steps + +Once a real RPM program is running the basic monitor, the following extensions are the natural progression toward a fieldable product. + +**14-slot tray support** via an MCP23017 I2C GPIO expander (adds AM/PM per day); the firmware's bitmask and event structure extend naturally to 16 bits. + +**Opaque deployment-ID assignment** (a random UUID or clinic-assigned device code) in the Notehub device tag or serial-number field so downstream routes can correlate events to the correct caregiver via a patient-record lookup in the downstream covered system, keyed on device UID. + +**Voltage-variable sync behavior** via `hub.set` `voutbound` — automatically extend the outbound cadence as the LiPo voltage drops, maximizing runtime without manual intervention. + +**[Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/)** for over-the-air host firmware updates so new features (buzzer support, new alert rules) can be pushed to deployed devices without a pharmacy recall. + +**A scheduled inbound Notefile** (`pill_reminder.qi`) that the Notecard can trigger a local buzzer or LED on, turning the device from a passive sensor into an active reminder system. ## 11. Summary diff --git a/87-post-discharge-vitals-relay-hub/README.md b/87-post-discharge-vitals-relay-hub/README.md index 5d25b418..f9b12a1e 100644 --- a/87-post-discharge-vitals-relay-hub/README.md +++ b/87-post-discharge-vitals-relay-hub/README.md @@ -472,24 +472,41 @@ If a problem is not on this list, the [Blues community forum](https://discuss.bl The hub is intentionally scoped to the post-discharge window — one patient, one wall outlet, the standard Bluetooth SIG health profiles, and the smallest viable commissioning workflow. Per-patient baselines, multi-device concurrency, OTA firmware, and proprietary activity-band data are all real product features that belong in a follow-on rather than complicating the reference design. -**Simplified for the POC:** - -- **One BLE connection at a time.** The nRF52840's Central role supports multiple concurrent connections, but the sketch only opens one. If a patient manages to trigger two devices simultaneously (unlikely with health devices that connect-measure-disconnect quickly), the second connect attempt is queued after the first device disconnects. A multi-connection extension is straightforward in the Adafruit nRF52 library. -- **Alert cooldown is a fixed firmware constant, not remotely configurable.** The hub suppresses repeated `vitals_alert.qo` Notes of the same type for 5 minutes (`ALERT_COOLDOWN_MS`). The cooldown duration cannot be adjusted per patient without a firmware reflash. A production deployment would expose this as a Notehub environment variable alongside the clinical thresholds, so care coordinators can tighten or relax the alert rate for individual patients. -- **Weight-delta alerting, not absolute.** The `weight_gain` alert fires on change vs. previous reading, not on absolute weight. On first boot there is no previous reading so no delta alert is possible. A daily-comparison window (today vs. same time yesterday) is a more robust clinical metric and requires persisting the previous day's reading — doable by storing it in a `_notecard.db` database Notefile. -- **Heart rate only from activity band.** The Heart Rate Service (0x180D) provides heart rate, but step count is not part of the standard service — it lives in proprietary manufacturer-specific GATT services that differ across activity band brands. The firmware captures only heart rate from that service. -- **Blood Pressure Measurement — `user_id` and `measurement_status` not captured.** `parseBpMmhg` correctly decodes systolic, diastolic, and pulse rate for any compliant 0x2A35 layout. Only the timestamp field (flags bit 1) affects the pulse-rate offset: the parser adds 7 bytes to the mandatory 7-byte header when the timestamp is present, correctly handling both timestamp-present (Omron M4) and timestamp-absent layouts. The User ID (flags bit 3) and Measurement Status (flags bit 4) fields appear after pulse rate in the spec ordering; they are not used and their values are discarded. -- **BLE bonding requires a commissioning step, and public/static-address devices also require an allow-list entry.** The hub is fail-closed by default: unrecognized devices are ignored. Before shipping to a patient, a commissioning build with both `-DALLOW_UNENROLLED_DEVICES_FOR_DEV=1` and `-DALLOW_COMMISSIONING_BUILD` is needed to pair the patient's specific devices and store their bond keys. After commissioning, inspect the `bond_established` Notes in `commissioning.db` on Notehub: any device whose `addr_type` is `0x00` (public) or `0x01` (random static) must also be added to `ENROLLED_DEVICES` in `vitals_config.h` — bonding alone is not sufficient for those devices because the hub cannot identify them through IRK resolution. Remove both commissioning flags before deploying to patients. The MAC allow-list is a compile-time constant that cannot be updated without a reflash. -- **BLE pairing uses encrypted but unauthenticated bonding.** The commissioning step uses Just Works pairing (`setMITMProtect(false)`) because most consumer health devices lack input/output capabilities. This provides an encrypted BLE connection but offers no man-in-the-middle protection during the initial key exchange. For production deployments handling patient data, the clinical and security teams should define a controlled commissioning procedure (e.g., pairing only in a secured kitting environment at the point of device preparation), evaluate device and vendor choices that support authenticated pairing modes (Numeric Comparison or Passkey Entry) where input/output capabilities exist, and review the full threat model for the deployment setting before processing real patient data. -- **No offline-reading catchup.** If the hub is unplugged for several days and re-plugged, it doesn't know what readings it missed. Readings taken while the hub was offline are simply absent from the record. -- **Activity band steps not captured.** Standard Heart Rate Service (0x180D) does not carry step count. Activity bands that expose a proprietary step-count characteristic require a device-specific firmware extension. - -**Production next steps:** -- Investigate host firmware OTA: [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) targets hosts whose bootloader can be driven over UART by the Notecard (e.g., STM32 System Memory bootloader). The Adafruit Feather nRF52840's UF2 bootloader uses USB mass-storage enumeration, which does not fit that model. A production deployment would need either a custom UART-accessible bootloader on the nRF52840 or an alternative delivery path, for example, Nordic Bluetooth DFU triggered by a Notecard-delivered environment-variable flag — before OTA firmware updates can be offered as a supported feature. -- Per-patient baseline learning: store a 7-day rolling average weight in a local `.db` Notefile and alert when the single-day reading is more than `weight_delta_kg` above the rolling average rather than just the previous reading. -- Heartbeat Note: emit a `heartbeat.qo` every 24 hours even if no readings arrived, so the care team can distinguish "patient not using devices" from "hub offline." -- Low-voltage notification: the Notecard's `card.voltage` response monitors the supply rail; a `voltage_low` alert can page the care coordinator if the hub is losing power or the USB supply is marginal. -- Remotely configurable alert cooldown: expose `ALERT_COOLDOWN_MS` as a Notehub environment variable so care coordinators can tune the alert rate per patient without a reflash. +### Simplified for the POC + +The simplifications below are deliberate scope choices — each is a place where a production deployment will add concurrency, a configurable knob, or a hardened security path once a real post-discharge program runs it. As the warning above states, **this is a proof-of-concept reference design, not a cleared medical device.** + +**One BLE connection at a time.** The nRF52840's Central role supports multiple concurrent connections, but the sketch only opens one. If a patient manages to trigger two devices simultaneously (unlikely with health devices that connect-measure-disconnect quickly), the second connect attempt is queued after the first device disconnects. A multi-connection extension is straightforward in the Adafruit nRF52 library. + +**Alert cooldown is a fixed firmware constant, not remotely configurable.** The hub suppresses repeated `vitals_alert.qo` Notes of the same type for 5 minutes (`ALERT_COOLDOWN_MS`). The cooldown duration cannot be adjusted per patient without a firmware reflash. A production deployment would expose this as a Notehub environment variable alongside the clinical thresholds, so care coordinators can tighten or relax the alert rate for individual patients. + +**Weight-delta alerting, not absolute.** The `weight_gain` alert fires on change vs. previous reading, not on absolute weight. On first boot there is no previous reading so no delta alert is possible. A daily-comparison window (today vs. same time yesterday) is a more robust clinical metric and requires persisting the previous day's reading — doable by storing it in a `_notecard.db` database Notefile. + +**Heart rate only from activity band.** The Heart Rate Service (0x180D) provides heart rate, but step count is not part of the standard service — it lives in proprietary manufacturer-specific GATT services that differ across activity band brands. The firmware captures only heart rate from that service. + +**Blood Pressure Measurement — `user_id` and `measurement_status` not captured.** `parseBpMmhg` correctly decodes systolic, diastolic, and pulse rate for any compliant 0x2A35 layout. Only the timestamp field (flags bit 1) affects the pulse-rate offset: the parser adds 7 bytes to the mandatory 7-byte header when the timestamp is present, correctly handling both timestamp-present (Omron M4) and timestamp-absent layouts. The User ID (flags bit 3) and Measurement Status (flags bit 4) fields appear after pulse rate in the spec ordering; they are not used and their values are discarded. + +**BLE bonding requires a commissioning step, and public/static-address devices also require an allow-list entry.** The hub is **fail-closed by default: unrecognized devices are ignored.** Before shipping to a patient, a commissioning build with both `-DALLOW_UNENROLLED_DEVICES_FOR_DEV=1` and `-DALLOW_COMMISSIONING_BUILD` is needed to pair the patient's specific devices and store their bond keys. After commissioning, inspect the `bond_established` Notes in `commissioning.db` on Notehub: any device whose `addr_type` is `0x00` (public) or `0x01` (random static) must also be added to `ENROLLED_DEVICES` in `vitals_config.h` — bonding alone is not sufficient for those devices because the hub cannot identify them through IRK resolution. **Remove both commissioning flags before deploying to patients.** The MAC allow-list is a compile-time constant that cannot be updated without a reflash. + +**BLE pairing uses encrypted but unauthenticated bonding.** The commissioning step uses Just Works pairing (`setMITMProtect(false)`) because most consumer health devices lack input/output capabilities. This provides an encrypted BLE connection but **offers no man-in-the-middle protection during the initial key exchange.** For production deployments handling patient data, the clinical and security teams should define a controlled commissioning procedure (e.g., pairing only in a secured kitting environment at the point of device preparation), evaluate device and vendor choices that support authenticated pairing modes (Numeric Comparison or Passkey Entry) where input/output capabilities exist, and review the full threat model for the deployment setting before processing real patient data. + +**No offline-reading catchup.** If the hub is unplugged for several days and re-plugged, it doesn't know what readings it missed. Readings taken while the hub was offline are simply absent from the record. + +**Activity band steps not captured.** Standard Heart Rate Service (0x180D) does not carry step count. Activity bands that expose a proprietary step-count characteristic require a device-specific firmware extension. + +### Production Next Steps + +Taking this proof-of-concept toward a fieldable hub means hardening firmware delivery, baseline modeling, and supply-rail visibility for a real patient population. + +**Investigate host firmware OTA.** [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) targets hosts whose bootloader can be driven over UART by the Notecard (e.g., STM32 System Memory bootloader). The Adafruit Feather nRF52840's UF2 bootloader uses USB mass-storage enumeration, which does not fit that model. A production deployment would need either a custom UART-accessible bootloader on the nRF52840 or an alternative delivery path, for example, Nordic Bluetooth DFU triggered by a Notecard-delivered environment-variable flag — before OTA firmware updates can be offered as a supported feature. + +**Per-patient baseline learning.** Store a 7-day rolling average weight in a local `.db` Notefile and alert when the single-day reading is more than `weight_delta_kg` above the rolling average rather than just the previous reading. + +**Heartbeat Note.** Emit a `heartbeat.qo` every 24 hours even if no readings arrived, so the care team can distinguish "patient not using devices" from "hub offline." + +**Low-voltage notification.** The Notecard's `card.voltage` response monitors the supply rail; a `voltage_low` alert can page the care coordinator if the hub is losing power or the USB supply is marginal. + +**Remotely configurable alert cooldown.** Expose `ALERT_COOLDOWN_MS` as a Notehub environment variable so care coordinators can tune the alert rate per patient without a reflash. ## 11. Summary diff --git a/88-reefer-trailer-cold-chain-door-event-monitor/README.md b/88-reefer-trailer-cold-chain-door-event-monitor/README.md index 4ec88d1f..0a1f04c0 100644 --- a/88-reefer-trailer-cold-chain-door-event-monitor/README.md +++ b/88-reefer-trailer-cold-chain-door-event-monitor/README.md @@ -500,24 +500,39 @@ For anything not covered above, search or post on the [Blues community forum](ht The design hits the two failure modes that account for most refrigerated cargo loss — excursion and unauthorized door access — using direct sensor input and no OEM reefer integration, so it works across heterogeneous fleets. Humidity, multi-zone mapping, J1939 telemetry, and geofence logic are deliberate scope choices to be added where a deployment warrants them. -**Simplified for the POC:** - -- **Two probes only.** A 53 foot trailer can stratify several degrees from front to rear and from floor to ceiling. This design fixes one DS18B20 near the forward evaporator and one near the rear return-air panel, which is enough to catch reefer failure and gross excursions but is not a full thermal map of the cargo zone. -- **No humidity or dew-point sensor.** Some loads (leafy greens, certain pharmaceuticals, paper goods) are humidity-sensitive in addition to temperature-sensitive. The current Notes carry temperature only. -- **Coarse probe placement guidance.** Section 5 specifies forward and rear positions, but does not prescribe an evaporator-vs-cargo-zone placement scheme calibrated to a particular load type or trailer geometry. Operators are expected to refine probe placement during their first commissioning runs. -- **Reed switch is binary, not multi-state.** The Adafruit #375 reports open or closed only. It cannot distinguish a door cracked an inch from a door swung wide, and it has no concept of which door (left or right) was actuated on a split-rear configuration. -- **No driver or dispatcher app integration.** Alerts are routed from Notehub to whatever downstream destination is configured; this project does not ship a mobile app for the driver or a dashboard for dispatch. -- **No reefer ECU integration.** The design is intentionally OEM-agnostic, so it cannot read setpoint, defrost cycle, refrigerant pressure, fuel level, or alarm codes from the reefer controller itself. Operators see cargo-zone temperature, not reefer health. -- **Single 12 V feed assumption.** The wiring assumes a standard trailer accessory circuit. Battery-only installations or installations that need to survive a fully parked trailer for days would benefit from a different power architecture, including an upstream regulator with lower quiescent draw. - -**Production next steps:** - -- **Add humidity (and dew point) sensing.** Wire an [SHT41](https://www.adafruit.com/product/5776) on the Qwiic bus and add `rh_pct` and `dewpoint_c` fields to the per-sample, summary, and alert Notes. The compact alert template can absorb the additional fields without breaking the satellite data budget. -- **Multi-zone temperature mapping.** Move from two probes to four or six DS18B20s on the same 1-Wire bus (the library and template can scale), and emit per-zone min, mean, and max in the hourly summary. Helpful for high-value loads where a hot spot in one corner of the trailer is the early warning. -- **Reefer ECU integration.** For fleets with homogeneous reefer fleets, add a J1939 or CAN tap so setpoint, defrost, fuel level, and alarm codes ride along with the cargo-zone telemetry. Pair with the existing Notes rather than replacing them. -- **Geofence-aware alerting.** Use the `lat` and `lon` fields already on every alert to suppress door-open events at known authorized stops (yard, customer DC, fuel network) and elevate door events at unexpected locations. This logic is best run in Notehub or downstream rather than on-device. -- **Notecard Outboard DFU.** Wire [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) so threshold logic updates and bug fixes can ship over the air, including over NTN where appropriate. -- **Compliance reporting for FSMA-Cold and HACCP.** Layer a Notehub route into a compliance archive that aggregates per-sample logs and hourly summaries into per-shipment PDF reports, suitable for FSMA Sanitary Transportation rule audits and HACCP records for food shippers, or for pharma cold-chain release decisions. +### Simplified for the POC + +The simplifications below are deliberate scope choices — each marks a place where a real fleet deployment will want to add another sensor, finer placement guidance, or an OEM integration once the basic excursion-and-door monitor is proven in the field. + +**Two probes only.** A 53 foot trailer can stratify several degrees from front to rear and from floor to ceiling. This design fixes one DS18B20 near the forward evaporator and one near the rear return-air panel, which is enough to catch reefer failure and gross excursions but is **not a full thermal map of the cargo zone**. + +**No humidity or dew-point sensor.** Some loads — leafy greens, certain pharmaceuticals, paper goods — are humidity-sensitive in addition to temperature-sensitive, but the current Notes carry temperature only. + +**Coarse probe placement guidance.** Section 5 specifies forward and rear positions, but does not prescribe an evaporator-vs-cargo-zone placement scheme calibrated to a particular load type or trailer geometry. Operators are expected to refine probe placement during their first commissioning runs. + +**Reed switch is binary, not multi-state.** The Adafruit #375 reports open or closed only. It cannot distinguish a door cracked an inch from a door swung wide, and it has no concept of which door (left or right) was actuated on a split-rear configuration. + +**No driver or dispatcher app integration.** Alerts are routed from Notehub to whatever downstream destination is configured; this project does not ship a mobile app for the driver or a dashboard for dispatch. + +**No reefer ECU integration.** The design is intentionally OEM-agnostic, so it cannot read setpoint, defrost cycle, refrigerant pressure, fuel level, or alarm codes from the reefer controller itself. Operators see cargo-zone temperature, not reefer health. + +**Single 12 V feed assumption.** The wiring assumes a standard trailer accessory circuit. Battery-only installations or installations that need to survive a fully parked trailer for days would benefit from a different power architecture, including an upstream regulator with lower quiescent draw. + +### Production Next Steps + +Once the basic monitor is running across a real fleet, the following extensions are the natural progression — roughly from the most immediately useful to the most integration-dependent. + +**Add humidity (and dew point) sensing** by wiring an [SHT41](https://www.adafruit.com/product/5776) on the Qwiic bus and adding `rh_pct` and `dewpoint_c` fields to the per-sample, summary, and alert Notes. The compact alert template can absorb the additional fields without breaking the satellite data budget. + +**Multi-zone temperature mapping** moves from two probes to four or six DS18B20s on the same 1-Wire bus (the library and template can scale), emitting per-zone min, mean, and max in the hourly summary. This is helpful for high-value loads where a hot spot in one corner of the trailer is the early warning. + +**Reefer ECU integration** adds a J1939 or CAN tap for fleets with homogeneous reefer fleets, so setpoint, defrost, fuel level, and alarm codes ride along with the cargo-zone telemetry. Pair it with the existing Notes rather than replacing them. + +**Geofence-aware alerting** uses the `lat` and `lon` fields already on every alert to suppress door-open events at known authorized stops (yard, customer DC, fuel network) and elevate door events at unexpected locations. This logic is best run in Notehub or downstream rather than on-device. + +**Notecard Outboard DFU** wires [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) so threshold logic updates and bug fixes can ship over the air, including over NTN where appropriate. + +**Compliance reporting for FSMA-Cold and HACCP** layers a Notehub route into a compliance archive that aggregates per-sample logs and hourly summaries into per-shipment PDF reports, suitable for FSMA Sanitary Transportation rule audits and HACCP records for food shippers, or for pharma cold-chain release decisions. ## 12. Summary diff --git a/89-pallet-attached-cold-chain-logger/README.md b/89-pallet-attached-cold-chain-logger/README.md index bb0ec105..281af474 100644 --- a/89-pallet-attached-cold-chain-logger/README.md +++ b/89-pallet-attached-cold-chain-logger/README.md @@ -512,29 +512,37 @@ For satellite-reliant lanes, the primary lever is `dwell_batch_factor` — it dy The logger commits to a specific scope: independent, pallet-level evidence with a tamper-evident chain, scoped to the radios and physics that are actually available in a shipping container. Calibrated peak-G shock recording, cryptographic tamper proof, GPS, and lithium transport paperwork are real production concerns and are called out below — they extend this design rather than replacing it. -**Remaining design boundaries:** +### Remaining Design Boundaries -- **Skylo satellite is opportunistic, not available inside enclosed metal structures.** Skylo uses geostationary (GEO) satellites; the antenna needs a clear view of the southern sky (northern hemisphere). Notes queue in flash and flush via cellular or WiFi when coverage resumes — enclosed-transit segments become store-and-forward gaps, not data loss. For routes where enclosed-transit exceeds the available battery reserve, a Starnote for Iridium — paired with a companion Notecard on a Notecarrier XI (a Starnote is a satellite add-on and does not operate standalone) — adds Iridium LEO coverage (global, even inside container terminals) as an alternative or supplement. +The boundaries below are deliberate scope choices — each marks where a production deployment will want to add a radio, a calibrated sensor, stronger cryptographic evidence, or compliance paperwork on top of the basic pallet-level logger. -- **Shock detection is heuristic.** The `shock_detected` alert fires on accumulated motion-event count per interval, not on a calibrated peak-G threshold. For fragile biologics or fragile cargo requiring documented peak-G evidence, add a dedicated calibrated shock recorder alongside this device. +**Skylo satellite is opportunistic, not available inside enclosed metal structures.** Skylo uses geostationary (GEO) satellites; the antenna needs a clear view of the southern sky (northern hemisphere). Notes queue in flash and flush via cellular or WiFi when coverage resumes — enclosed-transit segments become **store-and-forward gaps, not data loss**. For routes where enclosed-transit exceeds the available battery reserve, a Starnote for Iridium — paired with a companion Notecard on a Notecarrier XI (a Starnote is a satellite add-on and does not operate standalone) — adds Iridium LEO coverage (global, even inside container terminals) as an alternative or supplement. -- **Alert cooldowns limit excursion record density.** The 30-minute cooldown suppresses repeat alerts during sustained excursions, which is good for on-call noise reduction. The `cargo_data.qo` hourly summaries and `cargo_log.qo` per-sample entries fill this gap — a complete excursion is visible in both the summary min/max fields and the per-sample `temp_c` values in the log. Compliance systems should use the log and summaries, not just the alerts, for excursion documentation. +**Shock detection is heuristic.** The `shock_detected` alert fires on accumulated motion-event count per interval, not on a calibrated peak-G threshold. For fragile biologics or fragile cargo requiring documented peak-G evidence, add a dedicated calibrated shock recorder alongside this device. -- **Chain hash is integrity evidence within each boot segment, not cryptographic proof.** The `chain_crc` is a 32-bit non-cryptographic hash replayed within each `boot_seg`. It detects accidental corruption and provides evidence against casual manipulation of the log contents within a segment. A cold boot (planned or uncontrolled) starts a new `boot_seg`, resetting `seq` and `chain_crc` to 0 — the remote log shows a new `boot_seg` value at the boundary, providing a traceable record of the reset event. Uncontrolled cold boots (power loss, brown-out) before `NotePayloadSaveAndSleep` completes lose the in-progress accumulator state and create a visible `boot_seg` increment; summary accumulators and alert cooldown timestamps from the interrupted cycle are not recoverable. The tilt baseline orientation **is** preserved across uncontrolled cold boots via `chain_boot.dbx`, so tilt detection does not silently re-seed from the post-reboot orientation. For deployments requiring strong cryptographic tamper evidence across boot boundaries, augment the chain approach with a server-side keyed MAC or timestamping service. +**Alert cooldowns limit excursion record density.** The 30-minute cooldown suppresses repeat alerts during sustained excursions, which is good for on-call noise reduction. The `cargo_data.qo` hourly summaries and `cargo_log.qo` per-sample entries fill this gap — a complete excursion is visible in both the summary min/max fields and the per-sample `temp_c` values in the log. Compliance systems should use the log and summaries, **not just the alerts**, for excursion documentation. -- **PT100 calibration document must be sourced at procurement.** The MAX31865 hardware is capable of NIST-traceable accuracy, but traceability is only realized if the PT100 probe is accompanied by a calibration certificate from an accredited laboratory. The specified Omega PR-21C-3-100-A-1/8-0600-M12-2 must be ordered with the **CAL-3** NIST-traceable calibration option (performed per ISO 10012-1 / ANSI/NCSL Z540-1). Verify calibration documentation at the time of procurement — a probe shipped without it does not satisfy the traceability requirement regardless of accuracy class. +**Chain hash is integrity evidence within each boot segment, not cryptographic proof.** The `chain_crc` is a 32-bit non-cryptographic hash replayed within each `boot_seg`. It detects accidental corruption and provides evidence against casual manipulation of the log contents within a segment. A cold boot (planned or uncontrolled) starts a new `boot_seg`, resetting `seq` and `chain_crc` to 0 — the remote log shows a new `boot_seg` value at the boundary, providing a traceable record of the reset event. Uncontrolled cold boots (power loss, brown-out) before `NotePayloadSaveAndSleep` completes lose the in-progress accumulator state and create a visible `boot_seg` increment; summary accumulators and alert cooldown timestamps from the interrupted cycle are not recoverable. The tilt baseline orientation **is** preserved across uncontrolled cold boots via `chain_boot.dbx`, so tilt detection does not silently re-seed from the post-reboot orientation. For deployments requiring strong cryptographic tamper evidence across boot boundaries, augment the chain approach with a server-side keyed MAC or timestamping service. -- **No GPS location.** Notecard for Skylo includes GNSS for location, but this firmware does not request GPS fixes. Adding `card.location.mode` and including position in the summary and state-change Notes is a natural extension for multi-modal shipments where knowing *where* a temperature excursion or handling event occurred matters as much as *when*. +**PT100 calibration document must be sourced at procurement.** The MAX31865 hardware is capable of NIST-traceable accuracy, but traceability is only realized if the PT100 probe is accompanied by a calibration certificate from an accredited laboratory. The specified Omega PR-21C-3-100-A-1/8-0600-M12-2 must be ordered with the **CAL-3** NIST-traceable calibration option (performed per ISO 10012-1 / ANSI/NCSL Z540-1). Verify calibration documentation at the time of procurement — a probe shipped without it does not satisfy the traceability requirement regardless of accuracy class. -- **Lithium battery transport compliance.** The 3.7 V / 2 000 mAh Li-Po cell (7.4 Wh) is subject to transport safety regulations on every mode of carriage — UN 38.3 testing, IATA Section II (Packing Instruction 966/967) for air, IMDG Code Class 9 for ocean. Confirm compliance and sourcing of UN 38.3 documentation with your freight forwarder before the first shipment. For volume deployment, source cells from a manufacturer that supplies UN 38.3 test documentation on request. +**No GPS location.** Notecard for Skylo includes GNSS for location, but this firmware does not request GPS fixes. Adding `card.location.mode` and including position in the summary and state-change Notes is a natural extension for multi-modal shipments where knowing *where* a temperature excursion or handling event occurred matters as much as *when*. -**Production next steps:** +**Lithium battery transport compliance.** The 3.7 V / 2 000 mAh Li-Po cell (7.4 Wh) is subject to transport safety regulations on every mode of carriage — UN 38.3 testing, IATA Section II (Packing Instruction 966/967) for air, IMDG Code Class 9 for ocean. Confirm compliance and sourcing of UN 38.3 documentation with your freight forwarder before the first shipment. For volume deployment, source cells from a manufacturer that supplies UN 38.3 test documentation on request. -- Integrate GPS fixes into the summary and state-change Notes (`card.location.mode` + `card.location`) so excursion and handling records include geographic context. -- Wire [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) for over-the-air firmware updates. -- Implement **MKT** (Mean Kinetic Temperature) calculation in firmware or as a Notehub JSONata transform — MKT is the single-value thermal summary most pharma quality systems require for release decisions after transit. -- Add the `boot_seg` counter to `cargo_data.qo` summaries (currently present only in `cargo_log.qo`) so compliance systems can cross-reference summary records with the log's boot-segment boundaries without querying the raw log. -- Evaluate adding a server-side keyed MAC or timestamping service on top of the `chain_crc` for deployments requiring cryptographic tamper evidence. +### Production Next Steps + +Once the basic logger is proven on real shipments, the following extensions are the natural progression toward a production cold-chain evidence system. + +**GPS context on every record** integrates GPS fixes into the summary and state-change Notes (`card.location.mode` + `card.location`) so excursion and handling records include geographic context. + +**Over-the-air firmware updates** wire [Notecard Outboard DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) for remote firmware updates. + +**Mean Kinetic Temperature calculation** implements **MKT** in firmware or as a Notehub JSONata transform — MKT is the single-value thermal summary most pharma quality systems require for release decisions after transit. + +**Boot-segment cross-referencing** adds the `boot_seg` counter to `cargo_data.qo` summaries (currently present only in `cargo_log.qo`) so compliance systems can cross-reference summary records with the log's boot-segment boundaries without querying the raw log. + +**Cryptographic tamper evidence** evaluates adding a server-side keyed MAC or timestamping service on top of the `chain_crc` for deployments requiring strong tamper evidence. ## 12. Summary From b7e12cefc84f7e9ae7173ddcead643c73c7a2080 Mon Sep 17 00:00:00 2001 From: Rob Lauer Date: Tue, 2 Jun 2026 14:49:52 -0500 Subject: [PATCH 6/6] consistent first mention of notehub --- 58-commercial-grease-interceptor-level-monitor/README.md | 2 +- 60-lone-worker-panic-fall-detection-beacon/README.md | 2 +- .../README.md | 2 +- .../README.md | 2 +- .../README.md | 2 +- 65-off-grid-livestock-water-tank-monitor/README.md | 2 +- 66-remote-apiary-hive-health-monitor/README.md | 2 +- 68-cnc-machine-spindle-load-cycle-time-tracker/README.md | 2 +- 69-injection-molding-shot-to-shot-process-monitor/README.md | 2 +- 70-trailer-manufacturer-connected-trailer-platform/README.md | 2 +- 71-legacy-diesel-generator-fleet-performance-uplift/README.md | 2 +- 72-solar-array-string-level-performance-dashboard/README.md | 2 +- 74-returnable-container-tote-pool-tracker/README.md | 2 +- 75-heavy-equipment-hours-of-use-utilization-tracker/README.md | 2 +- 76-untethered-trailer-chassis-fleet-tracker/README.md | 2 +- 78-rail-car-condition-interchange-tracker/README.md | 2 +- 79-utility-distribution-transformer-load-monitor/README.md | 2 +- 80-ev-charger-session-utilization-monitor/README.md | 2 +- 81-commercial-tenant-sub-metering-bridge/README.md | 2 +- .../README.md | 2 +- 83-off-grid-solar-battery-site-controller/README.md | 2 +- 84-remote-cabinet-backup-battery-sentinel/README.md | 2 +- 85-cellular-medication-adherence-pillbox/README.md | 2 +- 87-post-discharge-vitals-relay-hub/README.md | 2 +- 88-reefer-trailer-cold-chain-door-event-monitor/README.md | 2 +- 89-pallet-attached-cold-chain-logger/README.md | 2 +- 26 files changed, 26 insertions(+), 26 deletions(-) diff --git a/58-commercial-grease-interceptor-level-monitor/README.md b/58-commercial-grease-interceptor-level-monitor/README.md index 457b89f5..f3587df9 100644 --- a/58-commercial-grease-interceptor-level-monitor/README.md +++ b/58-commercial-grease-interceptor-level-monitor/README.md @@ -8,7 +8,7 @@ This reference application is intended to provide inspiration and help you get s -This project is a [truck-roll reduction](https://blues.com/truck-roll-reduction/) device for pumping providers who service **commercial grease interceptors**. A waterproof ultrasonic distance sensor installed in the access cover reports fill level over cellular every 15 minutes; when the level reaches a threshold, an alert dispatches immediately to [Notehub](https://notehub.io). Trucks are routed on actual condition, not a fixed calendar. +This project is a [truck-roll reduction](https://blues.com/truck-roll-reduction/) device for pumping providers who service **commercial grease interceptors**. A waterproof ultrasonic distance sensor installed in the access cover reports fill level over cellular every 15 minutes; when the level reaches a threshold, an alert dispatches immediately to the [Blues Notehub](https://blues.com/notehub/) cloud service. Trucks are routed on actual condition, not a fixed calendar. **What you'll have at the end:** A weatherproof wall-mounted enclosure with a Notecarrier CX + Notecard Cell+WiFi that samples a DFRobot ultrasonic sensor every 15 minutes, publishes daily summaries and threshold alerts to Notehub, and lets you tune alert thresholds and sample intervals via fleet-level environment variables without re-flashing. diff --git a/60-lone-worker-panic-fall-detection-beacon/README.md b/60-lone-worker-panic-fall-detection-beacon/README.md index d6824578..f156d7f8 100644 --- a/60-lone-worker-panic-fall-detection-beacon/README.md +++ b/60-lone-worker-panic-fall-detection-beacon/README.md @@ -28,7 +28,7 @@ This project is that device — a wearable safety beacon built on two core detec -That's the reason [Notecard for Skylo](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) (NOTE-NBGLWX) is the foundation of this design, not as a nice-to-have, but as the architectural foundation. It carries three radios on one M.2 module — cellular (LTE-M / NB-IoT / GPRS), WiFi, and satellite over the [Skylo](https://www.skylo.tech/) non-terrestrial network (NTN) — and selects among them automatically. The cellular path covers the vast majority of activations — cellular is broadly deployed, even in surprisingly rural areas. But when cellular genuinely fails, the Skylo satellite link is there, on the same board: no companion module, no second device to wire in. Skylo covers supported regions (see the [Notecard for Skylo datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) for the current coverage footprint); within that footprint, a device with an unobstructed view of the sky can deliver a distress message to Notehub even when every terrestrial network is unavailable. Satellite coverage is not guaranteed in every no-cellular location — it depends on the Skylo coverage region, sky-view geometry, and antenna orientation, but for the substations, oilfields, and rural worksites this design targets, it provides the safety margin that cellular alone cannot. +That's the reason [Notecard for Skylo](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) (NOTE-NBGLWX) is the foundation of this design, not as a nice-to-have, but as the architectural foundation. It carries three radios on one M.2 module — cellular (LTE-M / NB-IoT / GPRS), WiFi, and satellite over the [Skylo](https://www.skylo.tech/) non-terrestrial network (NTN) — and selects among them automatically. The cellular path covers the vast majority of activations — cellular is broadly deployed, even in surprisingly rural areas. But when cellular genuinely fails, the Skylo satellite link is there, on the same board: no companion module, no second device to wire in. Skylo covers supported regions (see the [Notecard for Skylo datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) for the current coverage footprint); within that footprint, a device with an unobstructed view of the sky can deliver a distress message to the [Blues Notehub](https://blues.com/notehub/) cloud service even when every terrestrial network is unavailable. Satellite coverage is not guaranteed in every no-cellular location — it depends on the Skylo coverage region, sky-view geometry, and antenna orientation, but for the substations, oilfields, and rural worksites this design targets, it provides the safety margin that cellular alone cannot. The firmware sets a single [`card.transport`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-transport) preference of `wifi-cell-ntn`: the Notecard prefers WiFi where a provisioned AP is reachable, falls back to cellular (the de-facto primary for a roaming worker), and falls back again to Skylo satellite when every terrestrial network is unavailable. Failover happens inside the Notecard; the host firmware never branches on which network is live. The WiFi path is an opportunistic bonus — a field tech standing near a facility WiFi AP may sync an alert without any cellular usage at all — but it is only active when network credentials have been provisioned on the Notecard and a compatible AP is within range. diff --git a/61-regulatory-grade-pharmacy-lab-cold-storage-audit-monitor/README.md b/61-regulatory-grade-pharmacy-lab-cold-storage-audit-monitor/README.md index ec56b01f..b0665211 100644 --- a/61-regulatory-grade-pharmacy-lab-cold-storage-audit-monitor/README.md +++ b/61-regulatory-grade-pharmacy-lab-cold-storage-audit-monitor/README.md @@ -16,7 +16,7 @@ This project is a [safety assurance](https://blues.com/safety-assurance/) refere The problem is not that facilities lack refrigerators — it's that most of them lack automated monitoring. A datalogger that must be manually downloaded, a wall thermometer read once per shift, or a WiFi-connected sensor that goes dark whenever the facility's network hiccups are all insufficient under a regulatory audit. Automated monitoring with individually timestamped readings and immediate excursion alerts is far more defensible than manual spot checks, and it produces a record that is complete even when nobody was watching. -This reference design demonstrates how to close that gap. The Notecarrier CX, with its onboard Cygnet STM32 host, wakes every five minutes to read a high-precision digital temperature sensor, check a magnetic door switch, and correlate both readings against an ambient-light sensor inside the unit. Each wake produces one timestamped reading Note queued in the Notecard's on-device store; the queue flushes to Notehub on the scheduled cellular connection. If the temperature strays outside configured limits, or if the door is left open beyond an acceptable threshold, an alert Note is transmitted immediately — bypassing the batched outbound window and landing in whatever on-call or compliance system the operator routes it to. +This reference design demonstrates how to close that gap. The Notecarrier CX, with its onboard Cygnet STM32 host, wakes every five minutes to read a high-precision digital temperature sensor, check a magnetic door switch, and correlate both readings against an ambient-light sensor inside the unit. Each wake produces one timestamped reading Note queued in the Notecard's on-device store; the queue flushes to the [Blues Notehub](https://blues.com/notehub/) cloud service on the scheduled cellular connection. If the temperature strays outside configured limits, or if the door is left open beyond an acceptable threshold, an alert Note is transmitted immediately — bypassing the batched outbound window and landing in whatever on-call or compliance system the operator routes it to. **Why Notecard.** Pharmacies and clinical labs operate tightly managed network environments. PCI-compliant retail pharmacy networks, HIPAA-covered clinical networks, and federally regulated vaccine storage programs all share one thing: strict rules against unknown IoT-class devices on the primary LAN. A temperature sensor attached to the pharmacy WiFi is either going to fail a network security review or be quietly firewalled off from the internet. An independent cellular data path sidesteps that entire conversation — the Notecard registers on the carrier's network directly, never touches the facility's LAN, and the IT team never has to issue a network access request or sign a BAA for a refrigerator. diff --git a/62-construction-site-environmental-noise-exposure-monitor/README.md b/62-construction-site-environmental-noise-exposure-monitor/README.md index 7c786885..71981a37 100644 --- a/62-construction-site-environmental-noise-exposure-monitor/README.md +++ b/62-construction-site-environmental-noise-exposure-monitor/README.md @@ -28,7 +28,7 @@ This project is a solar-powered cellular **area monitor** — a fixed, perimeter **Device-side responsibilities.** The order of operations on the Cygnet STM32 host matters because the PM sensor's fan would contaminate the sound measurement if it ran during the dB(A) window. Every 5 minutes the host wakes, samples sound for 15 seconds first — before any I²C traffic starts the PMSA003I — then initialises the PM sensor, waits 30 seconds for laser and fan to stabilise, and averages 10 readings over the next 10 seconds. Every sample folds into a rolling window kept in Notecard flash so it survives the sleep, and between cycles [`card.attn`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-attn) cuts Cygnet power entirely, dropping host current to essentially zero. Queued Notes ride from the Cygnet to the Notecard over I²C using the `note-arduino` library's `JAdd*` helpers — no JSON hand-marshaling, no modem AT commands. -**Notecard responsibilities.** The Notecard buffers each [Note](https://dev.blues.io/api-reference/glossary/#note) in its on-device queue, opens a cellular session on the configured [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence (default 30 minutes), and treats any `sync:true` alert Note as an immediate interrupt — a saw fires up near the sensor, and the alert leaves the device on a session opened in the next few seconds. The Notecard also owns GNSS: its built-in receiver acquires a site fix on first boot, re-acquires every 4 hours by default, and embeds the last-known fix in every outbound Note. Because the receiver retains a cached fix across power cycles, the first `card.location` response after the enclosure is moved to a new site can still return the previous site's coordinates — the firmware guards against that by treating the first non-zero response after boot as a baseline and flipping `location_valid` to `true` only when a subsequent response carries a newer `time` timestamp. See [Limitations](#10-limitations-and-next-steps). [Environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) flow back from Notehub on each inbound sync, so a GC can retune the dB(A) or PM thresholds on the fly without rolling a truck to the site. +**Notecard responsibilities.** The Notecard buffers each [Note](https://dev.blues.io/api-reference/glossary/#note) in its on-device queue, opens a cellular session on the configured [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence (default 30 minutes), and treats any `sync:true` alert Note as an immediate interrupt — a saw fires up near the sensor, and the alert leaves the device on a session opened in the next few seconds. The Notecard also owns GNSS: its built-in receiver acquires a site fix on first boot, re-acquires every 4 hours by default, and embeds the last-known fix in every outbound Note. Because the receiver retains a cached fix across power cycles, the first `card.location` response after the enclosure is moved to a new site can still return the previous site's coordinates — the firmware guards against that by treating the first non-zero response after boot as a baseline and flipping `location_valid` to `true` only when a subsequent response carries a newer `time` timestamp. See [Limitations](#10-limitations-and-next-steps). [Environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) flow back from the [Blues Notehub](https://blues.com/notehub/) cloud service on each inbound sync, so a GC can retune the dB(A) or PM thresholds on the fly without rolling a truck to the site. **Notehub responsibilities.** Each enclosure's embedded global SIM gets it onto carrier cellular worldwide and delivers data to [Notehub](https://notehub.io) over the Internet, which ingests every event, stores it, and applies project-level routes. Exposure summaries (`env_summary.qo`) and threshold alerts (`env_alert.qo`) land in separate [Notefiles](https://dev.blues.io/api-reference/glossary/#notefile) so the safety officer's inbox and the long-term compliance archive can be served from the same device without any per-Note filter logic in between. Notehub also appends `where_lat`, `where_lon`, and related location metadata to every event from the Notecard's last-known GNSS fix. diff --git a/63-construction-equipment-anti-theft-tracker-with-immobilizer/README.md b/63-construction-equipment-anti-theft-tracker-with-immobilizer/README.md index 9695d282..9f397ae8 100644 --- a/63-construction-equipment-anti-theft-tracker-with-immobilizer/README.md +++ b/63-construction-equipment-anti-theft-tracker-with-immobilizer/README.md @@ -16,7 +16,7 @@ This project is a [loss prevention](https://blues.com/loss-prevention/) referenc The result is an industry that leans heavily on equipment marking, insurance claims, and post-theft police reports. What's mostly missing is a device that provides real-time location during a theft in progress *and* can physically disable the equipment before it leaves the region — all without depending on an infrastructure that may not exist at the job site or at the final stash location. -This project is that device. It monitors GPS location against a configurable job-site geofence, watches for unexpected after-hours motion, and accepts a remote immobilizer command from Notehub that stages a relay to cut the ignition circuit on the thief's next key-on attempt — a polled, staged proof-of-concept immobilizer rather than a continuously-held cut, with the limitations that implies (see §11). The whole stack — GPS, cellular, and satellite fallback — is contained in a single Blues Notecard for Skylo installed in a weatherproof enclosure that runs indefinitely on a LiPo battery topped off by a small solar panel. +This project is that device. It monitors GPS location against a configurable job-site geofence, watches for unexpected after-hours motion, and accepts a remote immobilizer command from the [Blues Notehub](https://blues.com/notehub/) cloud service that stages a relay to cut the ignition circuit on the thief's next key-on attempt — a polled, staged proof-of-concept immobilizer rather than a continuously-held cut, with the limitations that implies (see §11). The whole stack — GPS, cellular, and satellite fallback — is contained in a single Blues Notecard for Skylo installed in a weatherproof enclosure that runs indefinitely on a LiPo battery topped off by a small solar panel. **Why Notecard.** Construction sites have no WiFi. Even if a site happens to have a hotspot, requiring site IT coordination for a security device defeats the purpose. Cellular works for the vast majority of scenarios, but a stolen skid steer doesn't stay parked in a well-covered urban area. It ends up in a rural equipment yard, a metal barn, or a shipping container at a port. That's the scenario where cellular alone fails and satellite becomes the difference between a recovered asset and a total write-off. Notecard for Skylo ([NOTE-NBGLWX](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/)) handles all three radio paths — LTE-M/NB-IoT cellular, WiFi (where available), and Skylo satellite — in a single M.2 module, without any firmware branching. Planetary roaming and satellite fallover are not optional extras for this use case; they are the core differentiators. diff --git a/65-off-grid-livestock-water-tank-monitor/README.md b/65-off-grid-livestock-water-tank-monitor/README.md index a67e3288..04380bd9 100644 --- a/65-off-grid-livestock-water-tank-monitor/README.md +++ b/65-off-grid-livestock-water-tank-monitor/README.md @@ -14,7 +14,7 @@ This project is a solar-powered [remote monitoring](https://blues.com/solutions- After following this guide, you will have a solar-powered off-grid tank monitor that: - **Samples tank level, pump current, and battery voltage** every 15 minutes via analog sensors wired to a Notecarrier CX -- **Alerts the rancher immediately** (via Notehub routes to SMS/push/webhook) when the tank drops below 20% full (alert) or 10% full (critical) +- **Alerts the rancher immediately** (via the [Blues Notehub](https://blues.com/notehub/) cloud service, with routes to SMS/push/webhook) when the tank drops below 20% full (alert) or 10% full (critical) - **Reports system health** (battery voltage, pump current) every 4 hours to a time-series database for trend analysis - **Falls back to satellite** (Skylo NTN) when cellular is unavailable, with the identical firmware handling both transports - **Runs for weeks on solar** even during cloudy stretches, thanks to an adaptive sleep strategy that extends the sample interval when the battery is low diff --git a/66-remote-apiary-hive-health-monitor/README.md b/66-remote-apiary-hive-health-monitor/README.md index 10e96c68..99357c9f 100644 --- a/66-remote-apiary-hive-health-monitor/README.md +++ b/66-remote-apiary-hive-health-monitor/README.md @@ -8,7 +8,7 @@ This reference application is intended to provide inspiration and help you get s -This project is a solar-powered hive monitor that turns each hive into a [remotely-monitored asset](https://blues.com/solutions-remote-monitoring/) — tracking hive weight and brood-box climate every 15 minutes, capturing a brief acoustic snapshot of the colony once per day, and reporting it all without grid power and without a truck roll every time the data looks wrong. A single [Notecard for Skylo](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) carries cellular, WiFi, and Skylo satellite radios on one module and fails over between them automatically, so the same hardware and firmware reach Notehub from an orchard with cell coverage or a meadow beyond any tower. +This project is a solar-powered hive monitor that turns each hive into a [remotely-monitored asset](https://blues.com/solutions-remote-monitoring/) — tracking hive weight and brood-box climate every 15 minutes, capturing a brief acoustic snapshot of the colony once per day, and reporting it all without grid power and without a truck roll every time the data looks wrong. A single [Notecard for Skylo](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) carries cellular, WiFi, and Skylo satellite radios on one module and fails over between them automatically, so the same hardware and firmware reach the [Blues Notehub](https://blues.com/notehub/) cloud service from an orchard with cell coverage or a meadow beyond any tower. ## 1. Project Overview diff --git a/68-cnc-machine-spindle-load-cycle-time-tracker/README.md b/68-cnc-machine-spindle-load-cycle-time-tracker/README.md index 1110f3d6..786cb6c6 100644 --- a/68-cnc-machine-spindle-load-cycle-time-tracker/README.md +++ b/68-cnc-machine-spindle-load-cycle-time-tracker/README.md @@ -22,7 +22,7 @@ The data is already there — on controls that expose it. A meaningful subset of -Cellular is the answer. A [Blues Wireless for OPTA](https://shop.blues.com/products/wireless-for-opta?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) snapped onto the Arduino OPTA's expansion port gives the device its own independent cellular data channel — a private uplink to Notehub that needs no plant LAN credentials, no firewall exception, and no IT ticket. The Modbus TCP connection to the CNC runs over a direct point-to-point Ethernet cable between the OPTA and the machine control: two devices on a private subnet with no routing to the shop floor network at all. The monitoring device is invisible to plant IT because it never touches plant IT's infrastructure. +Cellular is the answer. A [Blues Wireless for OPTA](https://shop.blues.com/products/wireless-for-opta?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) snapped onto the Arduino OPTA's expansion port gives the device its own independent cellular data channel — a private uplink to the [Blues Notehub](https://blues.com/notehub/) cloud service that needs no plant LAN credentials, no firewall exception, and no IT ticket. The Modbus TCP connection to the CNC runs over a direct point-to-point Ethernet cable between the OPTA and the machine control: two devices on a private subnet with no routing to the shop floor network at all. The monitoring device is invisible to plant IT because it never touches plant IT's infrastructure. **Deployment scenario.** A single Arduino OPTA RS485 + Blues Wireless for OPTA mounts on the machine's electrical panel DIN rail. A two-meter Cat6 patch cable runs from the OPTA's RJ45 port directly to the CNC controller's Modbus TCP Ethernet port — a closed, private connection with its own subnet. The cellular antenna exits through a cable gland on the panel door. The panel's existing 24 VDC supply powers the assembly. First-light is an hour of wiring; the OEM's service technician never needs to interact with the shop's network team. diff --git a/69-injection-molding-shot-to-shot-process-monitor/README.md b/69-injection-molding-shot-to-shot-process-monitor/README.md index 007a8142..376f8f5d 100644 --- a/69-injection-molding-shot-to-shot-process-monitor/README.md +++ b/69-injection-molding-shot-to-shot-process-monitor/README.md @@ -15,7 +15,7 @@ This project is a shot-level process monitor for plastic [injection molding](htt After completing this project, you will have: - A compact DIN-rail enclosure mounted in the machine's electrical cabinet - Hydraulic injection pressure and mold temperature collected continuously at the edge -- Five shot-level metrics (`peak_psi`, `fill_ms`, `pack_psi`, `temp_avg_c`, cooling-rate slope) in Notehub's `shot.qo` Notefile — one event per shot (or per N shots, configurable) +- Five shot-level metrics (`peak_psi`, `fill_ms`, `pack_psi`, `temp_avg_c`, cooling-rate slope) in the [Blues Notehub](https://blues.com/notehub/) cloud service's `shot.qo` Notefile — one event per shot (or per N shots, configurable) - Real-time alerts routed to your CMMS, webhook, or quality system whenever any metric exceeds configurable thresholds - No modification to the machine, no touching the mold, no plant-network involvement — 100% cellular - Commissioning takes ~50–100 shots to establish baseline thresholds; thereafter the system runs autonomously diff --git a/70-trailer-manufacturer-connected-trailer-platform/README.md b/70-trailer-manufacturer-connected-trailer-platform/README.md index 8419e6e0..c3117e8d 100644 --- a/70-trailer-manufacturer-connected-trailer-platform/README.md +++ b/70-trailer-manufacturer-connected-trailer-platform/README.md @@ -16,7 +16,7 @@ This project is a connected-trailer platform for trailer OEM integration, target A trailer OEM that wants to own the connectivity layer — rather than ceding it to the reefer OEM — needs a hardware-and-software platform that's on the trailer from day one. That platform has to read everything the fleet operator actually cares about: the reefer setpoint and actual temperature from the refrigeration unit itself, body-air temperature at two points in the cargo space (the data the shipper trusts at delivery time, not the reefer unit's own sensor), tire pressure on every axle, rear-door events that tell the cold-chain story, and GPS for asset location and route compliance. It has to survive 10–15 years of operation across regions, carriers, and signal environments, including long rural hauls, intermodal drayage moves, and multi-day DC (**distribution center**) dwells where the trailer sits disconnected from the tractor for days at a stretch, often in areas where cellular coverage is unreliable. -**Why Notecard.** A trailer OEM cannot commit to a modem they might have to re-source in year four of a ten-year program. Notecard for Skylo solves this at the module level: it combines LTE-M/NB-IoT cellular and Skylo satellite (via **NTN**, Non-Terrestrial Network, meaning communication through geostationary satellites rather than cell towers) in a single pre-certified M.2 form-factor module with an embedded SIM, 500 MB of cellular data, and 10 years of service included. The OEM installs one hardware SKU, flashes one firmware image, and ships trailers into any regional market without per-unit carrier activation, without SIM swaps, and without a per-site recurring data-plan negotiation. When a trailer crosses into a cellular dead zone — a mountain pass, a rural cold-storage depot, a remote intermodal rail yard — Notecard for Skylo transitions transparently to the Skylo satellite network, so the cold-chain record and the TPMS safety log stay continuous. Notehub gives the OEM's cloud a single API endpoint regardless of which radio delivered any given message. That's the connectivity bundle a trailer manufacturer needs to compete on the data layer rather than concede it to the reefer OEM by default. Pre-certified global cellular plus satellite plus included data, all in one module with a credible long-term roadmap, is exactly the program-level assurance a trailer OEM needs. +**Why Notecard.** A trailer OEM cannot commit to a modem they might have to re-source in year four of a ten-year program. Notecard for Skylo solves this at the module level: it combines LTE-M/NB-IoT cellular and Skylo satellite (via **NTN**, Non-Terrestrial Network, meaning communication through geostationary satellites rather than cell towers) in a single pre-certified M.2 form-factor module with an embedded SIM, 500 MB of cellular data, and 10 years of service included. The OEM installs one hardware SKU, flashes one firmware image, and ships trailers into any regional market without per-unit carrier activation, without SIM swaps, and without a per-site recurring data-plan negotiation. When a trailer crosses into a cellular dead zone — a mountain pass, a rural cold-storage depot, a remote intermodal rail yard — Notecard for Skylo transitions transparently to the Skylo satellite network, so the cold-chain record and the TPMS safety log stay continuous. The [Blues Notehub](https://blues.com/notehub/) cloud service gives the OEM's cloud a single API endpoint regardless of which radio delivered any given message. That's the connectivity bundle a trailer manufacturer needs to compete on the data layer rather than concede it to the reefer OEM by default. Pre-certified global cellular plus satellite plus included data, all in one module with a credible long-term roadmap, is exactly the program-level assurance a trailer OEM needs. diff --git a/71-legacy-diesel-generator-fleet-performance-uplift/README.md b/71-legacy-diesel-generator-fleet-performance-uplift/README.md index 27a0b6a6..075ffe1c 100644 --- a/71-legacy-diesel-generator-fleet-performance-uplift/README.md +++ b/71-legacy-diesel-generator-fleet-performance-uplift/README.md @@ -16,7 +16,7 @@ This project is an [asset performance optimization](https://blues.com/solutions- The cost of this information gap is concrete. A standby generator that fails to start during a utility outage is worse than no generator at all — the false sense of protection it provides can delay emergency response. A generator that does start but is running low on fuel, or trending toward coolant overtemp, will fail mid-outage without warning. Run-hour data that never leaves the controller can't be used to schedule preventive maintenance before a critical service interval is missed. These are not exotic failure modes; they happen regularly at facilities that have generators but not generator *monitoring*. -This project closes that gap — for active alarm state, a firmware-observed alarm chronology, and operating data. A [Blues Wireless for OPTA](https://shop.blues.com/products/wireless-for-opta?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) snapped onto an Arduino OPTA RS485 industrial **PLC** (programmable logic controller) sits on the DIN rail inside the generator panel, polls seven holding registers once per minute over the controller's Modbus port (including the active alarm bitmask), and routes alert events, an hourly alarm-history log, and hourly summaries to [Notehub](https://notehub.io) via cellular. Installation requires new RS-485 wiring to the controller's communications terminals and matching the controller's Modbus serial settings (baud rate, parity, slave address), but involves no writes to start/stop or safety circuits — the firmware is strictly read-only over Modbus. No dependency on the facility network. +This project closes that gap — for active alarm state, a firmware-observed alarm chronology, and operating data. A [Blues Wireless for OPTA](https://shop.blues.com/products/wireless-for-opta?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) snapped onto an Arduino OPTA RS485 industrial **PLC** (programmable logic controller) sits on the DIN rail inside the generator panel, polls seven holding registers once per minute over the controller's Modbus port (including the active alarm bitmask), and routes alert events, an hourly alarm-history log, and hourly summaries to the [Blues Notehub](https://blues.com/notehub/) cloud service via cellular. Installation requires new RS-485 wiring to the controller's communications terminals and matching the controller's Modbus serial settings (baud rate, parity, slave address), but involves no writes to start/stop or safety circuits — the firmware is strictly read-only over Modbus. No dependency on the facility network. **Why Notecard.** The timing of this deployment is the whole point. The standby generator exists to provide power when mains power fails — which is exactly when the facility's WiFi router also goes dark. A monitoring system that relies on the building's LAN cannot report a failure-to-start at the moment that matters most. Worse, a purely LAN-dependent monitor might be relied on as evidence that everything is fine, right up until the UPS batteries run dry. Cellular with an antenna routed outside the metal generator enclosure provides a communication path that is completely independent of the facility's power and network infrastructure. The cellular path is alive precisely because it draws from the generator panel's own battery-backed DC control bus — the same battery that starts the engine. diff --git a/72-solar-array-string-level-performance-dashboard/README.md b/72-solar-array-string-level-performance-dashboard/README.md index 07eba751..9a04e6f7 100644 --- a/72-solar-array-string-level-performance-dashboard/README.md +++ b/72-solar-array-string-level-performance-dashboard/README.md @@ -16,7 +16,7 @@ This project is an [asset performance optimization](https://blues.com/solutions- A modern string inverter or combiner box already knows, at the register level, exactly how much DC current and voltage each string is producing. What it doesn't have is a network path off the array and into the asset manager's dashboard. The maintenance tech has to show up on-site with a laptop and a Modbus cable to pull that data, which is exactly what doesn't happen until something breaks badly enough to trigger a service ticket. The result is months of invisible partial production loss that neither the owner nor the O&M (operations and maintenance) contractor can see until the quarterly energy report shows a yield gap. -This project adds that missing network path. It reads per-string DC voltage and current from a Modbus RTU source, typically a multi-MPPT string inverter where each MPPT input tracks one string — every five minutes, reads the irradiance from a pyranometer (a calibrated instrument that measures incident solar radiation in watts per square meter, W/m²) and the panel temperature from a backsheet probe, and computes a **Performance Ratio** (**PR**) — the ratio of actual string power to the expected power given current irradiance and temperature — for each string independently. The root-cause hypothesis (shading, soiling, string fault) depends on having an independent operating voltage reading per string; multi-MPPT inverters implementing the [SunSpec Model 160 Multiple MPPT](https://sunspec.org/sunspec-modbus-specifications/) register model provide this signal set. See [§11](#11-limitations-and-next-steps) for hardware compatibility and the implications for deployments where only per-string current is available from the monitored device. Strings that fall below a configurable PR threshold get an immediate alert with a root-cause hypothesis. When a string's PR recovers above the threshold, the device locally rearms the alert — the internal underperformance flag is cleared so a subsequent degradation fires a fresh event, but no recovery Note is sent to Notehub. Every hour a summary Note records the per-string window means and the array-level shared-reference irradiance and module temperature for trend analysis. +This project adds that missing network path. It reads per-string DC voltage and current from a Modbus RTU source, typically a multi-MPPT string inverter where each MPPT input tracks one string — every five minutes, reads the irradiance from a pyranometer (a calibrated instrument that measures incident solar radiation in watts per square meter, W/m²) and the panel temperature from a backsheet probe, and computes a **Performance Ratio** (**PR**) — the ratio of actual string power to the expected power given current irradiance and temperature — for each string independently. The root-cause hypothesis (shading, soiling, string fault) depends on having an independent operating voltage reading per string; multi-MPPT inverters implementing the [SunSpec Model 160 Multiple MPPT](https://sunspec.org/sunspec-modbus-specifications/) register model provide this signal set. See [§11](#11-limitations-and-next-steps) for hardware compatibility and the implications for deployments where only per-string current is available from the monitored device. Strings that fall below a configurable PR threshold get an immediate alert with a root-cause hypothesis. When a string's PR recovers above the threshold, the device locally rearms the alert — the internal underperformance flag is cleared so a subsequent degradation fires a fresh event, but no recovery Note is sent to the [Blues Notehub](https://blues.com/notehub/) cloud service. Every hour a summary Note records the per-string window means and the array-level shared-reference irradiance and module temperature for trend analysis. **Why Notecard.** Solar arrays sit on rooftops, in open fields, and under parking canopies — three of the places where WiFi ranges the least and site IT involvement is the highest hurdle. A rooftop system at a strip mall isn't going to get a permanent AP installed on the ballast tray. A ground mount in a rural field has no building nearby. A carport canopy shared by a retail parking lot has a network owned by the tenant's coffee franchise, not the solar O&M contractor. Cellular removes every one of those constraints. The Notecard Cell+WiFi variant ships with a prepaid global SIM and registers on the cellular network automatically — no SIM activation form, no per-site IT discussion, and no router credentials to manage. The WiFi radio is present in the hardware but is not used in this build: a metal NEMA 4X enclosure substantially attenuates WiFi signals, and the firmware explicitly clears any previously stored WiFi credentials at first boot via `card.wifi` — this ensures cellular-only operation even on a reused or previously provisioned Notecard rather than relying on an assumption about the device's prior state. For a portfolio O&M operator managing dozens of customer sites, the single most valuable thing about cellular-first IoT is that the same firmware and SKU deploys identically on site one and site forty-three. There is no site-specific network configuration at all. diff --git a/74-returnable-container-tote-pool-tracker/README.md b/74-returnable-container-tote-pool-tracker/README.md index ab766eec..5740df18 100644 --- a/74-returnable-container-tote-pool-tracker/README.md +++ b/74-returnable-container-tote-pool-tracker/README.md @@ -8,7 +8,7 @@ This reference application is intended to provide inspiration and help you get s -This project is an [asset location tracking](https://blues.com/solutions-location-tracking/) solution for reusable container pools — plastic totes, pressurized kegs, and gas cylinders — that reports location on motion events and daily heartbeats using cellular connectivity and the [Notecard's](https://shop.blues.com/products/notecard-cellular?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) built-in accelerometer. Containers emit a motion event when they start or stop moving, and a daily confirmation when idle, all over LTE Cat-1 bis. The hardware is a [Notecarrier CX](https://shop.blues.com/products/notecarrier-cx?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) with a Notecard Cell+WiFi (see §4 for the BOM); operators tune heartbeat interval and motion sensitivity from Notehub without re-flashing. +This project is an [asset location tracking](https://blues.com/solutions-location-tracking/) solution for reusable container pools — plastic totes, pressurized kegs, and gas cylinders — that reports location on motion events and daily heartbeats using cellular connectivity and the [Notecard's](https://shop.blues.com/products/notecard-cellular?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) built-in accelerometer. Containers emit a motion event when they start or stop moving, and a daily confirmation when idle, all over LTE Cat-1 bis. The hardware is a [Notecarrier CX](https://shop.blues.com/products/notecarrier-cx?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) with a Notecard Cell+WiFi (see §4 for the BOM); operators tune heartbeat interval and motion sensitivity from the [Blues Notehub](https://blues.com/notehub/) cloud service without re-flashing. ## 1. Project Overview diff --git a/75-heavy-equipment-hours-of-use-utilization-tracker/README.md b/75-heavy-equipment-hours-of-use-utilization-tracker/README.md index e5c50c62..1f5fdf58 100644 --- a/75-heavy-equipment-hours-of-use-utilization-tracker/README.md +++ b/75-heavy-equipment-hours-of-use-utilization-tracker/README.md @@ -8,7 +8,7 @@ This reference application is intended to provide inspiration and help you get s -This project is a retrofit [asset location tracking](https://blues.com/solutions-location-tracking/) solution for mobile heavy equipment — excavators, generators, compactors, light towers, and any machine a rental company or OEM needs to bill by the hour and maintain on schedule. A magnetically mounted, solar-trickle-charged enclosure uses a 3-axis accelerometer to detect engine-on/off transitions via vibration signature, accumulates a persistent software hour meter, and reports location and utilization back to [Notehub](https://notehub.io) over cellular or satellite — with no wiring harness, no equipment modification, and no dependency on a job-site network. [Skylo](https://www.skylo.tech/)-supported satellite fallback keeps the device reporting from remote pipeline corridors, open-pit mines, and wind-farm construction zones where terrestrial coverage runs thin. The hardware is a Notecarrier CX with a Notecard for Skylo and an external IMU (see §4 for the BOM). +This project is a retrofit [asset location tracking](https://blues.com/solutions-location-tracking/) solution for mobile heavy equipment — excavators, generators, compactors, light towers, and any machine a rental company or OEM needs to bill by the hour and maintain on schedule. A magnetically mounted, solar-trickle-charged enclosure uses a 3-axis accelerometer to detect engine-on/off transitions via vibration signature, accumulates a persistent software hour meter, and reports location and utilization back to the [Blues Notehub](https://blues.com/notehub/) cloud service over cellular or satellite — with no wiring harness, no equipment modification, and no dependency on a job-site network. [Skylo](https://www.skylo.tech/)-supported satellite fallback keeps the device reporting from remote pipeline corridors, open-pit mines, and wind-farm construction zones where terrestrial coverage runs thin. The hardware is a Notecarrier CX with a Notecard for Skylo and an external IMU (see §4 for the BOM). ## 1. Project Overview diff --git a/76-untethered-trailer-chassis-fleet-tracker/README.md b/76-untethered-trailer-chassis-fleet-tracker/README.md index 5e4629d0..8a58198f 100644 --- a/76-untethered-trailer-chassis-fleet-tracker/README.md +++ b/76-untethered-trailer-chassis-fleet-tracker/README.md @@ -10,7 +10,7 @@ This reference application is intended to provide inspiration and help you get s This project is a solar-trickle-charged, tractor-independent GPS and motion tracker for [asset location tracking](https://blues.com/solutions-location-tracking/) on freight trailers and intermodal chassis. The device delivers cellular-first telemetry with truly global Iridium LEO satellite fallback — keeping the trailer or chassis visible across trans-oceanic container routes and polar corridors where geostationary satellite networks have no coverage at all. The hardware is a Blues Notecarrier XI with a Swan host, a cellular Notecard, and a Starnote for Iridium (see §4 for the BOM). -The unit mounts on the trailer roof or chassis frame, runs a parked/moving state machine entirely on-device, and delivers departure, arrival, and position Notes to [Notehub](https://notehub.io) over cellular with automatic Iridium satellite fallback — no tractor hookup, no site IT, and no dependence on terrestrial coverage. +The unit mounts on the trailer roof or chassis frame, runs a parked/moving state machine entirely on-device, and delivers departure, arrival, and position Notes to the [Blues Notehub](https://blues.com/notehub/) cloud service over cellular with automatic Iridium satellite fallback — no tractor hookup, no site IT, and no dependence on terrestrial coverage. ## 1. Project Overview diff --git a/78-rail-car-condition-interchange-tracker/README.md b/78-rail-car-condition-interchange-tracker/README.md index 0e5aa245..6772b405 100644 --- a/78-rail-car-condition-interchange-tracker/README.md +++ b/78-rail-car-condition-interchange-tracker/README.md @@ -30,7 +30,7 @@ This architecture maps directly to Blues' [supply chain tracking](https://blues. **Device-side responsibilities.** The work on the car itself is bounded by one constraint — a 15-minute wake window that has to do everything and then disappear. The Cygnet STM32L433 host on the Notecarrier CX comes up via [`card.attn`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-attn) sleep, reads its sensors, scores shock events, looks for coupler-state edges, evaluates three alert conditions on standard builds (seven on TANK_CAR builds), and queues Notes to the Notecard over I²C. The moment that's done it goes back to sleep — fully powered off, with the Notecard holding the persistent state struct in its own flash until the next ATTN fire rehydrates it. -**Notecard responsibilities.** Everything that has to think about the network lives in the Notecard, not the host. It holds [Notes](https://dev.blues.io/api-reference/glossary/#note) in its on-device queue, runs GPS position fixes every five minutes while motion is detected (motion-gated so a car sitting in a yard isn't burning battery on GNSS), and syncs outbound data on a voltage-variable [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) schedule that stretches the interval as the battery drains. Transport selection is fully autonomous: if LTE-M can't reach a tower the Notecard switches to Skylo NTN and ships the queued Notes over satellite — the firmware never asks which path was used. The Notecard also distributes [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) from Notehub, so fleet-wide thresholds can be retuned without a truck roll. +**Notecard responsibilities.** Everything that has to think about the network lives in the Notecard, not the host. It holds [Notes](https://dev.blues.io/api-reference/glossary/#note) in its on-device queue, runs GPS position fixes every five minutes while motion is detected (motion-gated so a car sitting in a yard isn't burning battery on GNSS), and syncs outbound data on a voltage-variable [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) schedule that stretches the interval as the battery drains. Transport selection is fully autonomous: if LTE-M can't reach a tower the Notecard switches to Skylo NTN and ships the queued Notes over satellite — the firmware never asks which path was used. The Notecard also distributes [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) from the [Blues Notehub](https://blues.com/notehub/) cloud service, so fleet-wide thresholds can be retuned without a truck roll. **Notehub responsibilities.** Once a Note leaves the car, the Notecard's embedded global SIM carries it over supported carriers worldwide and delivers it to [Notehub](https://notehub.io), which ingests events, stores them, and applies project-level [routes](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub). The three Notefiles (`railcar_status.qo`, `railcar_alert.qo`, `railcar_location.qo`) are deliberately separate so each can take its own downstream path: status Notes flow to a long-term analytics store for trend analysis; alert Notes fan out to an on-call endpoint (email, SMS, webhook, CMMS ticket) in near-real time; location Notes feed a geofencing service or time-series location store where interchange-boundary detection happens. diff --git a/79-utility-distribution-transformer-load-monitor/README.md b/79-utility-distribution-transformer-load-monitor/README.md index c582bc5f..a8e2549f 100644 --- a/79-utility-distribution-transformer-load-monitor/README.md +++ b/79-utility-distribution-transformer-load-monitor/README.md @@ -41,7 +41,7 @@ CT installation is **non-invasive**: the split-core sensors clamp directly onto **Device-side responsibilities.** The host on the pole has a simple, repeating job. Every 5 minutes (configurable) the Cygnet STM32L4 on the Notecarrier CX wakes, reads the configured CT channels — two for the common split-phase install, three when `phase_count=3` is set for three-phase — reads the enclosure-internal I²C temperature sensor, runs three threshold checks in firmware, and queues the results as [Notes](https://dev.blues.io/api-reference/glossary/#note) via the Notecard over I²C. The moment that's done it goes back to sleep. Between wakes the host is completely powered off through the Notecard's [`card.attn`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-attn) mechanism, with the host power rail held low until the wake interval expires and ATTN brings the rail back up. All the state that has to survive that gap — summary accumulators, alert cooldown counters, elapsed time — is serialized to Notecard flash via `NotePayloadSaveAndSleep` before each sleep and restored with `NotePayloadRetrieveAfterSleep` on the next wake. -**Notecard responsibilities.** The Notecard takes everything the host just queued and decides when it goes over the air. Notes sit in its on-device queue and flush on the [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence (default 60 minutes), but any Note flagged `sync:true` — every alert — bypasses that timer and ships immediately. The Notecard also handles [environment variable](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) distribution from Notehub, so an operations engineer can retune thresholds across the fleet without re-flashing firmware; the device picks them up on the next inbound sync. (GNSS is available on supported hardware if a future revision needs one-time asset location, but it isn't used in this design — enabling it has antenna, power, and cost implications not covered here.) +**Notecard responsibilities.** The Notecard takes everything the host just queued and decides when it goes over the air. Notes sit in its on-device queue and flush on the [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence (default 60 minutes), but any Note flagged `sync:true` — every alert — bypasses that timer and ships immediately. The Notecard also handles [environment variable](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) distribution from the [Blues Notehub](https://blues.com/notehub/) cloud service, so an operations engineer can retune thresholds across the fleet without re-flashing firmware; the device picks them up on the next inbound sync. (GNSS is available on supported hardware if a future revision needs one-time asset location, but it isn't used in this design — enabling it has antenna, power, and cost implications not covered here.) **Notehub responsibilities.** Once a Note leaves the pole, the Notecard's embedded global SIM carries it over supported carriers worldwide and delivers it to [Notehub](https://notehub.io), where events are ingested, stored, and routed downstream. Two Notefiles carry everything the device says: `xfmr_summary.qo` for hourly templated rollups suitable for long-term trending, and `xfmr_alert.qo` for event-triggered, immediate-delivery Notes. Organizing devices into [Fleets](https://dev.blues.io/guides-and-tutorials/fleet-admin-guide/) by service territory or transformer rating lets engineers set threshold [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) that apply across an entire group — all 25-kVA residential units on one feeder share one threshold profile — while still allowing per-device overrides for unusual transformers. [Smart Fleet rules](https://dev.blues.io/notehub/notehub-walkthrough/#using-smart-fleet-rules) can automatically assign a Notecard to the correct fleet based on its reported data. diff --git a/80-ev-charger-session-utilization-monitor/README.md b/80-ev-charger-session-utilization-monitor/README.md index 72dd2195..f8fcd8eb 100644 --- a/80-ev-charger-session-utilization-monitor/README.md +++ b/80-ev-charger-session-utilization-monitor/README.md @@ -8,7 +8,7 @@ This reference application is intended to provide inspiration and help you get s -This project is a cellular [energy monitoring](https://blues.com/solutions-energy-monitoring/) retrofit for Level 2 EV chargers — for fleet managers, facilities teams, and charging-network operators who need to know how their installed chargers are actually being used. The design clamps a DIN-rail energy meter onto each charger's AC feed and reports three streams to Notehub over cellular: per-session metered kWh and peak power, hourly utilization and availability, and mains-offline alerts. Energy is measured by a hardware-metered instrument; charger availability is tracked from the meter's V_rms register — when mains voltage is absent the circuit is definitively offline. No modification to the charger hardware, no OCPP enrollment, no site IT involvement required. The hardware is a Notecarrier CX with a Notecard Cell+WiFi and an EASTRON SDM120-Modbus energy meter (see §4 for the BOM); see [§10](#10-limitations-and-next-steps) for design boundaries and production expansion paths. +This project is a cellular [energy monitoring](https://blues.com/solutions-energy-monitoring/) retrofit for Level 2 EV chargers — for fleet managers, facilities teams, and charging-network operators who need to know how their installed chargers are actually being used. The design clamps a DIN-rail energy meter onto each charger's AC feed and reports three streams to the [Blues Notehub](https://blues.com/notehub/) cloud service over cellular: per-session metered kWh and peak power, hourly utilization and availability, and mains-offline alerts. Energy is measured by a hardware-metered instrument; charger availability is tracked from the meter's V_rms register — when mains voltage is absent the circuit is definitively offline. No modification to the charger hardware, no OCPP enrollment, no site IT involvement required. The hardware is a Notecarrier CX with a Notecard Cell+WiFi and an EASTRON SDM120-Modbus energy meter (see §4 for the BOM); see [§10](#10-limitations-and-next-steps) for design boundaries and production expansion paths. ## 1. Project Overview diff --git a/81-commercial-tenant-sub-metering-bridge/README.md b/81-commercial-tenant-sub-metering-bridge/README.md index a1f9b2e8..82736705 100644 --- a/81-commercial-tenant-sub-metering-bridge/README.md +++ b/81-commercial-tenant-sub-metering-bridge/README.md @@ -30,7 +30,7 @@ In a multi-tenant building, the WiFi access points are almost always under tenan 2. Invisible to tenants — the tenant cannot see or intercept it 3. Operationally simple — no IT setup, no passwords, no tenant cooperation -A cellular Notecard meets all three criteria. It's a SIM-bearing module that calls home to Notehub over the cellular network — a connection the tenant has no access to and no visibility into, exactly the same way the building's alarm system uses its own GSM dialout. There is no form to fill out, no AP to pair to, and no IT ticket to raise with any tenant. The data channel is as landlord-owned as the panel itself. +A cellular Notecard meets all three criteria. It's a SIM-bearing module that calls home to the [Blues Notehub](https://blues.com/notehub/) cloud service over the cellular network — a connection the tenant has no access to and no visibility into, exactly the same way the building's alarm system uses its own GSM dialout. There is no form to fill out, no AP to pair to, and no IT ticket to raise with any tenant. The data channel is as landlord-owned as the panel itself. This is not a niche edge case. Billing disputes are among the most contentious issues in commercial tenancy, and the architecture matters: a meter whose data travels over the tenant's network is a meter whose readings a clever tenant can plausibly dispute. A cellular Notecard is the only architecture that eliminates that dispute by design. diff --git a/82-aerial-lift-rental-equipment-battery-health-monitor/README.md b/82-aerial-lift-rental-equipment-battery-health-monitor/README.md index f3af69e6..40aec9f0 100644 --- a/82-aerial-lift-rental-equipment-battery-health-monitor/README.md +++ b/82-aerial-lift-rental-equipment-battery-health-monitor/README.md @@ -30,7 +30,7 @@ This project is the watcher. A small monitoring device clipped to the pack reads **Device-side responsibilities.** The host's job is to turn four raw signals into pack health numbers the rental company can act on. Every `sample_interval_s` seconds (default 300 seconds / 5 minutes), the Cygnet STM32 on the Notecarrier CX wakes and reads pack voltage from the INA228 over I²C, pack current from the right source for the build (INA228 `readCurrent()` through an external precision shunt in the default field build `ENABLE_ACS758 0`, the ACS758 Hall-effect sensor on A1 in the alternative `ENABLE_ACS758 1`, or the onboard INA228 shunt in bench builds `BENCH_ONLY 1`), and the pack temperature from the NTC thermistor. When the machine's BMS is CAN-accessible, the host also polls cell-group voltages over the SPI CAN interface. (**CAN BMS integration requires vendor-specific CAN ID and frame parser configuration before the feature will work with any real BMS** — the shipped firmware is a placeholder for this path; see §7.3 and §9.) From those four streams, the firmware updates SoC via a voltage-based OCV lookup, accumulates absolute current above a 0.5 A noise floor into a running cycle Ah throughput total (one sampled Ah estimate per wake), and updates a rolling SoH estimate whenever a heuristic pseudo-cycle completes (SoC dips below 30% then recovers above 90%). Threshold checks run after every sample, and any trip fires an immediate Note. Between wakes, [`card.attn`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-attn) cuts host power; the Notecard idles. The full assembly still draws quiescent current from the buck regulator, INA228, thermistor divider, and any optional CAN hardware — materially above the Notecard's own idle figure, so see [§9](#9-validation-and-testing) for Mojo-measured whole-device figures. -**Notecard responsibilities.** Notecard for Skylo is the part that decides when those numbers actually leave the machine. It holds [Notes](https://dev.blues.io/api-reference/glossary/#note) in its onboard queue, manages the cellular or satellite session on the configured [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence, and flushes any `sync:true` alert the instant a threshold trips. It also distributes [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) from Notehub, so fleet-level threshold adjustments reach devices without a reflash. The built-in Skylo NTN radio activates automatically whenever terrestrial cellular is unavailable — the firmware doesn't manage the handoff, and the same alert reaches Notehub from a rural job site that it reaches from an urban yard. +**Notecard responsibilities.** Notecard for Skylo is the part that decides when those numbers actually leave the machine. It holds [Notes](https://dev.blues.io/api-reference/glossary/#note) in its onboard queue, manages the cellular or satellite session on the configured [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence, and flushes any `sync:true` alert the instant a threshold trips. It also distributes [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) from the [Blues Notehub](https://blues.com/notehub/) cloud service, so fleet-level threshold adjustments reach devices without a reflash. The built-in Skylo NTN radio activates automatically whenever terrestrial cellular is unavailable — the firmware doesn't manage the handoff, and the same alert reaches Notehub from a rural job site that it reaches from an urban yard. **Notehub responsibilities.** Once Notes leave the lift, the Notecard's embedded global SIM carries them over supported carriers worldwide and lands them in [Notehub](https://notehub.io), where every event is stored and project-level routes fan it out. Hourly telemetry summaries and immediate alerts use separate [Notefiles](https://dev.blues.io/api-reference/glossary/#notefile) so the rental company can route each one to where it belongs: alerts to an on-call or rental ERP system for immediate triage, summaries to a long-term analytics store for cycle-life trending. [Smart Fleets](https://dev.blues.io/notehub/notehub-walkthrough/#using-smart-fleet-rules) are how a single firmware image serves machines with different pack chemistries and rated capacities — fleet-level environment variables encode the pack specs, and per-device overrides handle the machines that deviate. diff --git a/83-off-grid-solar-battery-site-controller/README.md b/83-off-grid-solar-battery-site-controller/README.md index da9e2c93..1da39b6e 100644 --- a/83-off-grid-solar-battery-site-controller/README.md +++ b/83-off-grid-solar-battery-site-controller/README.md @@ -8,7 +8,7 @@ This reference application is intended to provide inspiration and help you get s -This project is a bank-level solar and battery monitoring solution — a Blues [battery management systems](https://blues.com/battery-management-systems/) reference design — for remote off-grid sites powered by solar arrays and battery banks. A Blues Notecarrier CX reads two Victron VE.Direct devices — a SmartShunt for battery-bank metrics and a SmartSolar MPPT charge controller for solar-side metrics, and reports battery-bank-level state of charge (SoC), daily solar harvest, load draw, battery temperature, and charge state to Notehub every four hours, with immediate alerts before the site goes dark. Connectivity is provided by a Blues Notecard seated in the carrier's M.2 slot; two SKUs are supported with no firmware changes between them — [Notecard Cell+WiFi (NOTE-MBGLW)](https://dev.blues.io/datasheets/notecard-datasheet/note-mbglw/) for sites within terrestrial cellular range, and [Notecard for Skylo (NOTE-NBGLWX)](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) for fallback satellite coverage for sites where cellular coverage is marginal or absent. +This project is a bank-level solar and battery monitoring solution — a Blues [battery management systems](https://blues.com/battery-management-systems/) reference design — for remote off-grid sites powered by solar arrays and battery banks. A Blues Notecarrier CX reads two Victron VE.Direct devices — a SmartShunt for battery-bank metrics and a SmartSolar MPPT charge controller for solar-side metrics, and reports battery-bank-level state of charge (SoC), daily solar harvest, load draw, battery temperature, and charge state to the [Blues Notehub](https://blues.com/notehub/) cloud service every four hours, with immediate alerts before the site goes dark. Connectivity is provided by a Blues Notecard seated in the carrier's M.2 slot; two SKUs are supported with no firmware changes between them — [Notecard Cell+WiFi (NOTE-MBGLW)](https://dev.blues.io/datasheets/notecard-datasheet/note-mbglw/) for sites within terrestrial cellular range, and [Notecard for Skylo (NOTE-NBGLWX)](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) for fallback satellite coverage for sites where cellular coverage is marginal or absent. ## 1. Project Overview diff --git a/84-remote-cabinet-backup-battery-sentinel/README.md b/84-remote-cabinet-backup-battery-sentinel/README.md index abd2ccf5..fb9a3a35 100644 --- a/84-remote-cabinet-backup-battery-sentinel/README.md +++ b/84-remote-cabinet-backup-battery-sentinel/README.md @@ -34,7 +34,7 @@ The Notecard manages its own cellular session against the supported carrier netw **Device-side responsibilities.** Every two minutes the Cygnet STM32L433 host on the Notecarrier CX wakes for a few seconds, samples the battery, decides whether anything has gone wrong, and goes back to sleep. In those seconds it reads pack voltage and bidirectional current from the INA228 over Qwiic, picks up surface temperature from the NTC thermistor on A0, and evaluates six battery-condition rules plus one sensor-health check. Any tripped rule becomes an alert [Note](https://dev.blues.io/api-reference/glossary/#note) marked `sync:true` for immediate delivery. Window statistics accumulate in a state struct that `NotePayloadSaveAndSleep` writes into Notecard flash before [`card.attn`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-attn) cuts host power entirely between samples. Window-average power (`voltAvg × currAvg`) is derived at summary time, not sampled per-read from the INA228 power register. -**Notecard responsibilities.** The Notecard owns the radio so the host never has to. It manages its own cellular session against supported carrier networks worldwide via the embedded global SIM, queues Notes in on-device storage, opens a session on the configured [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence (default 60 minutes), and short-circuits that cadence whenever a `sync:true` alert lands — those go out immediately. On the inbound side it pulls down [environment variable](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) updates from Notehub, so the field operator can retune any threshold or either cadence without reflashing. +**Notecard responsibilities.** The Notecard owns the radio so the host never has to. It manages its own cellular session against supported carrier networks worldwide via the embedded global SIM, queues Notes in on-device storage, opens a session on the configured [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence (default 60 minutes), and short-circuits that cadence whenever a `sync:true` alert lands — those go out immediately. On the inbound side it pulls down [environment variable](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) updates from the [Blues Notehub](https://blues.com/notehub/) cloud service, so the field operator can retune any threshold or either cadence without reflashing. **Notehub responsibilities.** Everything that leaves the cabinet lands in [Notehub](https://notehub.io), which ingests and stores each event and runs the project's routes. The two Notefiles — `battery_summary.qo` for periodic telemetry and `battery_alert.qo` for threshold trips — stay deliberately separate so a route can fan summaries into a long-term analytics store while pushing alerts straight to whoever is on call. diff --git a/85-cellular-medication-adherence-pillbox/README.md b/85-cellular-medication-adherence-pillbox/README.md index c1893e25..fac3c4e1 100644 --- a/85-cellular-medication-adherence-pillbox/README.md +++ b/85-cellular-medication-adherence-pillbox/README.md @@ -8,7 +8,7 @@ This reference application is intended to provide inspiration and help you get s -This project is a [remote patient monitoring](https://blues.com/remote-patient-monitoring/) device that catches missed doses before they become clinical events. A Blues Notecard Cell+WiFi riding on a Notecarrier CX wakes every 30 seconds, reads seven snap-action micro-switches inside a standard weekly pillbox, and uploads a cellular event to Notehub **each time a compartment lid is detected open during a scheduled 30-second poll** — no WiFi configuration, no smartphone, and nothing for the patient to set up. +This project is a [remote patient monitoring](https://blues.com/remote-patient-monitoring/) device that catches missed doses before they become clinical events. A Blues Notecard Cell+WiFi riding on a Notecarrier CX wakes every 30 seconds, reads seven snap-action micro-switches inside a standard weekly pillbox, and uploads a cellular event to the [Blues Notehub](https://blues.com/notehub/) cloud service **each time a compartment lid is detected open during a scheduled 30-second poll** — no WiFi configuration, no smartphone, and nothing for the patient to set up. ## 1. Project Overview diff --git a/87-post-discharge-vitals-relay-hub/README.md b/87-post-discharge-vitals-relay-hub/README.md index f9b12a1e..551cf5a4 100644 --- a/87-post-discharge-vitals-relay-hub/README.md +++ b/87-post-discharge-vitals-relay-hub/README.md @@ -8,7 +8,7 @@ This reference application is intended to provide inspiration and help you get s -This project is a [remote patient monitoring](https://blues.com/remote-patient-monitoring/) hub for 30–60-day post-discharge recovery programs. A Blues Notecard Cell+WiFi paired with an nRF52840 host that has native Bluetooth Low Energy scans for a patient's BLE-enabled medical devices — weight scale, blood pressure cuff, pulse oximeter, and activity band — relays each completed reading to Notehub over cellular, and immediately syncs readings that exceed configurable clinical thresholds so the care team is alerted without waiting for the next scheduled upload. No WiFi required, no app to configure, no network credentials to enter. Plug it in and it works. +This project is a [remote patient monitoring](https://blues.com/remote-patient-monitoring/) hub for 30–60-day post-discharge recovery programs. A Blues Notecard Cell+WiFi paired with an nRF52840 host that has native Bluetooth Low Energy scans for a patient's BLE-enabled medical devices — weight scale, blood pressure cuff, pulse oximeter, and activity band — relays each completed reading to the [Blues Notehub](https://blues.com/notehub/) cloud service over cellular, and immediately syncs readings that exceed configurable clinical thresholds so the care team is alerted without waiting for the next scheduled upload. No WiFi required, no app to configure, no network credentials to enter. Plug it in and it works. ## 1. Project Overview diff --git a/88-reefer-trailer-cold-chain-door-event-monitor/README.md b/88-reefer-trailer-cold-chain-door-event-monitor/README.md index 0a1f04c0..8f4885bd 100644 --- a/88-reefer-trailer-cold-chain-door-event-monitor/README.md +++ b/88-reefer-trailer-cold-chain-door-event-monitor/README.md @@ -10,7 +10,7 @@ This reference application is intended to provide inspiration and help you get s This project is a [loss prevention](https://blues.com/loss-prevention/) reference design that keeps continuous watch over refrigerated (**reefer**) trailers — catching temperature excursions before a load is spoiled and logging every door event before a pallet walks out the back. Two DS18B20 temperature probes and a magnetic door reed switch feed a Blues Notecarrier CX, which packages sensor events and hands them to a Notecard for [Skylo](https://www.skylo.tech/resources/geographical-coverage) for multi-network delivery: cellular when a tower is in range, Skylo satellite when it isn't. -**What you'll have when you're done:** a weatherproof, trailer-powered monitor that samples cargo temperature every minute, queues each sample locally for Notehub delivery on the next outbound session (arriving in the cloud/Notehub in batches, default once per hour), fires an alert on the next sample cycle (up to ~60 seconds after the event, plus network-establishment time) when a door opens or a temperature threshold is breached, and ships hourly compliance summaries to Notehub over cellular or WiFi. Per-sample logs and hourly summaries use cellular/WiFi-only Notefiles; the Notecard discards their queued Notes when connecting via NTN, so they never consume the bundled satellite data budget. On periodic hub sessions over NTN — which occur when terrestrial coverage is unavailable — only pending alert Notes carry payload data over the satellite link. +**What you'll have when you're done:** a weatherproof, trailer-powered monitor that samples cargo temperature every minute, queues each sample locally for [Blues Notehub](https://blues.com/notehub/) cloud service delivery on the next outbound session (arriving in the cloud/Notehub in batches, default once per hour), fires an alert on the next sample cycle (up to ~60 seconds after the event, plus network-establishment time) when a door opens or a temperature threshold is breached, and ships hourly compliance summaries to Notehub over cellular or WiFi. Per-sample logs and hourly summaries use cellular/WiFi-only Notefiles; the Notecard discards their queued Notes when connecting via NTN, so they never consume the bundled satellite data budget. On periodic hub sessions over NTN — which occur when terrestrial coverage is unavailable — only pending alert Notes carry payload data over the satellite link. **Energy footprint:** steady-state draw from a 12 V trailer supply is roughly 30–60 mAh per 24 h (dominated by one hourly cellular session of ~15–45 seconds at ~250 mA average). NTN satellite sessions consume more per event due to longer link establishment, but alert-only delivery over satellite keeps the 10 KB data budget intact. Commissioning validates actual consumption with [Blues Mojo](https://shop.blues.com/products/mojo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link). See [§9](#9-validation-and-testing). diff --git a/89-pallet-attached-cold-chain-logger/README.md b/89-pallet-attached-cold-chain-logger/README.md index 281af474..7111c7f7 100644 --- a/89-pallet-attached-cold-chain-logger/README.md +++ b/89-pallet-attached-cold-chain-logger/README.md @@ -45,7 +45,7 @@ This project uses [Notecard for Skylo (NOTE-NBGLWX)](https://shop.blues.com/prod When the state changes, a `cargo_state.qo` note is dispatched immediately via `sync:true` so the remote system learns about the transition in near-real-time over whatever radio is available. If the first send attempt fails (transient Notecard I²C issue), the transition is persisted in `ColdChainState` and retried on every subsequent wake until the Notecard confirms the `note.add`, so no state transition is permanently lost. -**Tamper-evident local log.** Every sample cycle appends one compact-templated entry to the `cargo_log.qo` Notefile. Each entry includes a monotonic sequence number (`seq`, incremented before every note.add), a rolling integrity hash (`chain_crc`) computed over the previous hash, the sequence number, boot segment, and all sensor readings, and a `boot_seg` counter that increments on every cold boot. The boot-segment counter is persisted both in the Notecard sleep payload (planned-sleep resilience) and in a Notecard-local notefile `chain_boot.dbx` (power-loss resilience). Log entries are queued for the regular outbound window rather than synced immediately, batching with outbound sessions without consuming an extra satellite session per sample. The `_time` field is always included in each entry: the real epoch when the Notecard has obtained valid time from Notehub, or `0` as a documented pre-sync sentinel. Downstream consumers should treat `_time == 0` as pre-sync and use Notehub's event receive-time as the best available approximation for those records. A `motion_valid` flag (`1` = card.motion returned valid data; `0` = card.motion was unavailable) is also included in every entry so downstream consumers can distinguish "no motion occurred" (`motion = 0`, `motion_valid = 1`) from "motion data unavailable" (`motion = 0`, `motion_valid = 0`) — preserving the compliance semantics of the per-sample audit log even when the accelerometer interface is temporarily unreachable. A downstream verifier replays the chain **within each `boot_seg` group** from seq=1 (seed=0); a gap in `seq` within a segment indicates a dropped transmission; a `chain_crc` mismatch indicates a modified or inserted record; and a new `boot_seg` value marks the start of a new, independent chain segment caused by a device cold boot. +**Tamper-evident local log.** Every sample cycle appends one compact-templated entry to the `cargo_log.qo` Notefile. Each entry includes a monotonic sequence number (`seq`, incremented before every note.add), a rolling integrity hash (`chain_crc`) computed over the previous hash, the sequence number, boot segment, and all sensor readings, and a `boot_seg` counter that increments on every cold boot. The boot-segment counter is persisted both in the Notecard sleep payload (planned-sleep resilience) and in a Notecard-local notefile `chain_boot.dbx` (power-loss resilience). Log entries are queued for the regular outbound window rather than synced immediately, batching with outbound sessions without consuming an extra satellite session per sample. The `_time` field is always included in each entry: the real epoch when the Notecard has obtained valid time from the [Blues Notehub](https://blues.com/notehub/) cloud service, or `0` as a documented pre-sync sentinel. Downstream consumers should treat `_time == 0` as pre-sync and use Notehub's event receive-time as the best available approximation for those records. A `motion_valid` flag (`1` = card.motion returned valid data; `0` = card.motion was unavailable) is also included in every entry so downstream consumers can distinguish "no motion occurred" (`motion = 0`, `motion_valid = 1`) from "motion data unavailable" (`motion = 0`, `motion_valid = 0`) — preserving the compliance semantics of the per-sample audit log even when the accelerometer interface is temporarily unreachable. A downstream verifier replays the chain **within each `boot_seg` group** from seq=1 (seed=0); a gap in `seq` within a segment indicates a dropped transmission; a `chain_crc` mismatch indicates a modified or inserted record; and a new `boot_seg` value marks the start of a new, independent chain segment caused by a device cold boot. **Notecard responsibilities.** Notecard for Skylo holds outbound [Notes](https://dev.blues.io/api-reference/glossary/#note) in its on-device flash queue and decides for itself which radio to use — cellular, WiFi, or NTN satellite — depending on what's reachable from wherever the pallet currently sits. It flushes the queue on the configured [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) outbound cadence (default 60 minutes), and any Note marked `sync:true` jumps the queue and opens a session immediately on whatever radio is available. Coming the other way, the Notecard distributes [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) from Notehub, so shipper operations can change threshold values, sample cadence, or summary cadence mid-route without reflashing firmware.