Overview

1. Overview

Purpose of the API

This API defines the structure, transport, and permissions for exchanging data between optical sensor systems (OSS8), the backend Websocket Secure Server (W3S), and client applications operated by end users. It ensures that all communication is:

Schema-validated via strict MessageTypeId contracts
Permission-controlled, based on sender and message type
Transported via WebSockets for low-latency, real-time operation
Consistent, regardless of whether the payload is structured JSON or binary image data

System Participants

OSS8 (Sensor System):
Hardware units generating status, alarms, and image data. They also respond to commands and push telemetry to the backend.
W3S (Backend + Middleware):
Acts as a relay, validator, permission enforcer, and message router. It may forward, log, or consume messages, depending on their type and permissions.
Client (User Interface):
Web or mobile App applications operated by authorized users, capable of sending commands and receiving relevant sensor messages and images.

Transport Protocol

All messages are sent over authenticated WebSockets using:

Text frames for structured JSON messages
Binary frames for image data, with a JSON header prepended via a defined framing format

Message Architecture Summary

Each message consists of a standard top-level JSON structure, which includes:

MessageTypeId: Identifies the purpose and type of the message / data
DeviceId: The origin or target of the message
Timestamp: When the message was created
Version: API version the sender implements
Payload: The actual data, or metadata if binary content follows

Binary messages are framed with a fixed-size prefix that declares the length of the JSON header, followed by the image data (e.g., encoded in JPEG XL).

MessageTypeId & Permissions Concept

Each message includes a MessageTypeId, which:

Determines how the message is parsed and validated
Controls which roles can send or receive that message type
Enables schema-based validation via the backend jsonschema W3S middleware
Helps prevent forgery, by validating the payload against a known contract for that MessageTypeId