diff --git a/52-vfd-pump-predictive-maintenance/README.md b/52-vfd-pump-predictive-maintenance/README.md index 4aa60f6b..1484816f 100644 --- a/52-vfd-pump-predictive-maintenance/README.md +++ b/52-vfd-pump-predictive-maintenance/README.md @@ -8,19 +8,19 @@ This reference application is intended to provide inspiration and help you get s -This project is a [downtime prevention](https://blues.com/downtime-prevention/) reference design that turns an industrial centrifugal pump into a predictively-maintained, remotely-monitored asset by reading what the pump's existing **VFD** (variable frequency drive) already knows about itself — over **Modbus RTU**, on a real industrial **PLC** (programmable logic controller), with a cellular [Notecard](https://shop.blues.com/products/notecard-cellular?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) for the uplink. +This project is a [downtime prevention](https://blues.com/downtime-prevention/) reference design that turns an industrial centrifugal pump into a predictively-maintained, remotely-monitored asset by reading what the pump's existing **VFD (variable frequency drive)** already knows about itself over **Modbus RTU**, on a real industrial **PLC** (programmable logic controller), with a cellular [Notecard](https://shop.blues.com/products/notecard-cellular?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) for the data uplink. ## 1. Project Overview **The problem.** Industrial centrifugal pumps almost universally run behind a VFD. Modern drives from ABB, Yaskawa, Danfoss, and Schneider all expose the pump's operating telemetry through Modbus holding registers — motor current, output frequency, output torque, drive temperature, runtime hours, active fault code, and almost nobody reads them. The VFD is sitting in the cabinet doing the work; the data is right there. What's missing is the network path off the plant floor. -A failing pump rarely just stops. It signals first: motor current can shift at constant frequency as bearing drag, fouling, valve position, fluid viscosity, or impeller condition change the load on the drive. Transient electrical faults can cluster on a stressed contactor or in a cavitating hydraulic regime. Actual runtime can drift above expected duty cycle as a downstream valve fouls and the pump runs longer to do the same work. None of these telemetry shifts are *diagnostic* by themselves, but they are leading indicators a maintenance team would happily act on a week early. This project is the device that catches those anomalies and routes them out, before a tank runs dry on a Saturday night. See the [Signal limitations](#12-limitations-and-next-steps) Note for what this telemetry can and cannot conclude. +A failing pump rarely just stops. It signals first: motor current can shift at constant frequency as bearing drag, fouling, valve position, fluid viscosity, or impeller condition change the load on the drive. Transient electrical faults can cluster on a stressed contactor or in a cavitating hydraulic regime. Actual runtime can drift above expected duty cycle as a downstream valve fouls and the pump runs longer to do the same work. *None of these telemetry shifts are diagnostic by themselves*, but they are leading indicators a maintenance team would happily act on a week early. This project is the device that catches those anomalies and routes them out, before a tank runs dry on a Saturday night. See the [Signal limitations](#12-limitations-and-next-steps) note for what this telemetry can and cannot conclude. -**Why Notecard.** Pump rooms sit on isolated **OT** (operational technology) networks where corporate WiFi is off-limits for instrumentation by plant policy, and retrofitting a separate OT-friendly access point per pump is unrealistic. Cellular removes the dependency on plant LAN credentials, VLAN provisioning, site WiFi, or a local gateway. (Some sites will still require OT/security review before *any* wireless instrumentation is allowed; the device just doesn't need access to the plant network itself.) The Notecard's prepaid global cellular service means the same firmware and architecture deploys across regions — choose the matching Wireless for OPTA cellular variant for the deployment geography. WiFi remains as an opportunistic fallback for the rare site that *can* offer a rooftop AP, without compromising the cellular-first model. +**Why Notecard.** Pump rooms sit on isolated OT (operational technology) networks where corporate WiFi is off-limits for instrumentation by plant policy, and retrofitting a separate OT-friendly access point per pump is unrealistic. Cellular removes the dependency on plant LAN credentials, VLAN provisioning, site WiFi, or a local gateway. (Some sites will still require OT/security review before *any* wireless instrumentation is allowed; the device just doesn't need access to the plant network itself.) The Notecard's bundled global cellular data and service means the same firmware and architecture deploys across regions — choose the matching [Blues Wireless for OPTA](https://shop.blues.com/products/wireless-for-opta?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) cellular variant for the deployment geography. WiFi remains as an opportunistic fallback for the rare site that *can* offer a rooftop AP, without compromising the cellular-first model. -**Why OPTA.** This is exactly the sweet spot for Wireless for OPTA: a real industrial PLC reading a real industrial Modbus device, with no PC or gateway in the middle. The Arduino OPTA is DIN-rail-mounted, 12–24 VDC powered, and programmable with both Arduino sketches and IEC 61131-3 PLC languages, so it deploys exactly the same way across plants whose IT and OT teams will never agree on a network plan. Pairing it with Blues Wireless for OPTA adds cellular and WiFi to a device that already speaks the language of the plant. +**Why OPTA.** This is exactly the sweet spot for Wireless for OPTA: a real industrial PLC reading a real industrial Modbus device, with no PC or gateway in the middle. The [Arduino OPTA](https://www.arduino.cc/pro/hardware-arduino-opta/) is DIN-rail-mounted, 12–24 VDC powered, and programmable with both Arduino sketches and IEC 61131-3 PLC languages, so it deploys exactly the same way across plants whose IT and OT teams will never agree on a network plan. Pairing it with Blues Wireless for OPTA adds cellular and WiFi to a device that already speaks the language of the plant. **Deployment scenario.** A single OPTA + Wireless for OPTA mounted on the DIN rail next to the VFD inside the pump's electrical panel, RS-485 daisied to the drive's communication port, antenna routed out through a cable gland to a magnetic-mount whip on the cabinet roof. Line power from a 24 VDC panel supply that's already there. No PC, no gateway, no plant LAN involvement. @@ -28,24 +28,24 @@ A failing pump rarely just stops. It signals first: motor current can shift at c ![System architecture: VFD ↔ Modbus RTU over RS-485 ↔ OPTA + Wireless for OPTA ↔ cellular ↔ Notehub ↔ customer cloud](diagrams/01-system-architecture.svg) -**Device-side responsibilities.** Inside the pump panel, the OPTA's Cortex-M7 plays Modbus RTU **client** (master) to the VFD's **server** (slave), polling six holding registers across the onboard RS-485 transceiver once a minute. Between polls it accumulates rolling hourly statistics — mean, peak, count — in RAM and runs four anomaly-detection rules against them, deciding event-by-event whether the plant cares about what it just saw. When something is worth reporting, the host hands a JSON Note to the Notecard over I²C through Blues Wireless for OPTA's AUX connector. No modem AT commands, no session state machine, no raw socket management — the `note-arduino` library's `JAdd*` helpers build the request and the Notecard takes it from there. +**Device-side responsibilities.** Inside the pump panel, the OPTA's Cortex-M7 plays Modbus RTU **client** (master) to the VFD's **server** (slave), polling six holding registers across the onboard RS-485 transceiver once a minute. Between polls it accumulates rolling hourly statistics — mean, peak, count — in RAM and runs four anomaly-detection rules against them, deciding event-by-event whether the plant cares about what it just saw. When something is worth reporting, the host hands a JSON [Note](https://dev.blues.io/api-reference/glossary/#note) to the Notecard over I²C through Blues Wireless for OPTA's AUX connector. No modem AT commands, no session state machine, no raw socket management — the `note-arduino` library's `JAdd*` helpers build the request and the Notecard takes it from there. -**Notecard responsibilities.** The Notecard's on-device queue holds every [Note](https://dev.blues.io/api-reference/glossary/#note) the host writes, then ships them out on the [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence (default hourly). Anything tagged `sync:true` jumps the queue and the radio comes up immediately. The same module also pulls [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) on every inbound sync, which is what lets a maintenance lead retune thresholds — or even point the firmware at a different drive vendor's register addresses — from a browser, without anyone visiting the panel. +**Notecard responsibilities.** The Notecard's on-device queue holds every Note the host writes, then ships them out on the [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence (default hourly). Anything tagged `sync:true` jumps the queue and the radio comes up immediately. The same module also pulls [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) on every inbound sync, which is what lets a maintenance lead retune thresholds — or even point the firmware at a different drive vendor's register addresses — from a browser, without anyone visiting the panel. **Notehub responsibilities.** [Notehub](https://notehub.io) is where the events land — every one ingested, every one stored, project-level [routes](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub) fanning them onward. Because every plant's VFDs may sit at different register addresses, the per-fleet [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) story is what keeps a single firmware image servicing an ABB plant in Ohio and a Yaskawa plant in São Paulo. See [Smart Fleets](https://dev.blues.io/notehub/notehub-walkthrough/#using-smart-fleet-rules) for how to organize them by vendor or site. -**Routing to the cloud (high level).** Notehub supports HTTP, MQTT, AWS, Azure, GCP, Snowflake, and several other destinations; route setup is project-specific. See the [Notehub routing docs](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub) — this project ships no specific downstream endpoint. +**Routing to the cloud (high level).** Notehub supports HTTP, MQTT, AWS, Azure, GCP, Snowflake, and several other destinations; route setup is project-specific. See the [Notehub routing docs](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub) for more information. ## 3. Technical Summary -**What you'll have when done:** An OPTA + Notecard assembly mounted in a pump panel, reading six telemetry registers from the VFD once per minute, reporting hourly summaries to [Notehub](https://notehub.io), and emitting immediate alerts when four anomaly rules trigger. +**What you'll have when done:** An OPTA + Notecard assembly mounted in a pump panel, reading six telemetry registers from the VFD once per minute, reporting hourly summaries to Notehub, and emitting immediate alerts when four anomaly rules trigger. **Minimum steps** (60–90 minutes, assuming site access and a calibrated VFD): 1. Install Arduino core + libraries (`Arduino Mbed OS Opta Boards`, `note-arduino`, `ArduinoModbus`, `ArduinoRS485`) via Library Manager. 2. Set `PRODUCT_UID` in the firmware; compile and flash via `arduino-cli` (see [§8. Build and Flash](#8-build-and-flash) below). 3. On Notehub: create project, claim Notecard, create one fleet, set `modbus_slave_id` and `modbus_baud` to match your VFD's configuration. 4. Wire OPTA RS-485 to VFD Modbus port; confirm 120 Ω termination at each end of the bus. -5. Power up and monitor Notehub's In-Browser Terminal: `card.status` should report healthy; first `vfd_summary.qo` Note appears within ~60 s. +5. Power up and monitor via a serial monitor: `card.status` should report healthy; first `vfd_summary.qo` Note appears within ~60 s. Here is a sample Note this device emits: @@ -67,17 +67,21 @@ Here is a sample Note this device emits: | Part | Qty | Rationale | |------|-----|-----------| | [Arduino OPTA RS485](https://store.arduino.cc/products/opta-rs485) | 1 | Industrial PLC with onboard RS-485 transceiver, DIN-rail mount, 12–24 VDC supply. Programmable with Arduino sketches or IEC 61131-3 PLC languages. Hosts the Modbus client and edge logic. | -| [Blues Wireless for OPTA (NA, SKU 992-00155-C)](https://shop.blues.com/products/wireless-for-opta?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Snaps onto the OPTA's expansion port; adds a [Notecard Cell+WiFi (MBNAW)](https://dev.blues.io/datasheets/notecard-datasheet/note-wbnaw/) over I²C. Cellular coverage is regional — pick the matching SKU for the deployment geography (EMEA variant: [SKU 992-00156-C](https://shop.blues.com/products/wireless-for-opta?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link)). The Notecard manages its own cellular session against supported carrier networks worldwide via its embedded global SIM. | +| [Blues Wireless for OPTA](https://shop.blues.com/products/wireless-for-opta?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Snaps onto the OPTA's expansion port; adds a [Notecard Cell+WiFi (WBNAW)](https://dev.blues.io/datasheets/notecard-datasheet/note-wbnaw/) over I²C. Cellular coverage is regional — pick the matching SKU for the deployment geography. The Notecard manages its own cellular session against supported carrier networks worldwide via its embedded global SIM. | | External cellular antenna(s) w/ SMA, ~3m lead (e.g. [SparkFun CEL-16432](https://www.sparkfun.com/lte-hinged-external-antenna-698mhz-2-7ghz-sma-male.html)) | 1 required, 2 recommended | At minimum, route the **primary** cellular antenna outside any metal cabinet; rubber-duck antennas inside a steel panel will not work reliably. For best LTE Cat-1 performance also route the **diversity** antenna externally if the layout allows it. SMA bulkhead leads through cable glands keep the IP rating intact. | -| [Mojo](https://shop.blues.com/products/mojo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Bench-only coulomb counter for validating the Wireless-for-OPTA + Notecard subsystem energy per session during commissioning. Not deployed to the field. | +| [Mojo](https://shop.blues.com/products/mojo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Coulomb counter for validating the Wireless for OPTA + Notecard subsystem energy per session during commissioning. Not deployed to the field. | | 24 VDC DIN-rail supply, ≥10W (e.g. [MeanWell HDR-15-24](https://www.meanwell.com/Upload/PDF/HDR-15/HDR-15-SPEC.PDF)) | 1 | Powers OPTA and expansion. Most pump panels already have one — only buy if needed. | | 120 Ω termination resistor | 1–2 | RS-485 termination at each end of the bus. The OPTA's onboard transceiver does not include a permanent terminator. | | Shielded twisted pair, 22 AWG, RS-485 rated, ~1m | 1 | A → A, B → B, shield → drive ground. Length depends on the panel layout. | | DIN rail, ~10 cm | 1 | Mount for the OPTA + expansion. Likely already present in the panel. | + + The Arduino OPTA WiFi variant works equally well if WiFi/BLE on the host MCU is desired; the firmware is unchanged. The OPTA Lite that ships in the standard Wireless for OPTA bundle has **no onboard RS-485** and is not suitable for this project. -The Blues hardware ships with an active SIM including 500 MB of data and 10 years of service — no activation fees, no monthly commitment. + + +The Blues hardware ships with an active SIM bundled with 500 MB of data and 10 years of service — no activation fees, no monthly commitment. ## 5. Wiring and Assembly @@ -97,7 +101,7 @@ The Blues hardware ships with an active SIM including 500 MB of data and 10 year - OPTA `COM` (RS-485 GND) → VFD communication ground (consult the drive's manual; ABB ACS580 calls it `AGND`, Yaskawa GA500 calls it `SC`, Danfoss FC-302 calls it `Common`). - Place a 120 Ω resistor across A/B at *each* end of the bus. With one OPTA and one drive, that means two terminators total (one at each device). 4. **Drive configuration.** Configure the VFD as a Modbus RTU **server** (slave); the OPTA acts as the Modbus **client** (master). Defaults the firmware ships with: slave ID `1`, baud rate `19200`, 8 data bits, no parity, 1 stop bit (`8N1`). Real drives vary — match baud, parity, stop bits, and slave address to whatever the VFD is configured for, and override the firmware's defaults via the `modbus_*` environment variables on Notehub. Common vendor parameter groups: ABB `5800–5805`, Yaskawa `H5-xx`, Danfoss `8-3x`, Schneider `Comm-1.x`. -5. **Bench validation.** During first-light testing, splice the Mojo inline between the 24 VDC supply and the Wireless-for-OPTA power input so it can measure the *expansion + Notecard subsystem* energy per session. The OPTA itself is line-powered and not the subject of measurement. +5. **Bench validation.** During first-light testing, splice the Mojo inline between the 24 VDC supply and the Wireless for OPTA power input so it can measure the *expansion + Notecard subsystem* energy per session. The OPTA itself is line-powered and not the subject of measurement. ## 6. Notehub Setup @@ -127,7 +131,11 @@ The Blues hardware ships with an active SIM including 500 MB of data and 10 year | `drive_temp_alarm_c` | `75.0` | Drive heatsink °C above which `drive_overtemp` fires. | | `expected_run_hours_per_day` | `12.0` | Expected runtime per day; runtime drift > 25% above this fires `runtime_drift`. | - > **VFD register-map gotchas.** The defaults above are illustrative only. Real VFDs differ on: 0-based vs 1-based addressing conventions (Modicon "40001" notation vs raw); per-register scaling (current may be 0.1 A, 0.01 A, or % of rated); signedness (torque and temperature are often signed); 32-bit values that span two registers (runtime hours often does, with vendor-specific word order); and active-fault-code vs fault-history-log distinction. The shipped firmware reads six contiguous 16-bit registers with hardcoded scaling — production deployments need a vendor-specific firmware build with proper handling. + + + **VFD register-map gotchas.** The defaults above are illustrative only. Real VFDs differ on: 0-based vs 1-based addressing conventions (Modicon "40001" notation vs raw); per-register scaling (current may be 0.1 A, 0.01 A, or % of rated); signedness (torque and temperature are often signed); 32-bit values that span two registers (runtime hours often does, with vendor-specific word order); and active-fault-code vs fault-history-log distinction. The shipped firmware reads six contiguous 16-bit registers with hardcoded scaling — production deployments need a vendor-specific firmware build with proper handling. + + 5. **Configure routes.** Add one [route](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub) for `vfd_event.qo` (alerts, low-volume, real-time delivery to a CMMS or on-call endpoint) and a second for `vfd_summary.qo` (long-term storage, batched delivery to an analytics/historian system). Splitting the two Notefiles at the source means each can be fanned out to a different destination at a different urgency without filter logic in the route. @@ -161,7 +169,7 @@ Polling cadence is `sample_minutes` (default 1 minutes). For each sample, `accum ### Event payload design -Two [template-backed](https://dev.blues.io/notecard/notecard-walkthrough/low-bandwidth-design#working-with-note-templates) Notefiles. Templates give summary and alert records a stable schema, store as fixed-length records on the Notecard rather than free-form JSON, and minimize on-wire payload size — material at 24 summary Notes per day per pump over a multi-year deployment. Actual cellular data usage depends on sync cadence, signal conditions, routing behavior, and event frequency, so production deployments should validate usage with [Notehub usage data](https://dev.blues.io/notehub/notehub-walkthrough/#configuring-your-billing-account) before sizing SIM data plans. +Two [template-backed](https://dev.blues.io/notecard/notecard-walkthrough/low-bandwidth-design#working-with-note-templates) Notefiles. Templates give summary and alert records a stable schema, store as fixed-length records on the Notecard rather than free-form JSON, and minimize on-wire payload size — material at 24 summary Notes per day per pump over a multi-year deployment. Actual cellular data usage depends on sync cadence, signal conditions, routing behavior, and event frequency, so production deployments should validate usage with [Notehub usage data](https://dev.blues.io/notecard/notecard-walkthrough/low-bandwidth-design/#viewing-usage-data-on-notehub). `vfd_summary.qo` (hourly): @@ -311,7 +319,7 @@ if (g_baseline_seeded[bin] && ## 10. Validation and Testing -Expected steady-state behavior on a healthy pump: one summary Note per hour and zero event Notes. The Notecard's [`card.status`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-status) and [`hub.status`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-status) requests are useful smoke tests during commissioning — both can be issued from the blues.dev In-Browser Terminal. +Expected steady-state behavior on a healthy pump: one summary Note per hour and zero event Notes. The Notecard's [`card.status`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-status) and [`hub.status`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-status) requests are useful smoke tests during commissioning. **Modbus first-light.** Before connecting to the real drive, run the firmware against a [USB-to-RS-485 adapter](https://www.sparkfun.com/products/9822) and a software Modbus simulator (Modbus Mechanic, ModRSsim2, or equivalent) wired to the OPTA's RS-485 terminals. Verify the six register reads match what the simulator is publishing. @@ -323,7 +331,7 @@ Expected steady-state behavior on a healthy pump: one summary Note per hour and | Modem active (cellular session) | ~250 mA average, with ≤2 A bursts during GSM transmit | | WiFi active (when WiFi fallback engaged) | ~80 mA average | -Splice the [Mojo](https://shop.blues.com/products/mojo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) inline on the Wireless-for-OPTA power input and confirm: (a) idle current is in the published µA range between syncs, (b) per-session energy lands in the few-mAh range for an hourly outbound sync, and (c) total energy per day is consistent across runs. Note that this measurement is the **whole expansion subsystem** — Notecard plus the expansion's onboard regulators and I²C glue, not the Notecard alone, unless you physically isolate the Notecard's `VMODEM_P` rail. Also Note that the Notecard's lowest-power state requires `VUSB` not present and `AUX_EN` not held high; see the [Notecard low-power-design docs](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design/) for the gating conditions. +Splice the [Mojo](https://shop.blues.com/products/mojo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) inline on the Wireless for OPTA power input and confirm: (a) idle current is in the published µA range between syncs, (b) per-session energy lands in the few-mAh range for an hourly outbound sync, and (c) total energy per day is consistent across runs. Note that this measurement is the **whole expansion subsystem** — Notecard plus the expansion's onboard regulators and I²C glue, not the Notecard alone, unless you physically isolate the Notecard's `VMODEM_P` rail. Also Note that the Notecard's lowest-power state requires `VUSB` not present and `AUX_EN` not held high; see the [Notecard low-power-design docs](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design/) for the gating conditions. **Fault simulation.** Easiest path: drop `current_alarm_factor` to 1.0 in the Fleet's environment variables — the next `inbound` sync will pull the new value, the next hourly summary will trip `load_anomaly`, and the event will land in Notehub within a session-establishment window. @@ -331,7 +339,7 @@ Splice the [Mojo](https://shop.blues.com/products/mojo?utm_source=dev-blues&utm_ **Notecard not claiming to the project.** - Verify `PRODUCT_UID` in the sketch exactly matches the ProductUID on Notehub (Projects → Project Settings). -- Confirm cellular signal: in Notehub's In-Browser Terminal, run `card.status` and check the `"signal"` field. Minimum -100 dBm for LTE Cat-1. +- Confirm cellular signal: in the Blues In-Browser Terminal, run `card.status` and check the `"signal"` field. Minimum -100 dBm for LTE Cat-1. - If deploying indoors or in a metal cabinet without an external antenna, the bundled rubber-duck antenna will not work — thread the external SMA antenna through a cable gland and screw it to the primary antenna port. **Modbus reads failing (firmware logs "Modbus error" or no data in summary Notes).** 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 d6e957b4..abf0d712 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 @@ -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 Notehub's In-Browser 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 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/). | Variable | Default | Purpose | |---|---|---| @@ -368,7 +368,7 @@ The *shape* of the trace is as informative as the absolute level. What you want **Device claims to Notehub but no events appear after 2+ hours.** - Check Notecard firmware is up to date: Notehub → Devices → click your device → Device Info → Notecard version. If outdated, trigger a [Notecard firmware update](https://dev.blues.io/notecard/notecard-walkthrough/updating-notecard-firmware/). - Confirm ProductUID in firmware matches your Notehub project. Notecard will not transmit to the wrong project. -- In Notehub's In-Browser Terminal (top-right button), run `hub.status` to check cellular signal (`"signal": -100 to -50` dBm is typical). If `"status": "disconnected"`, wait 2–3 minutes and retry; initial connection can take multiple cycles. +- In the [Blues In-Browser Terminal](https://dev.blues.io/terminal/) (top-right button), run `hub.status` to check cellular signal (`"signal": -100 to -50` dBm is typical). If `"status": "disconnected"`, wait 2–3 minutes and retry; initial connection can take multiple cycles. - Check that templates are registered: Events tab should show `cooler_summary.qo` and `cooler_alert.qo` Notefiles (even if empty). If missing, the `defineTemplates()` function failed—check firmware logs via USB serial with DEBUG_SERIAL enabled. **Events appear but temp_f or compressor_amps show NaN or -9999.** @@ -376,7 +376,7 @@ The *shape* of the trace is as informative as the absolute level. What you want - `compressor_amps = 0.0`: CT is reading zero. Check that the CT clamp is around only one hot leg of the compressor circuit (not both, which cancels the field). Verify TRRS connector is fully seated at the SCT-013 input. Check A0 bias-circuit voltage is ~1.65 V (measure with a multimeter between A0 and GND). **Door-open alerts fire every sample even when door is closed.** -- Door reed switch is stuck closed or the door-frame magnet is permanently magnetized. Confirm the switch reads LOW on D6 when door is physically closed and HIGH when open (check with a pin voltage meter or Notehub terminal `card.attn` disabled, then upload a sketch that prints `digitalRead(D6)` to serial). +- Door reed switch is stuck closed or the door-frame magnet is permanently magnetized. Confirm the switch reads LOW on D6 when door is physically closed and HIGH when open (check with a pin voltage meter or the [Blues In-Browser Terminal](https://dev.blues.io/terminal/) `card.attn` disabled, then upload a sketch that prints `digitalRead(D6)` to serial). - If magnet is stuck, replace the magnet. **Cellular sessions happen more frequently than expected (not just every `summary_interval_min`).** diff --git a/55-demand-response-solar-battery-dispatcher/README.md b/55-demand-response-solar-battery-dispatcher/README.md index fed58f40..da887ca0 100644 --- a/55-demand-response-solar-battery-dispatcher/README.md +++ b/55-demand-response-solar-battery-dispatcher/README.md @@ -97,7 +97,7 @@ Here is a sample Note this device emits: | [Arduino OPTA RS485](https://store.arduino.cc/products/opta-rs485) | 1 | Industrial PLC with onboard RS-485 transceiver, DIN-rail mount, 12–24 VDC supply, and four relay outputs. Required for the RS-485 interface; the OPTA Lite has no RS-485 and is not suitable. | | [Blues Wireless for OPTA (NA, SKU 992-00155-C)](https://shop.blues.com/products/wireless-for-opta?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Snaps onto the OPTA's expansion port; adds a Notecard Cell+WiFi ([NOTE-WBNAW](https://dev.blues.io/datasheets/notecard-datasheet/note-wbnaw/)) over I²C. For EMEA deployments use [SKU 992-00156-C](https://shop.blues.com/products/wireless-for-opta?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link). | | External cellular antenna(s) with SMA, ~3 m lead (e.g. [SparkFun CEL-16432](https://www.sparkfun.com/lte-hinged-external-antenna-698mhz-2-7ghz-sma-male.html)) | 1 primary, 1 diversity recommended | Metal equipment cabinets kill rubber-duck antennas. Route at least the primary antenna outside through a cable gland; the diversity antenna improves LTE Cat-1 performance in marginal-signal sites. | -| [Blues Mojo](https://shop.blues.com/products/mojo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Bench-only coulomb counter for validating the Wireless-for-OPTA + Notecard subsystem energy per session during commissioning. Not deployed to the field. | +| [Blues Mojo](https://shop.blues.com/products/mojo?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) | 1 | Bench-only coulomb counter for validating the Wireless for OPTA + Notecard subsystem energy per session during commissioning. Not deployed to the field. | | 24 VDC DIN-rail supply, ≥15 W (e.g. [MeanWell HDR-15-24](https://www.meanwell.com/Upload/PDF/HDR-15/HDR-15-SPEC.PDF)) | 1 | Powers OPTA and expansion. Most solar equipment cabinets already have one; buy only if the cabinet doesn't. | | 120 Ω, ¼ W resistor | 2 | RS-485 line termination at each physical end of the Modbus bus. The OPTA's transceiver has no permanent terminator; floating the bus line causes spurious framing errors. | | Shielded twisted pair, 22 AWG, RS-485 rated | 1–3 m | A → A, B → B, shield → drive ground. Use a daisy-chain topology (not a star), shield and ground the cable per the inverter and BMS vendor installation guides, and terminate at both physical ends of the bus. Consult each vendor's documentation for maximum recommended bus length at your chosen baud rate. | @@ -158,7 +158,7 @@ The Blues hardware ships with an active SIM including 500 MB of data and 10 year ### Bench power validation -6. **Mojo placement.** During commissioning, splice the [Mojo](https://dev.blues.io/datasheets/mojo-datasheet/) inline between the 24 VDC supply and the Wireless-for-OPTA power input to measure the expansion + Notecard subsystem energy per cellular session. See [Section 9](#9-validation-and-testing) for the expected figures. +6. **Mojo placement.** During commissioning, splice the [Mojo](https://dev.blues.io/datasheets/mojo-datasheet/) inline between the 24 VDC supply and the Wireless for OPTA power input to measure the expansion + Notecard subsystem energy per cellular session. See [Section 9](#9-validation-and-testing) for the expected figures. ## 6. Notehub Setup @@ -519,7 +519,7 @@ Note that the OPTA itself is an always-on 24 VDC device whose steady-state draw - Verify the external antenna is properly connected via SMA lead (rubber-duck antenna inside a metal cabinet will not work). - Check that the Wireless for OPTA is fully seated onto the OPTA's expansion port. - Ensure the 24 VDC power supply voltage is stable (use a multimeter at the OPTA power terminals). -- Look for any error messages on the USB serial debug port (`115200 baud`). Issue a `card.status` from the Notehub terminal to check registration. +- Look for any error messages on the USB serial debug port (`115200 baud`). Issue a `card.status` from the [Blues In-Browser Terminal](https://dev.blues.io/terminal/) to check registration. **Modbus polling shows -9999 (device unreachable).** - Verify that inverter and BMS are configured to the same baud rate, parity, and stop bits. See `modbus_baud`, `modbus_parity`, `modbus_stop_bits` in Section 5. @@ -534,7 +534,7 @@ Note that the OPTA itself is an always-on 24 VDC device whose steady-state draw - Ensure the relay output wires are connected to the correct field-device digital input terminals and that the input voltage rating matches. **Dispatch command expires too soon or TOU window doesn't transition as expected.** -- Verify the Notecard has acquired valid UTC time from at least one Notehub sync. Call `card.time` from the Notehub terminal and confirm `time` is non-zero. +- Verify the Notecard has acquired valid UTC time from at least one Notehub sync. Call `card.time` from the [Blues In-Browser Terminal](https://dev.blues.io/terminal/) and confirm `time` is non-zero. - Check that TOU window hours (`peak_start_utc`, `peak_end_utc`, etc.) are in UTC. The firmware does not perform local-time conversion. - Verify the corresponding environment variables are set to non-equal values (equal values disable the window). diff --git a/60-lone-worker-panic-fall-detection-beacon/README.md b/60-lone-worker-panic-fall-detection-beacon/README.md index c7884aaa..45bffd9a 100644 --- a/60-lone-worker-panic-fall-detection-beacon/README.md +++ b/60-lone-worker-panic-fall-detection-beacon/README.md @@ -462,7 +462,7 @@ If GPS times out, only the initial `beacon_alert.qo` Note is sent; the cached lo ## 9. Validation and Testing -**Expected steady-state behavior.** In normal operation, a healthy beacon produces zero `beacon_alert.qo` events and zero `beacon_location.qo` events. To verify that Notecard provisioning, template registration, and connectivity are all working after assembly, trigger a test fall or panic (see below) and confirm the event appears in Notehub within session-establishment time (typically 30–90 seconds on cellular). If no event appears, check the Notecard's sync status via Notehub's In-Browser Terminal (`{"req":"hub.status"}`) to see the last sync time, pending Note count, and transport-layer error. +**Expected steady-state behavior.** In normal operation, a healthy beacon produces zero `beacon_alert.qo` events and zero `beacon_location.qo` events. To verify that Notecard provisioning, template registration, and connectivity are all working after assembly, trigger a test fall or panic (see below) and confirm the event appears in Notehub within session-establishment time (typically 30–90 seconds on cellular). If no event appears, check the Notecard's sync status via the [Blues In-Browser Terminal](https://dev.blues.io/terminal/) (`{"req":"hub.status"}`) to see the last sync time, pending Note count, and transport-layer error. **Simulating a fall.** On the bench, a realistic fall simulation: hold the device at chest height and drop it onto a padded surface from 50–80 cm. The firmware's default thresholds (0.55g free-fall, 2.5g impact) are tuned for human-body-scale falls. You should see the haptic motor pulse twice (non-blocking, monitoring continues during the buzz sequence) and a `beacon_alert.qo` Note with `"type":"fall"` appear in Notehub within session-establishment time, typically 30–90 seconds in cellular conditions. If the device acquires a fresh GPS fix during the background search window, a follow-up `beacon_location.qo` Note will appear shortly after with the event-time coordinates. In poor GNSS conditions (indoors, obstructed sky view) the background search times out after 90 seconds and only the initial alert Note is sent. @@ -514,7 +514,7 @@ A productive bench exercise: run the device for 2 hours on a known-capacity LiPo - Verify the `PRODUCT_UID` in `lone_worker_beacon_helpers.h` matches your Notehub project's ProductUID exactly. - Check that the Notecard has a provisioned SIM (should ship with one; confirm at [Blues shop](https://shop.blues.com)). - Ensure cellular or WiFi coverage is available. If indoors and no WiFi is provisioned, power cycle and move to a window or open area. -- From Notehub's In-Browser Terminal (click the terminal icon in project settings), issue `{"req":"hub.status"}`. If `last_sync` is very recent, the Notecard is communicating. If `last_sync` is old or `status` is `error`, the Notecard cannot reach cellular or Notehub. +- From the [Blues In-Browser Terminal](https://dev.blues.io/terminal/), issue `{"req":"hub.status"}`. If `last_sync` is very recent, the Notecard is communicating. If `last_sync` is old or `status` is `error`, the Notecard cannot reach cellular or Notehub. **Panic button or fall detection does not trigger.** - Check the haptic motor for signs of life: power on the beacon, wait 5 seconds for boot to complete, then hold the panic button for 3+ seconds. You should feel a vibration within 1–2 seconds of pressing. If no vibration, check the motor's wiring to the DRV2605L and that the DRV2605L is seated on I²C (address 0x5A). @@ -522,19 +522,19 @@ A productive bench exercise: run the device for 2 hours on a known-capacity LiPo - Check the startup fault pattern: a slow double-buzz (buzz, pause, buzz) repeating every 5 seconds indicates a boot-time configuration error (missing `PRODUCT_UID`, failed `hub.set`, or template registration failure). Verify the `PRODUCT_UID` and power-cycle the beacon. **Alerts appear in Notehub but coordinates are missing or stale.** -- `loc_age_s: -1.0` means the Notecard had no cached GPS fix when the alert fired. This is normal indoors. If outdoors with a clear sky view and `loc_age_s` is still -1 after multiple alerts, the Notecard may not have acquired a GPS fix since power-on. Run `{"req":"card.location"}` from the Notehub terminal to force a fix attempt and check the response. +- `loc_age_s: -1.0` means the Notecard had no cached GPS fix when the alert fired. This is normal indoors. If outdoors with a clear sky view and `loc_age_s` is still -1 after multiple alerts, the Notecard may not have acquired a GPS fix since power-on. Run `{"req":"card.location"}` from the [Blues In-Browser Terminal](https://dev.blues.io/terminal/) to force a fix attempt and check the response. - No `beacon_location.qo` follow-up Note means GPS did not acquire a fresh fix within the 90-second background search window. This is normal indoors or under heavy tree cover. If GPS should be working, trigger a test alert and check the Notecard's `card.location` response for lock time and signal quality. **Battery drains too quickly.** - Verify the host MCU is not stuck in a high-clock state. From the Arduino IDE Serial Monitor (115200 baud, after uncommenting `#define DEBUG_SERIAL` in the .ino file), you should see periodic log messages (one per outer loop pass, ~10 per second) with healthy current draws. If the Serial Monitor is active and you see frequent output, the debug serial is forcing the STM32 to maintain its USB clock — disable `DEBUG_SERIAL` to reduce MCU idle from ~10–15 mA to ~5–10 mA. -- Confirm the Notecard is in low-power periodic mode: issue `{"req":"hub.get"}` from the Notehub 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. +- 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 Notehub's In-Browser 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":"-"}`. +- 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":"-"}`. **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. diff --git a/66-remote-apiary-hive-health-monitor/README.md b/66-remote-apiary-hive-health-monitor/README.md index 62ffb871..46eee37b 100644 --- a/66-remote-apiary-hive-health-monitor/README.md +++ b/66-remote-apiary-hive-health-monitor/README.md @@ -508,7 +508,7 @@ Because the unit is solar-powered, the absolute mAh number matters less than the | 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. | -| 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 Notehub terminal. Environment variable changes are pulled on the next scheduled inbound or after a manual sync. See §6 step 4 for commissioning settings. | +| 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 diff --git a/69-injection-molding-shot-to-shot-process-monitor/README.md b/69-injection-molding-shot-to-shot-process-monitor/README.md index 7868eae5..9bd9091e 100644 --- a/69-injection-molding-shot-to-shot-process-monitor/README.md +++ b/69-injection-molding-shot-to-shot-process-monitor/README.md @@ -404,7 +404,7 @@ float denom = (float)(n * sxx - sx * sx); 1. **Estimate your daily Note volume.** Use: `notes_per_day = (86400 s ÷ cycle_time_s) ÷ report_every_n_shots`. A 20-second cycle with `report_every_n_shots=1` produces ~4,320 Notes/day; setting `report_every_n_shots=10` drops that to ~432 — still capturing trend signals without a 10× data-volume penalty. -2. **Run a 24–72 hour validation soak.** After commissioning, check [Notehub usage data](https://dev.blues.io/notehub/notehub-walkthrough/#configuring-your-billing-account) to confirm actual consumption aligns with your estimate. Cellular data usage depends on sync cadence, signal conditions, Note queue depth at sync time, and routing behavior — the measured figure is more reliable than any pre-deployment estimate. +2. **Run a 24–72 hour validation soak.** After commissioning, check [Notehub usage data](https://dev.blues.io/notecard/notecard-walkthrough/low-bandwidth-design/#viewing-usage-data-on-notehub) to confirm actual consumption aligns with your estimate. Cellular data usage depends on sync cadence, signal conditions, Note queue depth at sync time, and routing behavior — the measured figure is more reliable than any pre-deployment estimate. 3. **Tune `report_every_n_shots` and `outbound_min` for the machine.** A fast machine (≤15 seconds cycle) running at `report_every_n_shots=1` will accumulate large numbers of queued Notes between hourly syncs. Validate queue headroom empirically before production: disconnect the cellular antenna, let the machine run for the expected outage window (e.g. 4–8 hours for a typical overnight signal gap), reconnect, and confirm that all Notes arrive in Notehub. Missing `cycle` sequence numbers in the delivered Notes reveal dropped queue entries. If your Note rate times the expected outage window risks saturation, increase `report_every_n_shots` or shorten `outbound_min` to flush the queue more frequently. Actual queue capacity depends on template size, Notecard firmware version, and session behavior — the measured result is more reliable than any pre-deployment estimate.