Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions 55-demand-response-solar-battery-dispatcher/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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 |
|---|---|
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down
Loading
Loading