From c041725ff3dce7551ef285c626a09a304a472489 Mon Sep 17 00:00:00 2001 From: TJ VanToll Date: Thu, 30 Jul 2026 13:59:59 -0400 Subject: [PATCH] chore: link updates per Notehub API page change --- 55-demand-response-solar-battery-dispatcher/README.md | 4 ++-- .../README.md | 4 ++-- 81-commercial-tenant-sub-metering-bridge/README.md | 10 +++++----- .../04-low-power-digital-signage/README.md | 2 +- accelerator-archive/09-valve-monitor/web-app/README.md | 2 +- .../10-flow-rate-monitor/web-app/README.md | 2 +- .../34-cellular-modbus-client/README.md | 2 +- 7 files changed, 13 insertions(+), 13 deletions(-) diff --git a/55-demand-response-solar-battery-dispatcher/README.md b/55-demand-response-solar-battery-dispatcher/README.md index 4ebb7ad7..a48e0c47 100644 --- a/55-demand-response-solar-battery-dispatcher/README.md +++ b/55-demand-response-solar-battery-dispatcher/README.md @@ -42,7 +42,7 @@ This project closes that gap. A [Blues Wireless for OPTA](https://blues.com/prod **[Notecard](https://shop.blues.com/products/notecard-cellular?utm_source=dev-blues&utm_medium=web&utm_campaign=store-link) responsibilities.** The Notecard queues the [Notes](https://dev.blues.io/api-reference/glossary/#note) (the JSON-based events), ships them on the configured [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `periodic` outbound cadence, and checks Notehub for inbound `dispatch.qi` commands every five minutes. That five-minute window is what keeps dispatch latency comfortably inside the ten-minute response envelope most utility DR programs require. The same module pulls [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) on each inbound sync, which is how a fleet operator re-tunes the TOU schedule, SOC thresholds, or Modbus addresses from a browser without ever opening the cabinet. -**Notehub responsibilities.** Events flow from the Notecard's embedded global SIM into [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). On the cloud side, whatever orchestrates dispatch — a utility rate scheduler, an energy management system, a webhook bridge to the utility DR API — queues commands by posting a Note to the device's `dispatch.qi` Notefile via the [Notehub API](https://dev.blues.io/api-reference/notehub-api/api-introduction/); the Notecard pulls it in on the next inbound sync. [Environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) set at the [Fleet](https://dev.blues.io/guides-and-tutorials/fleet-admin-guide/) level carry the site's TOU schedule so the device can act autonomously — provided the Notecard has acquired a valid UTC time from at least one prior sync. On cold boot before that happens, `resolveMode()` sees `epoch = 0` and stays in `normal` rather than misapplying the schedule; TOU windows engage as soon as the clock is available. +**Notehub responsibilities.** Events flow from the Notecard's embedded global SIM into [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). On the cloud side, whatever orchestrates dispatch — a utility rate scheduler, an energy management system, a webhook bridge to the utility DR API — queues commands by posting a Note to the device's `dispatch.qi` Notefile via the [Notehub API](https://dev.blues.io/api-reference/notehub-api/); the Notecard pulls it in on the next inbound sync. [Environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) set at the [Fleet](https://dev.blues.io/guides-and-tutorials/fleet-admin-guide/) level carry the site's TOU schedule so the device can act autonomously — provided the Notecard has acquired a valid UTC time from at least one prior sync. On cold boot before that happens, `resolveMode()` sees `epoch = 0` and stays in `normal` rather than misapplying the schedule; TOU windows engage as soon as the clock is available. **Routing to the cloud (high level only).** Notehub supports HTTP, MQTT, AWS IoT Core, Azure IoT Hub, 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. @@ -198,7 +198,7 @@ The Blues hardware ships with an active SIM including 500 MB of data and 10 year 5. **Configure routes.** Add a route for `solar_telemetry.qo` to a long-term analytics or historian destination (this Note is relatively high frequency, 96 records per device per day at the 15-minute default) and a separate route for `dr_event.qo` to a real-time notification channel such as a CMMS, SCADA system, or operator dashboard. Because the two Notefiles are separate at the source, each can be routed differently with no filter logic in the route itself. -6. **Inbound dispatch path.** Cloud-side systems send dispatch commands by posting a Note to the device's `dispatch.qi` Notefile via the [Notehub API](https://dev.blues.io/api-reference/notehub-api/api-introduction/) (`POST /v1/projects/{projectUID}/devices/{deviceUID}/notes/dispatch.qi`). The Note body carries a `mode` string and an optional `expires_epoch` Unix timestamp. The Notecard delivers the Note to the device within the next inbound sync window (≤5 minutes). +6. **Inbound dispatch path.** Cloud-side systems send dispatch commands by posting a Note to the device's `dispatch.qi` Notefile via the [Notehub API](https://dev.blues.io/api-reference/notehub-api/) (`POST /v1/projects/{projectUID}/devices/{deviceUID}/notes/dispatch.qi`). The Note body carries a `mode` string and an optional `expires_epoch` Unix timestamp. The Notecard delivers the Note to the device within the next inbound sync window (≤5 minutes). | `mode` value | Effect | |---|---| diff --git a/63-construction-equipment-anti-theft-tracker-with-immobilizer/README.md b/63-construction-equipment-anti-theft-tracker-with-immobilizer/README.md index 301eec51..52828eb6 100644 --- a/63-construction-equipment-anti-theft-tracker-with-immobilizer/README.md +++ b/63-construction-equipment-anti-theft-tracker-with-immobilizer/README.md @@ -34,7 +34,7 @@ This project is that device. It monitors GPS location against a configurable job **Notecard responsibilities.** Notecard for Skylo is doing most of the connectivity work behind the scenes. It buffers queued [Notes](https://dev.blues.io/api-reference/glossary/#note) in on-device flash, opens a cellular or satellite session on the [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence, and treats any `sync:true` alert Note as an immediate uplink: the difference between an alert reaching the operator in seconds and the equipment crossing a county line. The same module also owns the GPS receiver, the accelerometer, the real-time clock, and the battery-voltage ADC, so no external sensors are needed. [Environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/) flow back from Notehub on each inbound sync. A fleet manager can retune the geofence radius or the after-hours window from a browser, and the firmware automatically reissues `hub.set` and `card.location.mode` so all three Notecard cadences stay aligned with the new wake interval. -**Notehub responsibilities.** [Notehub](https://notehub.io) ingests every event from every device — whether it arrived over cellular or Skylo — stores it, and applies the project's [routes](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub). Alert Notes (`alert.qo`) and tracker heartbeats (`tracker.qo`) land in separate Notefiles, so the security platform that needs alerts the moment they happen and the fleet-management store that needs position history can be served from the same device with no filter logic in between. Operators stage an `immobilize` or `release` command by posting a Note to the device's `immobilize.qi` inbound queue from the Notehub UI or via the [Notehub REST API](https://dev.blues.io/api-reference/notehub-api/api-introduction/). [Smart Fleets](https://dev.blues.io/notehub/notehub-walkthrough/#using-smart-fleet-rules) push site-level geofence and after-hours defaults to every machine on a job site at once. +**Notehub responsibilities.** [Notehub](https://notehub.io) ingests every event from every device — whether it arrived over cellular or Skylo — stores it, and applies the project's [routes](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub). Alert Notes (`alert.qo`) and tracker heartbeats (`tracker.qo`) land in separate Notefiles, so the security platform that needs alerts the moment they happen and the fleet-management store that needs position history can be served from the same device with no filter logic in between. Operators stage an `immobilize` or `release` command by posting a Note to the device's `immobilize.qi` inbound queue from the Notehub UI or via the [Notehub REST API](https://dev.blues.io/api-reference/notehub-api/). [Smart Fleets](https://dev.blues.io/notehub/notehub-walkthrough/#using-smart-fleet-rules) push site-level geofence and after-hours defaults to every machine on a job site at once. **Routing to the cloud (high level).** Notehub supports HTTP, MQTT, AWS IoT, Azure, GCP, Snowflake, and 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. @@ -201,7 +201,7 @@ Verify that your charger module's output connector pitch and polarity match the | `outbound_min` | `240` | > 0 | Minutes between Notecard outbound batch sessions — how often queued heartbeat Notes are transmitted to Notehub. Intentionally longer than `heartbeat_stopped_min` so multiple heartbeats accumulate per outbound session, reducing total cellular radio time without degrading detection latency. Alert Notes (`sync:true`) bypass this window and transmit immediately. | | `alert_cooldown_min` | `5` | > 0 | Minimum minutes between repeated alerts of the same type. Each alert type (`geofence_breach`, `motion_after_hours`, `cmd_retrieve_failed`) has its own independent cooldown timer, so one alert type cannot suppress the other. On the Skylo satellite link, consider raising this to 15–30 minutes to protect the 10 KB/month data budget during a sustained geofence-breach event. | -5. **Issue an immobilize command.** From the Notehub UI (or via the [Notehub REST API](https://dev.blues.io/api-reference/notehub-api/api-introduction/)), add a Note to the device's `immobilize.qi` inbound queue with body `{"cmd":"immobilize"}`. Command delivery has two **sequential** latency stages: (1) the Notecard pulls the inbound Note on its next `inbound` sync session, and (2) the host Cygnet processes the command only when it next wakes and runs `setup()`. Under the default cadence, combined worst-case end-to-end latency from posting the command to the `immobilize_armed` acknowledgment appearing in Notehub is at most **~6 minutes** during the after-hours window (≤ 4 minutes for the Notecard inbound sync, then ≤ 2 minutes until the next Cygnet wake), **~9 minutes** while moving (4 + 5 minutes), and just under **2 hours** while stationary during business hours (up to 60 minutes for the Notecard daytime inbound sync + up to 60 minutes until the next Cygnet wake). The daytime inbound automatically extends to match `heartbeat_stopped_min` (default 60 minutes) to avoid idle cellular sessions; if near-real-time command delivery is required around the clock, reduce `heartbeat_stopped_min` or add a motion-triggered wake (see §11 Production next steps). To cancel before the relay fires, send `{"cmd":"release"}`. +5. **Issue an immobilize command.** From the Notehub UI (or via the [Notehub REST API](https://dev.blues.io/api-reference/notehub-api/)), add a Note to the device's `immobilize.qi` inbound queue with body `{"cmd":"immobilize"}`. Command delivery has two **sequential** latency stages: (1) the Notecard pulls the inbound Note on its next `inbound` sync session, and (2) the host Cygnet processes the command only when it next wakes and runs `setup()`. Under the default cadence, combined worst-case end-to-end latency from posting the command to the `immobilize_armed` acknowledgment appearing in Notehub is at most **~6 minutes** during the after-hours window (≤ 4 minutes for the Notecard inbound sync, then ≤ 2 minutes until the next Cygnet wake), **~9 minutes** while moving (4 + 5 minutes), and just under **2 hours** while stationary during business hours (up to 60 minutes for the Notecard daytime inbound sync + up to 60 minutes until the next Cygnet wake). The daytime inbound automatically extends to match `heartbeat_stopped_min` (default 60 minutes) to avoid idle cellular sessions; if near-real-time command delivery is required around the clock, reduce `heartbeat_stopped_min` or add a motion-triggered wake (see §11 Production next steps). To cancel before the relay fires, send `{"cmd":"release"}`. **Queue semantics — last command wins.** The firmware drains the entire `immobilize.qi` queue on each wake: it calls `note.get` in a loop until the queue is empty, applying each command in order. The final command in the queue takes effect. If you post `immobilize` and immediately follow it with `release`, the `release` will win on the same wake cycle. Keep at most one outstanding command in the queue at any time; do not post a new command until either the `immobilize_armed` alert (confirming a staged immobilize) or the `release_confirmed` alert (confirming the immobilize was cleared) appears in Notehub. Both alerts are emitted once — on the exact wake cycle that processes the corresponding command. This is a **staged, edge-triggered** POC immobilizer — the relay is not asserted until the device wakes and detects an OFF→ON ignition edge while the command is staged (one prior wake observed OFF, the firing wake observes ON). The relay deliberately does not fire while the engine is already running. diff --git a/81-commercial-tenant-sub-metering-bridge/README.md b/81-commercial-tenant-sub-metering-bridge/README.md index fbbc14fc..27590cfa 100644 --- a/81-commercial-tenant-sub-metering-bridge/README.md +++ b/81-commercial-tenant-sub-metering-bridge/README.md @@ -46,7 +46,7 @@ This is not a niche edge case. Billing disputes are among the most contentious i **Notecard responsibilities.** The Notecard is the cellular muscle and the sleep gate. It queues [Notes](https://dev.blues.io/api-reference/glossary/#note) locally, wakes the cellular radio on the configured [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/#hub-set) `outbound` cadence (default 60 min), and flushes the entire queue to Notehub in a single cellular session. Environment-variable changes pushed from Notehub come back on its `inbound` cadence (default 120 min), and [`card.attn`](https://dev.blues.io/api-reference/notecard-api/card-requests/#card-attn) sleep mode cuts host power between samples so the Cygnet draws essentially zero current from the supply between wakeups. -**Notehub responsibilities.** Once Notes arrive at [Notehub](https://notehub.io) over the Notecard's embedded global SIM, they're stored durably and routed downstream. Notehub is also the **sole monthly aggregation path**: a billing or property-management platform sums each tenant's `t*_wh` values across all hourly `meter_summary.qo` events for a device over any billing period using the [Notehub Event Query API](https://dev.blues.io/api-reference/notehub-api/api-introduction/). The device never emits a month-end Note and never tries to compute a billing total; the hourly event stream in Notehub is the complete, authoritative record. +**Notehub responsibilities.** Once Notes arrive at [Notehub](https://notehub.io) over the Notecard's embedded global SIM, they're stored durably and routed downstream. Notehub is also the **sole monthly aggregation path**: a billing or property-management platform sums each tenant's `t*_wh` values across all hourly `meter_summary.qo` events for a device over any billing period using the [Notehub Event Query API](https://dev.blues.io/api-reference/notehub-api/). The device never emits a month-end Note and never tries to compute a billing total; the hourly event stream in Notehub is the complete, authoritative record. [Fleets](https://dev.blues.io/guides-and-tutorials/fleet-admin-guide/) group devices per property so a property manager with multiple buildings can push sensor calibration settings per-building without touching individual devices. A Notehub HTTP or MQTT route can forward each `meter_summary.qo` Note directly to the property-management or billing platform as it arrives. @@ -241,7 +241,7 @@ Once your device is appearing in the **Devices** tab and events are flowing, con | `volt_scale` | `1200.0` | Voltage transducer calibration: line-voltage V RMS ÷ ADC-pin V RMS. | Default (1200.0) matches ZMPT101B at 120 V nominal. Measure line voltage with a precision AC voltmeter and trim for accuracy. | | `num_tenants` | `4` | Active current channels to sample (1–4). | Set to the actual number of tenants metered to skip unnecessary ADC reads. | -3. **Configure routes.** Route `meter_summary.qo` to your time-series database or billing platform. This is the canonical energy record and the correct source for monthly aggregation — sum each tenant's `t*_wh` values across all hourly events over the billing period using the [Notehub Event Query API](https://dev.blues.io/api-reference/notehub-api/api-introduction/). See the [Notehub routing docs](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub) for destination types. +3. **Configure routes.** Route `meter_summary.qo` to your time-series database or billing platform. This is the canonical energy record and the correct source for monthly aggregation — sum each tenant's `t*_wh` values across all hourly events over the billing period using the [Notehub Event Query API](https://dev.blues.io/api-reference/notehub-api/). See the [Notehub routing docs](https://dev.blues.io/notehub/notehub-walkthrough/#routing-data-with-notehub) for destination types. ### What you should see in Notehub @@ -372,7 +372,7 @@ Nine 4-byte floats: estimated interval energy (Wh), 15-minute blocked-average de } ``` -To derive monthly per-tenant totals, sum `t*_wh` across all `meter_summary.qo` events for a device over the billing period using the [Notehub Event Query API](https://dev.blues.io/api-reference/notehub-api/api-introduction/), then divide by 1000 to obtain estimated kWh. This Notehub-side aggregation is the sole monthly rollup path; no device-side monthly note is generated. +To derive monthly per-tenant totals, sum `t*_wh` across all `meter_summary.qo` events for a device over the billing period using the [Notehub Event Query API](https://dev.blues.io/api-reference/notehub-api/), then divide by 1000 to obtain estimated kWh. This Notehub-side aggregation is the sole monthly rollup path; no device-side monthly note is generated. ### 7.5 Low-power strategy @@ -505,7 +505,7 @@ If compilation fails with a `PRODUCT_UID is not defined` warning, revisit step 2 **Transmitted — hourly (canonical record).** `meter_summary.qo`: one Note per `summary_interval_min` (default 24 per day). Template-encoded, queued and flushed in the Notecard's periodic outbound sync. Carries `t1_wh`–`t4_wh` (estimated interval energy in Wh), `t1_demand_w`–`t4_demand_w` (peak 15-minute blocked-average demand W), and `fault_mask` (combined per-channel fault bitmask) for each tenant. Note is **not** sync:true; it batches with the periodic radio window. These Notes are the authoritative energy record and the sole input for Notehub-side monthly aggregation. -**Routed.** Notes flow through Notehub to whatever downstream the project routes specify. A typical deployment routes `meter_summary.qo` to a time-series database as the primary billing and analytics record. Monthly per-tenant totals are derived by summing `t*_wh` across the billing period's hourly events in Notehub — either via the [Event Query API](https://dev.blues.io/api-reference/notehub-api/api-introduction/) or a downstream aggregation pipeline. Notehub stores every Note durably; no device-side aggregate is needed to reconstruct any monthly total. +**Routed.** Notes flow through Notehub to whatever downstream the project routes specify. A typical deployment routes `meter_summary.qo` to a time-series database as the primary billing and analytics record. Monthly per-tenant totals are derived by summing `t*_wh` across the billing period's hourly events in Notehub — either via the [Event Query API](https://dev.blues.io/api-reference/notehub-api/) or a downstream aggregation pipeline. Notehub stores every Note durably; no device-side aggregate is needed to reconstruct any monthly total. ## 10. Validation and Testing @@ -599,7 +599,7 @@ Taking the bridge toward a production rollout means calibrating each installed c **Notecard Outboard DFU** lets [firmware be updated](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update/) across the entire fleet without a truck roll to each panel. -**Integrate with a billing platform** by configuring a Notehub HTTP route that POSTs each `meter_summary.qo` to the analytics and billing database. Configure the downstream system to reject or quarantine any `meter_summary.qo` where `fault_mask != 0` and fall back to manual estimation for the affected period. Monthly totals are derived by querying the [Notehub Event Query API](https://dev.blues.io/api-reference/notehub-api/api-introduction/) and summing `t*_wh` for each device over the billing period. +**Integrate with a billing platform** by configuring a Notehub HTTP route that POSTs each `meter_summary.qo` to the analytics and billing database. Configure the downstream system to reject or quarantine any `meter_summary.qo` where `fault_mask != 0` and fall back to manual estimation for the affected period. Monthly totals are derived by querying the [Notehub Event Query API](https://dev.blues.io/api-reference/notehub-api/) and summing `t*_wh` for each device over the billing period. **Capture a commissioning baseline** on first installation by recording the ADC DC offset for each channel with all loads off and storing the values in Notehub device metadata. The downstream system can compare `fault_mask` flags against these baselines to distinguish genuine zero-load readings from sensor faults. diff --git a/accelerator-archive/04-low-power-digital-signage/README.md b/accelerator-archive/04-low-power-digital-signage/README.md index 0034dac5..ce78ada6 100644 --- a/accelerator-archive/04-low-power-digital-signage/README.md +++ b/accelerator-archive/04-low-power-digital-signage/README.md @@ -95,7 +95,7 @@ to get your firmware up and running. Once the app is running, you can update the display using the environment variables above, either using the Notehub UI or one of the shell scripts in the [`scripts`](scripts/) folder. -The scripts use the Notehub API, so you'll need follow the [instructions here](https://dev.blues.io/api-reference/notehub-api/api-introduction/) to get an authentication token. +The scripts use the Notehub API, so you'll need follow the [instructions here](https://dev.blues.io/api-reference/notehub-api/) to get an authentication token. You'll also need your Notehub project's UID, which you can find in the `Settings` screen. For setting fleet variables, you'll need the Fleet UID, which you can find on the `Settings` tab for your fleet. For device variables, you need the Device UID, which you can find on the device screen. diff --git a/accelerator-archive/09-valve-monitor/web-app/README.md b/accelerator-archive/09-valve-monitor/web-app/README.md index aa02a914..ffd497ff 100644 --- a/accelerator-archive/09-valve-monitor/web-app/README.md +++ b/accelerator-archive/09-valve-monitor/web-app/README.md @@ -358,7 +358,7 @@ The project’s `src/pages/api` directory are [APIs](https://nextjs.org/docs/api-routes/introduction) as opposed to React-powered HTML pages. The Valve Monitor web app uses these routes in several places to access the -[Notehub API](https://dev.blues.io/api-reference/notehub-api/api-introduction/) +[Notehub API](https://dev.blues.io/api-reference/notehub-api/) server without triggering a full-page reload. > **NOTE**: If you’re new to Next.js, the [Next.js official interactive diff --git a/accelerator-archive/10-flow-rate-monitor/web-app/README.md b/accelerator-archive/10-flow-rate-monitor/web-app/README.md index 6958e86d..58182d7b 100644 --- a/accelerator-archive/10-flow-rate-monitor/web-app/README.md +++ b/accelerator-archive/10-flow-rate-monitor/web-app/README.md @@ -358,7 +358,7 @@ The project’s `src/pages/api` directory are [APIs](https://nextjs.org/docs/api-routes/introduction) as opposed to React-powered HTML pages. The Flow Rate Monitor web app uses these routes in several places to access the -[Notehub API](https://dev.blues.io/api-reference/notehub-api/api-introduction/) +[Notehub API](https://dev.blues.io/api-reference/notehub-api/) server without triggering a full-page reload. > **NOTE**: If you’re new to Next.js, the [Next.js official interactive diff --git a/accelerator-archive/34-cellular-modbus-client/README.md b/accelerator-archive/34-cellular-modbus-client/README.md index 6053a95f..c05519c7 100644 --- a/accelerator-archive/34-cellular-modbus-client/README.md +++ b/accelerator-archive/34-cellular-modbus-client/README.md @@ -373,7 +373,7 @@ You'll use `server.py` as the Modbus server and the Swan as the Modbus client. To quickly exercise all the supported Modbus functions, you can run the [`test.py`](./test.py) Python script. -1. Set up Programmatic API Access on your Notehub project by following [this documentation](https://dev.blues.io/api-reference/notehub-api/api-introduction/#authentication-with-oauth-bearer-tokens). You now have a client ID and secret. +1. Set up Programmatic API Access on your Notehub project by following [this documentation](https://dev.blues.io/api-reference/notehub-api/#authentication-with-oauth-bearer-tokens). You now have a client ID and secret. 1. Go to your Notehub project's Devices tab, double-click your device in the list, and copy down the Device UID. 1. Go to your Notehub project's Settings tab and copy down the Project UID. 1. You now have all the information you need to run `test.py`: