TelemetryOS Applications

TelemetryOS applications run in a managed Chrome browser on devices, executed inside a secure iframe with full access to modern browser APIs. They communicate with the platform through the TelemetryOS SDK, which provides JavaScript APIs for storage, media, playlists, hardware, and more. This page covers the concepts you need before writing code.

How Applications Work

An application is a standard web project (HTML, CSS, JavaScript) that TelemetryOS 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 you'd expect 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, so the target environment is always known and consistent.

Application Components

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

The render view is the only required component. It contains the visual content that displays on the screen — a menu board, a dashboard, a kiosk interface, or any other experience built for the display. The render view is loaded at the path defined in telemetry.config.json (conventionally /render) and runs continuously on the device.

The settings view provides a configuration interface that appears in Studio when an administrator selects the application in a playlist. Settings views are ideal for exposing options like city names, API keys, color themes, or content selections without requiring code changes. Data saved in the settings view is written to instance storage and is immediately available to the render view on the device.

The web view is a browser-accessible interface that runs outside Studio and the device player entirely. Staff, operators, or the public access it via URL on phones, tablets, and desktops. Web views use application-scoped and shared storage to communicate with the render and settings views.

Workers are background scripts that run continuously on devices, even when the render view isn't visible. They handle tasks like periodic data synchronization, polling external APIs, or processing incoming messages. Workers have full SDK access and share storage with the other components.

Containers allow applications to run Docker services directly on the device. A kiosk application might include a local API server; a manufacturing dashboard might run inference models. Containers communicate with the frontend over localhost and only run on physical devices (not in Studio).

All five components communicate through the SDK's storage and messaging APIs, creating a cohesive application from independent pieces. For implementation details on each component, see the Development section.

Storage Scopes

The SDK provides four storage scopes that control how data is shared across the fleet.

Application storage is global — data written here is available to every instance of the application on every device. This is useful for shared configuration that applies everywhere, like a company logo URL or a global announcement.

Instance storage is scoped to a specific placement of the application in a playlist. When the same weather application is placed on two different playlists showing different cities, each instance has its own storage. Settings views write to instance storage by default, making it the most commonly used scope.

Device storage persists data on a single physical device. It survives application updates and playlist changes but doesn't sync to other devices. Device storage is appropriate for local calibration data, cached credentials, or hardware-specific configuration.

Shared storage enables communication between different applications running on the same device. Applications opt into a shared namespace, allowing a data-collection application to publish information that a display application consumes without tight coupling.

Changes to storage propagate in real time. When a settings view updates a value, the render view on the device receives the change within seconds through subscription callbacks.

Git-to-Screen Deployment

The deployment model is designed to feel natural for development teams already using Git. Code lives in version control. Pushes trigger builds. Builds produce deployable artifacts. Artifacts are assigned to devices through playlists.

This means the same branching strategies used for web applications work here. A develop branch can target test devices, a staging branch goes to QA displays, and main deploys to production. Feature branches let developers test in isolation before merging. Semantic versioning tracks what's running where.

Rollback is immediate — select a previous version in Studio and it propagates to devices within seconds. There's no manual file copying, USB drives, or device-by-device updates.

Offline Behavior

Applications run locally on the device once they're downloaded. Content, code, and cached data persist in device storage, so the application continues working during network interruptions. The platform handles content synchronization automatically — when connectivity returns, queued storage writes sync and new content downloads resume.

Designing for offline means thinking about what the application should show when it can't reach an external API. The SDK's proxy includes fleet-wide caching, so frequently requested data may already be available locally. For applications that depend heavily on real-time data, a fallback UI (showing cached data with a timestamp, or a "last updated" indicator) keeps the experience useful rather than broken.

What's Different from Regular Web Development

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

The runtime is always Chrome, so there's no need to polyfill or test across browsers. Target modern JavaScript and CSS confidently.

Applications run client-side only. There's no server-side rendering or Node.js runtime on the device (though containers can provide backend services). If you need server-side logic, use a container or call an external API through the SDK proxy.

Hardware access goes through the SDK, not directly through browser APIs. Camera capture, serial communication, and GPIO interaction all use SDK methods that bridge to the underlying hardware.

The deployment target is a managed fleet, not individual users. Think about how configuration will vary 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

Explore real-world examples of what teams build on TelemetryOS in Use Cases, then learn about the Chrome-based runtime and supported technologies in Languages Supported. When you're ready to write code, the Quick Start walks through building and deploying a first application step by step.