Browse pages
Connected Devices
Devices hold state, apply rules, and sync while offline, so the product owes them a protocol: messages, versions, client rules, and the shape of offline uploads. This page states the protocol block an entry point carries when devices reach it. A project selects it for each entry point that serves scanners, kiosks, or offline-capable clients.
Stack: any
Layer: frontend-ui
Activation#
Activation scope: local.
Applicable specification kinds: entry-point.
A project selects devices for an entry point when devices reach it with stored state, local rules, or offline sync. A browser or API entry point with no device client does not select it.
Baseline Relationship#
This extension replaces no baseline provision. It switches on no record type: it adds the protocol block to entry-point records.
The block names the messages the entry point exchanges, the version rule devices follow, the client rules devices apply with their scenarios, the nonce that makes retries idempotent, and the force and simulate flags on offline uploads.
Standards#
Describe Device Messages as a Channel Fragment#
ruleruleguidancelitespec/ext/devices#describe-device-messages-as-a-channel-fragmentA device protocol MUST describe its messages as an AsyncAPI channel fragment with named operations and payloads.
Applies toartifact: record:entry-point; conformance: records
Why
Devices and servers evolve apart: a scanner runs last year's firmware against this week's server. A channel fragment names each direction, each message, and each payload in one shape both sides read, so a mismatch shows in the record before it shows on the loading dock.
Example
protocol:
channel: scanner/check-in
publish:
message: check-in.recorded
payload: { code, nonce, scannedAt }
subscribe:
message: check-in.denied
payload: { code, reason }Checka reviewer answers
Reviewed forThe protocol blocks on the device entry points list named operations with payloads in the channel shape.
Marked guidance: a reviewer answers this question.
Version the Device Protocol#
ruleruleguidancelitespec/ext/devices#version-the-device-protocolA device protocol MUST state its version rule with numbering, overlap, and the upgrade path.
Applies toartifact: record:entry-point; conformance: records
Why
Old firmware cannot be recalled from the field, so several protocol versions stay live at once. Numbering tells a device which version it speaks, overlap tells the server how long to answer old versions, and the upgrade path tells the device how to move forward. Without the three, a server upgrade bricks every device that missed the memo.
Checka reviewer answers
Reviewed forThe protocol blocks state numbering, overlap, and the upgrade path devices follow.
Marked guidance: a reviewer answers this question.
State Client Rules with Scenarios#
ruleruleguidancelitespec/ext/devices#state-client-rules-with-scenariosEach client rule in a device protocol MUST carry the scenarios that prove it.
Applies toartifact: record:entry-point; conformance: records
Why
Client rules run where the server cannot see them: validation a scanner applies offline, storage limits a kiosk enforces, queueing a phone does in a tunnel. A rule without scenarios is a rumor about what devices do. Scenarios pin the rule to observable device behavior the product tests against.
Example
The rule a scanner queues scans while offline carries the scenario a scan queued offline uploads on reconnect.
Checka reviewer answers
Reviewed forEach client rule in the protocol blocks points at scenarios that prove it.
Marked guidance: a reviewer answers this question.
Identify Retries with a Nonce#
ruleruleguidancelitespec/ext/devices#identify-retries-with-a-nonceEach mutating device message MUST carry a client-generated nonce as its idempotency key.
Applies toartifact: record:entry-point; conformance: records
Why
A device that loses signal mid-send retries what the server already applied. The nonce gives the retry a stable identity scoped to the device, so the server answers the repeat from the first attempt instead of lending, paying, or shipping twice.
Example
A loan scan carries nonce: 7f3a, and the second delivery of the same nonce returns the first attempt's result.
Checka reviewer answers
Reviewed forThe mutating messages in the protocol blocks carry a client-generated nonce scoped to the device.
Marked guidance: a reviewer answers this question.
Simulate Offline Uploads Before Applying#
ruleruleguidancelitespec/ext/devices#simulate-offline-uploads-before-applyingAn offline upload with simulate MUST return its outcome without writing.
Applies toartifact: command-handler
Why
A device back online after a week holds uploads the world outgrew: prices changed, holds lapsed, windows closed. Simulating the queue shows what would happen before anything is written, so the operator reconciles first and applies second.
Example
A scanner uploads three hundred queued scans with simulate, reviews the two the server would refuse, and then uploads for real.
Checka reviewer answers
Reviewed forSimulated uploads in the device tests return outcomes with no writes behind them.
Marked guidance: a reviewer answers this question.
Apply Forced Uploads over Newer State#
ruleruleguidancelitespec/ext/devices#apply-forced-uploads-over-newer-stateAn offline upload with force MUST apply over newer server state and record the overwrite.
Applies toartifact: command-handler
Why
Sometimes the device is right and the server is stale: a supervisor corrected the count on the floor while the server held the old one. Force lets the operator say so explicitly, and the recorded overwrite keeps the decision visible instead of burying it in a silent win.
Example
A corrected count uploads with force, overwrites the server value, and leaves an overwrite record naming the operator.
Checka reviewer answers
Reviewed forForced uploads in the device tests overwrite newer server values and leave overwrite records.
Marked guidance: a reviewer answers this question.
Conventions#
Version Protocols by Date#
conventiondefaultguidancelitespec/ext/devices#version-protocols-by-dateProtocol versions use calendar numbering of the form YYYY.N.
ReplacementA project names its protocol numbering scheme in its device documentation.
Applies toartifact: record:entry-point; conformance: records
Why
Calendar numbering tells a support engineer how old a device is at a glance. Any scheme works when every device and the server share it.
Checka reviewer answers
Reviewed forProtocol versions read as calendar numbers, or the device documentation names the numbering scheme.
Marked guidance: a reviewer answers this question.
Replay Uploads in Queue Order#
conventiondefaultguidancelitespec/ext/devices#replay-uploads-in-queue-orderThe server applies an offline queue in the order the device queued it.
ReplacementA project names the order its server applies offline queues.
Applies toartifact: command-handler
Why
Queue order matches what the operator saw on the device: first scanned, first applied. Another order replays the day out of sequence and surprises everyone reading the log.
Checka reviewer answers
Reviewed forThe server applies offline queues in device order in the upload tests, or the project names another order.
Marked guidance: a reviewer answers this question.
Dependencies#
Packages: None.
Related extensions: concurrency for the nonce idempotency keys and overlapping-write handling.
Guides: None.