Fleet Administrator's Guide

Notehub provides numerous features that allow you to organize devices into projects and fleets, provision and configure them at scale, route their data to external systems, manage the firmware they run, monitor their health, and operate the fleet day-to-day.

Organizational Tooling

Notehub organizes the work of coordinating your IoT application around three concepts: projects (the top-level container), products (a kind of connected system inside a project), and fleets (operational groupings of devices inside a project). Team members are granted role-based access at the project level. This section covers each concept and the decisions involved in using them well.

Projects, Products, and Fleets

Notehub organizes devices using three orthogonal concepts. Each answers a different question:

• Project — the top-level container and the primary isolation boundary. A project owns its routes, integrations, environment variables, and team membership.
• Product — a logical kind of connected system, identified by a ProductUID in reverse-DNS format (e.g. com.acme.refrigerator.upright). A device's product association is set at provisioning (first boot) and is effectively permanent. A project can contain one or more products, but every Notecard is associated with exactly one product.
• Fleet — a freely reassignable operational grouping of devices inside a project. Fleets are managed at the project level (not inside a product), so a single fleet can include devices from multiple products if that suits your operations. Fleets are the right tool for nearly everything operational.

A good way to wrap your head around the difference between products and fleets is that a product is about permanent identity, while a fleet is about flexible operational grouping. Routes, environment variables, firmware targeting, and team access all live at the project level and can be scoped or filtered without splitting products.

note

Most Blues customers configure their Notehub projects to use a single product with one or more fleets. However, the option to use multiple products within a project exists for the scenarios described below.

When to Use Multiple Projects...or Multiple Products in a Project

To be clear: most Notehub projects use only a single product to keep things simple. However, the multi-product use case is valid, and it's worth being clear about why.

tip

You can add as many projects, products, and fleets to your Notehub account as you want. Blues does not limit these in any way.

Because ProductUIDs are effectively permanent and most configurations within Notehub (e.g. routes, environment variables, firmware targeting, team access) actually live at the project level, the question is rarely "single product vs multiple products." It's usually one of:

• Single project vs multiple projects when you need real isolation — different customers, environments, compliance scopes, or fundamentally different device types that don't share routes and integrations.
• Single product vs multiple fleets when you need operational grouping that should remain reassignable (e.g. region, lifecycle, hardware revision, rollout cohort, beta vs stable, and so on).

The legitimate cases for multiple products inside one project are narrow. The most common is production vs staging vs development, where you want to share project-level infrastructure but keep the device populations distinct. Even then, separate projects are often a cleaner answer.

For fundamentally different device types — a refrigeration monitor and a vehicle gateway, say — use separate projects rather than separate products inside one project. Different device types typically want different routes, different integrations, and different operational ownership, all of which are project-level concerns.

tip

Start with one project, one product, and as many fleets as you need. Move to multiple projects when you need true isolation between customers, environments, or device categories. Move to multiple products inside a project only when you specifically want distinct, permanent device identities to share the same project-level routes, integrations, and team collaborators.

Team Management

Notehub allows for the creation and management of team members who may be delegated varying levels of access to projects. With the provided role-based privileges, a single team member can have differing degrees of access to multiple projects under an account.

Team members can be granted one or more of three different roles on a single project:

• Owner (Collaborator) has full administrative privileges.
• Developer (Collaborator) has limited administrative privileges.
• Viewer has read-only privileges.

Fleet Management

Fleets allow for the organization of Notecard devices into logical groupings. Fleets are managed at the project level.

Static Fleets

A static fleet contains exactly the devices you assign to it. Membership only changes when an operator (or an API call, batch job, or smart fleet rule) adds or removes a device. Static fleets are a good default for most groupings (e.g. by region, by customer, by hardware variant, and/or by lifecycle stage).

Static fleets can be named and used in any way that fits your individual project. If you are looking for guidance, we recommend the following:

• Using a New fleet to view (and potentially triage) Notecard devices newly-added to a project.
• Using one or more Operational fleets denoting active devices and organized by device type, region, or some scope of environment variables.
• Using a Repair fleet for all devices that have been taken out of service but may be put back into service when functioning properly.
• Using a Decommissioned fleet for all devices that are out of service and will not return to service.
• Using custom-tagged fleets to identify devices that may need to be monitored for anomalies, associated with a geolocation, linked to a specific custodian, and so on.

Users concerned about the possibility of a "rogue" device polluting data in Notehub will find the usage of the New fleet useful. Newly-provisioned devices will appear in New, allowing for easy re-assignment or removal of unidentified devices. Likewise, using an Operational fleet allows users to designate specific devices as approved to route data to third-party cloud applications.

Smart Fleets

A smart fleet is a fleet whose membership is driven by a rule rather than by explicit assignment. You enable smart fleet rules on a fleet and provide a JSONata expression that Notehub evaluates against each incoming event from a device. The expression decides whether the device should be added to the fleet, removed from it, or left alone, using three return functions:

• $addToFleet() — adds the current device to the fleet.
• $removeFromFleet() — removes the current device from the fleet.
• $leaveFleetAlone() — neither adds nor removes the current device.

Optionally, a Notefiles filter can restrict which Notefiles trigger the rule, so the expression only sees the events it is meant to evaluate.

Smart fleets are useful any time membership should reflect a condition in the device's recent data rather than a manual designation. For example:

• A High Temperature fleet that contains every device currently reporting body.temperature > 20.
• A Low Battery fleet that contains every device whose most recent _session.qo reported voltage below a threshold.
• A Recently Online fleet that contains every device that has synced in the last N hours.
• A Geofence fleet that contains every device currently inside a specific bounding box, based on the device's latest location event.

Because the rules run against incoming events, smart fleets keep themselves current as new data arrives. You can also apply a rule on demand using the Apply Now button in the fleet's settings, which evaluates the most recent event for each device in the project.

For a full walkthrough see Using Smart Fleet Rules.

tip

Static fleets and smart fleets are not mutually exclusive. A device can sit in a static Operational fleet for lifecycle purposes and simultaneously appear in a smart High Temperature fleet that triggers alerting routes. Use the static fleet for "where is this device in its lifecycle?" and the smart fleet for "what is this device doing right now?".

Device Provisioning

Provisioning is how a Notecard moves from a generic, factory-fresh device to one that is uniquely identified, configured for a specific Notehub project, and associated with a specific customer or fleet. Blues provides several complementary mechanisms for provisioning, and most production deployments use more than one of them across a device's lifecycle.

Choosing a Provisioning Mechanism

Out-of-the-Box Provisioning

Every Notecard leaves manufacturing with device and Notehub certificates already installed. This is what allows a Notecard to power on, connect to a cellular, satellite, LoRaWAN, or WiFi network, and authenticate against Notehub without any configuration step on your part. Each Notecard arrives with:

• A unique, immutable DeviceUID.
• Cryptographic credentials that authenticate the device against Notehub.
• The factory-default firmware required to communicate with Notehub.

Out-of-the-box provisioning gets a Notecard onto Notehub, but it does not associate the device with your project or fleet. At a minimum, your deployment process MUST set a ProductUID on the Notecard (e.g. via a hub.set request) so Notes route to your Notehub project, assign the device to the right fleet, and set any environment variables your host firmware needs. The mechanisms below cover those remaining steps.

Hardware Specific QR Codes

Each individually packaged Notecard includes stickers with QR codes:

1. On the Notecard: Links to a device-specific page showing details like the SKU and DeviceUID.
2. Loose stickers inside the bag: Contain QR codes unique to that specific device (see Unique Device URLs below for details).
3. On the bag: Links to the Notecard Quickstart guide.

The loose stickers can be applied to your product, allowing operators and end users to scan the QR code and be redirected to a device- or product-specific URL (such as a cloud dashboard, web-based provisioning flow, or any other custom experience).

Unique Device URLs

The loose stickers contain links to a unique URL for each Notecard, based on the device's DeviceUID. For example:

HTTP://QRGO.ORG/ID/864009060869498/515438

• The domain qrgo.org is a Blues-owned domain that facilitates redirects to Notehub.
• The second URL segment after the domain is the Notecard's globally unique DeviceUID.
• The third URL segment after the domain is a random PIN that is used internally by Notehub.

Learn how to configure the per-device redirect target in Creating a Device Dashboard.

Provisioning Patterns

Hardware-specific QR codes are the right tool whenever provisioning needs a human to associate a particular Notecard with a particular product, serial number, or customer. Because each loose sticker contains the Notecard's DeviceUID in the URL, any web app you point those scans at receives the DeviceUID as part of the request, giving your backend an unambiguous handle on the physical device the operator is holding.

Here are some typical provisioning patterns:

• Pairing a Notecard with a product serial number. Operator scans the Notecard sticker, then scans a second QR code on the enclosing product. Your backend records the association and writes the product's serial number to Notehub as an environment variable.
• Stateful manufacturing UIs. The web app the QR code resolves to can branch based on the device's current state in your system (e.g. unprovisioned, in test, in inventory, shipped). The operator always sees the right UI for where the device is in its lifecycle.
• End-customer experiences. Once a device is in the field, the same QR code can resolve to a customer-facing dashboard. The redirect target is driven by your backend, not baked into the sticker.

Provisioning with Batch Jobs

Notehub batch jobs let you provision and configure many devices in a single operation by uploading a JSON file (or submitting it through the Jobs API). They are the right tool whenever you need to act on a batch of devices identified by some criterion (e.g. by fleet, by tag, or by an explicit list of DeviceUIDs) rather than one device at a time.

Here are some provisioning patterns that fit batch jobs well:

• Customer onboarding. A customer orders N units. Run a batch job that assigns those devices to the customer's fleet and writes their environment variables (e.g. region, units, refresh interval, setpoints, customer ID, etc.) in one shot.
• Mapping DeviceUIDs to your own serial numbers. A batch job can set a _sn serial number environment variable (or any other key) on a list of devices, using a JSON payload that maps each DeviceUID to the matching value from your system.
• Fleet realignment. Move a group of devices from one fleet to another (e.g. from a "shipped" fleet to a "delivered" fleet) without touching them individually.
• Backfill and audit. Generate a report across a batch of devices to verify configuration before they ship. Dry-run mode lets you validate the payload before any device is touched.

tip

Batch jobs are idempotent, so re-running the same job is safe and reapplies the same configuration. This makes batch jobs the safest mechanism for re-provisioning devices that may have been touched out of band.

Data Handling

Notehub sits in the middle of two data flows: events from your Notecard fleet going out to the backend systems that consume them, and configurations and commands coming back in to the devices.

note

The fleet administrator perspective on data handling is less about what Notehub can do (that information is found in the Notehub Walkthrough) and more about how you architect those flows when you are operating many devices for many destinations.

Routing Data Out from Notecard to Cloud

A route is a project-level definition that forwards Notecard events to an external system. Routes are how your fleet's data reaches your cloud, analytics pipeline, alerting platform, or customer- or fleet-specific destinations.

note

For the route types, UI walkthrough, retry mechanics, and JSONata transform syntax, see Routing Data with Notehub.

Here are some fleet administrator decisions related to routing data:

• Filtering scope. Routes can be scoped by fleet and/or by Notefile.
• Multicasting. Any event can fan out across multiple routes simultaneously. A common production pattern is one route to your cloud endpoint, one to your own analytics, and one to a backup (e.g. S3 archive).
• Per-device targeting via placeholders. Rather than creating N routes for N customer endpoints, a single route can use placeholder variables like [device], [$customer_endpoint], or [.body.region] in the URL. One route serves many devices with destinations driven by environment variables or event content.
• Retry posture. Enable automatic retry on transient failures, and use bulk event replay to recover after a downstream outage. Routes whose downstream cannot tolerate duplicates need idempotent handlers.

tip

When in doubt, prefer more, narrower routes over a single broadcast route. Narrow routes make filtering, rate-limiting, and failure isolation straightforward.

Pulling Data in from Cloud to Notecard

Three mechanisms move data from Notehub down to a Notecard device: inbound Notes, environment variables, and DB Notefiles. Choosing between them is straightforward:

tip

In short: environment variables are state, inbound Notes are events, and DB Notefiles are replicated records. See Sending Data from Notehub to Notecard for the UI walkthrough and code samples.

Environment Variable Hierarchy

Environment variables can be defined in several places, and any single variable can resolve to a different value depending on where it was set. Notecard resolves a requested variable by walking the following precedence order and returning the first match:

1. The value set in Notehub directly on the Device's record.
2. The value set in Notehub on a Fleet the device belongs to.
3. The value set in Notehub on the Project the device belongs to.
4. The value set on the Notecard with env.default.

For a fleet admin, this hierarchy is the single most important thing to understand about environment variables. It is what lets you push a config change to one device, one fleet, or the entire project without disturbing the others. The general guidance:

• Project-level for organization-wide defaults.
• Fleet-level for customer-, region-, or product-variant-specific settings.
• Device-level for ad-hoc overrides during testing, troubleshooting, or one-off configuration.
• env.default for compile-time fallbacks that ship with the host firmware and apply when the Notecard has never synced.

For the full feature reference — including how variables are synced, queried from the host, and used in route placeholders — see Understanding Environment Variables.

Firmware Management

A Notecard has the ability to administer two sets of firmware that you may need to update over the device's lifetime: the Notecard firmware (managed by Blues, distributed via Notehub or locally via CLI) and your host firmware (managed by you, uploaded to Notehub or locally via direct programming). Both can be updated over-the-air through Notehub at the device, fleet, or project level.

This section covers the decisions a fleet admin makes when running those updates in production.

note

The Notehub Walkthrough covers the mechanics — Manage Firmware for the UI walkthrough, Updating Notecard Firmware for the Notecard-specific procedure, and the Host Firmware Update Guide for everything on the host DFU side.

Notecard Firmware vs Host Firmware

The two sets of firmware update independently and serve different purposes:

Fleet admins typically update Notecard firmware on a slower cadence (tied to Blues releases, with clear changelogs) and host firmware whenever their team ships. The two are scheduled and rolled out independently.

Targeting Strategy

Firmware updates can be scoped at three levels. The right choice depends on how much production risk you can tolerate:

• Device-level. Useful for engineering tests, RMA reproductions, or one-off field repair. Not appropriate for production rollouts.
• Fleet-level. The workhorse for production. Maintain dedicated fleets for staged rollout and let each rollout follow the fleet boundary.
• Project-level. Broadest scope. Rarely the right answer for production because it precludes staged rollout. Reasonable for development projects where every device is a test device.

Monitoring Fleet Health

A fleet admin running production devices needs answers to three questions every day:

1. Are my devices online?
2. Are my devices reporting normal values?
3. Where are the unhealthy devices right now?

Notehub provides a tool for each. Choosing the right one for each scenario, and combining them so they cover one another, is the fleet admin's job.

Silence Detection: Watchdog vs Heartbeat

Two features detect devices that have gone silent. They are not interchangeable.

Watchdog Events are configured per fleet. When a device exceeds the fleet's inactivity threshold, Notehub emits a _watchdog.qo event with metadata about the silent device. Watchdog events flow through your normal data pipeline and they can be routed to your ticketing system, on-call paging service, analytics warehouse, or anywhere else.

Heartbeat Alert Monitors are configured per project (with optional fleet scoping). When a device exceeds the configured inactivity threshold, Notehub sends an Email, Slack, or SMS notification directly.

Which to use:

• Watchdog Events when silence should flow into a system you already operate (ticketing, data lake, custom dashboard). Cheap, routable, and works across many destinations.
• Heartbeat Monitor for a simple way to get email, Slack, or SMS alerts when devices go silent.

The two aren't mutually exclusive — you can run both as needed for your particular use case.

Value-Threshold Detection: Event Alert Monitors

Event Alert Monitors fire when values inside the Notes your devices send cross a threshold you define.

There are two key decisions to consider when using Event Alert Monitors:

• Per-device vs aggregated. Enable "Per Device Monitoring" when you want to know which device crossed the threshold (the typical production case). Disable it when you care about a fleet-wide condition (e.g. "the average humidity across the warehouse fleet exceeded 80%").
• Method = None vs aggregated. Set Method to None for instant alerts the moment any event crosses the threshold. Use Average, Maximum, Minimum, Sum, or Count with a rolling timespan when you want to suppress noise or evaluate behavior over a window of time (e.g. Count > 100 over 1 hour can catch runaway firmware that is sending too many events).

Grouping by State: Smart Fleets for Monitoring

Smart fleets are not strictly an alerting tool, but they complement alert monitors nicely. A smart fleet whose rule is body.temperature > 20 ? $addToFleet() : $removeFromFleet() gives you a live list of every currently-too-hot device. This can be useful for device triage when an alert fires, and useful as a route filter (e.g. route only events from devices currently in a problem state to a specialized handler).

When alerts and smart fleets cover the same condition, they serve different needs: the alert notifies you when something happened, the smart fleet tells you what is happening right now.

Triaging a Specific Device

When a monitor fires or a customer reports a problem with a single device, the question is always "what does Notehub know about this device right now?"

There are four places to look:

• Device summary tab for top-level state: current fleet, last activity timestamp, recent connectivity, environment variables in effect.
• Events tab (filtered to the device) for the recent event stream — the actual data the device is sending. Compare against a healthy peer in the same fleet to spot deviations.
• Sessions tab (filtered to the device) for the connection history. Useful when the device is online intermittently: are syncs failing? Cellular sessions dropping early? Cell tower changing?
• _health.qo Health Log for the firmware-side diagnostic log emitted by Notecard. Often the fastest way to find out why a device is misbehaving when the UI views don't make it obvious.

A productive triage pass usually starts at the summary tab, drops into events for the data signal, sessions for the connectivity signal, and the health log only when the first three don't explain the problem.

Recovering from Route Failures

Routes can fail when downstream services have outages, certificates expire, and/or schemas change. Build the recovery posture into your route configuration up front:

• Enable automatic retry on every route that can tolerate it.
• Watch the route log for repeated failures. A small number of retries is normal; a sustained failure stream is an outage worth paging on.
• Bulk re-routing is your recovery tool once a downstream service is restored. Select the affected events and re-route them manually rather than treating them as lost.

tip

A monitoring setup that covers all three questions might look like:

Watchdog events on every operational fleet feeding the data lake, a Heartbeat Monitor on the most critical fleet paging on-call, an Event Monitor for the one threshold that matters most (battery, temperature, error rate), and two or three smart fleets keeping live state for triage. Start small and grow the setup as you discover what actually needs attention.

Day-to-Day Fleet Operations

This section covers the recurring operational tasks a fleet administrator handles once the fleet is running: tagging, decommissioning, auditing, and programmatic automation.

Tags for Cross-Cutting Organization

Fleets are the primary unit of organization, but devices often need to be grouped in ways that cut across fleets (e.g. by hardware revision, by firmware version, by support tier, by an internal classification that does not warrant its own fleet). Tags can be a useful tool in these scenarios.

A Notecard can carry multiple comma-separated tags, and tags are queryable through the Get Project Devices API. Tag assignments are also mirrored to the _tag reserved environment variable, which means a route or smart-fleet rule can read tags via the standard environment variable mechanism.

Use tags for:

• Cross-cutting classifications that span fleets (e.g. hardware revision or support tier).
• Temporary cohorts for an investigation or campaign (e.g. tag every device that exhibited a specific symptom, then operate on the tag).

See Organizing Devices by Tag for more information.

Decommissioning a Device

A device's last day on the fleet has three options, increasing in permanence:

1. Temporarily block connections. Use the Danger Zone on the device summary tab (or the Disable Device API) to prevent a misbehaving device from syncing while you investigate. The device keeps consuming a small amount of cellular data retrying, so this is not a long-term parking spot.
2. Move to a Decommissioned fleet. Reassign the device to a purpose-built fleet whose route filters and environment variable scope exclude it from your production data pipelines. The device record is preserved for audit and recovery, but the device no longer participates in routes, alerts, or normal operations.
3. Delete the device. Permanent! Use the Delete Device API or the Notehub UI when the device will never return. Deletion preserves the DeviceUID, but the same Notecard re-added later becomes a new record without history.

The conservative posture is: block first, move to "Decommissioned" fleet, then delete the device later (or never). Note that permanent deletion forfeits the audit trail tied to the device record.

For RMA workflows where a device may return to service under a different customer, prefer the "Decommissioned" fleet approach so you can re-provision without losing history.

Auditing Changes

Two audit logs cover the project lifecycle:

• The project audit log captures collaborator changes, ProductUID changes, and other project-level configuration changes.
• The billing account audit log (under the billing account's Audit Log tab) captures plan changes, event-credit purchases, payment-method updates, and contact-info changes.

Make audit log review a recurring habit (weekly or monthly, depending on fleet size and team size) so unexpected changes surface while you can still reconstruct context. Audit logs are also the first place to look when something stops working after a configuration change.

Programmatic Operations

The Notehub API is the right tool when you need to automate fleet tasks in custom ways. For routine bulk operations (e.g. environment variable updates, mass fleet reassignment, scheduled reports), batch jobs already cover most cases declaratively without writing any code.

However, the Notehub API earns its keep when fleet operations need to react to events in your own systems in real time, or when you need to integrate Notehub with workflows that batch jobs don't model. Some examples:

• A customer adds an order in your backend, then your code calls the API to assign their devices to a fleet and write customer-specific environment variables.
• Tie firmware rollouts into your CI/CD pipeline.
• Build custom dashboards or operational tooling that fetch live Notehub data on demand.
• Drive conditional provisioning workflows that depend on real-time business data.

For a hands-on tutorial, see Using the Notehub API.