Coldwave Documentation

Appearance

Application Developer Guide ​

This guide explains how to use the Coldwave Cloud Backend v5 to build applications: dashboards, configuration UIs, mobile apps or integrations that consume device data and control devices.

It focuses on how to use the backend from an application point of view. For the full list of endpoints, request/response schemas and events, refer to the module reference.

Who this guide is for ​

This document is intended for:

  • Frontend and full-stack developers building web or mobile user interfaces.
  • System integrators who want to connect existing applications to Coldwave.
  • Backend developers who need to consume Coldwave data or trigger actions.

You should be familiar with basic web technologies (HTTP, JSON, WebSockets) and have access to a running Coldwave backend instance (<<URL>>) provided by your organization or OEM.

All REST endpoints live under a versioned base path:

text
https://<<URL>>/api/v1/...

What you can build with the Coldwave backend ​

Typical applications based on the Coldwave backend include:

  • Monitoring dashboards

    • Show current values and status of devices (temperature, mode, connectivity, …).
    • Display metadata such as location, installation info, customer labels.

  • Configuration and commissioning tools

    • Write device properties (setpoints, operating modes) and call device methods.
    • Attach metadata (names, locations, tags) to devices.

  • Operations & maintenance tools

  • Integrations

    • Forward live events to third-party tools via the websocket stream.
    • Store application state alongside the fleet (data and userdata modules).

Core concepts in one picture ​

The Coldwave backend models the world in a few core entities:

  • Tenant Every resource belongs to exactly one tenant — your organization or your customer's. Your account lives in a tenant, and everything you can see or change is scoped to it.

  • Device Represents a physical (or virtual) IoT device. A device:

    • Is identified by its device id or its IMEI — API routes accept either.
    • Is the container for services.
    • Has no built-in display name — human-readable names and locations live in metadata.

  • Service A typed interface a device exposes, identified by a service identifier (UUID). Devices of the same type share the same service identifiers, so one schema describes them all. Examples:

    • A "temperature" service with temperature, humidity, battery level.
    • A "lift control" service with mode, door state, error code.

  • Property The smallest unit of data. A property:

    • Belongs to exactly one service on exactly one device.
    • Has a canonical hexadecimal id (0x0800) and a type (UINT16, FLOAT, BOOL, …).
    • May be read-only or writable (the schema carries the hint; the device has the final say).

  • Schema The schema describes how a service should be presented, per service identifier:

    • Human-readable names (temperature), units (°C, %), descriptions, translations.
    • Enum definitions (1 = off, 2 = silent, 3 = running), value ranges, display formats.
    • Read-only / actionable flags, and the methods a service supports.

    Schemas are maintained in the backend and not enforced on the physical device. You can change labels, units or enums without touching device firmware.

  • Metadata The meta module keeps per-device information that is not measurement data:

    • Maintained by the backend: connectivity status (online / offline / idle) and lastMessage timestamp.
    • Maintained by you: a free-form data object for names, locations, tags — anything your application wants to attach.

  • Events (WebSocket) Every state change in the backend is an event. Over a websocket you receive the ones you are allowed to read — property updates, status changes, metadata edits — and apply them on top of your initial REST snapshot.

Coldwave Resource Names (CRNs) ​

Every resource is identified by a CRN, a structured string you will see in API responses wherever a resource is referenced:

text
crn#tenant:Ba9mN3pQ.device:Yk3pL7rW.service:00000000-0000-2001-8003-006d0099ab53
  • Segments run broadest → most specific (tenant → device → service), so a child CRN contains its parents. You can tell which device a service belongs to by string prefix.
  • Treat a CRN as an opaque handle: pass it back as-is, don't build one by hand.
  • Access control matches your permissions against CRNs — whether you may read or write a resource is decided on this string.

Typical application flow ​

Most applications follow the same high-level flow:

  1. Authenticate — log in with email and password over a DPoP-signed request and obtain an access/refresh token pair (Authentication & Sessions).
  2. Discover devices — GET /api/v1/devices?depth=2 returns devices, their services and all current property values in one response (Devices & Properties).
  3. Load schemas — GET /api/v1/schema?depth=1 and build a local mapping from (serviceIdentifier, propertyId) to name, unit, enum and flags (Schemas).
  4. Load metadata — GET /api/v1/meta?depth=1 for display names, locations and connectivity status (Metadata).
  5. Open the websocket — fetch a ticket, connect, and apply incoming events to your local state (WebSocket & Events).
  6. Write reactively — property writes and method calls go through REST; their effects come back as events.

How this guide is organized ​

Next steps ​

  • The module reference documents every endpoint, request/response schema, error and event — the same information this guide links throughout.
  • IAM covers tenants, roles, user groups and access management for multi-tenant applications and customer portals.
  • Device groups, codebooks and functions extend the data model beyond the basics shown here.
  • The audit module records who changed what — useful for operations tooling.