InTouch device and cloud specification

Release boundary

The reference implementation runs one organization on one node. It can enroll device identities, accept arbitrary timestamped sensor channels, persist telemetry and clips, stream camera previews, and deliver desired configuration and flush commands. Android, iOS and the browser have foreground acquisition and viewer examples. The C99 core exposes driver and transport boundaries. A Linux executable supplies host diagnostics and a disk spool. Timing and storage limits differ by SDK and are documented with each client. The following product requirements distinguish this release from the target architecture.

Device model and connected inputs

A device represents a provisioned publisher. A physical asset may carry several devices and the same mobile phone may change assignments over time. The target registry records dated relationships among organization, site, asset, device, input port and sensor. A gateway must identify each downstream channel independently. Store a calibration revision with calibrated measurements. Preserve source values when applying conversion factors.

Use epoch milliseconds for interoperability and retain original event time. The server assigns a monotonic database sequence for receipt ordering. Production high-rate vibration and audio require a start time, monotonic sample counter and integer nanosecond delta or sampling frequency. The current JSON representation has millisecond resolution. A gateway with an unsynchronized clock must include a quality flag and its monotonic tick count in values. Do not silently move historical samples to their upload time.

Acquisition and delivery state machine

1. A user starts a phone session or a commissioned gateway loads a profile. Declare permitted sensors, minimum cadence, requested precision, buffer capacity and privacy mode.
2. Choose sensors by availability. A motion threshold operates in the device frame on acceleration magnitude. Apply cooldown to avoid repeated event messages. This detector has no crash-classification performance claim.
3. Preserve a burst as a group of timestamped readings. A cache write and a network acknowledgement are separate transitions. Persist immutable batch identifiers across process restart. New samples collected during upload belong to another mutable buffer.
4. Flush on a timer, size threshold, manual control or event. Reuse the ID and body if the response was lost. A receipt acknowledges the whole batch after one transaction commits. A content conflict stops that replay and requires investigation.
5. Apply the returned configuration after local validation. Report the applied revision on a later heartbeat. The operator can distinguish saved intent, a disconnected device and confirmed application.
6. Stop acquisition on consent withdrawal. Independent retention policies cover cached data and already-uploaded data. Production deletion must reach media, samples, indexes, exports and backups according to the applicable retention policy.

Production incident capture should maintain a circular pre-trigger buffer and a pinned post-trigger window. For example, retain 10 s before and 5 s after threshold crossing at 50 Hz. At three 16-bit axes the raw acceleration window is 4,500 bytes before timestamps and headers. Record a summary immediately and schedule the full burst or clip for an allowed link. Retriggering extends the same event up to a policy cap. Reserve storage for incident metadata. Emit explicit overflow and truncation counters. Current clients send threshold-triggered samples and queued data, with platform-specific debounce.

Battery, network and storage budgets

Treat the following as initial engineering targets. Validate on a named device, OS version, signal level, screen state and route. Report measured distributions and baseline conditions before promoting a target to an SLA.

Size a 30-minute disconnect at 25 Hz as 45,000 readings. At 100 encoded bytes per reading the payload alone needs 4.5 MB, plus indexes, metadata and filesystem reserve. Both current mobile row caps can saturate before that window. Choose the cap using measured bytes per retained sample and the expected offline window. For 10,000 active devices each sending 20 readings every 10 seconds, plan for 1,000 batch writes/s and 20,000 samples/s before reconnect and media peaks. No such fleet-scale result is claimed for the reference node.

Measure duty cycle and bytes separately for sensor, radio and encoder. Compare gzip versus plain payload with identical data. Include TLS handshake and retransmissions in cellular budgets. Use conservative upper bounds for camera bitrate multiplied by duration and event frequency. In production, throttle backlog drains per tenant, grant a bounded number of in-flight messages, jitter reconnects, decay sampling during stillness or thermal pressure, and restore detail on movement. Track the oldest queued reading and discarded samples alongside delivery latency.

Server, SaaS and deployment design

The initial server shares a durable SQLite volume across container replacements. SQLite serializes writers and stores media BLOBs alongside sample metadata. A DB page ceiling protects the host. Leave space for WAL and backups. Saturation returns a retryable storage error. High-volume video and multi-region writes require the storage split below.

• Device ingress. Terminate TLS at the edge. Provision per-device keys or certificates, rate-limit by device and tenant and reject oversized or invalid envelopes before storage. Add MQTT 5 sessions with expiry and QoS 1 for restricted embedded transports. Keep an HTTP fallback for firewalled sites.
• Data plane. Partition normalized events by tenant and device. Retain immutable raw envelopes and schema versions in object storage. Maintain hot indexed recent samples and spatial positions, plus columnar history and downsampled aggregates. Use event-time watermarks for delayed bursts. Late samples update historical views independently of current asset state.
• Media plane. Store encrypted clips in tenant-scoped object paths. Issue short-lived upload and read grants, checksum completed parts and expire abandoned sessions. Link event time and clip time with an uncertainty estimate. Audit operator playback and extraction.
• Control plane. Separate desired configuration from device observations. Use compare-and-swap writes, command deadlines, bounded delivery attempts, signed firmware manifests and staged rollout cohorts. Support A/B images and rollback on boot-loop or missing attestation. A digital output actuator must declare legal states, valid transitions, interlocks, local override, command expiry and independently observed feedback. Physical process safety remains local to its controller.
• Viewer. Show last contact, stale data, event time, delivery order, precise sensor units, desired/applied configuration, command status and retained media. The running console plots relative coordinate traces. Production adds licensed Mappls base maps, geofences, asset membership, role-based precision limits and incident correlation.
• Platform operations. Partition secrets and encryption keys per environment. Measure ingest/commit latency, dedupe ratio, spool age, throttle/drop rates, media transfer, config lag and command expiry. Alarm separately for backend faults and disconnected devices. Exercise snapshot restoration, replay and failover. Keep audit records free of raw bearer tokens.

Production release gates