diff --git a/53-municipal-wastewater-lift-station-monitor/README.md b/53-municipal-wastewater-lift-station-monitor/README.md index 3b335484..41ab5c78 100644 --- a/53-municipal-wastewater-lift-station-monitor/README.md +++ b/53-municipal-wastewater-lift-station-monitor/README.md @@ -8,7 +8,7 @@ This reference application is intended to provide inspiration and help you get s -This project is a [downtime prevention](https://blues.com/downtime-prevention/) retrofit for municipal wastewater lift stations that catches pump failures, discharge obstructions, and high-water conditions before they become a sanitary overflow. A handful of sensors and a cellular (or, for stations beyond reliable carrier coverage, satellite) [Notecard](https://shop.blues.com/products/notecard-cellular?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) transform a sealed concrete vault into a remotely-monitored station that delivers alerts to the on-call crew within minutes, not hours after a manual site visit. +This project is a [downtime prevention](https://blues.com/downtime-prevention/) retrofit for municipal wastewater lift stations that catches pump failures, discharge obstructions, and high-water conditions before they become a sanitary overflow. A handful of sensors and 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 that carries cellular, WiFi, and Skylo satellite radios and fails over between them automatically — transform a sealed concrete vault into a remotely-monitored station that delivers alerts to the on-call crew within minutes, not hours after a manual site visit. One SKU and one firmware image cover the entire fleet, from the station three blocks from city hall to the one at the edge of the service territory beyond any cell tower. ## 1. Project Overview @@ -16,45 +16,47 @@ 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 Cygnet host MCU evaluates three fault rules every 60 seconds and routes alerts to Notehub via cellular the instant any rule trips. 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 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.** 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 SIM covers automatically. The NOTE-MBGLW's cellular radio reaches the vast majority of municipal infrastructure without site-specific network provisioning, login credentials, firewall rules, or per-site IT overhead. WiFi is available as an opportunistic fallback for the rare station adjacent to an accessible AP. Stations at the fringe of the service territory — beyond the reach of any cellular carrier — use a Starnote instead: the same M.2 form factor, the same Notecard API, the same firmware, but with a satellite link over the [Skylo](https://www.skylo.tech/) network rather than a terrestrial cell tower. The same firmware image deploys across the entire fleet; the connectivity module is the only variable. +**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. -**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. Cellular antenna cable exits through a conduit fitting to a magnetic-mount or direct-mount antenna on the cabinet exterior or above-grade access point. +**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. ## 2. System Architecture -![System architecture: wet well sensors (level transducer, two CTs, float) → above-grade enclosure with Notecarrier CX → cellular MBGLW or Starnote satellite → Notehub → on-call/analytics](diagrams/01-system-architecture.svg) +![System architecture: wet well sensors (level transducer, two CTs, float) → above-grade enclosure with Notecarrier CX → Notecard for Skylo (cellular / WiFi / satellite) → Notehub → on-call/analytics](diagrams/01-system-architecture.svg) **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.** Whichever module is in the M.2 slot — MBGLW for cellular sites or Starnote for satellite sites — runs the same playbook: 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. On cellular that means a Note in flight 15–60 seconds after the host queues it; on satellite it means first-in-line for the next Skylo pass, 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.** 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. -**Notehub responsibilities.** The Notecard's embedded global SIM (or Skylo subscription) hands 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. +**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. **Routing to the cloud (high level).** Notehub supports HTTP, MQTT, AWS, Azure, GCP, Snowflake, and a wide range of other destinations; route setup is project-specific and not implemented here. See the [Notehub routing docs](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub) for configuration guidance. -### Satellite-specific considerations (Option B, Starnote) +### Satellite (NTN) operation considerations -The Starnote uses the same Notecard API as the MBGLW, but the satellite link has operational characteristics that must be planned for, not assumed away: +The same Notecard for Skylo runs the same firmware everywhere, but at stations that routinely fall back to the satellite link the NTN path has operational characteristics that must be planned for, not assumed away. These apply only while the unit is transmitting over satellite — stations within cellular coverage behave like any other cellular Notecard. -**Alert latency.** `sync:true` Notes are prioritized for the next available satellite pass, but locating a Skylo satellite and completing transmission can take several minutes. For Starnote stations, "alert in minutes" is realistic; "alert in seconds" is not. The 30-minute alert cooldown in the firmware is still meaningful because a satellite station is reporting a fault to the crew before the wet well overflows, not instantaneously. +**Alert latency.** `sync:true` Notes are prioritized for the next available satellite session, but locating a Skylo satellite and completing transmission can take several minutes. When a station is operating over satellite, "alert in minutes" is realistic; "alert in seconds" is not. The 30-minute alert cooldown in the firmware is still meaningful because a satellite station is reporting a fault to the crew before the wet well overflows, not instantaneously. -**Inbound sync cadence and data cost.** Each inbound sync (used to pull updated environment variables from Notehub) consumes approximately 50 bytes of satellite data. At the default `inbound:120` (every 2 hours), that is ~600 bytes per day — a significant fraction of the bundled 10 KB. For Starnote deployments, set `inbound_interval_min` to `240` or higher via the Notehub environment-variable panel to reduce inbound satellite data consumption. The firmware re-issues `hub.set` whenever `inbound_interval_min` or `summary_interval_min` changes, so neither adjustment requires a firmware reflash (see the env-var table in [Section 5](#6-notehub-setup)). +**Inbound sync cadence and data cost.** Each inbound sync (used to pull updated environment variables from Notehub) consumes approximately 50 bytes of satellite data. At the default `inbound:120` (every 2 hours), that is ~600 bytes per day — a significant fraction of the bundled 10 KB satellite allocation. For stations expected to operate over satellite, set `inbound_interval_min` to `240` or higher via the Notehub environment-variable panel to reduce inbound satellite data consumption. The firmware re-issues `hub.set` whenever `inbound_interval_min` or `summary_interval_min` changes, so neither adjustment requires a firmware reflash (see the env-var table in [Section 5](#6-notehub-setup)). -**Payload discipline.** Starnote for Skylo 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 satellite Notefiles, and validate payload size on any schema change. +**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.** The Starnote for Skylo must operate with its antenna outdoors and free from obstructions — for the northern hemisphere, an unobstructed view of the southern sky. 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 Starnote; substituting an uncertified GPS/GNSS patch risks regulatory non-compliance and link failure. +**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. -**Power envelope.** The Starnote idles at typically less than 4 µA @ 5 V — lower than the MBGLW's ~18 µA. During a satellite session, VMODEM_P requires a sustained 350 mA supply capability, similar in magnitude to an LTE session. The HDR-15-5 (3 A rated) handles both variants with margin. See the [Validation section](#9-validation-and-testing) for a per-state current breakdown. +**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. -**Mandatory initial cellular sync.** Before any satellite (NTN) operation is possible, the Starnote must complete at least one non-NTN sync with Notehub over cellular or WiFi to associate with a project. Ensure the unit has cellular 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, 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. ## 3. Technical Summary -**What you'll have:** A [Notecarrier CX](https://shop.blues.com/products/notecarrier-cx?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) + Notecard sending sample lift_alert and lift_summary events to your Notehub project every 60 seconds without needing sensors in the field. +**What you'll have:** A [Notecarrier CX](https://shop.blues.com/products/notecarrier-cx?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) + Notecard for Skylo sending sample lift_alert and lift_summary events to your Notehub project every 60 seconds without needing sensors in the field. 1. **Create a Notehub project** at [notehub.io](https://notehub.io) and copy its ProductUID. 2. **Flash the firmware:** @@ -73,7 +75,7 @@ The Starnote uses the same Notecard API as the MBGLW, but the satellite link has For bench-only testing, use compile-time flags to inject synthetic sensor values (see "Bench fault simulation" below in Section 8). -Two connectivity SKUs cover the full deployment spectrum. Stations within LTE coverage use a **Notecard Cell+WiFi (MBGLW)**. Truly rural stations beyond reliable cellular reach use a **[Starnote](https://shop.blues.com/products/starnote?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link)** ([datasheet](https://dev.blues.io/datasheets/starnote-datasheet/starnote-for-skylo/)), which routes telemetry over the Skylo satellite network. The firmware is identical for both variants; Notehub configuration is shared, though satellite deployments benefit from wider inbound sync intervals to conserve bundled satellite data. See [Satellite-specific considerations](#satellite-specific-considerations-option-b-starnote) in Section 2. +A single SKU covers the full deployment spectrum. Every station uses a **[Notecard for Skylo](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/)): stations within LTE coverage transmit over cellular, and stations beyond reliable cellular reach fall back automatically to the Skylo satellite network — no second device, no different part number, no antenna swap. The firmware and Notehub configuration are identical everywhere; stations expected to operate over satellite simply benefit from wider inbound sync intervals to conserve bundled satellite data. See [Satellite (NTN) operation considerations](#satellite-ntn-operation-considerations) in Section 2. Here is a sample Note this device emits: @@ -96,8 +98,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 an embedded Cygnet STM32L433 host — no separate MCU needed for this analog + digital sensor mix. | -| **Option A — cellular sites:** [Notecard Cell+WiFi (MBGLW)](https://shop.blues.com/products/notecard-cell-wifi?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) ([datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-mbglw/)) | 1 | LTE Cat-1 bis cellular (Quectel EG916Q-GL modem) removes per-site network provisioning; prepaid SIM covers all stations from one SKU. Onboard PCB antenna handles WiFi; cellular requires the external LTE antenna below. Use this SKU for stations within LTE coverage — the majority of municipal infrastructure. | -| **Option B — satellite/rural sites:** [Starnote](https://dev.blues.io/datasheets/starnote-datasheet/starnote-for-skylo/) | 1 | Same M.2 form factor and Notecard API as Option A; routes telemetry over the Skylo satellite network instead of a terrestrial cell tower. Use this SKU for stations beyond reliable LTE coverage. Requires the satellite patch antenna below (replace the LTE antenna and pigtail with the satellite items). Satellite link is lower-bandwidth and higher-latency than LTE; alert and summary Notes queue in the Notecard's local store and sync on the Starnote's satellite session cadence. | +| [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. The firmware's `card.transport` `wifi-cell-ntn` setting makes it prefer cellular at in-coverage stations and fall back automatically to the Skylo satellite network at stations beyond cellular reach — no second device or part-number decision. Removes per-site network provisioning; the embedded global SIM and bundled satellite allocation cover the whole fleet from one SKU. Requires the antennas below. | | [Blues Mojo](https://shop.blues.com/products/mojo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Coulomb-counter on the power rail for bench-validation of the sleep/wake/transmit energy profile. Not deployed to the field. | | [WIKA LH-10](https://www.wika.com/en-us/lh_10.WIKA), 0–15 PSI gauge, 4–20 mA 2-wire, 316L SS, IP68, with vented cable | 1 | Submersible hydrostatic level transmitter purpose-built for water/wastewater wet-well immersion (the WIKA S-10 is a general-purpose / sanitary transmitter; the LH-10 is the family member rated for permanent submersion in raw sewage). The vented polyurethane cable (an internal vent tube equalizes the sensor's reference side to atmosphere, making the measurement gauge pressure = water head) doubles as the support tether — secured with a stainless cable grip at the cover plate. 316L SS wetted parts tolerate raw sewage. 15 PSI range covers ≈ 10 m of wet-well head. 4–20 mA 2-wire loop-powered output; wiring is identical to any other loop-powered transmitter. Specify "vented cable" and M20×1.5 or ½ NPT conduit seal fitting when ordering. Available from WIKA, instrumart.com, and major industrial distributors. | | 150 Ω, 1% resistor (level sensor shunt) | 1 | Converts 4–20 mA loop current to 0.6–3.0 V for the 3.3 V STM32 ADC (full-scale within VREF). | @@ -108,14 +109,11 @@ 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. | -| **Option A — cellular antenna:** Taoglas MA800.A.BI.001 multiband LTE antenna, 3 m RG-174 cable, SMA-M connector (or equivalent mag-mount whip) | 1 | Magnetic-mount external LTE antenna routed through a liquid-tight cable gland to the cabinet exterior or above-grade access point. SMA-M plug on the cable mates with the SMA-F bulkhead pigtail listed below. | -| **Option A — cellular pigtail:** u.FL to SMA-F bulkhead pigtail, 150 mm RG178 coax (e.g. Taoglas CAB.0150.A.01; available from Mouser or direct from Taoglas) | 1 | Connects the Notecard MBGLW's cellular u.FL port to the SMA-F bulkhead fitting in the enclosure wall; the LTE antenna cable's SMA-M plug seats into the bulkhead female. Route and secure through the enclosure wall before closing the box. | -| **Option B — satellite antenna:** Skylo-certified LTE-band antenna included with the Starnote for Skylo (u.FL variant); passive GPS/GNSS antenna for the GPS connector per the [Starnote for Skylo datasheet](https://dev.blues.io/datasheets/starnote-datasheet/starnote-for-skylo/) | 1 set | Use only the Skylo-certified antenna supplied with the Starnote on the SAT u.FL port — do not substitute an uncertified GPS/GNSS patch, which risks regulatory non-compliance and link failure. The GPS connector requires a separate passive GPS/GNSS antenna per the datasheet. Both antennas must be mounted outdoors with an unobstructed view of the sky (in the northern hemisphere, an unobstructed view of the southern sky). Route cables through liquid-tight fittings into the enclosure. | +| 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). | +| 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. | -**Option A (MBGLW):** Ships with an active global SIM including 500 MB of data and 10 years of service — no activation fees, no monthly commitment. - -**Option B (Starnote):** Ships with 10 KB of bundled Skylo satellite data; no satellite provider subscription, monthly minimums, or activation fees apply. Additional data is billed per byte (see the [Starnote for Skylo datasheet](https://dev.blues.io/datasheets/starnote-datasheet/starnote-for-skylo/) for current pricing). Minimizing inbound sync frequency conserves the bundled allocation. See [Section 2](#satellite-specific-considerations-option-b-starnote) for guidance. +**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 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). Minimizing inbound sync frequency conserves the bundled satellite allocation. See [Section 2](#satellite-ntn-operation-considerations) for guidance. ## 5. Wiring and Assembly @@ -127,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 connectivity module (Notecard MBGLW or Starnote) seats into the M.2 slot. **Option A (cellular):** the Notecard MBGLW's cellular u.FL port connects via a u.FL-to-SMA-F bulkhead pigtail through the enclosure wall; the external LTE antenna cable's SMA-M plug seats into the bulkhead female. The MBGLW's WiFi function uses the onboard PCB antenna — no external WiFi antenna required. **Option B (satellite):** the Starnote's u.FL antenna port connects directly to the satellite patch antenna cable — no SMA bulkhead pigtail needed, but the patch must mount with a clear sky view. 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. 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. **Level sensor (4–20 mA current loop)** @@ -222,7 +220,7 @@ The `.ino` file is self-contained for the Arduino IDE (which compiles `.ino` + ` | Responsibility | Function | |---|---| -| Notecard configuration (`hub.set`, accelerometer disable) | `notecardConfigure` | +| Notecard configuration (`hub.set`, `card.transport` `wifi-cell-ntn` for cellular→satellite fallback, accelerometer disable) | `notecardConfigure` | | Notefile template registration | `defineTemplates` | | Env-var threshold fetch (every wake) | `fetchEnvOverrides` | | Re-issue `hub.set` when `summary_interval_min` changes | `applyHubSetIfChanged` | @@ -300,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 itself sits in its own [low-power idle](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design/) state between radio sessions (~18 µA @ 5 V for the NOTE-MBGLW; typically less than 4 µA @ 5 V for the Starnote). +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. -**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. For Starnote (Option B) deployments, `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. +**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 MBGLW's included 500 MB, and a meaningful but manageable fraction of the Starnote's bundled 10 KB. +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. ### Retry and error handling @@ -414,35 +412,26 @@ 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/)): -**Option A — MBGLW (cellular):** - -| Operating state | Notecard (MBGLW) | Cygnet host | 5 V rail total | -|---|---|---|---| -| Deep sleep — host cut by ATTN, Notecard idle | ~18 µA | ~0 µA | ~20 µA | -| Host active — sensor reads + I²C (~300 milliseconds per 60 seconds cycle) | ~18 µA | ~20–30 mA | ~20–30 mA | -| LTE session only, host asleep (batched summary) | ~250 mA avg, ≤600 mA peak | ~0 µA | ~250 mA avg | -| Host active + immediate LTE session (alert `sync:true`) | ~250 mA avg | ~20–30 mA | ~270 mA avg | - -**Option B — Starnote (satellite):** +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. -| Operating state | Starnote | Cygnet host | 5 V rail total | +| Operating state | Notecard for Skylo | Cygnet host | 5 V rail total | |---|---|---|---| -| Deep sleep — host cut by ATTN, Starnote idle | typically < 4 µA | ~0 µA | < 6 µA | -| Host active — sensor reads + I²C (~300 milliseconds per 60 seconds cycle) | typically < 4 µA | ~20–30 mA | ~20–30 mA | -| Satellite session only, host asleep (batched summary) | up to 350 mA sustained on VMODEM_P | ~0 µA | ~350 mA | -| Host active + immediate satellite session (alert `sync:true`) | up to 350 mA sustained | ~20–30 mA | ~370 mA | +| Deep sleep — host cut by ATTN, Notecard idle | ~8 µA | ~0 µA | ~10 µA | +| Host active — sensor reads + I²C (~300 milliseconds per 60 seconds cycle) | ~8 µA | ~20–30 mA | ~20–30 mA | +| Network session only, host asleep (batched summary) — cellular or satellite | ~250 mA avg, brief multi-hundred-mA (up to ~2 A for a few ms) peaks | ~0 µA | ~250 mA avg | +| Host active + immediate network session (alert `sync:true`) | ~250 mA avg | ~20–30 mA | ~270 mA avg | -**24-hour energy budget (Option A, cellular, powered continuously from 120 VAC supply, illustrative numbers; cellular session length dominates and varies with signal conditions):** +**24-hour energy budget (cellular operation, powered continuously from 120 VAC supply, illustrative numbers; network session length dominates and varies with signal conditions — satellite sessions land in the same magnitude):** -- Idle: ~20 µA × ~24 h ≈ **~0.5 mAh/day** (the Notecard idle plus carrier-board quiescent draw, accumulated for the ~99.5% of the day the host is gated off). +- Idle: ~10 µA × ~24 h ≈ **~0.25 mAh/day** (the Notecard idle plus carrier-board quiescent draw, accumulated for the ~99.5% of the day the host is gated off). - Host wakes: ~25 mA × 0.3 seconds × 60 wakes/hr × 24 hours ≈ 10,800 mA·s ≈ **~3 mAh/day** (10,800 mA·s ÷ 3600 s/hr). -- Hourly outbound session: ~250 mA avg × ~10 seconds × 24 sessions/day ≈ 60,000 mA·s ≈ **~17 mAh/day** (assumes a typical LTE Cat-1 bis session including network registration; a clean network and queued-template summary commonly lands in the 5–15 seconds range, while marginal coverage stretches it well past 30 seconds). +- Hourly outbound session: ~250 mA avg × ~10 seconds × 24 sessions/day ≈ 60,000 mA·s ≈ **~17 mAh/day** (assumes a typical LTE-M session including network registration; a clean network and queued-template summary commonly lands in the 5–15 seconds range, while marginal coverage — or a fallback to satellite — stretches it well past 30 seconds). - Occasional alerts (assume 2/day): ~250 mA × ~10 seconds × 2 ≈ **~1.4 mAh/day**. **Total: roughly ~22 mAh/day in steady state, with hourly cellular sessions dominating the budget.** Weak-signal sites where the modem camps in registration can easily push this 2–3× higher. The MeanWell HDR-15-5 (85–264 VAC input, 5 VDC 3 A output) provides continuous power from the station's 120 VAC control supply, so energy budgeting is not the deployment constraint, but validating these current draws with Mojo confirms the sleep/wake architecture is working and surfaces signal-quality issues early. **Expected Mojo trace over 24 hours:** -- Dominant pattern: 60-second intervals of near-zero current (~20 µA, host and Notecard idle). +- Dominant pattern: 60-second intervals of near-zero current (~10 µA, host and Notecard idle). - Every 60 seconds: 300 milliseconds spike at ~25 mA (host wakes, reads sensors, issues I²C). - Every ~60 minutes: longer spike at ~250–350 mA lasting ~2–5 seconds (Notecard modem session for summary). - Occasional taller/longer spikes: alerts firing with `sync:true` (variable timing, depends on fault events). @@ -464,8 +453,8 @@ arduino-cli lib install "Blues Wireless Notecard" 4. If `hub.set` fails, the Notecard may not have cellular or WiFi coverage. Check antenna connection and signal strength (use `card.signal` request via serial via the [Notecard CLI](https://dev.blues.io/tools-and-sdks/notecard-cli/)). **No events appearing in Notehub after 5 minutes.** Check: -1. **Network availability** — does the Notecard have cellular or WiFi? Use the serial log or `card.signal` to verify. -2. **Event payload size** — for Starnote (Option B), Notes exceeding 256 bytes are silently dropped. Check the serial log for `note.add` success/failure status. +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. 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: @@ -489,7 +478,7 @@ This reference design covers the bulk of typical municipal lift stations, but it - **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 variant caveats (Option B, Starnote).** The Starnote firmware is identical to the cellular variant, but the satellite link has material operational differences. Alert and summary Notes queue in the Notecard's local store and sync on the Starnote's satellite session schedule — `sync:true` Notes are prioritized for the next available pass, but locating a Skylo satellite and completing transmission takes several minutes (not seconds). Each Note must stay within the Starnote for Skylo's 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 antenna included with the Starnote must be mounted outdoors with an unobstructed sky view (in the northern hemisphere, an unobstructed view of the southern sky); stations with the enclosure entirely below grade will need an above-grade cable run. Starnote idle current is typically less than 4 µA @ 5 V; satellite modem sessions require up to 350 mA sustained on VMODEM_P — the HDR-15-5 at 3 A handles both variants with margin (see [Section 8](#9-validation-and-testing) for the full per-state breakdown). +- **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. **Production next steps:** @@ -497,10 +486,10 @@ This reference design covers the bulk of typical municipal lift stations, but it - 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 so threshold algorithm improvements roll out to the fleet without a truck roll to each underground vault. +- [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. ## 12. Summary -The on-call engineer who used to first hear about a sanitary sewer overflow from a citizen complaint on Monday morning now gets a page at 2 AM Saturday — wet well rising while a pump is running, or a float switch closing, or a pump that should be on but isn't. Three sensors, one cellular (or satellite) Notecard, and three rules running on a sleeping host turn an opaque concrete vault into a station that calls for help before it overflows — and the same firmware drops onto the station three blocks from city hall or the one at the edge of the service territory, with only the M.2 module changing. +The on-call engineer who used to first hear about a sanitary sewer overflow from a citizen complaint on Monday morning now gets a page at 2 AM Saturday — wet well rising while a pump is running, or a float switch closing, or a pump that should be on but isn't. Three sensors, one Notecard for Skylo that carries cellular, WiFi, and satellite on a single module, and three rules running on a sleeping host turn an opaque concrete vault into a station that calls for help before it overflows — and the exact same hardware and firmware drops onto the station three blocks from city hall or the one at the edge of the service territory, reaching cellular where there's a tower and the Skylo satellite network where there isn't, with nothing to swap. diff --git a/53-municipal-wastewater-lift-station-monitor/diagrams/01-system-architecture.svg b/53-municipal-wastewater-lift-station-monitor/diagrams/01-system-architecture.svg index d765e749..bac7c2c0 100644 --- a/53-municipal-wastewater-lift-station-monitor/diagrams/01-system-architecture.svg +++ b/53-municipal-wastewater-lift-station-monitor/diagrams/01-system-architecture.svg @@ -11,7 +11,7 @@ System Architecture - Lift station — cellular or satellite, shared firmware + Lift station — cellular + satellite on one module, shared firmware @@ -42,8 +42,8 @@ Connectivity - A · MBGLW (cellular) - B · Starnote (satellite) + Notecard for Skylo + cellular · WiFi · satellite @@ -64,5 +64,5 @@ - Cellular alerts arrive in seconds; satellite alerts on the next Skylo pass. + Cellular alerts arrive in seconds; satellite-fallback alerts on the next Skylo session. diff --git a/53-municipal-wastewater-lift-station-monitor/diagrams/02-wiring-assembly.svg b/53-municipal-wastewater-lift-station-monitor/diagrams/02-wiring-assembly.svg index 61ebc7c0..ed04e78f 100644 --- a/53-municipal-wastewater-lift-station-monitor/diagrams/02-wiring-assembly.svg +++ b/53-municipal-wastewater-lift-station-monitor/diagrams/02-wiring-assembly.svg @@ -22,7 +22,7 @@ Notecarrier CX - + Cygnet · MBGLW or Starnote + + Cygnet · Notecard for Skylo A0 diff --git a/53-municipal-wastewater-lift-station-monitor/firmware/lift_station_monitor/lift_station_monitor.ino b/53-municipal-wastewater-lift-station-monitor/firmware/lift_station_monitor/lift_station_monitor.ino index 0d0b048a..352a1d5c 100644 --- a/53-municipal-wastewater-lift-station-monitor/firmware/lift_station_monitor/lift_station_monitor.ino +++ b/53-municipal-wastewater-lift-station-monitor/firmware/lift_station_monitor/lift_station_monitor.ino @@ -17,7 +17,9 @@ Hardware: - Notecarrier CX (Cygnet STM32L433 host) - - Notecard Cell+WiFi MBGLW (M.2 slot) + - Notecard for Skylo NOTE-NBGLWX (M.2 slot) — cellular + WiFi + Skylo + satellite (NTN) on one board; card.transport selects cellular-primary + with automatic satellite fallback (see notecardConfigure()). - 4-20 mA submersible level transducer → A0 (150 Ω shunt to GND) - SCT-013-030 split-core CT, pump 1 → A1 (bias circuit) - SCT-013-030 split-core CT, pump 2 → A2 (bias circuit) diff --git a/53-municipal-wastewater-lift-station-monitor/firmware/lift_station_monitor/lift_station_monitor_helpers.cpp b/53-municipal-wastewater-lift-station-monitor/firmware/lift_station_monitor/lift_station_monitor_helpers.cpp index 9115e465..db9987a7 100644 --- a/53-municipal-wastewater-lift-station-monitor/firmware/lift_station_monitor/lift_station_monitor_helpers.cpp +++ b/53-municipal-wastewater-lift-station-monitor/firmware/lift_station_monitor/lift_station_monitor_helpers.cpp @@ -69,10 +69,10 @@ float clampF(double v, float minv, float maxv, float fallback) { } // --------------------------------------------------------------------------- -// notecardConfigure — cold-boot hub.set (periodic mode) and accelerometer -// disable. PRODUCT_UID is included here and in applyHubSetIfChanged() so that -// any successful hub.set, regardless of call site, binds the device to the -// intended Notehub project. +// notecardConfigure — cold-boot hub.set (periodic mode), transport selection, +// and accelerometer disable. PRODUCT_UID is included here and in +// applyHubSetIfChanged() so that any successful hub.set, regardless of call +// site, binds the device to the intended Notehub project. // --------------------------------------------------------------------------- void notecardConfigure(void) { J *req = notecard.newRequest("hub.set"); @@ -86,6 +86,27 @@ void notecardConfigure(void) { Serial.println("[CONFIG] hub.set (cold boot) failed; applyHubSetIfChanged() will retry."); } + // Transport selection for the Notecard for Skylo (NOTE-NBGLWX). + // The board carries WiFi, cellular, and Skylo satellite (NTN) radios, but + // satellite fallback is NOT enabled by default — the factory transport is + // "wifi-cell" (WiFi preferred, cellular fallback, no NTN). Set "wifi-cell-ntn" + // so the Notecard prefers WiFi where an AP is reachable, falls back to + // cellular (the de-facto primary at most stations), and finally to Skylo + // satellite at stations beyond terrestrial coverage — automatic failover + // with no firmware branching. The Notecard persists this setting in its own + // flash, so issuing it once on cold boot is sufficient. + // + // Note: Skylo requires at least one non-NTN (cellular or WiFi) sync to + // associate with Notehub and register templates before NTN can be used. + // In "periodic" mode the cold-boot hub.set above triggers that first sync + // over cellular/WiFi, so commission each unit where it has terrestrial + // coverage even if it will routinely operate over satellite. + req = notecard.newRequest("card.transport"); + JAddStringToObject(req, "method", "wifi-cell-ntn"); + if (!notecard.sendRequestWithRetry(req, 10)) { + Serial.println("[CONFIG] card.transport (wifi-cell-ntn) failed; will retry on next cold boot."); + } + // Disable the onboard accelerometer to keep scope traces clean during // bench validation — removes occasional interrupt-driven current blips. req = notecard.newRequest("card.motion.mode"); @@ -104,7 +125,8 @@ bool defineTemplates(void) { // lift_alert.qo: immediate-sync alert notes (low volume, real-time). // format:"compact" produces a fixed-width binary encoding that keeps - // each Note well within Starnote for Skylo's 256-byte payload ceiling. + // each Note well within the 256-byte payload ceiling enforced when the + // Notecard for Skylo is transmitting over the satellite (NTN) link. // level_pct may carry LEVEL_INVALID_SENTINEL (-9999) when the level sensor // is faulted; the 4-byte float field accommodates any float value. J *req = notecard.newRequest("note.template"); @@ -123,7 +145,7 @@ bool defineTemplates(void) { } // lift_summary.qo: hourly aggregates (batched outbound sync). - // format:"compact" keeps the note within the 256-byte satellite ceiling. + // format:"compact" keeps the note within the 256-byte NTN (satellite) ceiling. // level_pct and level_avg_pct may carry LEVEL_INVALID_SENTINEL; the 4-byte // float field accommodates any float value. level_faults counts samples in // the window where the level sensor returned an out-of-range ADC value 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 abf0d712..84d94484 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 @@ -12,9 +12,9 @@ This project is a cellular [energy savings](https://blues.com/energy-savings/) r ## 1. Project Overview -**The problem.** For a chain QSR (quick-service restaurant), c-store (convenience store), or grocery operator, the walk-in cooler is one of the most expensive assets in a store, and one of the least visible. Energy cost per location is second only to labor, and a significant fraction of that energy budget runs through the compressor of one or more walk-in boxes. Operators who get visibility into compressor runtime, door discipline, and temperature trends across their fleet can cut energy spend materially: a door held open five minutes longer than necessary during a busy lunch rush costs real money in wasted refrigeration, and a compressor running six hours a day instead of four because box air temperature has quietly drifted 2 °F above the corporate temperature target costs even more at scale. +**The problem.** For a chain QSR (quick-service restaurant), convenience store, or grocery operator, the walk-in cooler is one of the most expensive assets in a store, and one of the least visible. Energy cost per location is second only to labor, and a significant fraction of that energy budget runs through the compressor of one or more walk-in boxes. Operators who get visibility into compressor runtime, door discipline, and temperature trends across their fleet can cut energy spend materially: a door held open five minutes longer than necessary during a busy lunch rush costs real money in wasted refrigeration, and a compressor running six hours a day instead of four because box air temperature has quietly drifted 2 °F above the corporate temperature target costs even more at scale. -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, c-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. +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. @@ -30,11 +30,11 @@ This project is the device that gets past that barrier. One SKU, cellular-connec **Device-side responsibilities.** Inside the cooler's mechanical-room enclosure, the Cygnet STM32 host on the Notecarrier CX comes up every `sample_interval_sec` seconds (default 60), reads all three sensors, updates the per-window accumulators (kWh proxy, compressor runtime, door open seconds and event count), and runs the two alert rules. Then it either queues a summary [Note](https://dev.blues.io/api-reference/glossary/#note) for the next window or goes straight back to sleep. Between wakes the host is fully powered down via [`card.attn`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-attn) — the Notecard holds the sleep state and brings the host back when the next interval lands. -**Notecard responsibilities.** Whatever the host queues, the Notecard takes care of. Notes wait in the on-device queue until the [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence (default 60 minutes) opens a cellular (or opportunistic WiFi) session and flushes them in one batch. Anything tagged `sync:true` skips the queue and the radio comes up immediately. The Notecard also pulls [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) from Notehub on every inbound sync — setpoint targets, alert timers, and cadences all tunable from a browser, no firmware reflash, no field visit. +**Notecard responsibilities.** Whatever the host queues, the Notecard takes care of. Notes wait in the on-device queue until the [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence (default 60 minutes) opens a cellular (or opportunistic WiFi) session and flushes them in one batch. Anything tagged `sync:true` skips the queue and the radio comes up immediately. The Notecard also pulls [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) from Notehub on every inbound sync — setpoint targets, alert timers, and cadences all tunable from a browser, no firmware updates or field visits required. -**Notehub responsibilities.** The Notecard's embedded global SIM lands events in [Notehub](https://notehub.io), which ingests them, stores every one, and runs the project-level routes. Summaries and alerts go to separate [Notefiles](https://dev.blues.io/api-reference/glossary/#notefile) on purpose: `cooler_summary.qo` for the hourly telemetry that flows to BI or a long-term store, and `cooler_alert.qo` for the immediate notifications that need to land on a phone or a Slack channel — no filter logic inside the route, just two streams pointed at the right destinations. [Fleets](https://dev.blues.io/guides-and-tutorials/fleet-admin-guide/) and [Smart Fleets](https://dev.blues.io/notehub/notehub-walkthrough/#using-smart-fleet-rules) make it easy to set a corporate temperature target per banner or region while still overriding the one flagship that runs tighter. +**Notehub responsibilities.** The Notecard's embedded global SIM lands events in [Blues Notehub](https://notehub.io), which ingests them, stores every one, and runs the project-level routes to your cloud application of choice. Summaries and alerts go to separate JSON-based [Notefiles](https://dev.blues.io/api-reference/glossary/#notefile) on purpose: `cooler_summary.qo` for the hourly telemetry that flows to BI or a long-term store, and `cooler_alert.qo` for the immediate notifications that need to land on a phone or a Slack channel — no filter logic inside the route, just two streams pointed at the right destinations. [Fleets](https://dev.blues.io/guides-and-tutorials/fleet-admin-guide/) and [Smart Fleets](https://dev.blues.io/notehub/notehub-walkthrough/#using-smart-fleet-rules) make it easy to set a corporate temperature target per banner or region while still overriding the one flagship that runs tighter. -**Routing to the cloud (high level).** Notehub supports HTTP, MQTT, AWS, Azure, GCP, Snowflake, and other destinations. Route configuration is project-specific — this project ships no downstream endpoint. See the [Notehub routing docs](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub) for setup details. +**Routing to the cloud.** Notehub supports HTTP, MQTT, AWS, Azure, GCP, Snowflake, and other destinations. Route configuration is project-specific — this project ships no downstream endpoint. See the [Notehub routing docs](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub) for setup details. ## 3. Technical Summary @@ -82,7 +82,7 @@ After completing this project, you will deploy a complete cellular-connected wal 1. **Three non-invasive sensors** mounted on the cooler (temperature probe in the box, current transformer clamp on the compressor hot leg, magnetic reed switch on the door) — no electrical changes required, no cooperation from the cooler's OEM. -2. **A local enclosure** (Notecarrier CX with onboard Cygnet host, Notecard Cell+WiFi, power supply, and bias/pull-up circuits) that samples all three sensors every 60 seconds and automatically sleeps between samples. +2. **A local enclosure** (Notecarrier CX with onboard Cygnet STM32 host, Notecard Cell+WiFi, power supply, and bias/pull-up circuits) that samples all three sensors every 60 seconds and automatically sleeps between samples. 3. **Notehub as your cloud backend**, storing and routing two streams of data: - **Telemetry**: One summary event per hour per cooler, containing averages (temperature, compressor amps) and totals (runtime minutes, door-open events, apparent kWh, window duration). @@ -165,7 +165,7 @@ Pin-by-pin connections: 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/cooler_monitor/cooler_monitor.ino` as the `PRODUCT_UID` constant before flashing. 2. **Claim the Notecard.** Power the unit; on first cellular connection the Notecard associates with your project automatically. 3. **Create Fleets.** The natural grouping for a multi-site cooler program is one [Fleet](https://dev.blues.io/guides-and-tutorials/fleet-admin-guide/) per banner or region — every store in a given franchise territory typically shares the same setpoint targets and alert thresholds. [Smart Fleet](https://dev.blues.io/notehub/notehub-walkthrough/#using-smart-fleet-rules) rules let you break out exceptions automatically (e.g., flagship stores with tighter temperature tolerances) without manual device reassignment. -4. **Set environment variables.** All variables below are optional; firmware defaults apply until overridden. Any variable set in Notehub takes effect on the device's next inbound sync — no reflash required. **To set a variable in Notehub:** navigate to your project → Devices (or Fleet) → scroll down to Environment Variables → click "Edit" (JSON view) → add or update the variable and save. The firmware configures the Notecard's `inbound` sync interval to `2 × summary_interval_min` (so 120 minutes at the default `summary_interval_min = 60`), which is when the Notecard pulls fresh env-var values from Notehub into its on-device cache. The host then picks the new values up on its next 60-second wake. **Worst-case time from "save in Notehub" to "value applied on the device" is therefore roughly the inbound interval (up to 120 minutes by default) plus one sample cycle (~60 seconds).** To exercise the full path quickly during commissioning, lower `summary_interval_min` (which also halves the inbound interval) or trigger an immediate session via `hub.sync` from the [Blues In-Browser Terminal](https://dev.blues.io/terminal/). +4. **Set environment variables.** All variables below are optional; firmware defaults apply until overridden. Any variable set in Notehub takes effect on the device's next inbound sync — no reflash required. **To set a variable in Notehub:** navigate to your project → Devices (or Fleet) → scroll down to Settings/Environment Variables → add or update the variable and save. The firmware configures the Notecard's `inbound` sync interval to `2 × summary_interval_min` (so 120 minutes at the default `summary_interval_min = 60`), which is when the Notecard pulls fresh env-var values from Notehub into its on-device cache. The host then picks the new values up on its next 60-second wake. **Worst-case time from "save in Notehub" to "value applied on the device" is therefore roughly the inbound interval (up to 120 minutes by default) plus one sample cycle (~60 seconds).** To exercise the full path quickly during commissioning, lower `summary_interval_min` (which also halves the inbound interval) or trigger an immediate session via `hub.sync` from the [Blues In-Browser Terminal](https://dev.blues.io/terminal/). | Variable | Default | Purpose | |---|---|---| diff --git a/57-propane-lpg-tank-fill-telemetry/README.md b/57-propane-lpg-tank-fill-telemetry/README.md index d4c898d3..5fcd8b39 100644 --- a/57-propane-lpg-tank-fill-telemetry/README.md +++ b/57-propane-lpg-tank-fill-telemetry/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/) 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 cellular [Notecard](https://shop.blues.com/products/notecard?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) carries the data, and an optional [Starnote](https://shop.blues.com/products/starnote?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) satellite module extends the same architecture to rural sites with no cellular coverage. 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. 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. ## 1. Project Overview @@ -19,11 +19,11 @@ The root cause is infrastructure. A propane tank sits in a field, on a farm, at 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. -**Why Notecard.** 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. A dealer network spans all of these site types and can't afford a different hardware solution for each one. The Notecard Cell+WiFi variant handles the vast majority of installs on a single SKU: cellular removes the per-site IT dependency entirely, and the WiFi radio is available as an optional fallback when credentials are provisioned — useful for the rare tank near a residential AP. The Notecard ships with an active SIM including 500 MB of data and 10 years of service — no activation fees and no monthly per-SIM commitment. For the last 5 % of installs — remote mountain cabins, properties with no cellular coverage — a **Starnote for [Skylo](https://www.skylo.tech/)** connects to the Notecard via its 6-pin JST port and is mounted externally with a clear sky view, extending the same firmware and Notehub project to NTN satellite backhaul with no code changes; see [§4](#4-hardware-requirements), [§5](#5-wiring-and-assembly), [§6](#6-notehub-setup), and [§11](#11-limitations-and-next-steps) for the satellite deployment path. +**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. -**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. For installations where cellular coverage is absent, a Starnote for Skylo (Ignion Antennas variant) connects to the Notecard via the 6-pin JST cable and is mounted face-up on the enclosure exterior with an unobstructed sky view; it provides NTN satellite backhaul over the same Notehub project with 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. 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. @@ -34,11 +34,11 @@ This project solves all three. A weatherproof electronics enclosure mounted on a ## 2. System Architecture -![System architecture: propane tank with 4–20 mA float transmitter and DS18B20 → edge enclosure outside hazardous area → cellular MBGLW or Starnote satellite → Notehub → dispatch / ERP / time-series DB](diagrams/01-system-architecture.svg) +![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 idles at ~18 µ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 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 holds Notes in its on-device queue, opens a cellular (or opportunistic WiFi) session on the [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence, and pushes any `sync:true` alert through immediately. For the remote 5% of tanks beyond any tower, a Starnote for Skylo plugged into the 6-pin JST port adds NTN satellite transport — the Notecard chooses cellular or satellite automatically and the firmware never changes. The Starnote does have to live outside the enclosure 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 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. **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. @@ -94,26 +94,25 @@ 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 STM32 host — handles the 12-bit ADC for the 4-20 mA loop and OneWire for the temperature probe with no external MCU needed. | -| [Notecard Cell+WiFi (MBGLW)](https://shop.blues.com/products/notecard-cell-wifi?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) · [datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-mbglw/) | 1 | Cellular removes per-site IT involvement; optional WiFi fallback when credentials are provisioned. Single SKU deploys across the full dealer territory. | +| [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. The firmware's `card.transport` `wifi-cell-ntn` setting makes it prefer cellular at in-coverage tanks and fall back automatically to the Skylo satellite network at remote sites beyond cellular reach — no second device or part-number decision. Cellular removes the per-site IT dependency; the embedded global SIM and bundled satellite allocation cover the whole territory from one SKU. Requires the antennas below. | | [Blues Mojo](https://shop.blues.com/products/mojo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | **Bench only.** Coulomb counter on the 5 V supply rail for validating power behavior during commissioning (see §9). Remove and discard for field deployment; not integrated into production units. | | Rochester Sensors M6300-LP Magnetel® Rough Rider® LP gas gauge + R6315-12 4-20 mA transmitter — [M6300-LP datasheet](https://rochestergauges.com/wp-content/uploads/M6300-LP.pdf) · [R6315-12 datasheet](https://rochestersensors.com/wp-content/uploads/R6315-12-July-8.pdf) · [6300 series installation guide](https://rochestersensors.com/wp-content/uploads/6300_Magnetel_Gauge.pdf). Available from [John M. Ellsworth Co.](https://www.jmesales.com/rochester-gauge-magnetel-4-20-ma-liquid-level-transmitter/) and LP gas equipment distributors. | 1 | Float-type magnetel level transmitter designed specifically for LP gas service. A float rides the liquid propane surface inside the tank and drives a two-wire 4-20 mA current loop proportional to fill level: 4 mA at 0 % fill, 20 mA at 100 % fill. **Representative orderable assembly:** M6300-LP gauge body (1¼″ NPT, 4″ dial) with R6315-12 transmitter module attached — the R6315-12 clips to the M6300 gauge body and provides the 4-20 mA output. The R6315-12 outputs 4-20 mA proportional to the float position; see the R6315-12 datasheet for electrical specifications and wiring. **Mounting:** the M6300-LP installs at the tank's existing 1¼″ NPT dip-tube gauge port (the standard gauge opening on most horizontal residential and commercial LP tanks). Dip-tube length and float arm length vary by tank geometry — confirm the correct M6300-LP model suffix against the Rochester Sensors product application table and the tank's nameplate before ordering. Some larger commercial tanks use a 2″ NPT gauge boss; Rochester Sensors offers corresponding variants. **Electrical:** two-wire loop-powered, 12–28 V DC supply. **Note:** because the float tracks the liquid surface directly, no density or temperature correction is applied in firmware — the 4-20 mA output is already proportional to fill level regardless of liquid temperature or density. Installation at a propane pressure vessel must be performed by a licensed LP gas technician per NFPA 58. | | [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 NOTE-MBGLW modem can 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: 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. | | 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. | -| External magnetic-mount cellular antenna, SMA connector, ≥3 m cable (e.g. [SparkFun CEL-16432](https://www.sparkfun.com/lte-hinged-external-antenna-698mhz-2-7ghz-sma-male.html)) | 1 | Route outside the enclosure. **Magnetic-mount bases require a ferrous surface** — they will not adhere to a polycarbonate enclosure lid. Mount on a nearby steel bracket or strike plate; alternatively, select an adhesive-mount or weatherproof bulkhead-style outdoor antenna when no ferrous surface is available at the mounting location. Do not rely on a stub antenna inside a polycarbonate enclosure at tank-side — signal margin is too variable. One antenna is required for the NOTE-MBGLW's **MAIN** u.FL cellular port. The NOTE-MBGLW (LTE Cat-1 bis) does not expose a cellular diversity (DIV) port — do not attempt to add a second cellular antenna. | -| u.FL-to-SMA pigtail, ~15–20 cm (e.g. Taoglas WCA.15 or equivalent) | 1 | **Required.** The Notecard's cellular connection is u.FL; this pigtail adapts the MAIN u.FL port to an external SMA magnetic-mount antenna cable. Route the pigtail from the Notecard MAIN u.FL through the enclosure wall via a cable gland or SMA bulkhead connector, then connect to the external antenna cable outside. | -| u.FL WiFi antenna stub or short u.FL-to-SMA pigtail | 0–1 | **Optional.** Required only if WiFi credentials will be provisioned and WiFi fallback is expected at this installation. Connect to the NOTE-MBGLW's **WIFI** u.FL port. A short internal u.FL stub whip is sufficient inside a polycarbonate enclosure. If the enclosure is metal, route an external pigtail through a cable gland instead. Not required for cellular-only operation. | -| IP68-rated PG-11 nylon cable gland, 5–10 mm cable OD (e.g. Lapp SKINTOP® MS-M PG 11 or equivalent) | 3–5 | One gland per field cable entering the enclosure. This installation requires penetrations for: **(1)** primary cellular antenna pigtail or SMA bulkhead; **(2)** DS18B20 temperature probe cable; **(3)** 4–20 mA transmitter loop wiring (two conductors from transmitter to enclosure); **(4)** optional WiFi antenna pigtail if the enclosure is metal and an external lead is needed; and **(5)** optional Starnote for Skylo JST connector cable (satellite deployments only, route the JST cable from the Notecard through Gland 5 to the externally-mounted Starnote). 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. | +| 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. | +| 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. | | 12 V sealed lead-acid battery, 7–10 Ah (e.g. Universal Power Group UB1280, 8 Ah) | 1 | Energy reservoir for cloudy periods and overnight. At this device's duty cycle, 8 Ah provides ≥3 days of autonomy without solar input (see [Limitations](#11-limitations-and-next-steps) for power budget). | | Inline fuse holder + 5 A automotive blade fuse (e.g. Bussmann BP/HHM + ATC5) | 1 | Placed in the battery (+) lead as close to the battery positive terminal as possible. Protects wiring from a short-circuit fault in the load circuit. The 5 A rating provides adequate protection for the ≤2 A maximum load while giving headroom above the controller's worst-case startup surge. Use a weatherproof fuse holder if the battery is outside the NEMA 4X enclosure. | -| **[Starnote for Skylo (Ignion Antennas)](https://shop.blues.com/products/starnote?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link)** (optional, satellite deployments only) | 0–1 | NTN satellite module for sites with no cellular coverage. **Choose the Ignion Antennas variant**: it includes onboard S-Band and L-Band antennas that are certified on Skylo's network — no external satellite antenna is required or permitted (the certification covers the onboard antennas only). **Connection:** the Starnote does not use the Notecarrier CX's M.2 slot. It connects to the Notecard Cell+WiFi via the Notecard's 6-pin JST port using the supplied connector cable; route the cable through a dedicated cable gland (Gland 5. See §5). When a Starnote is present and connected, the Notecard automatically routes queued Notes over NTN satellite when cellular is unavailable; no firmware changes are required. **Mounting:** the Starnote **must be mounted outside the enclosure, face-up, with an unobstructed view of the sky** — it cannot receive satellite signals from inside a closed enclosure or beneath a metal obstruction. The daily summary Note (~40 bytes) fits within typical NTN payload budgets. Follow the [Starnote Quickstart](https://dev.blues.io/quickstart/starnote-quickstart/) and [Satellite Best Practices guide](https://dev.blues.io/starnote/satellite-best-practices/) for provisioning and duty-cycle guidance before deploying. | | [Victron SmartSolar MPPT 75/10](https://www.victronenergy.com/solar-charge-controllers/smartsolar-mppt-75-10) solar charge controller | 1 | Regulates solar panel output to charge the 12 V SLA battery safely. The SmartSolar MPPT 75/10 exposes dedicated **LOAD+ / LOAD−** output terminals with built-in low-voltage disconnect (LVD) that automatically cuts load power to protect the SLA from deep discharge — this specific feature is required for the wiring in §5. If a different controller is substituted, confirm it has equivalent LOAD terminals with LVD before following the §5 wiring steps. | | Monocrystalline solar panel, 10–20 W, 12 V nominal (e.g. Renogy 10W Monocrystalline RNG-10D-SS) | 1 | 10 W is adequate for mid-latitude sites (≥4 h/day usable sun). Size up to 20 W for northern latitudes, winter deployments, or sites with frequent cloud cover. Mount with a clear sky view, not against the tank body. | | NEMA 4X polycarbonate enclosure, ~8 × 6 × 3.5″ | 1 | Weatherproof housing rated for outdoor tank-side mounting. Polycarbonate is UV-resistant and non-sparking. | -Blues hardware ships with an active SIM including 500 MB of data and 10 years of service — no activation fees and no monthly SIM commitment. +**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 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). Minimizing inbound sync frequency conserves the bundled satellite allocation. @@ -128,7 +127,7 @@ Blues hardware ships with an active SIM including 500 MB of data and 10 years of ![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 Cell+WiFi 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. 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. @@ -140,11 +139,10 @@ All Notecarrier CX host I/O lands on its dual 16-pin header. The Notecard Cell+W | Gland | Cable / penetration | |---|---| -| 1 | Primary cellular antenna: u.FL-to-SMA pigtail or SMA bulkhead lead (MAIN port) | -| 2 | DS18B20 temperature probe cable | -| 3 | 4–20 mA transmitter loop wiring (2-conductor, from transmitter to enclosure) | -| 4 | WiFi antenna pigtail (only if routing externally through a metal enclosure) | -| 5 | Starnote JST connector cable (satellite deployments only) | +| 1 | Skylo-certified MAIN antenna lead (or its SMA bulkhead) — carries cellular and satellite | +| 2 | GPS/GNSS antenna lead (GPS u.FL port) | +| 3 | DS18B20 temperature probe cable | +| 4 | 4–20 mA transmitter loop wiring (2-conductor, from transmitter to enclosure) | Match each gland's cable-OD clamp range to the actual cable outer diameter. Tighten all glands to the manufacturer's torque spec after routing cables; leave no unused penetration open. @@ -184,20 +182,18 @@ 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 Cell+WiFi (MBGLW) into the Notecarrier CX M.2 slot and secure the retaining screw. +Seat the Notecard for Skylo (NOTE-NBGLWX) into the Notecarrier CX M.2 slot and secure the retaining screw. -The NOTE-MBGLW (LTE Cat-1 bis) exposes two antenna-relevant u.FL ports — **MAIN** (cellular) and **WIFI**. It does **not** have a cellular diversity (DIV) port; do not install a second cellular antenna. +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: -Connect antennas as follows: - -- **MAIN port (cellular)** — attach a u.FL-to-SMA pigtail, route through Gland 1 (or an SMA panel-mount bulkhead), connect the external antenna cable outside the enclosure. **Magnetic-mount bases will not adhere to polycarbonate** — position the magnetic base on a nearby steel bracket or strike plate with a clear sky view. If no ferrous surface is available, use an adhesive-mount or weatherproof bulkhead-style outdoor antenna instead. *Do not skip this connection — cellular operation requires an external antenna.* -- **WIFI port** — required only if WiFi credentials will be provisioned at this installation. Inside a polycarbonate enclosure a short u.FL stub whip is sufficient; inside a metal enclosure route a pigtail externally through Gland 4. Omit entirely for cellular-only installations. +- **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. Select antenna cable lengths to suit the routing distance before ordering — most pre-terminated assemblies should not be cut or field-terminated. Secure any excess cable outside the enclosure with a gentle loop; do not coil cable inside the enclosure. **Step 7 — 4–20 mA current loop (gauge-port level transmitter).** -The Rochester Sensors M6300-LP + R6315-12 is a two-wire loop-powered instrument. A single 2-conductor cable runs from the transmitter (at the tank gauge port, outside or at the hazardous boundary) to the electronics enclosure. Route this cable through Gland 3. Wire the loop from the **dedicated 24 V boost converter output** — not the 12 V system rail and not the 5 V Notecarrier rail (see compliance Note below): +The Rochester Sensors M6300-LP + R6315-12 is a two-wire loop-powered instrument. A single 2-conductor cable runs from the transmitter (at the tank gauge port, outside or at the hazardous boundary) to the electronics enclosure. Route this cable through Gland 4. Wire the loop from the **dedicated 24 V boost converter output** — not the 12 V system rail and not the 5 V Notecarrier rail (see compliance Note below): - **24 V boost converter Vin+** → charge controller **LOAD+** (same 12 V rail that feeds the 5 V step-down). **24 V boost converter GND** → **system GND**. - **24 V boost converter Vout+** (regulated 24 V) → transmitter **+ terminal** (loop supply in). @@ -225,22 +221,16 @@ Confirm that system GND (battery −), charge controller LOAD−, step-down Vin **Step 8 — DS18B20 temperature probe.** -Route the DS18B20 cable through Gland 2. Mount the probe body against the tank shell — ideally under a layer of closed-cell foam tape to improve thermal contact and reduce ambient-air influence — and secure the cable with a zip tie to prevent mechanical strain at the gland. Inside the enclosure: +Route the DS18B20 cable through Gland 3. Mount the probe body against the tank shell — ideally under a layer of closed-cell foam tape to improve thermal contact and reduce ambient-air influence — and secure the cable with a zip tie to prevent mechanical strain at the gland. Inside the enclosure: - **DS18B20 red wire (VCC)** → **+3V3** on the Notecarrier CX header. - **DS18B20 black wire (GND)** → **GND** on the Notecarrier CX header. - **DS18B20 yellow wire (data)** → **D2** on the Notecarrier CX header. - **4.7 kΩ pull-up resistor** between the data wire and **+3V3**. The Notecarrier CX does not include an onboard OneWire pull-up; this resistor is required. -**Step 9 (optional) — Starnote for Skylo satellite module.** - -Required only at sites with no cellular coverage. If adding a Starnote: +**Step 9 — Satellite operation (automatic, no added hardware).** -- Install Gland 5 and route the Starnote's 6-pin JST connector cable from inside the enclosure to outside through Gland 5. -- Inside the enclosure, connect the JST cable to the matching 6-pin JST port on the Notecard Cell+WiFi (MBGLW). The Starnote receives power from the Notecard over this connection — no additional power wiring is required. -- **Mount the Starnote (Ignion Antennas) face-up on the exterior of the enclosure** (enclosure lid or an exterior wall), or on a small external bracket, with an unobstructed view of the sky. The onboard Ignion antennas cover both S-Band and L-Band — no external satellite antenna cable is needed or allowed. Use the Starnote's two mounting holes and UV-resistant hardware; the module is weather-rated for outdoor mounting. -- Secure the JST cable inside the enclosure with a zip tie to prevent mechanical strain at Gland 5. Tighten Gland 5 to the manufacturer's torque spec. -- Provision satellite service through Notehub per the [Starnote Quickstart](https://dev.blues.io/quickstart/starnote-quickstart/). After provisioning, the Notecard automatically falls back to NTN satellite for any queued Notes it cannot deliver over cellular — no firmware changes are required. +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. **Final pre-power checklist.** @@ -248,10 +238,9 @@ Required only at sites with no cellular coverage. If adding a Starnote: - All GND nodes common: battery −, charge controller LOAD−, step-down Vin−, step-down Vout−, boost converter GND, Notecarrier GND. - Step-down output confirmed at 5.0 V before connecting Notecarrier. - Boost converter Vin+ wired to 12 V system rail (LOAD+); boost converter Vout+ confirmed at 24 V before connecting transmitter loop wiring. -- Notecard MAIN u.FL port connected to an external antenna routed outside the enclosure; no second cellular antenna connected (NOTE-MBGLW has no DIV port). +- Skylo-certified MAIN antenna connected and routed outdoors with a clear sky view (carries both cellular and satellite); GPS/GNSS antenna connected to the GPS port and routed outdoors. - 120 Ω shunt installed in the current loop with A0 tapped at the transmitter − / shunt junction; loop supply drawn from 24 V boost converter output (not the 12 V rail). - Inline fuse installed in battery (+) lead, as close to the battery positive terminal as possible. -- (Satellite deployments only) Starnote JST cable connected to Notecard, Starnote mounted face-up outside the enclosure with a clear sky view, Gland 5 sealed. ## 6. Notehub Setup @@ -260,7 +249,7 @@ Required only at sites with no cellular coverage. If adding a Starnote: 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 Cell+WiFi supports WiFi as an optional secondary transport — the device operates normally on cellular alone if no WiFi credentials are set. Two reliable provisioning paths are available for this hardware stack: +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: - **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. @@ -286,7 +275,7 @@ Required only at sites with no cellular coverage. If adding a Starnote: | `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).** At sites with no cellular coverage, add a Starnote for Skylo (Ignion Antennas) to the hardware, connect it to the Notecard via the 6-pin JST cable, and mount it outside the enclosure with a clear sky view (see §4 BOM and §5 Step 9 for wiring details). Follow the [Starnote Quickstart](https://dev.blues.io/quickstart/starnote-quickstart/) to provision satellite service through Notehub. All events from this device travel through the same Notehub project regardless of transport — no firmware changes or separate project are needed. The daily summary Note (~40 bytes per record) fits within typical NTN satellite payload budgets; 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 — 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. 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. @@ -305,7 +294,7 @@ Dependencies: | Responsibility | Where | |---|---| -| Notecard configuration (`hub.set`, templates) | `hubConfigure`, `defineTemplates` | +| Notecard configuration (`hub.set`, `card.transport` `wifi-cell-ntn` for cellular→satellite fallback, templates) | `hubConfigure`, `defineTemplates` | | Environment-variable fetch per wake | `fetchEnvOverrides` | | 4-20 mA loop read → mA current | `readTransmitterMA` | | DS18B20 OneWire temperature read | `readTemperatureC` | @@ -393,17 +382,17 @@ Two [template-backed](https://dev.blues.io/notecard/notecard-walkthrough/low-ban } ``` -Two alert types are defined: `low_fill` (fill percentage dropped below `fill_alert_pct`) and `high_consumption` (smoothed daily consumption rate has exceeded `consumption_alert_gal_per_day` for `consumption_alert_streak` consecutive sample cycles, default 3, to debounce transient spikes from ADC jitter or post-refill noise). A third synthetic type, `sensor_fault`, fires when the transmitter current is outside the valid 4-20 mA window — open-circuit or short on the current loop. All three use the same `tank_alert.qo` Notefile with `sync:true` so they bypass the daily outbound window and arrive at the dealer's dispatch system within the Notecard's session-establishment window (typically well under 60 seconds in good cellular coverage; see the [NOTE-MBGLW datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-mbglw/) for authoritative timing figures). +Two alert types are defined: `low_fill` (fill percentage dropped below `fill_alert_pct`) and `high_consumption` (smoothed daily consumption rate has exceeded `consumption_alert_gal_per_day` for `consumption_alert_streak` consecutive sample cycles, default 3, to debounce transient spikes from ADC jitter or post-refill noise). A third synthetic type, `sensor_fault`, fires when the transmitter current is outside the valid 4-20 mA window — open-circuit or short on the current loop. All three use the same `tank_alert.qo` Notefile with `sync:true` so they bypass the daily outbound window and arrive at the dealer's dispatch system within the Notecard's session-establishment window (typically well under 60 seconds in good cellular coverage, and minutes when the unit is operating over the Skylo satellite link; see the [NOTE-NBGLWX datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) for authoritative figures). -**Satellite alert latency.** On NTN satellite sites (Starnote for Skylo), `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 to hours**, not seconds. The session energy profile is also materially different from LTE Cat-1 bis; the Mojo current figures in §9 do not apply to satellite sessions. Validate alert timing and solar/battery sizing separately for satellite deployments using the [Satellite Best Practices guide](https://dev.blues.io/starnote/satellite-best-practices/) before commissioning. +**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. ### 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 itself idles at ~18 µA between cellular wakes (NOTE-MBGLW Cell+WiFi published idle figure; cellular-only Notecard SKUs idle at ~8 µA, use the correct figure for this SKU). 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. 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. 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. @@ -529,15 +518,15 @@ Every `sample_interval_min` (default 15 min) the Cygnet wakes, reads the LP gaug | Firmware state | Expected current (5 V rail, Mojo) | Source | |---|---|---| -| Deep sleep (host cut via `card.attn`, Notecard idle, radio off) | ~18 µA @ 5 V | Blues-published figure for NOTE-MBGLW (Notecard Cell+WiFi variant); 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/). Note: the Cell+WiFi variant idles at ~18 µA @ 5 V; the cellular-only Notecards idle at ~8 µA @ 5 V — use the correct figure for this SKU. 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. | +| 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 cellular session — LTE Cat-1 bis, NOTE-MBGLW, small queued Note, good signal (3 bars, RSRP −90 dBm) | ~0.42 mAh per sync session; in-session average ~25–50 mA; peak modem supply demand up to 750 mA sustained / 2 A brief bursts | Per-session energy derived from the Blues [low-power design guide](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design/) 12-hour / 30-minute periodic-sync test: NOTE-MBGLW row = **10.12 mAh ÷ 24 sessions ≈ 0.42 mAh per session** at 3-bar signal. Session duration is typically 30–60 s; dividing 0.42 mAh by 30–60 s implies an in-session average of ~25–50 mA across the full session including modem ramp-up and teardown — expect a broad hump on the Mojo trace, not a sharp spike. Peak modem supply requirement: **750 mA sustained / 2 A brief bursts** per the [Blues low-power hardware design application Note](https://dev.blues.io/datasheets/application-notes/low-power-hardware-design/); the SLA battery and Pololu D24V22F5 step-down (2.5 A rated) in this design comfortably source ≥ 2 A. Weaker signal or first-time network registration will increase session energy above 0.42 mAh; the Blues low-power design guide 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 | 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. | -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 ~25–50 mA for the cellular sync. Between sample spikes the trace should sit flat at the ~18 µ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** — ~18 µA Notecard floor × 24 h ≈ **~0.5 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** — **~0.42 mAh**. The expected daily total is therefore roughly **5–8 mAh/day**. If the Mojo 24-hour total runs materially above this range, the cellular session may be staying open longer than expected or the Notecard may be in `continuous` mode rather than `periodic`; confirm with `hub.status`. +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`. -**Satellite deployments (Starnote for Skylo).** The current figures and alert-latency estimates above apply only to cellular (LTE Cat-1 bis) sessions. At NTN satellite sites, the Starnote adds a continuous idle draw on top of the Notecard's ~18 µA, satellite sessions have a different transmit-current envelope than LTE, and Skylo's duty-cycle rules constrain the number of sessions per day. `sync:true` alert delivery depends on a satellite pass being available — latency is minutes to hours, not seconds. **Validate solar panel sizing, battery capacity, and alert latency separately for every satellite deployment** 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 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. ## 10. Troubleshooting @@ -569,12 +558,12 @@ Note: the 4-20 mA transmitter loop is powered from the 24 V boost converter circ **Battery drains quickly / device stops after a few hours.** - Confirm the host is actually entering deep sleep. The firmware calls `NotePayloadSaveAndSleep` after each sample cycle; if this fails, the host will run continuously and drain the battery in hours. Check that `card.attn` is properly wired (see §5 Step 5) and that the ATTN signal is reaching the Cygnet host. - If using the Mojo for validation, confirm it is removed before field deployment. The Mojo adds a continuous measurement load even during deep sleep. -- For satellite deployments (Starnote), review the [Satellite Best Practices guide](https://dev.blues.io/starnote/satellite-best-practices/) — satellite sessions draw more power than cellular sessions and may require a larger battery or solar panel. +- For sites operating over the Skylo satellite (NTN) link, review the [Satellite Best Practices guide](https://dev.blues.io/starnote/satellite-best-practices/) — satellite session timing and duty-cycle behavior differ from cellular and may shift the energy budget; size the battery and solar panel against the expected satellite session pattern. **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. -- If the Notecard has a WiFi stub antenna inside the enclosure, it may not have sufficient signal. If the enclosure is metal, route the WiFi pigtail externally through Gland 4. +- 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. ## 11. Limitations and Next Steps @@ -586,7 +575,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. -- **Starnote requires an unobstructed outdoor mount.** The Starnote for Skylo (satellite deployments only) must be mounted outside the NEMA 4X enclosure, face-up, with a clear sky view — it cannot communicate through the enclosure or beneath a metal obstruction. At remote tank sites, confirm a suitable mounting location on the enclosure exterior or a nearby bracket before specifying the Starnote deployment 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. @@ -605,4 +594,4 @@ This reference design covers the common case of a dealer instrumenting a tank fl ## 12. Summary -The dealer who used to roll a truck every six weeks because that's what the calendar said now rolls a truck because a specific tank is at 22% and trending toward empty in nine days. A float transmitter at the gauge port, a temperature probe on the shell, a cellular Notecard (with a Starnote for the last remote 5%), and a daily summary in Notehub turn every tank in the territory into a self-reporting asset — fewer miles, fewer emergency calls, and no more Friday-night apologies to the customer whose heat just went out. +The dealer who used to roll a truck every six weeks because that's what the calendar said now rolls a truck because a specific tank is at 22% and trending toward empty in nine days. A float transmitter at the gauge port, a temperature probe on the shell, a single Notecard for Skylo that carries cellular, WiFi, and satellite on one module — reaching cellular near town and the Skylo satellite network at the remote cabin with nothing to swap — and a daily summary in Notehub turn every tank in the territory into a self-reporting asset — fewer miles, fewer emergency calls, and no more Friday-night apologies to the customer whose heat just went out. diff --git a/57-propane-lpg-tank-fill-telemetry/diagrams/01-system-architecture.svg b/57-propane-lpg-tank-fill-telemetry/diagrams/01-system-architecture.svg index 7d0a5095..70378d1d 100644 --- a/57-propane-lpg-tank-fill-telemetry/diagrams/01-system-architecture.svg +++ b/57-propane-lpg-tank-fill-telemetry/diagrams/01-system-architecture.svg @@ -11,7 +11,7 @@ System Architecture - Propane / LPG Tank Fill Telemetry — cellular or satellite + Propane / LPG Tank Fill Telemetry — cellular + satellite on one module @@ -40,8 +40,8 @@ Connectivity - A · MBGLW (cellular) - B · Starnote (satellite) + Notecard for Skylo + cellular · WiFi · satellite diff --git a/57-propane-lpg-tank-fill-telemetry/diagrams/02-wiring-assembly.svg b/57-propane-lpg-tank-fill-telemetry/diagrams/02-wiring-assembly.svg index 6ec27771..969ba89d 100644 --- a/57-propane-lpg-tank-fill-telemetry/diagrams/02-wiring-assembly.svg +++ b/57-propane-lpg-tank-fill-telemetry/diagrams/02-wiring-assembly.svg @@ -25,7 +25,7 @@ Notecarrier CX - + Cygnet · MBGLW + + Cygnet · Notecard for Skylo A0 diff --git a/57-propane-lpg-tank-fill-telemetry/firmware/propane_tank_telemetry/propane_tank_telemetry.ino b/57-propane-lpg-tank-fill-telemetry/firmware/propane_tank_telemetry/propane_tank_telemetry.ino index fe9699be..d6e7d318 100644 --- a/57-propane-lpg-tank-fill-telemetry/firmware/propane_tank_telemetry/propane_tank_telemetry.ino +++ b/57-propane-lpg-tank-fill-telemetry/firmware/propane_tank_telemetry/propane_tank_telemetry.ino @@ -3,11 +3,12 @@ // Propane / LPG Tank Fill Telemetry — 4–20 mA Float-Transmitter Variant // // Host: Blues Notecarrier CX (onboard Cygnet STM32 host) -// Notecard: Blues Notecard Cell+WiFi (MBGLW); at sites with no cellular -// coverage, add a Starnote for Skylo connected to the Notecard's -// 6-pin JST port for automatic NTN satellite fallback — no firmware -// changes required; the Notecard routes queued notes over satellite -// when cellular is unavailable +// Notecard: Notecard for Skylo (NOTE-NBGLWX) — a single M.2 module carrying +// cellular (LTE-M / NB-IoT / GPRS), WiFi, and Skylo satellite (NTN) +// radios with automatic failover. At sites with no cellular coverage +// the same board falls back to Skylo satellite automatically — no +// second device and no firmware changes; the Notecard routes queued +// notes over satellite when cellular and WiFi are unavailable // Sensors: 4-20 mA LP gauge-port level transmitter (float type, e.g. Rochester // Sensors M6300-LP + R6315-12) → 120 Ω shunt → A0 // DS18B20 waterproof temperature probe (OneWire) → D2 @@ -51,8 +52,8 @@ // - Each wake: sample sensors, update consumption EWMA, evaluate thresholds. // - When REPORT_INTERVAL_HR has elapsed, queue one tank_status.qo note. // - Alerts (low_fill, high_consumption, sensor_fault) are sent sync:true. -// - Between wakes the host is cut entirely; Notecard idles at ~18 µA -// (NOTE-MBGLW Notecard Cell+WiFi published idle figure). +// - Between wakes the host is cut entirely; the Notecard for Skylo idles +// at ~8 µA (NOTE-NBGLWX published idle figure). // // Sensor math, fill-level calculation, and consumption tracking live in // propane_tank_telemetry_helpers.h (included below). @@ -172,6 +173,29 @@ static void hubConfigure() { } else { #ifdef usbSerial usbSerial.println("[hub.set] failed — will retry on next wake"); +#endif + } + + // Transport selection for the Notecard for Skylo (NOTE-NBGLWX). + // The board carries WiFi, cellular, and Skylo satellite (NTN) radios, but + // satellite fallback is NOT enabled by default — the factory transport does + // not include NTN. Set "wifi-cell-ntn" so the Notecard prefers WiFi where an + // AP is reachable, falls back to cellular (the de-facto primary at most tank + // sites), and finally to Skylo satellite at remote sites beyond terrestrial + // coverage — automatic cellular→satellite failover with no firmware + // branching. The Notecard persists this setting in its own flash, so issuing + // it once on cold boot is sufficient. + // + // Note: Skylo requires at least one initial non-NTN (cellular or WiFi) sync + // to associate with Notehub and register Notefile templates before NTN can be + // used. In "periodic" mode the cold-boot hub.set above triggers that first + // sync over cellular/WiFi, so commission each unit where it has terrestrial + // coverage even if it will routinely operate over satellite. + J *t = notecard.newRequest("card.transport"); + JAddStringToObject(t, "method", "wifi-cell-ntn"); + if (!notecard.sendRequestWithRetry(t, 10)) { +#ifdef usbSerial + usbSerial.println("[card.transport] wifi-cell-ntn failed — will retry on next cold boot"); #endif } } diff --git a/60-lone-worker-panic-fall-detection-beacon/README.md b/60-lone-worker-panic-fall-detection-beacon/README.md index 45bffd9a..d5db5b32 100644 --- a/60-lone-worker-panic-fall-detection-beacon/README.md +++ b/60-lone-worker-panic-fall-detection-beacon/README.md @@ -8,7 +8,7 @@ This reference application is intended to provide inspiration and help you get s -This project is a wearable [safety assurance](https://blues.com/safety-assurance/) device for utility linemen, oilfield pumpers, field service technicians, and solo contractors. A Blues [Notecard Cell+WiFi](https://shop.blues.com/products/notecard-cellular?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) paired with a [Starnote for Skylo](https://shop.blues.com/products/starnote?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) satellite module turns a belt-clip enclosure into a cellular-first, satellite-backed distress beacon — detecting falls and accepting an explicit panic-button press — that can reach a dispatcher from the middle of nowhere, exactly where lone-worker incidents happen. +This project is a wearable [safety assurance](https://blues.com/safety-assurance/) device for utility linemen, oilfield pumpers, field service technicians, and solo contractors. 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 M.2 module that carries cellular, WiFi, and Skylo satellite radios and fails over between them automatically — turns a belt-clip enclosure into a cellular-first, satellite-backed distress beacon — detecting falls and accepting an explicit panic-button press — that can reach a dispatcher from the middle of nowhere, exactly where lone-worker incidents happen. ## 1. Project Overview @@ -28,21 +28,21 @@ This project is that device — a wearable safety beacon built on two core detec -That's the reason Starnote for [Skylo](https://www.skylo.tech/) is included in this design, not as a nice-to-have, but as the architectural foundation. The Notecard's cellular path covers the vast majority of activations — LTE Cat-1 bis is broadly deployed, even in surprisingly rural areas. But when cellular genuinely fails, the Starnote satellite link is there. Skylo covers supported regions (see the [Starnote datasheet](https://dev.blues.io/datasheets/starnote-datasheet/) 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 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. -The WiFi path in the Notecard Cell+WiFi variant is an opportunistic bonus: a field tech standing near a facility WiFi AP may sync an alert without any cellular usage at all. WiFi is only active when network credentials have been provisioned on the Notecard and a compatible AP is within range. +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. **Deployment scenario.** The beacon ships as a self-contained unit in a rugged belt-clip enclosure, powered by a 3.7V LiPo battery. Workers clip it onto their belt or hard-hat band like a pager. Worker IDs are pre-provisioned per device in Notehub before deployment; changes to `worker_id` propagate to the device on the next inbound sync, which defaults to every 2 hours, not immediately at shift start. Falls and panics generate immediate alerts. No app, no phone pairing, no worker attention required — just clip it on and go. ## 2. System Architecture -![System architecture: wearable I/O (LIS3DH accel, panic button, haptic motor) → Notecarrier CX with Cygnet host, Notecard MBGLW, and Starnote → cellular or Skylo satellite → Notehub → dispatch / paging / compliance](diagrams/01-system-architecture.svg) +![System architecture: wearable I/O (LIS3DH accel, panic button, haptic motor) → Notecarrier CX with Cygnet host and Notecard for Skylo (cellular / WiFi / satellite) → cellular or Skylo satellite → Notehub → dispatch / paging / compliance](diagrams/01-system-architecture.svg) **Device-side responsibilities.** The whole point of this device is that it must never miss the moment something goes wrong, so the Cygnet STM32L433 host on the Notecarrier CX never sleeps. It runs a dual-cadence loop instead: a fast inner loop reads the LIS3DH every 10 milliseconds (matching the sensor's 100 Hz ODR) while an outer ~10 Hz cadence handles Notecard I/O, GPS polling, the panic-button debounce, and the DRV2605L haptic feedback. The instant the two-stage algorithm confirms a fall — or the worker holds the button — the host queues the alert Note with the Notecard's cached location, triggers an immediate sync, and starts a non-blocking GPS search that runs in the background without ever pausing fall detection. If a fresh fix arrives within the window, a follow-up `beacon_location.qo` Note carries the event-time coordinates. All Notecard communication stays on I²C — no AT commands, no serial framing, no session management for the firmware to babysit. **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 quietly hands off to the attached Starnote for Skylo 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, 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. **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. @@ -121,9 +121,9 @@ 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 an embedded Cygnet STM32L433 host — no separate MCU needed. I²C, SPI, analog, and GPIO headers support the full sensor stack. | -| [Notecard Cell+WiFi (MBGLW)](https://shop.blues.com/products/notecard-cell-wifi?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) ([datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-mbglw/)) | 1 | Cellular-primary transport with integrated GPS/GNSS and WiFi fallback. Seats in the Notecarrier CX's M.2 slot. | -| [Starnote for Skylo — Antenna variant](https://shop.blues.com/products/starnote?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Satellite failover module. Select **Starnote for Skylo (Antenna)** when ordering — this variant has onboard Ignion antennas for both satellite (NTN) and GNSS; no external antenna is required for the Starnote itself. **GNSS role:** the Starnote's onboard GNSS antenna is used internally by the Starnote module for Skylo satellite link timing and synchronization — it is not the device's position source. The Notecard's own GPS module (fed by the GPS tail of the dual flexible antenna below) provides the location data embedded in alert Notes. Connects to the Notecard via the onboard 6-pin JST-SH cable. The module itself must be mounted with a clear, unobstructed sky view (polycarbonate enclosure top face is fine). Within Skylo's supported coverage regions, provides a satellite uplink path when cellular is unavailable. Includes bundled satellite data; see the [Starnote datasheet](https://dev.blues.io/datasheets/starnote-datasheet/) for coverage footprint and data details. | -| [Blues Flexible Dual LTE/Wi-Fi and GPS/GNSS Antenna](https://shop.blues.com/collections/accessories/products/dual-flexible-antenna-cell-wi-fi?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Quectel YCA001BA dual-element flexible adhesive antenna. One tail connects to the Notecard MBGLW `CELL` u.FL port (LTE 700–960 MHz / 1710–2690 MHz); the other connects to the Notecard MBGLW `GPS` u.FL port (1580–1620 MHz). Covers both Notecard RF ports in a single $3.25 purchase. Polycarbonate enclosures are RF-transparent — adhere both elements to the interior enclosure wall; no external cable routing or bulkhead required. Position the GNSS element on the top face for best sky view during GPS acquisition events. This GPS tail is the device's primary location source — `card.location` draws from the Notecard's own GPS module via this connection, not from the Starnote's onboard GNSS. | +| [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. | +| 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. | | [Adafruit DRV2605L Haptic Motor Controller (#2305)](https://www.adafruit.com/product/2305) | 1 | I²C haptic driver with 123 built-in waveform effects. Drives the ERM motor directly; no transistor or PWM circuit needed. Supports both ERM and LRA motors. | @@ -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 LTE Cat-1 bis, GNSS, and satellite signals. Requires cutouts for the panic button and the LiPo JST connector for battery access; the flexible dual antenna adheres 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; 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. | -All Blues hardware ships with an active SIM including 500 MB of cellular data and 10 years of service — no activation fees, no monthly commitment. +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). @@ -149,9 +149,9 @@ All Blues hardware ships with an active SIM including 500 MB of cellular data an ## 5. Wiring and Assembly -![Wiring: LIS3DH + DRV2605L on shared I²C; panic button to D9 INPUT_PULLUP; dual flex antenna on Notecard CELL + GPS u.FL; Starnote satellite via JST; LiPo 3.7 V → Mojo → +VBAT](diagrams/02-wiring-assembly.svg) +![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, Starnote, 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 Cell+WiFi seats into the M.2 slot and talks to the Cygnet host over the carrier's internal I²C. The Starnote connects to the Notecard with a single 6-pin JST-SH cable — no Notecarrier CX modification — and 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; 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. 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). -- **Starnote JST cable** → Notecard JST port (the 6-pin cable carries UART + power between Notecard and Starnote). The Starnote (Antenna) variant has onboard Ignion antennas — no external antenna cable to route. +- **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. -**Antenna placement and connector mapping.** The Blues Flexible Dual LTE/Wi-Fi and GPS/GNSS Antenna has two labeled tails: connect the LTE tail to the Notecard MBGLW `CELL` u.FL port and the GPS tail to the Notecard MBGLW `GPS` u.FL port. Peel and adhere both elements to the interior wall of the polycarbonate enclosure — polycarbonate is RF-transparent, so no external pigtail routing or bulkhead is needed. Position the GPS element on the top (sky-facing) wall for best acquisition geometry during GPS-on events. The **Starnote for Skylo (Antenna)** variant has onboard Ignion antennas; no external satellite antenna is connected or required. Mount the Starnote with its top face oriented toward the sky (inside the polycarbonate enclosure top is sufficient); in the northern hemisphere a southward orientation improves Skylo link margin. The Starnote's onboard GNSS antenna supports its own satellite link functions and is separate from the Notecard's GPS module; the Notecard `GPS` u.FL port (connected to the dual antenna's GPS tail) is the location source for all `card.location` data embedded in alert Notes. +**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. @@ -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 Starnote first-light sequence.** Before satellite transmission is possible, the Notecard must complete at least one successful cellular or WiFi sync. This is how the Notecard delivers the compact template definitions to Notehub. Follow the [Starnote for Skylo Quickstart](https://dev.blues.io/quickstart/starnote-quickstart/) to verify the Starnote connection and confirm satellite transport is functional before deploying. +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. 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. @@ -227,7 +227,7 @@ The firmware is split into three small files so the safety-critical detection pa | Responsibility | Function | |---|---| -| Notecard configuration (`hub.set`) at boot; returns fault state | `notecardConfigure()` | +| Notecard configuration (`hub.set` + one-time `card.transport` `wifi-cell-ntn` for cellular→satellite fallback) at boot; returns fault state | `notecardConfigure()` | | Compact template registration (2 templates, retried; returns fault state) | `defineTemplates()` | | Environment variable refresh with clamp validation; called at boot and every 2 h | `fetchEnvVars()` | | LIS3DH setup (100 Hz, ±4g) | `initAccel()` | @@ -250,7 +250,7 @@ The firmware uses a two-stage software algorithm sampled at ~100 Hz: ten `pollFa ### Event Payload Design -Both Notefiles use [compact templates](https://dev.blues.io/notecard/notecard-walkthrough/low-bandwidth-design#working-with-note-templates) with `"format":"compact"`. This is a hard requirement for Starnote NTN transport — compact Notes use fixed-length binary encoding, keeping the satellite packet well inside the 256-byte maximum payload limit and minimizing per-message satellite cost. The `_lat`/`_lon` keywords in the template body instruct the Notecard to embed its cached GPS location automatically; the firmware does not need to explicitly pass coordinates in the `note.add` body. +Both Notefiles use [compact templates](https://dev.blues.io/notecard/notecard-walkthrough/low-bandwidth-design#working-with-note-templates) with `"format":"compact"`. This is a hard requirement for Skylo NTN (satellite) transport — compact Notes use fixed-length binary encoding, keeping the satellite packet well inside the 256-byte maximum payload limit and minimizing per-message satellite cost. The `_lat`/`_lon` keywords in the template body instruct the Notecard to embed its cached GPS location automatically; the firmware does not need to explicitly pass coordinates in the `note.add` body. Both templates include an `event_id` field — a monotonic counter incremented once per new alert dispatch, **not** per retry. The same `event_id` value appears in both `beacon_alert.qo` and its paired `beacon_location.qo`. Downstream systems must use `(device, event_id)` as the join key — `event_id` resets to 0 on each power cycle and is not globally unique on its own. The scoped `(device, event_id)` pair is stable across repeated alerts of the same type, across retries, and across network reordering. @@ -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 runs in `periodic` mode with `outbound: 1440` (daily flush) and `inbound: 120` (2-hour environment-variable refresh). All emergency Notes carry `sync:true`, which bypasses the outbound interval and triggers an immediate cellular or satellite session — the daily flush is a backstop for any queued data that sync:true did not deliver. Between sync events the Notecard sits in its own low-power STOP2 idle state at ~8–18 µA. 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. +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. 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). @@ -308,7 +308,7 @@ A production implementation should use STM32L433 low-power STOP2 mode with GPIO **Startup path.** Both `notecardConfigure()` and `defineTemplates()` return a boolean. `notecardConfigure()` retries `hub.set` up to five times to handle the cold-boot I²C race. `defineTemplates()` retries each of the two template registrations (`beacon_alert.qo`, `beacon_location.qo`) up to three times. If either function returns false, `g_setupFault` is latched in `setup()`, and a distinctive slow double-buzz haptic pattern fires so a misconfigured device is obvious at power-on without needing debug serial. A missing or empty `PRODUCT_UID` is also caught at runtime and added to the fault latch. -A startup fault — missing or empty `PRODUCT_UID`, `hub.set` failure after five retries, any template registration failure, or LIS3DH initialization failure — is treated as unrecoverable. After the slow double-buzz pattern fires, `setup()` enters an infinite halt loop that repeats the fault buzz every 5 seconds; the beacon never enters `loop()` and no alerts are ever sent. This hard-stop behavior is intentional for a safety device: arming a beacon whose Notes cannot route, or whose Starnote compact transport may be broken, gives a false sense of protection. The recurring buzz makes an unconfigured device unmistakably obvious at power-on — verify `PRODUCT_UID`, Notecard connectivity, and template registration, then power-cycle before deploying. +A startup fault — missing or empty `PRODUCT_UID`, `hub.set` failure after five retries, any template registration failure, or LIS3DH initialization failure — is treated as unrecoverable. After the slow double-buzz pattern fires, `setup()` enters an infinite halt loop that repeats the fault buzz every 5 seconds; the beacon never enters `loop()` and no alerts are ever sent. This hard-stop behavior is intentional for a safety device: arming a beacon whose Notes cannot route, or whose compact Skylo NTN transport may be broken, gives a false sense of protection. The recurring buzz makes an unconfigured device unmistakably obvious at power-on — verify `PRODUCT_UID`, Notecard connectivity, and template registration, then power-cycle before deploying. **Sensor degradation.** `initAccel()` and `initHaptic()` each return a boolean; the main loop checks `g_accelReady` and `g_hapticReady` before calling the relevant functions. A missing or unresponsive LIS3DH at boot is treated as a hard fault — `g_setupFault` is latched alongside `g_accelFaultLatched`, the distinctive slow double-buzz fault pattern fires, and `setup()` enters the infinite halt loop. This ensures a beacon that cannot perform fall detection is immediately obvious at power-on and cannot be silently deployed as panic-only. A missing DRV2605L skips haptic feedback without crashing the loop. An accelerometer fault that develops after boot (consecutive bad reads beyond `ACCEL_FAIL_THRESHOLD` after `ACCEL_REINIT_MAX` failed reinitialisations) latches `g_accelFaultLatched` and clears `g_accelReady`, permanently disabling fall detection until power-cycle. The device then emits a single buzz every 30 seconds so an operator can recognize the unit has dropped to degraded panic-only mode. @@ -322,7 +322,7 @@ A startup fault — missing or empty `PRODUCT_UID`, `hub.set` failure after five ### Key Code Snippet 1: Compact Template with _lat/_lon -The `format: "compact"` and `port` arguments are required for Starnote NTN transport. The `_lat`/`_lon` template fields tell the Notecard to embed its cached best-available location (GNSS or cell-derived) in the compact packet automatically — the firmware never passes coordinates in the Note body. The `event_id` field uses type hint `14` (4-byte signed int32, per the Blues compact-template encoding table) and is written to both `beacon_alert.qo` and `beacon_location.qo` with the same value; downstream systems join the two Notes using `(device, event_id)` as the key. +The `format: "compact"` and `port` arguments are required for Skylo NTN (satellite) transport. The `_lat`/`_lon` template fields tell the Notecard to embed its cached best-available location (GNSS or cell-derived) in the compact packet automatically — the firmware never passes coordinates in the Note body. The `event_id` field uses type hint `14` (4-byte signed int32, per the Blues compact-template encoding table) and is written to both `beacon_alert.qo` and `beacon_location.qo` with the same value; downstream systems join the two Notes using `(device, event_id)` as the key. ```cpp J *req = notecard.newRequest("note.template"); @@ -341,7 +341,7 @@ notecard.sendRequest(req); ### Key Code Snippet 2: Immediate-Sync Alert -`sync:true` tells the Notecard to attempt a cellular (or satellite) session immediately, bypassing the periodic outbound interval. The Notecard tries cellular first; if that fails and Starnote is attached, the Note routes over satellite automatically. +`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. ```cpp J *req = notecard.newRequest("note.add"); @@ -454,7 +454,7 @@ If GPS times out, only the initial `beacon_alert.qo` Note is sent; the cached lo - `beacon_alert.qo` — emitted on confirmed fall or panic. `sync:true` triggers immediate cellular (or satellite) transmission. Contains: alert type, worker ID, `event_id` (monotonic correlation key), battery voltage, `loc_age_s` (cached-fix age at alert time), and cached location via compact template `_lat`/`_lon`. - `beacon_location.qo` — emitted after a confirmed alert when a fresh GPS fix arrives within the timeout window. `sync:true`. Contains: alert type (echoes the triggering event), worker ID, `event_id` (matches the paired `beacon_alert.qo`), and fresh event-time coordinates via `_lat`/`_lon`. This Note is optional — it is queued only if GPS succeeds during the background search window. -**Routed.** Both Notefiles arrive at Notehub regardless of whether they came via LTE Cat-1 bis or Skylo satellite — the transport is transparent in the event structure. Downstream systems should pair `beacon_alert.qo` and `beacon_location.qo` using `(device, event_id)` as the join key — `event_id` is device-local, resets to 0 on each power cycle, and is not unique across devices on its own. The initial alert carries the best-available cached location, and a subsequent `beacon_location.qo` with the same `event_id` (from the same device) supersedes it with event-time coordinates when GPS acquires within the 90-second background window. Pairing on `(device, event_id)` is unambiguous across repeated alert types, retries, and network reordering. +**Routed.** Both Notefiles arrive at Notehub regardless of whether they came via WiFi, cellular, or Skylo satellite — the transport is transparent in the event structure. Downstream systems should pair `beacon_alert.qo` and `beacon_location.qo` using `(device, event_id)` as the join key — `event_id` is device-local, resets to 0 on each power cycle, and is not unique across devices on its own. The initial alert carries the best-available cached location, and a subsequent `beacon_location.qo` with the same `event_id` (from the same device) supersedes it with event-time coordinates when GPS acquires within the 90-second background window. Pairing on `(device, event_id)` is unambiguous across repeated alert types, retries, and network reordering. **Alert triggers:** - `fall` — two-stage algorithm: free-fall phase followed by impact within the detection window. Suppressed if within 60 seconds of the previous alert. @@ -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 a Starnote attached and the device outdoors (antenna has sky view), force a satellite session by temporarily disabling cellular transport in the Notecard (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: `{"req":"card.transport","method":"-"}`. +**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"}`. **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. @@ -489,13 +489,12 @@ Alert overhead (per event): **Validation with Mojo is mandatory before deployment** — measure your actual steady-state draw and per-alert overhead. WiFi and satellite transports consume different energy profiles; sync cadence and GPS timeout settings affect total runtime. -**Published Notecard and Starnote figures (from Blues documentation)** +**Published Notecard for Skylo figures (from Blues documentation)** | Component | State | Published figure | |---|---|---| -| Notecard Cell+WiFi (MBGLW) | Idle, radio off (between syncs) | ~8–18 µA ([low-power design guide](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design/)) | -| Notecard Cell+WiFi (MBGLW) | LTE Cat-1 bis cellular sync (single queued Note) | ~0.28 mAh per sync; bursts during session establishment ([low-power design guide](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design/)) | -| Starnote for Skylo | Satellite transmit burst | Up to 1 A peak ([Starnote datasheet](https://dev.blues.io/datasheets/starnote-datasheet/)) | +| Notecard for Skylo (NOTE-NBGLWX) | Idle, radio off (between sessions) | ~8 µA ([datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/)) | +| Notecard for Skylo (NOTE-NBGLWX) | Network session (cellular or satellite) | ~250 mA average from the onboard BG95-S5 modem; brief peaks up to ~2 A for a few ms on a 2G transmit burst ([datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/)) | **Estimated whole-device figures — validate with Mojo before sizing for deployment** @@ -530,11 +529,11 @@ A productive bench exercise: run the device for 2 hours on a known-capacity LiPo - Confirm the Notecard is in low-power periodic mode: issue `{"req":"hub.get"}` from the [Blues In-Browser Terminal](https://dev.blues.io/terminal/). If `outbound` is greater than 1440 (24 hours) or `inbound` is less than 120 (2 hours), sync cadence may be excessive. See [Section 5, step 5](#6-notehub-setup) for recommended settings. - 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. -**Starnote satellite transmission fails or never completes.** -- The Starnote link is only active after the device has completed at least one successful cellular or WiFi sync to 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 coverage at least once. This is called the "first-light sequence." Move the device to cellular coverage, power it on, wait for a sync (check Notehub device status), then move back to the satellite-only zone. -- Verify the Starnote antenna orientation: the module's top face should point toward the sky (polycarbonate enclosure top is sufficient); in the northern hemisphere, southward orientation improves link margin. If the Starnote is mounted sideways or inverted, Skylo acquisition may fail. -- Check Starnote coverage: the Skylo network covers specific regions (see [Starnote datasheet](https://dev.blues.io/datasheets/starnote-datasheet/)). 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 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 hybrid transport: `{"req":"card.transport","method":"-"}`. +**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. +- 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"}`. **Fall detection generates false positives during normal work.** - Adjust the `freefall_g` and `impact_g` thresholds via environment variables (see [Section 5, step 5](#6-notehub-setup)). Increase `freefall_g` (e.g., 0.65 or 0.75) to require a deeper free-fall phase before the impact window opens. Increase `impact_g` (e.g., 3.0 or 3.5) to require a larger acceleration spike to confirm impact. Both changes reduce sensitivity and may suppress legitimate falls — validate with your specific worker activity profile. @@ -564,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). -- **Starnote requires initial cellular sync.** The Starnote NTN path is not available until the device has completed at least one successful cellular or WiFi session. A device that ships directly into a no-cellular zone will be unable to send via satellite until it has found cellular 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 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. -- **Satellite payload budget.** The Starnote for Skylo bundle includes 10 KB of data with a 50-byte minimum per packet. The compact alert template is well under 256 bytes; 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.** 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). - **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. @@ -586,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 Starnote satellite path covers the specific sites where cellular fails first and matters most. 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; 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. diff --git a/60-lone-worker-panic-fall-detection-beacon/diagrams/01-system-architecture.svg b/60-lone-worker-panic-fall-detection-beacon/diagrams/01-system-architecture.svg index 5ec1bb24..8a1206ac 100644 --- a/60-lone-worker-panic-fall-detection-beacon/diagrams/01-system-architecture.svg +++ b/60-lone-worker-panic-fall-detection-beacon/diagrams/01-system-architecture.svg @@ -26,11 +26,12 @@ Edge enclosure - Notecarrier CX - Cygnet STM32L433 - MBGLW + Starnote + Notecarrier CX + Cygnet STM32L433 + Notecard for Skylo - fall + panic detect + cellular · WiFi · satellite + fall + panic detect diff --git a/60-lone-worker-panic-fall-detection-beacon/diagrams/02-wiring-assembly.svg b/60-lone-worker-panic-fall-detection-beacon/diagrams/02-wiring-assembly.svg index 47985619..1cfe0bd9 100644 --- a/60-lone-worker-panic-fall-detection-beacon/diagrams/02-wiring-assembly.svg +++ b/60-lone-worker-panic-fall-detection-beacon/diagrams/02-wiring-assembly.svg @@ -19,26 +19,26 @@ Wiring & Assembly - I²C peripherals · panic GPIO · dual flex antenna · Starnote satellite + I²C peripherals · panic GPIO · Notecard for Skylo MAIN + GPS u.FL antennas Notecarrier CX - + Cygnet · MBGLW + + Cygnet · Notecard for Skylo SDA/SCL D9 - u.FL - JST + MAIN + GPS +VBAT - + @@ -54,23 +54,24 @@ Panic button D9 · INPUT_PULLUP - + - Dual flex antenna - CELL + GPS u.FL + MAIN antenna + Skylo-certified u.FL + cellular + satellite - - - - Starnote (Skylo) - satellite via JST + + + + GPS antenna + passive GNSS u.FL - + diff --git a/60-lone-worker-panic-fall-detection-beacon/firmware/lone_worker_beacon/lone_worker_beacon.ino b/60-lone-worker-panic-fall-detection-beacon/firmware/lone_worker_beacon/lone_worker_beacon.ino index e51c44a3..7bf21f29 100644 --- a/60-lone-worker-panic-fall-detection-beacon/firmware/lone_worker_beacon/lone_worker_beacon.ino +++ b/60-lone-worker-panic-fall-detection-beacon/firmware/lone_worker_beacon/lone_worker_beacon.ino @@ -3,8 +3,8 @@ * * Detects falls (two-stage: free-fall then impact), monitors a panic button * with 30 ms debounce and hold-to-confirm, drives a haptic motor for - * acknowledgment, and transmits alerts via Notecard — falling back to Starnote - * satellite when cellular coverage is absent. + * acknowledgment, and transmits alerts via a Notecard for Skylo — falling back + * to Skylo satellite (NTN) when cellular coverage is absent. * * ── Two-note alert flow ─────────────────────────────────────────────────── * On fall or panic: @@ -43,8 +43,11 @@ * * Hardware: * Notecarrier CX (Cygnet STM32L433 host) - * Notecard Cell+WiFi (MBGLW) — primary cellular/WiFi transport - * Starnote for Skylo — satellite failover + * Notecard for Skylo (NOTE-NBGLWX) — cellular + WiFi + Skylo + * satellite (NTN) on one M.2 board; + * card.transport selects cellular + * with automatic satellite fallback + * (see notecardConfigure()). * SparkFun LIS3DH breakout (SEN-13963) — 3-axis accelerometer * Adafruit DRV2605L breakout (#2305) — haptic motor driver * Adafruit Vibrating Mini Motor Disc (#1201) — haptic actuator @@ -77,7 +80,7 @@ uint32_t g_fallWindowMs = DEFAULT_FALL_WINDOW_MS; uint32_t g_freefallMinMs = DEFAULT_FREEFALL_MIN_MS; uint32_t g_panicHoldMs = DEFAULT_PANIC_HOLD_MS; // Fixed-size buffer (WORKER_ID_MAX chars + null) avoids Arduino String heap -// churn and prevents an oversized env-var from bloating Starnote packets. +// churn and prevents an oversized env-var from bloating Skylo NTN packets. char g_workerId[WORKER_ID_MAX + 1] = "worker-001"; // ── Application state ───────────────────────────────────────────────────── @@ -170,7 +173,7 @@ void setup() // Configure Notecard and register compact templates. Both must succeed for // the device to be considered healthy — template failure means notes may - // fall back to JSON instead of compact binary, breaking Starnote transport. + // fall back to JSON instead of compact binary, breaking Skylo NTN transport. bool cfgOk = notecardConfigure(); bool tplOk = defineTemplates(); g_setupFault = (!cfgOk || !tplOk); diff --git a/60-lone-worker-panic-fall-detection-beacon/firmware/lone_worker_beacon/lone_worker_beacon_helpers.cpp b/60-lone-worker-panic-fall-detection-beacon/firmware/lone_worker_beacon/lone_worker_beacon_helpers.cpp index 988a2513..a416b561 100644 --- a/60-lone-worker-panic-fall-detection-beacon/firmware/lone_worker_beacon/lone_worker_beacon_helpers.cpp +++ b/60-lone-worker-panic-fall-detection-beacon/firmware/lone_worker_beacon/lone_worker_beacon_helpers.cpp @@ -34,9 +34,10 @@ static uint32_t clampU32(const char *name, double v, uint32_t lo, uint32_t hi, } // ─── Notecard Configuration ─────────────────────────────────────────────── -// Retries hub.set up to 5 times to handle the cold-boot I²C race. Returns -// true only when the Notecard acknowledges without error. Failure latches -// g_setupFault in the caller. +// Retries hub.set up to 5 times to handle the cold-boot I²C race, then issues +// a one-time card.transport selection so the Notecard for Skylo enables Skylo +// satellite (NTN) fallback. Returns true only when hub.set acknowledges without +// error. Failure latches g_setupFault in the caller. // // mode: "periodic" with outbound: 1440 (daily flush) and inbound: 120 (2-hour // env-var refresh). All emergency notes use sync:true, which bypasses the @@ -53,17 +54,44 @@ bool notecardConfigure() J *rsp = notecard.requestAndResponse(req); bool ok = (rsp != NULL && !notecard.responseError(rsp)); if (rsp) notecard.deleteResponse(rsp); - if (ok) return true; + if (ok) break; DEBUG_PRINT("[CFG] hub.set attempt "); DEBUG_PRINT(attempt + 1); DEBUG_PRINTLN(" failed — retrying."); delay(500); + if (attempt == 4) { + DEBUG_PRINTLN("[FAULT] hub.set failed after 5 attempts."); + return false; + } } - DEBUG_PRINTLN("[FAULT] hub.set failed after 5 attempts."); - return false; + + // Transport selection for the Notecard for Skylo (NOTE-NBGLWX). + // The board carries WiFi, cellular, and Skylo satellite (NTN) radios, but + // satellite fallback is NOT enabled by default — the factory transport is + // "wifi-cell" (WiFi preferred, cellular fallback, no NTN). Set "wifi-cell-ntn" + // so the Notecard prefers WiFi where an AP is reachable, falls back to + // cellular (the de-facto primary for a roaming worker), and finally to Skylo + // satellite when every terrestrial network is unavailable — automatic + // failover with no firmware branching. The Notecard persists this setting in + // its own flash, so issuing it once on cold boot is sufficient. + // + // Note: Skylo requires at least one non-NTN (cellular or WiFi) sync to + // associate with Notehub and register templates before NTN can be used. + // Commission each beacon where it has terrestrial coverage even if it will + // routinely operate over satellite (see defineTemplates first-light note). + { + J *req = notecard.newRequest("card.transport"); + if (req) { + JAddStringToObject(req, "method", "wifi-cell-ntn"); + if (!notecard.sendRequestWithRetry(req, 10)) { + DEBUG_PRINTLN("[CFG] card.transport (wifi-cell-ntn) failed; will retry on next cold boot."); + } + } + } + return true; } // ─── Notefile Templates ─────────────────────────────────────────────────── -// compact + port are REQUIRED for Starnote NTN transport. _lat/_lon instruct +// compact + port are REQUIRED for Skylo NTN (satellite) transport. _lat/_lon instruct // the Notecard to embed its cached GPS fix at note.add time — the firmware // never passes coordinates in the note body. // @@ -161,7 +189,7 @@ void fetchEnvVars() if (body != NULL) { const char *wid = JGetString(body, "worker_id"); // Hard-clamp to WORKER_ID_MAX chars. An oversized worker_id bloats - // every Starnote compact packet; strncpy truncates silently so the + // every Skylo NTN compact packet; strncpy truncates silently so the // device remains functional even if a mis-configured env var is set. if (wid && strlen(wid) > 0) { strncpy(g_workerId, wid, WORKER_ID_MAX); diff --git a/60-lone-worker-panic-fall-detection-beacon/firmware/lone_worker_beacon/lone_worker_beacon_helpers.h b/60-lone-worker-panic-fall-detection-beacon/firmware/lone_worker_beacon/lone_worker_beacon_helpers.h index 2da73475..e2b058b3 100644 --- a/60-lone-worker-panic-fall-detection-beacon/firmware/lone_worker_beacon/lone_worker_beacon_helpers.h +++ b/60-lone-worker-panic-fall-detection-beacon/firmware/lone_worker_beacon/lone_worker_beacon_helpers.h @@ -100,7 +100,7 @@ struct AlertQueueEntry { // ── Worker ID ───────────────────────────────────────────────────────────── // Hard maximum for worker_id (chars, excluding null terminator). A fixed-size -// char buffer prevents oversized identifiers from bloating Starnote compact +// char buffer prevents oversized identifiers from bloating Skylo NTN compact // packets. Values longer than WORKER_ID_MAX are silently truncated in // fetchEnvVars(). Document this limit in the Notehub env-var README section. #define WORKER_ID_MAX 24 diff --git a/63-construction-equipment-anti-theft-tracker-with-immobilizer/firmware/construction_equipment_anti_theft/construction_equipment_anti_theft.ino b/63-construction-equipment-anti-theft-tracker-with-immobilizer/firmware/construction_equipment_anti_theft/construction_equipment_anti_theft.ino index 817ec95d..cb427378 100644 --- a/63-construction-equipment-anti-theft-tracker-with-immobilizer/firmware/construction_equipment_anti_theft/construction_equipment_anti_theft.ino +++ b/63-construction-equipment-anti-theft-tracker-with-immobilizer/firmware/construction_equipment_anti_theft/construction_equipment_anti_theft.ino @@ -11,6 +11,9 @@ // - Inbound immobilize command delivered via Notehub (immobilize.qi) // - Relay assertion on next key-on when immobilize command is staged // - Compact note templates compatible with Notecard for Skylo satellite uplink +// - Automatic WiFi → cellular → Skylo-satellite (NTN) failover, enabled at +// boot via card.transport "wifi-cell-ntn" so equipment stays reachable +// beyond terrestrial coverage (NTN is off by default and must be turned on) // - Deep sleep via NotePayloadSaveAndSleep between wake cycles // // Hardware: diff --git a/63-construction-equipment-anti-theft-tracker-with-immobilizer/firmware/construction_equipment_anti_theft/construction_equipment_anti_theft_helpers.cpp b/63-construction-equipment-anti-theft-tracker-with-immobilizer/firmware/construction_equipment_anti_theft/construction_equipment_anti_theft_helpers.cpp index 4c9fec22..67046642 100644 --- a/63-construction-equipment-anti-theft-tracker-with-immobilizer/firmware/construction_equipment_anti_theft/construction_equipment_anti_theft_helpers.cpp +++ b/63-construction-equipment-anti-theft-tracker-with-immobilizer/firmware/construction_equipment_anti_theft/construction_equipment_anti_theft_helpers.cpp @@ -81,6 +81,27 @@ bool ensureConfigured(Notecard &nc, const char *product_uid, AppState &s) if (nc.sendRequestWithRetry(req, 5)) { s.cfg_hub_ok = true; LOGLN("[APP] hub.set confirmed."); + + // ── Transport selection for the Notecard for Skylo (NOTE-NBGLWX) ── + // The board carries WiFi, cellular, and Skylo satellite (NTN) radios, + // but satellite fallback is NOT enabled by default — NTN must be + // explicitly turned on with card.transport. "wifi-cell-ntn" makes the + // Notecard prefer WiFi, fall back to cellular, and finally fall back to + // Skylo satellite when no terrestrial coverage exists — automatic + // failover with no firmware branching. The Notecard persists this in + // its own flash, so issuing it once (gated here by cfg_hub_ok, set only + // after a successful hub.set) is sufficient. + // + // Note: Skylo requires at least one non-NTN (cellular or WiFi) sync to + // associate with Notehub and register templates before NTN can be used. + // Commission each unit where it has terrestrial coverage even if it will + // routinely operate over satellite, so that first sync can complete. + J *tr = nc.newRequest("card.transport"); + JAddStringToObject(tr, "method", "wifi-cell-ntn"); + if (!sendRequestChecked(nc, tr)) { + LOGLN("[APP] WARN: card.transport (wifi-cell-ntn) failed — " + "satellite fallback may be unavailable until reapplied."); + } } else { LOGLN("[APP] ERROR: hub.set failed — will retry next wake. " "Notes will not reach Notehub until this succeeds."); diff --git a/65-off-grid-livestock-water-tank-monitor/README.md b/65-off-grid-livestock-water-tank-monitor/README.md index 8bf0f715..9deb84df 100644 --- a/65-off-grid-livestock-water-tank-monitor/README.md +++ b/65-off-grid-livestock-water-tank-monitor/README.md @@ -246,7 +246,7 @@ The implementation spans three files in the [`firmware/livestock_water_tank_moni ### Event payload design -Both Notefiles are [template-backed](https://dev.blues.io/notecard/notecard-walkthrough/low-bandwidth-design#working-with-note-templates), storing Notes as fixed-length binary records instead of free-form JSON. Compact binary encoding reduces per-Note wire size by roughly 3–5× and, critically, is required for the NOTE-NBGLWX Starnote/NTN satellite path — both templates are registered with `"format": "compact"` and an explicit port number so either Notefile can transit via satellite or cellular using the identical `note.add` call. Over a multi-year deployment generating 6 summary Notes per day, that compression also meaningfully extends the useful life of the 500 MB prepaid data budget. Alert Notes carry `sync:true` to request an immediate radio wake; fixed-length binary encoding means `pump_amps = 0.0` (pump off at alert time) is transmitted faithfully — there is no omitempty-style drop for zero-valued numeric fields in compact encoding. +Both Notefiles are [template-backed](https://dev.blues.io/notecard/notecard-walkthrough/low-bandwidth-design#working-with-note-templates), storing Notes as fixed-length binary records instead of free-form JSON. Compact binary encoding reduces per-Note wire size by roughly 3–5× and, critically, is required for the NOTE-NBGLWX Skylo NTN satellite path — both templates are registered with `"format": "compact"` and an explicit port number so either Notefile can transit via satellite or cellular using the identical `note.add` call. Over a multi-year deployment generating 6 summary Notes per day, that compression also meaningfully extends the useful life of the 500 MB prepaid data budget. Alert Notes carry `sync:true` to request an immediate radio wake; fixed-length binary encoding means `pump_amps = 0.0` (pump off at alert time) is transmitted faithfully — there is no omitempty-style drop for zero-valued numeric fields in compact encoding. `tank_status.qo` (periodic, every `summary_interval_min`; compact template-encoded, port 50): @@ -289,7 +289,7 @@ Both Notefiles are [template-backed](https://dev.blues.io/notecard/notecard-walk -**`alert_code` is an integer type code:** `0` = `level_low`, `1` = `level_critical`, `2` = `battery_low`. The integer field keeps the compact-template payload fixed-length binary — the same requirement as the summary template for the NOTE-NBGLWX Starnote/NTN path. All five fields (including `pump_amps = 0.0` when the pump is off) are always present in compact binary encoding. +**`alert_code` is an integer type code:** `0` = `level_low`, `1` = `level_critical`, `2` = `battery_low`. The integer field keeps the compact-template payload fixed-length binary — the same requirement as the summary template for the NOTE-NBGLWX Skylo NTN path. All five fields (including `pump_amps = 0.0` when the pump is off) are always present in compact binary encoding. @@ -313,7 +313,7 @@ When the firmware detects battery voltage below 12.0V (moderately discharged), i ### Key code snippet 1 — template registration -The template uses `"compact"` format and an explicit `port` — both required for the NOTE-NBGLWX Starnote/NTN satellite path. Type hints are literal numeric values representing field types: +The template uses `"compact"` format and an explicit `port` — both required for the NOTE-NBGLWX Skylo NTN satellite path. Type hints are literal numeric values representing field types: - `14.1` = 32-bit float (e.g., `level_pct`, `pump_amps`, `battery_v`) - `12` = 2-byte signed integer / int16_t (e.g., `alerts` field, range −32,768 to +32,767) - `true` = boolean field (e.g., `pump_on`) @@ -324,8 +324,8 @@ Template-backed Notes reduce per-event wire size by ~4× and are required for sa ```cpp J *req = notecard.newRequest("note.template"); JAddStringToObject(req, "file", NOTEFILE_SUMMARY); -JAddNumberToObject(req, "port", 50); // required for Starnote/NTN -JAddStringToObject(req, "format", "compact"); // required for Starnote/NTN +JAddNumberToObject(req, "port", 50); // required for Skylo NTN +JAddStringToObject(req, "format", "compact"); // required for Skylo NTN J *body = JAddObjectToObject(req, "body"); JAddNumberToObject(body, "_time", 14); // Unix timestamp (Notecard auto-fills) JAddNumberToObject(body, "level_pct", 14.1); // float32 @@ -341,7 +341,7 @@ if (notecard.sendRequest(req)) { ### Key code snippet 2 — immediate alert with sync -The alert Note uses the compact template registered for `tank_alert.qo` (port 51, `"compact"` format), so it travels over the NOTE-NBGLWX Starnote/NTN satellite path when cellular is unavailable — the identical `note.add` call works over either transport. `sync:true` tells the Notecard to wake the radio immediately rather than waiting for the next scheduled outbound window. The `alert_code` integer (0 = `level_low`, 1 = `level_critical`, 2 = `battery_low`) keeps the body fixed-length binary as required by the compact template; all fields, including `pump_amps = 0.0`, are always present. +The alert Note uses the compact template registered for `tank_alert.qo` (port 51, `"compact"` format), so it travels over the NOTE-NBGLWX Skylo NTN satellite path when cellular is unavailable — the identical `note.add` call works over either transport. `sync:true` tells the Notecard to wake the radio immediately rather than waiting for the next scheduled outbound window. The `alert_code` integer (0 = `level_low`, 1 = `level_critical`, 2 = `battery_low`) keeps the body fixed-length binary as required by the compact template; all fields, including `pump_amps = 0.0`, are always present. ```cpp if (!g.templatesInstalled) return false; // template required for satellite path diff --git a/65-off-grid-livestock-water-tank-monitor/firmware/livestock_water_tank_monitor/livestock_water_tank_monitor.ino b/65-off-grid-livestock-water-tank-monitor/firmware/livestock_water_tank_monitor/livestock_water_tank_monitor.ino index bc8ff562..7c88346d 100644 --- a/65-off-grid-livestock-water-tank-monitor/firmware/livestock_water_tank_monitor/livestock_water_tank_monitor.ino +++ b/65-off-grid-livestock-water-tank-monitor/firmware/livestock_water_tank_monitor/livestock_water_tank_monitor.ino @@ -280,6 +280,22 @@ static void notecardConfigure(void) { } } + // Enable the Skylo satellite (NTN) transport. NTN is OFF by default on the + // Notecard for Skylo (NOTE-NBGLWX) — the factory transport never engages the + // satellite radio. Setting "wifi-cell-ntn" enables automatic WiFi → cellular + // → Skylo-satellite fallback with no firmware branching: the Notecard prefers + // WiFi, falls back to cellular, and finally to Skylo NTN at sites beyond + // terrestrial coverage. Skylo requires at least one non-NTN (cellular/WiFi) + // sync first to associate with Notehub and register templates before NTN can + // be used; in periodic mode the cold-boot hub.set above triggers that initial + // sync. This setting persists in the Notecard's own flash, so issuing it once + // at cold boot is sufficient. + req = notecard.newRequest("card.transport"); + if (req) { + JAddStringToObject(req, "method", "wifi-cell-ntn"); + notecard.sendRequestWithRetry(req, 10); + } + // Disable the onboard accelerometer to eliminate interrupt noise on bench // power-trace measurements. Non-critical if this fails; idempotent. req = notecard.newRequest("card.motion.mode"); @@ -315,7 +331,7 @@ static bool reapplyHubSet(void) { // ============================================================================= // Register compact binary templates for both Notefiles. // "compact" format and an explicit port number are both required for -// NOTE-NBGLWX Starnote/NTN satellite operation; they are compatible with the +// NOTE-NBGLWX Skylo NTN satellite operation; they are compatible with the // cellular path too, so one template definition per Notefile covers both // transports. Type hints use literal numeric values (14.1 → float32, // 12 → int16 (2-byte signed, −32 768..+32 767), true → boolean) matching @@ -339,8 +355,8 @@ static void defineTemplates(void) { J *req = notecard.newRequest("note.template"); if (!req) return; JAddStringToObject(req, "file", NOTEFILE_SUMMARY); - JAddNumberToObject(req, "port", 50); // required for Starnote/NTN - JAddStringToObject(req, "format", "compact"); // required for Starnote/NTN + JAddNumberToObject(req, "port", 50); // required for Skylo NTN + JAddStringToObject(req, "format", "compact"); // required for Skylo NTN J *body = JAddObjectToObject(req, "body"); if (!body) { JDelete(req); return; } JAddNumberToObject(body, "_time", 14); // Unix timestamp (Notecard auto-fills) @@ -356,8 +372,8 @@ static void defineTemplates(void) { req = notecard.newRequest("note.template"); if (!req) return; JAddStringToObject(req, "file", NOTEFILE_ALERT); - JAddNumberToObject(req, "port", 51); // required for Starnote/NTN - JAddStringToObject(req, "format", "compact"); // required for Starnote/NTN + JAddNumberToObject(req, "port", 51); // required for Skylo NTN + JAddStringToObject(req, "format", "compact"); // required for Skylo NTN body = JAddObjectToObject(req, "body"); if (!body) { JDelete(req); return; } JAddNumberToObject(body, "_time", 14); // Unix timestamp (Notecard auto-fills) diff --git a/65-off-grid-livestock-water-tank-monitor/firmware/livestock_water_tank_monitor/livestock_water_tank_monitor_helpers.cpp b/65-off-grid-livestock-water-tank-monitor/firmware/livestock_water_tank_monitor/livestock_water_tank_monitor_helpers.cpp index 368d9362..3ec337c3 100644 --- a/65-off-grid-livestock-water-tank-monitor/firmware/livestock_water_tank_monitor/livestock_water_tank_monitor_helpers.cpp +++ b/65-off-grid-livestock-water-tank-monitor/firmware/livestock_water_tank_monitor/livestock_water_tank_monitor_helpers.cpp @@ -303,7 +303,7 @@ void evaluateAlerts(float levelPct, float pumpAmps, // ============================================================================= // Emit an immediate alert Note with sync:true to bypass the outbound interval. // Uses the compact template registered for tank_alert.qo (port 51, "compact" -// format) so the Note is satellite-safe on the NOTE-NBGLWX Starnote/NTN path. +// format) so the Note is satellite-safe on the NOTE-NBGLWX Skylo NTN path. // alertCode is an integer (ALERT_CODE_*) stored in the "alert_code" field; // fixed-length binary encoding means pump_amps = 0.0 (pump off at alert time) // is transmitted faithfully — compact encoding has no omitempty-style drop diff --git a/65-off-grid-livestock-water-tank-monitor/firmware/livestock_water_tank_monitor/livestock_water_tank_monitor_helpers.h b/65-off-grid-livestock-water-tank-monitor/firmware/livestock_water_tank_monitor/livestock_water_tank_monitor_helpers.h index d19adf7b..ad76c518 100644 --- a/65-off-grid-livestock-water-tank-monitor/firmware/livestock_water_tank_monitor/livestock_water_tank_monitor_helpers.h +++ b/65-off-grid-livestock-water-tank-monitor/firmware/livestock_water_tank_monitor/livestock_water_tank_monitor_helpers.h @@ -34,7 +34,7 @@ // ── Alert type codes (tank_alert.qo body field "alert_code") ───────────────── // Integer codes instead of strings keep the compact-template payload // fixed-length binary — the same requirement as the summary template for the -// NOTE-NBGLWX Starnote/NTN satellite path. The "alert_code" template field +// NOTE-NBGLWX Skylo NTN satellite path. The "alert_code" template field // uses type hint 12, which encodes as a 2-byte signed integer (int16_t, // range −32 768 to +32 767); values 0–2 fit trivially within that range. // All fields are always present in compact binary encoding, so pump_amps = 0.0 diff --git a/66-remote-apiary-hive-health-monitor/README.md b/66-remote-apiary-hive-health-monitor/README.md index 46eee37b..0511441f 100644 --- a/66-remote-apiary-hive-health-monitor/README.md +++ b/66-remote-apiary-hive-health-monitor/README.md @@ -8,14 +8,14 @@ This reference application is intended to provide inspiration and help you get s -This project is a solar-powered, cellular-connected 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. +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. ## 1. Project Overview **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 through the Notecard's cellular connection to Notehub — or, when cellular coverage fails at the margins, over satellite via Starnote for [Skylo](https://www.skylo.tech/). 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 — 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. @@ -23,7 +23,7 @@ This project is the remote set of eyes and ears that a beekeeper wants but canno -**Why Notecard.** 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 Cell+WiFi carries its own prepaid global SIM, so there is no per-site IT negotiation and no carrier contract. The Starnote for Skylo adds non-terrestrial network (**NTN**) satellite fallback for the yards that sit in coverage gaps — 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 at [dev.blues.io/starnote](https://dev.blues.io/starnote/satellite-best-practices/) before relying on Starnote as the sole backhaul.** The combination of low-power cellular with 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. 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. @@ -32,11 +32,11 @@ This project is the remote set of eyes and ears that a beekeeper wants but canno ## 2. System Architecture -![System architecture: sensors → Notecarrier CX with Cygnet host → Notecard Cell+WiFi → cellular/NTN → Notehub → routes; Starnote for Skylo mounts externally connected via 6-pin JST NTN cable; power from solar panel → Sunny Buddy BATT (Li-ion) and LOAD → Notecarrier](diagrams/01-system-architecture.svg) +![System architecture: sensors → Notecarrier CX with Cygnet host → Notecard for Skylo (cellular / WiFi / satellite) → cellular/NTN → Notehub → routes; power from solar panel → Sunny Buddy BATT (Li-ion) and LOAD → Notecarrier](diagrams/01-system-architecture.svg) **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 Cell+WiFi buffers each [Note](https://dev.blues.io/api-reference/glossary/#note) on its on-device flash queue, opens cellular sessions on the configured [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) outbound cadence, and hands off to the paired Starnote for Skylo when the orchard sits beyond terrestrial coverage — the beekeeper's daily summary still reaches Notehub whether the apiary has cellular bars or not. 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, not at the next scheduled flush. This build provisions only a cellular antenna; the Notecard's WiFi radio is not used. [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.** 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. **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. Assemble Starnote in separate IP65 enclosure with clear lid. +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). 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. @@ -107,10 +107,8 @@ Here is a sample Note this device emits: | Part | Qty | Rationale | |------|-----|-----------| | [Notecarrier CX](https://dev.blues.io/datasheets/notecarrier-datasheet/notecarrier-cx-v1-3/) ([buy](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 MCU — no separate Swan needed. Provides A0–A5 analog inputs, SDA/SCL I2C, and digital GPIO pins sufficient for all three sensors. | -| [Notecard Cell+WiFi (MBGLW)](https://dev.blues.io/datasheets/notecard-datasheet/note-mbglw/) ([buy](https://shop.blues.com/products/notecard?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link)) | 1 | Cellular connectivity with an integrated prepaid global SIM and no carrier contract. Seats into the Notecarrier CX M.2 slot. This build provisions only a cellular antenna; the MBGLW's WiFi radio is not enabled or used. | -| [Starnote for Skylo](https://dev.blues.io/datasheets/starnote-datasheet/) ([buy](https://shop.blues.com/products/starnote?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link)) | 1 | Satellite NTN fallback for apiaries beyond cellular range. **Must be mounted externally** — outside the main enclosure — with an unobstructed view of the sky; the integrated Ignion NTN/GPS patch antennas cannot acquire satellites through an opaque polycarbonate or metal enclosure. Skylo GEO coverage varies by geography and service region; verify coverage for your deployment area before relying on Starnote as the sole backhaul (see [satellite best practices](https://dev.blues.io/starnote/satellite-best-practices/)). Connects to the Notecard's onboard 6-pin JST NTN port via the supplied cable; host MCU must use I2C to Notecard when Starnote is attached. This design does not configure or transmit device location — the Starnote's integrated GPS receiver is used by the satellite stack internally for timing and ephemeris, not as a user-facing location source. | -| Small IP65 weatherproof enclosure for Starnote (e.g. 80 × 80 × 40 mm clear-lid polycarbonate project box) | 1 | Secondary housing for the Starnote module, mounted externally on the hive stand or main enclosure with the clear lid facing the sky. The clear polycarbonate lid passes the GPS and Skylo patch-antenna signals without attenuation; an opaque enclosure lid will degrade or block NTN/GPS reception. Drill one M16 cable-gland hole in the bottom for the 6-pin JST NTN cable and secure the Starnote PCB flat against the base with M2 standoffs or foam tape. Route the JST cable through the gland and seal with silicone. Source from electronics distributors (Hammond 1555C2, LeMotech, or equivalent rated IP54 or better; verify lid material is clear polycarbonate before ordering). | -| M16 cable glands (nylon, IP68) | 2 | One for the Starnote secondary enclosure (6-pin JST cable entry) and one additional gland if a second penetration is needed in the main enclosure for the sensor cable bundle. | +| [Notecard for Skylo (NOTE-NBGLWX)](https://dev.blues.io/datasheets/notecard-datasheet/note-nbglwx/) ([buy](https://shop.blues.com/products/notecard-for-skylo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link)) | 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. Seats into the Notecarrier CX M.2 slot. The firmware's `card.transport` `wifi-cell-ntn` setting makes it prefer cellular at in-coverage apiaries and fall back automatically to the Skylo satellite network at yards beyond cellular reach — no second device or part-number decision, and no separate satellite enclosure. The integrated prepaid global SIM means no carrier contract and no per-site IT negotiation. Skylo GEO coverage varies by geography and service region; verify coverage for your deployment area before relying on satellite as the sole backhaul (see [satellite best practices](https://dev.blues.io/starnote/satellite-best-practices/)). This design does not configure or transmit device location — the board's GPS/GNSS receiver is used by the satellite stack internally for timing and ephemeris, not as a user-facing location source. Requires the antennas below. | +| M16 cable glands (nylon, IP68) | 2 | One for the sensor cable bundle and one for the antenna pigtail penetration in the main enclosure. | | [Blues Mojo](https://dev.blues.io/datasheets/mojo-datasheet/) ([buy](https://shop.blues.com/products/mojo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link)) | 1 | **Bench commissioning only.** Coulomb counter for power-budget validation. Mounts inline on the Sunny Buddy load rail between the charger and the Notecarrier CX `+VBAT` pad; wired to Notecarrier CX Qwiic during bench testing. Must be removed from the field assembly before deployment. See §9 for usage. | | [SparkFun Load Cell Amplifier HX711 (SEN-13879)](https://www.sparkfun.com/products/13879) | 1 | 24-bit ADC front-end designed for Wheatstone-bridge load cells; interfaces to the Cygnet via two GPIO pins using bit-bang protocol. | | [Zemic H8C-C3-100KG single-ended shear-beam load cell](https://www.zemiceurope.com/media/Documentation/H8C_Datasheet.pdf) | 1 | IP67-rated alloy-steel single-ended shear-beam cell, 100 kg capacity, OIML C3 accuracy class, 4-wire Wheatstone bridge with 1 m cable. The H8C is normally one of 3–4 cells in a platform scale; for this single-cell POC it is mounted as a cantilever weigh module (fixed end bolted to a rigid bracket, free end carrying the load through a button or rocker pin). See §5 for the mount detail and §10 for the off-center loading limitations this introduces. Sized for a loaded double-brood Langstroth with supers (typically 40–80 kg). Available through [Zemicus USA](https://www.zemicusa.com/products/) and Zemic-authorized scale-supply distributors. | @@ -119,20 +117,20 @@ Here is a sample Note this device emits: | [SparkFun Sunny Buddy MPPT Solar Charger (PRT-12885)](https://www.sparkfun.com/products/12885) | 1 | Maximum power point tracking (MPPT) solar charger for single-cell Li-ion or LiPo (both chemistries share a 4.2 V CC/CV charge profile). Solar panel connects to the barrel-jack input (`IN+`/`IN−`); the battery connects to the `BATT` JST connector or `BAT+`/`GND` screw terminals; the `LOAD+`/`GND` output supplies the downstream device rail (Notecarrier CX via Mojo on the bench, or directly in the field). | | [Adafruit Lithium Ion Battery Pack 3.7V 4400mAh (#354)](https://www.adafruit.com/product/354) | 1 | Energy buffer for overnight and cloudy-day operation. The pack is two 18650-format Li-ion cells in parallel with integrated protection; the form factor and chemistry both differ from a LiPo pouch and the thermal-limit guidance in §10 is written specifically for Li-ion. At the nominal 15-minute sample cadence with the sleep-dominant firmware profile, estimated **active-phase** daily consumption is roughly 12–18 mAh (96 wakeup cycles × ~10 seconds at ~40 mA, plus one daily LTE Cat-1 bis sync at ~200 mA × ~60 seconds). The sleeping assembly also draws approximately 100–400 µA quiescent (Notecard low-power idle plus Notecarrier CX regulator and Sunny Buddy quiescent. See §9 power table), adding roughly 2.4–9.6 mAh/day. The whole-system daily budget is therefore approximately **14–28 mAh/day**, giving a 4 400 mAh pack at 80 % depth of discharge (3 520 mAh usable) on the order of **125–250 days of reserve** without any solar contribution. Actual reserve depends on NTN session frequency, cellular signal quality, and ambient temperature effects on Li-ion capacity — validate with Mojo during bench commissioning. Includes a JST-PH 2-pin connector that mates directly with the Sunny Buddy `BATT` JST port. | | [Voltaic Systems P105 5W 6V ETFE Solar Panel](https://voltaicsystems.com/5-watt-panel-etfe/) | 1 | 5 W, 6 V (peak 6.12 V / 940 mA) monocrystalline ETFE panel rated for long-term outdoor use. Ships with a 3.5 mm × 1.1 mm DC plug that inserts directly into the Sunny Buddy's barrel-jack solar input. At 940 mA peak, a full recharge of the 4400 mAh pack takes under 5 hours of direct sun. | -| [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. This is the **main** enclosure only; the Starnote mounts in its own separate small weatherproof enclosure (see Starnote row above). Drill two M16 cable-gland holes: one for the sensor cable bundle, one for the SMA antenna pigtail (or a third if routing the Starnote JST cable through the wall). Available from Hammond and authorized distributors. | +| [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. | -| [Adafruit u.FL to SMA Female Pigtail, 150 mm (#851)](https://www.adafruit.com/product/851) | 1 | Routes the Notecard's cellular u.FL connector through the enclosure wall; the panel-mount SMA female end fits in a drilled hole or cable-gland port. Disconnect the onboard u.FL cable from the Notecard and replace it with this pigtail for external antenna use. | -| [TE Connectivity Linx ANT-LTE-MON-SMA-L LTE-M/NB-IoT whip antenna](https://www.mouser.com/ProductDetail/TE-Connectivity-Linx/ANT-LTE-MON-SMA-L) | 1 | Multiband omni whip (700–2700 MHz, 3.2 dBi, SMA male) for LTE-M and NB-IoT. Screws onto the SMA female pigtail outside the enclosure; the tilt/swivel mount allows optimum sky orientation. | +| 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. | +| 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. | -The Notecard Cell+WiFi (MBGLW) ships with an active SIM and 500 MB of prepaid cellular data valid for 10 years — no activation fees and no monthly subscription. +**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. ## 5. Wiring and Assembly -![Wiring diagram: HX711 on D5/D6, SHT31-D via 4-wire jumpers on SDA/SCL, MAX9814 on A0, cellular u.FL pigtail to SMA whip, power chain: solar → Sunny Buddy (Li-ion at BATT) → LOAD → Mojo → Notecarrier +VBAT](diagrams/02-wiring-assembly.svg) +![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, the Notecard Cell+WiFi seats into the M.2 slot, and the Starnote for Skylo connects via the Notecard's onboard 6-pin JST SH NTN port — that satellite path mounts in its own clear-lidded enclosure outside the main box so the integrated patch antennas have 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 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. **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,15 +179,15 @@ The SHT31-D address defaults to 0x44; it coexists on the I2C bus with the Noteca **Analog reference (`+V_AREF` pin):** Leave unconnected; the STM32L433 ADC uses the internal 3.3 V reference for the A0 microphone input. -**Cellular antenna:** +**Antennas (single board, cellular + satellite + GPS):** -1. The Notecard Cell+WiFi ships with a small u.FL pigtail for bench use. Before closing the enclosure, disconnect the stock onboard u.FL cable from the Notecard's cellular u.FL port. -2. Connect the u.FL end of the Adafruit pigtail (product #851) to the Notecard's cellular u.FL port. The connector orients with the cable center-pin facing the port — it clicks firmly when fully seated. -3. Thread the pigtail's SMA female end through a drilled hole or M16 cable-gland port in the enclosure wall and secure it with the lock nut from outside. -4. Screw the TE Connectivity LTE whip antenna onto the SMA female bulkhead outside the enclosure. Orient the whip vertically for best omni coverage, or angle it toward the cell tower bearing if the site has a known marginal direction. -5. The Starnote for Skylo has integrated Ignion NTN/GPS patch antennas; no additional antenna hardware is required for satellite operation. The Notecard's cellular u.FL pigtail (steps 1–4 above) is the only antenna connection required inside the enclosure. +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. -**Starnote for Skylo:** Mount the Starnote in its own small IP65 weatherproof enclosure (see BOM) outside the main enclosure, with the clear polycarbonate lid facing the open sky. In the northern hemisphere, orient the lid toward the south and tilt it to maximize sky view. Attach the secondary enclosure to the top or side of the main enclosure, or to the hive stand upright, using exterior-grade fasteners or a stainless hose clamp. Drill an M16 cable-gland hole in the bottom of the Starnote enclosure, thread the 6-pin JST SH NTN cable through it, and seal with silicone. Run the cable into the main enclosure through a second M16 cable gland and plug it into the Notecard's onboard NTN JST port. Keep the cable run as short as practical — the supplied cable is sufficient for an adjacent-enclosure mount. Do not route the Starnote through the main enclosure: the Hammond 1554F2GY's opaque polycarbonate lid and any metal hardware inside the enclosure will attenuate or completely block the NTN and GPS patch antennas. +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. +3. Mount both antennas outside the enclosure with an unobstructed view of the sky. For satellite operation in the northern hemisphere, give the main antenna a clear view of the southern sky (toward the equator), where Skylo's GEO satellites sit; tilt and orient to maximize sky view. Route each through an M16 cable-gland port in the enclosure wall, or use a u.FL-to-SMA-F bulkhead pigtail (e.g. Adafruit #851) if you prefer an external SMA-mount antenna, securing the bulkhead with its lock nut from outside. + +Because the satellite link uses the same `MAIN` antenna as cellular, the placement that gives a good cellular signal also enables satellite fallback — there is no second module to mount and no JST cable to run. The opaque Hammond lid does not matter: both antennas live outside the box. **Mojo bench connection (remove before field deployment).** During bench commissioning, connect the second STEMMA QT / Qwiic cable from Mojo's Qwiic port to the Notecarrier CX Qwiic connector. The Notecard can then report the Mojo coulomb-counter tally (cumulative mAh, charge/discharge rate) in response to `card.power` requests issued from the blues.dev In-Browser Terminal. Remove the Mojo and Qwiic cable before sealing the field enclosure — the production firmware does not query Mojo in the deployed build. @@ -198,7 +196,7 @@ The SHT31-D address defaults to 0x44; it coexists on the I2C bus with the Noteca 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 coverage. The Notecard associates with your project on its first cellular sync. This initial sync is also essential for Starnote: it registers the device, downloads the current satellite ephemeris, and sets device time — all required before NTN transmissions will succeed. 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. 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/). **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. @@ -244,7 +242,7 @@ To open in Arduino IDE: **File → Open** and navigate to `firmware/apiary_hive_ | Responsibility | Where | |---|---| -| Notecard configuration (`hub.set`, disable accelerometer; no location configured, GPS receiver on Starnote is used internally by the satellite stack only) | `notecardConfigure()` | +| Notecard configuration (`hub.set`, `card.transport` `wifi-cell-ntn` for automatic cellular→Skylo satellite fallback, disable accelerometer; no location configured, the board's GPS receiver is used internally by the satellite stack only) | `notecardConfigure()` | | Note template definitions (compact, satellite-safe) | `defineTemplates()` | | Environment variable fetch and clamping | `fetchEnvOverrides()` | | HX711 10-sample weight average | `readWeightKg()` | @@ -272,7 +270,7 @@ These three features are averaged across the 12 windows and stored in the daily ### Event payload design -Two [template-backed](https://dev.blues.io/notecard/notecard-walkthrough/low-bandwidth-design#working-with-note-templates) Notefiles using `"format": "compact"` — required for NTN/Starnote operation and good practice regardless, as compact templates reduce on-wire payload size by 3–5× compared with free-form JSON. +Two [template-backed](https://dev.blues.io/notecard/notecard-walkthrough/low-bandwidth-design#working-with-note-templates) Notefiles using `"format": "compact"` — required for Skylo NTN (satellite) operation and good practice regardless, as compact templates reduce on-wire payload size by 3–5× compared with free-form JSON, keeping each Note well within the 256-byte NTN payload ceiling. `hive_summary.qo` (daily, templated compact): @@ -314,7 +312,9 @@ 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. -The initial sync cadence is set to `outbound: 1440` (daily) to minimize satellite transmission costs at NTN-only sites; `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 NTN data. Environment variable changes are applied on the next scheduled inbound sync. +`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. + +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. When `report_interval_hr` is changed in Notehub, the firmware automatically reissues `hub.set` with `outbound = report_interval_hr × 60` on the next wake cycle after the env var is picked up, keeping the Notecard's transmission schedule aligned with the local summary cadence. Changing `report_interval_hr` to `12` (for example) therefore both shortens the summary window and reduces the outbound sync interval to 720 minutes on the same wake cycle — no manual `hub.set` intervention required. @@ -328,7 +328,7 @@ When `report_interval_hr` is changed in Notehub, the firmware automatically reis ### Key code snippet 1: compact template definition -The `"format": "compact"` field is required for Starnote/NTN operation and cuts the per-Note wire size by 3–5× (e.g., a 200-byte JSON Note becomes ~40–80 bytes in compact form). `port` must be in the range 1–100. The numeric format codes (e.g., `14.1`, `12`) describe the wire encoding: `14.1` means a 4-byte IEEE 754 float, `12` means a 2-byte signed integer. The Notecard handles encoding/decoding automatically; no manual work required. +The `"format": "compact"` field is required for Skylo NTN (satellite) operation and cuts the per-Note wire size by 3–5× (e.g., a 200-byte JSON Note becomes ~40–80 bytes in compact form). `port` must be in the range 1–100. The numeric format codes (e.g., `14.1`, `12`) describe the wire encoding: `14.1` means a 4-byte IEEE 754 float, `12` means a 2-byte signed integer. The Notecard handles encoding/decoding automatically; no manual work required. ```cpp J *req = notecard.newRequest("note.template"); @@ -486,11 +486,11 @@ delay((uint32_t)sampleMin * 60000UL); | Cygnet + sensors active, weight + temp cycle (no audio) | ~15–30 mA, ~5–8 s/cycle | Whole-device estimate | | Cygnet + sensors active, weight + temp + audio cycle | ~20–40 mA, ~6–9 s/cycle | Whole-device estimate (audio adds ~5–30 mA × 0.75 seconds) | | Notecard low-power idle (between sessions, host off) | ~8–20 µA | Notecard datasheet | -| LTE Cat-1 bis cellular session | ~50–250 mA avg; ≤ 2 A peak | Notecard datasheet | -| Starnote NTN satellite uplink | ~100–300 mA during uplink | Starnote datasheet | +| Cellular session (BG95-S5 modem) | ~250 mA avg; brief peaks up to ~2 A for a few ms on a 2G burst | Notecard datasheet | +| 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 datasheet](https://dev.blues.io/datasheets/notecard-datasheet/note-mbglw/); 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 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. 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. @@ -507,7 +507,7 @@ Because the unit is solar-powered, the absolute mAh number matters less than the | Weight doesn't change between summaries, or only changes erratically | Load cell disconnected, or HX711 powered down before sleep | Verify all four load cell wires (E+, E-, A+, A-) are connected to HX711. Check that D5/D6 GPIO pins are not shorted or pulled low continuously. Confirm the HX711 sleep command is not being called prematurely. | | Audio features always show -9999 in summaries | Microphone disconnected, amplifier unpowered, or MAX9814 output clipped/floating | Verify A0 connection from MAX9814 to Notecarrier CX. Check that MAX9814 Vin and GND are connected to 3.3 V rail. Speak clearly into the microphone during the audio sample window (occurs on the first wake of each summary window, visible in debug output if `DEBUG_SERIAL` is enabled). | | Mojo shows no current draw, or > 500 mA continuous | Host not waking (ATTN pin not connected or not toggling), or firmware stuck in a loop | Verify Notecard `ATTN` pin is wired to Notecarrier CX `ATTN` (routed internally on the CX). Check firmware compile-time configuration and DEBUG_SERIAL output. If the unit draws power continuously with no pattern, the host is not sleeping — stop and debug firmware. | -| Starnote never transmits, even with sync:true alert | Initial cellular sync never completed, or Starnote power/antenna issue | The device must complete at least one successful cellular sync before NTN is enabled. Bring the unit into cellular coverage and force a `hub.sync` from Notehub. After the sync completes, alerts with `sync:true` will use satellite fallback if cellular is unavailable. Verify the Starnote clear polycarbonate enclosure lid faces the open sky. | +| Satellite (NTN) never transmits, even with sync:true alert | Initial cellular/WiFi sync never completed, `card.transport` not set to an `ntn` method, or antenna/sky-view issue | The device must complete at least one successful cellular or WiFi sync (which registers templates and downloads ephemeris) before NTN is enabled, and `card.transport` must be `wifi-cell-ntn` (set on first boot by `notecardConfigure()`). Bring the unit into cellular coverage and force a `hub.sync` from Notehub. After the sync completes, alerts with `sync:true` will fall back to satellite if cellular is unavailable. Verify the Skylo-certified `MAIN` antenna is mounted outdoors with a clear view of the (southern, northern-hemisphere) sky. | | Device claims to Notehub but doesn't pull environment variables | Inbound sync cadence too long (default 10080 minutes = 1 week) | During commissioning, force an immediate inbound sync by sending `{"req":"hub.sync"}` from the [Blues In-Browser Terminal](https://dev.blues.io/terminal/). Environment variable changes are pulled on the next scheduled inbound or after a manual sync. See §6 step 4 for commissioning settings. | ## 11. Limitations and Next Steps @@ -526,7 +526,7 @@ This reference design covers a single hive with a single load cell, exposed PCB- - **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. -- **Starnote connectivity requires initial cellular sync.** The device must complete at least one successful Notehub sync over cellular before NTN transmissions will work — Starnote needs time and location data to find satellites efficiently. A device deployed directly in a cellular dead zone will not transmit until it can be briefly brought into cellular coverage. +- **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. @@ -542,4 +542,4 @@ This reference design covers a single hive with a single load cell, exposed PCB- ## 12. Summary -The beekeeper who used to learn about a departed swarm three days after the fact now gets a daily weight-trend notification and an immediate alert the moment the hive loses 2 kg — wherever in the orchard, meadow, or forest edge the colony happens to live. Three sensors and a cellular Notecard turn the hive stand into a continuously monitored asset; the Starnote for Skylo closes the last gap when terrestrial coverage falls short of the apiary. Sampling runs every 15 minutes, the summary goes out once a day, and threshold alerts bypass the transmit timer entirely. Long-lived solar operation is achievable on the energy budget described in §4 and §10, but only after the commissioning steps in §9 — Mojo power validation, load-cell calibration, and a battery chemistry rated for the deployment climate. For a commercial beekeeper managing dozens of yards across a region, that's the difference between a minor nuisance and a significant economic loss — exactly the gap that cellular-first IoT is designed to close. +The beekeeper who used to learn about a departed swarm three days after the fact now gets a daily weight-trend notification and an immediate alert the moment the hive loses 2 kg — wherever in the orchard, meadow, or forest edge the colony happens to live. Three sensors and a single Notecard for Skylo — cellular, WiFi, and Skylo satellite on one module — turn the hive stand into a continuously monitored asset, reaching cellular where there's a tower and the Skylo satellite network where there isn't, with nothing to swap. Sampling runs every 15 minutes, the summary goes out once a day, and threshold alerts bypass the transmit timer entirely. Long-lived solar operation is achievable on the energy budget described in §4 and §10, but only after the commissioning steps in §9 — Mojo power validation, load-cell calibration, and a battery chemistry rated for the deployment climate. For a commercial beekeeper managing dozens of yards across a region, that's the difference between a minor nuisance and a significant economic loss — exactly the gap that cellular-first IoT is designed to close. diff --git a/66-remote-apiary-hive-health-monitor/diagrams/01-system-architecture.svg b/66-remote-apiary-hive-health-monitor/diagrams/01-system-architecture.svg index 04a3d0d3..021a56e9 100644 --- a/66-remote-apiary-hive-health-monitor/diagrams/01-system-architecture.svg +++ b/66-remote-apiary-hive-health-monitor/diagrams/01-system-architecture.svg @@ -31,25 +31,18 @@ (acoustic ZCR) - + Edge enclosure Notecarrier CX - Cygnet STM32L433 - Notecard Cell+WiFi - (MBGLW) + Cygnet STM32L433 + Notecard for Skylo + (NOTE-NBGLWX) + cellular · WiFi · satellite - samples · rules · sleep - - - - - 6-pin JST NTN cable - - Starnote for Skylo - (ext. mount · NTN satellite) + samples · rules · sleep diff --git a/66-remote-apiary-hive-health-monitor/diagrams/02-wiring-assembly.svg b/66-remote-apiary-hive-health-monitor/diagrams/02-wiring-assembly.svg index 3533e5ed..3c8f6feb 100644 --- a/66-remote-apiary-hive-health-monitor/diagrams/02-wiring-assembly.svg +++ b/66-remote-apiary-hive-health-monitor/diagrams/02-wiring-assembly.svg @@ -27,7 +27,8 @@ Notecarrier CX - Cygnet STM32L433 · MBGLW · Starnote + Cygnet STM32L433 · Notecard for Skylo + (cellular · WiFi · satellite) diff --git a/66-remote-apiary-hive-health-monitor/firmware/apiary_hive_monitor/apiary_hive_monitor.ino b/66-remote-apiary-hive-health-monitor/firmware/apiary_hive_monitor/apiary_hive_monitor.ino index 776a7760..f065981e 100644 --- a/66-remote-apiary-hive-health-monitor/firmware/apiary_hive_monitor/apiary_hive_monitor.ino +++ b/66-remote-apiary-hive-health-monitor/firmware/apiary_hive_monitor/apiary_hive_monitor.ino @@ -1,8 +1,8 @@ /*************************************************************************** apiary_hive_monitor.ino — Remote Apiary Hive Health Monitor - Blues Notecarrier CX (Cygnet STM32L433) + Notecard Cell+WiFi + Starnote - for Skylo. Reads hive weight (HX711 + load cell), brood-box temperature + Blues Notecarrier CX (Cygnet STM32L433) + Notecard for Skylo + (NOTE-NBGLWX). Reads hive weight (HX711 + load cell), brood-box temperature and humidity (SHT31-D), and acoustic features (ZCR, RMS, peak) from an analog microphone — no raw audio is buffered or transmitted. Pushes compact-template daily summaries plus immediate alerts for weight @@ -10,8 +10,9 @@ Hardware: - Notecarrier CX (onboard Cygnet STM32L433 host MCU) - - Notecard Cell+WiFi (MBGLW) in M.2 slot - - Starnote for Skylo via 6-pin JST NTN cable to Notecard + - Notecard for Skylo (NOTE-NBGLWX) in M.2 slot — cellular + WiFi + + Skylo satellite (NTN) on one board; card.transport selects WiFi/ + cellular-primary with automatic satellite fallback (notecardConfigure()) - SparkFun HX711 Load Cell Amplifier (SEN-13879) → D5 / D6 - Zemic H8C 100 kg single-ended shear-beam load cell (Wheatstone bridge) → HX711 - Adafruit SHT31-D Temperature & Humidity Sensor (#2857) → SDA / SCL @@ -134,7 +135,7 @@ void setup() { // ---- Abort cycle if boot config is incomplete ----------------------- // Compact templates (hive_summary.qo / hive_alert.qo) must be registered - // before any note.add so that Starnote compact-payload encoding is + // before any note.add so that Skylo NTN compact-payload encoding is // guaranteed. If notecardConfigure() or defineTemplates() failed this // wake, persist state and sleep immediately — no env fetch, no sensor // reads, no note emission. first_boot stays true so the next wake diff --git a/66-remote-apiary-hive-health-monitor/firmware/apiary_hive_monitor/apiary_hive_monitor_helpers.cpp b/66-remote-apiary-hive-health-monitor/firmware/apiary_hive_monitor/apiary_hive_monitor_helpers.cpp index f55513cf..e774d3d3 100644 --- a/66-remote-apiary-hive-health-monitor/firmware/apiary_hive_monitor/apiary_hive_monitor_helpers.cpp +++ b/66-remote-apiary-hive-health-monitor/firmware/apiary_hive_monitor/apiary_hive_monitor_helpers.cpp @@ -4,10 +4,12 @@ Contains: notecardConfigure() — hub.set (daily outbound / weekly inbound), - accelerometer disable; called once on first boot. + card.transport (wifi-cell-ntn) for automatic + cellular→Skylo satellite failover, accelerometer + disable; called once on first boot. defineTemplates() — registers compact Note templates for hive_summary.qo (port 10) and hive_alert.qo - (port 11); required for Starnote NTN operation. + (port 11); required for Skylo NTN operation. fetchEnvOverrides() — pulls operator thresholds from Notehub env vars, applies individual range clamps, then validates the temp_low_c / temp_high_c pair together before storing. @@ -97,6 +99,26 @@ bool notecardConfigure(bool freshBoot, const char *productUID) { return false; } + // Transport selection for the Notecard for Skylo (NOTE-NBGLWX). + // The board carries WiFi, cellular, and Skylo satellite (NTN) radios, but + // satellite fallback is NOT enabled by default — the factory transport is + // "wifi-cell" (WiFi preferred, cellular fallback, no NTN). Set "wifi-cell-ntn" + // so the Notecard prefers WiFi where an apiary AP is reachable, falls back to + // cellular (the primary at most orchard/meadow sites), and finally to Skylo + // satellite where there is no terrestrial coverage — automatic failover with + // no firmware branching. The Notecard persists this setting in its own flash, + // so issuing it once on first boot is sufficient. + // + // Note: Skylo requires at least one non-NTN (cellular or WiFi) sync to + // associate with Notehub and register templates before NTN can be used. In + // "periodic" mode the cold-boot hub.set above triggers that first sync over + // cellular/WiFi, so commission each unit where it has terrestrial coverage + // even if it will routinely operate over satellite. Non-critical at the + // transport level; a failure here is retried on the next cold boot. + req = notecard.newRequest("card.transport"); + JAddStringToObject(req, "method", "wifi-cell-ntn"); + notecard.sendRequest(req); + // Disable accelerometer — reduces idle interrupt noise on Mojo power trace. // Non-critical; failure does not prevent Notecard from operating normally. req = notecard.newRequest("card.motion.mode"); @@ -104,14 +126,14 @@ bool notecardConfigure(bool freshBoot, const char *productUID) { notecard.sendRequest(req); // This design does not configure or use device location — no - // card.location.mode call is issued. The Starnote's integrated GPS + // card.location.mode call is issued. The Notecard for Skylo's GPS/GNSS // receiver is used internally by the satellite stack for timing and // ephemeris only; location data is not read or transmitted by the host. return true; } // =========================================================================== -// defineTemplates — compact templates required for Starnote NTN operation +// defineTemplates — compact templates required for Skylo NTN operation // Returns true only if both templates registered without a Notecard error. // =========================================================================== bool defineTemplates(void) { diff --git a/66-remote-apiary-hive-health-monitor/firmware/apiary_hive_monitor/apiary_hive_monitor_helpers.h b/66-remote-apiary-hive-health-monitor/firmware/apiary_hive_monitor/apiary_hive_monitor_helpers.h index e074a3e0..195fb6df 100644 --- a/66-remote-apiary-hive-health-monitor/firmware/apiary_hive_monitor/apiary_hive_monitor_helpers.h +++ b/66-remote-apiary-hive-health-monitor/firmware/apiary_hive_monitor/apiary_hive_monitor_helpers.h @@ -10,8 +10,8 @@ Hardware context: - Notecarrier CX (onboard Cygnet STM32L433 host MCU) - - Notecard Cell+WiFi (MBGLW) in M.2 slot - - Starnote for Skylo via 6-pin JST NTN cable + - Notecard for Skylo (NOTE-NBGLWX) in M.2 slot — cellular + WiFi + + Skylo satellite (NTN) on one board - SparkFun HX711 (SEN-13879) + Zemic H8C single-ended shear-beam load cell - Adafruit SHT31-D (#2857) via 0.1″ jumper wires on SDA/SCL - Adafruit MAX9814 (#1713) analog microphone on A0 @@ -87,7 +87,7 @@ extern Adafruit_SHT31 sht31; // Returns true on success; false if a critical step fails (retry next wake). bool notecardConfigure(bool freshBoot, const char *productUID); -// Register compact Note templates compatible with Starnote NTN. +// Register compact Note templates compatible with Skylo NTN. // Returns true only if both templates registered without error. bool defineTemplates(void); diff --git a/75-heavy-equipment-hours-of-use-utilization-tracker/firmware/equipment_hours_tracker/equipment_hours_tracker.ino b/75-heavy-equipment-hours-of-use-utilization-tracker/firmware/equipment_hours_tracker/equipment_hours_tracker.ino index 768545ab..3a6f0ef4 100644 --- a/75-heavy-equipment-hours-of-use-utilization-tracker/firmware/equipment_hours_tracker/equipment_hours_tracker.ino +++ b/75-heavy-equipment-hours-of-use-utilization-tracker/firmware/equipment_hours_tracker/equipment_hours_tracker.ino @@ -3,6 +3,9 @@ * * Hardware: Blues Notecarrier CX (Cygnet STM32L4) + Notecard for Skylo * (NOTE-NBGLWX) + Adafruit LSM6DSOX accelerometer (I2C, #4517) + * Connectivity uses automatic WiFi→cellular→Skylo-satellite (NTN) + * fallback so assets stay reportable beyond terrestrial coverage + * (enabled in notecardConfigure() via card.transport "wifi-cell-ntn"). * * On each 30-second wake the host: restores persisted state, fetches env vars, * samples accelerometer for 2 s at 104 Hz, classifies vibration as IDLE / diff --git a/75-heavy-equipment-hours-of-use-utilization-tracker/firmware/equipment_hours_tracker/equipment_hours_tracker_helpers.cpp b/75-heavy-equipment-hours-of-use-utilization-tracker/firmware/equipment_hours_tracker/equipment_hours_tracker_helpers.cpp index 41cdbfe8..78c4ed4e 100644 --- a/75-heavy-equipment-hours-of-use-utilization-tracker/firmware/equipment_hours_tracker/equipment_hours_tracker_helpers.cpp +++ b/75-heavy-equipment-hours-of-use-utilization-tracker/firmware/equipment_hours_tracker/equipment_hours_tracker_helpers.cpp @@ -114,6 +114,20 @@ bool notecardConfigure(void) { return false; } + // Transport: enable WiFi→cellular→Skylo-satellite (NTN) automatic fallback. + // NTN is OFF by default on the Notecard for Skylo (NOTE-NBGLWX) — the factory + // transport never reaches the satellite radio, so without this request the + // device would silently lose connectivity beyond terrestrial coverage instead + // of falling back to satellite. "wifi-cell-ntn" lets the Notecard prefer + // WiFi, fall back to cellular, then to Skylo NTN, with no firmware branching. + // Note: Skylo requires at least one non-NTN (cellular/WiFi) sync first to + // associate with Notehub and register templates before NTN can be used; the + // cold-boot hub.set above triggers that initial terrestrial sync. The setting + // persists in the Notecard's own flash, so issuing it once at cold boot suffices. + req = notecard.newRequest("card.transport"); + JAddStringToObject(req, "method", "wifi-cell-ntn"); + if (!checkedRequest(req)) return false; + // Periodic GPS: acquire a fix every GPS_PERIOD_SECONDS (15 min). req = notecard.newRequest("card.location.mode"); JAddStringToObject(req, "mode", "periodic"); diff --git a/89-pallet-attached-cold-chain-logger/README.md b/89-pallet-attached-cold-chain-logger/README.md index 5cbdb379..f7737556 100644 --- a/89-pallet-attached-cold-chain-logger/README.md +++ b/89-pallet-attached-cold-chain-logger/README.md @@ -514,7 +514,7 @@ The logger commits to a specific scope: independent, pallet-level evidence with **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, Starnote for Iridium (LEO constellation, global coverage even inside container terminals) is an alternative or supplement. +- **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. - **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. diff --git a/89-pallet-attached-cold-chain-logger/firmware/cargo_cold_chain_monitor/cargo_cold_chain_monitor.ino b/89-pallet-attached-cold-chain-logger/firmware/cargo_cold_chain_monitor/cargo_cold_chain_monitor.ino index 0673b693..1a888169 100644 --- a/89-pallet-attached-cold-chain-logger/firmware/cargo_cold_chain_monitor/cargo_cold_chain_monitor.ino +++ b/89-pallet-attached-cold-chain-logger/firmware/cargo_cold_chain_monitor/cargo_cold_chain_monitor.ino @@ -176,6 +176,7 @@ void setup() { if (gState.config_version != CONFIG_VERSION) { Serial.println("[cargo] config version mismatch — forcing Notecard reconfiguration"); gState.hub_configured = false; + gState.transport_configured = false; gState.motion_configured = false; gState.templates_registered = false; gState.config_version = CONFIG_VERSION; diff --git a/89-pallet-attached-cold-chain-logger/firmware/cargo_cold_chain_monitor/cargo_cold_chain_monitor_helpers.cpp b/89-pallet-attached-cold-chain-logger/firmware/cargo_cold_chain_monitor/cargo_cold_chain_monitor_helpers.cpp index 62e2cebc..416cee7b 100644 --- a/89-pallet-attached-cold-chain-logger/firmware/cargo_cold_chain_monitor/cargo_cold_chain_monitor_helpers.cpp +++ b/89-pallet-attached-cold-chain-logger/firmware/cargo_cold_chain_monitor/cargo_cold_chain_monitor_helpers.cpp @@ -89,6 +89,33 @@ void notecardConfigure() { } if (rsp) notecard.deleteResponse(rsp); + // card.transport — enable the automatic WiFi → cellular → Skylo satellite + // (NTN) fallback that the README promises. NTN is OFF by default on the + // Notecard for Skylo (NOTE-NBGLWX): the factory transport never reaches the + // satellite radio, so without this request queued alerts would sit in flash + // forever once the pallet leaves terrestrial coverage. "wifi-cell-ntn" + // prefers WiFi where a provisioned AP is reachable (a connected DC), falls + // back to cellular over road and rail, and finally to Skylo NTN where + // neither is available and the antenna has sky exposure — with no firmware + // branching. + // + // An initial non-NTN (cellular or WiFi) sync is required first so the device + // can associate with Notehub and register templates before NTN is usable; + // the cold-boot hub.set above triggers that first terrestrial sync, so + // commission each unit where it has cellular/WiFi coverage. The Notecard + // persists this setting in its own flash, so issuing it once per cold boot + // is sufficient. + if (!gState.transport_configured) { + req = notecard.newRequest("card.transport"); + JAddStringToObject(req, "method", "wifi-cell-ntn"); + if (ncSend(req)) { + gState.transport_configured = true; + Serial.println("[cargo] card.transport configured (wifi-cell-ntn)"); + } else { + Serial.println("[cargo] card.transport failed — will retry on next wake"); + } + } + if (!gState.motion_configured) { req = notecard.newRequest("card.motion.mode"); JAddBoolToObject(req, "start", true); diff --git a/89-pallet-attached-cold-chain-logger/firmware/cargo_cold_chain_monitor/cargo_cold_chain_monitor_helpers.h b/89-pallet-attached-cold-chain-logger/firmware/cargo_cold_chain_monitor/cargo_cold_chain_monitor_helpers.h index 3b99f951..e815952a 100644 --- a/89-pallet-attached-cold-chain-logger/firmware/cargo_cold_chain_monitor/cargo_cold_chain_monitor_helpers.h +++ b/89-pallet-attached-cold-chain-logger/firmware/cargo_cold_chain_monitor/cargo_cold_chain_monitor_helpers.h @@ -54,8 +54,9 @@ // // CONFIG_VERSION is stored in gState.config_version at configuration time // and compared against the compiled value on every warm boot. A mismatch -// clears hub_configured, motion_configured, and templates_registered so -// hub.set, card.motion.mode, and note.template are fully reapplied. +// clears hub_configured, transport_configured, motion_configured, and +// templates_registered so hub.set, card.transport, card.motion.mode, and +// note.template are fully reapplied. // // Note: CONFIG_VERSION does NOT encode PRODUCT_UID. hub.set is re-issued // on every warm boot (see setup()) so a reflash with a new PRODUCT_UID @@ -188,6 +189,7 @@ struct ColdChainState { // ── Configuration-retry flags ──────────────────────────────────────────── bool hub_configured; + bool transport_configured; bool motion_configured; bool templates_registered; uint32_t config_version;