Core Concepts

This section covers the concepts you need before writing code: how applications run, the component model, how data flows between components, and how code gets from Git to device screens.

How Applications Work

A TelemetryOS application is a standard web project (HTML, CSS, JavaScript) that the platform builds from a Git repository and distributes to devices. On the device, the TOS Player loads the application in an iframe within its Chrome-based runtime. The iframe provides an isolated execution context while still exposing the full browser API surface — Canvas, WebGL, Fetch, WebSocket, IndexedDB, and everything else available in a modern browser.

The SDK bridges the gap between the browser sandbox and the platform. It exposes methods for reading and writing persistent storage, accessing the device media library, controlling playlist navigation, proxying external API requests (with built-in CORS handling and fleet-wide caching), and interacting with hardware like cameras, serial ports, and GPIO pins.

Because the runtime is a version-controlled Chrome instance managed by TelemetryOS, there are no cross-browser compatibility concerns. Every device in the fleet runs the same browser version.

Application Components

Applications are composed of up to five parts, each serving a distinct role.

The three browser-based components (render, settings, web) are configured as mount points — URL paths declared in telemetry.config.json. Workers and containers use separate configuration blocks.

All five components communicate through the SDK's storage and messaging APIs, creating a cohesive application from independent pieces.

What's Different from Regular Web Development

A few things distinguish TelemetryOS development from building a typical web application:

• The runtime is always Chrome. No polyfills or cross-browser testing needed. Target modern JavaScript and CSS confidently.
• Applications run client-side only. No server-side rendering or Node.js runtime on the device, though containers can provide backend services.
• Hardware access goes through the SDK. Camera capture, serial communication, and GPIO interaction all use SDK methods.
• The deployment target is a managed fleet. Think about how configuration varies across instances (use instance storage), how updates propagate (Git-to-Screen), and how the application behaves unattended (handle errors gracefully, avoid modals that require dismissal).

Next Steps

• Mount Points — How render, settings, and web components work
• Storage Scopes — The four storage scopes and how data flows between components
• Deployment Model — Git-to-Screen deployment, versioning, and rollback
• Offline — How applications handle network interruptions
• Languages & Runtime — Supported technologies and the Chrome runtime