Coldwave Cloud Backend

The backend is the cloud-endpoint that manages communications between all actors in the coldwave ecosystem: IoT-devices, mobile apps, web-based user-interfaces, as well as voice assistants and clients. The coldwave backend was designed with modularity in mind and comes with a wide collection of built-in modules. The most common used modules are documented in the Core section, while the more special-purpose modules can be found in the Utilities section. Each module manages its own state and contains all the utilities it needs to work properly. This allows to enable or disable modules freely to save computational and storage resources when a feature is not required.

TIP

This modular approach also allows for quick prototyping and integration of features. If there is any feature you would like to see, that is not already there, feel free to get in touch!

Terminology

The central entity within coldwave are Devices. They provide all the data most of the API is based on. Therefore, it is important to understand some basic structure and terminology. Below is a simplified diagram depicting a single Device and all its components, connected to the coldwave Backend. The terms used in the picture will be explained below.

Device

A Device, most of the time being a physical electronic component, within coldwave represents a collection of so called Services. These services are defined by the implementor of the device, except for one required, pre-defined service, called device-service. The device-service manages some base-information like a unique identifier and information about the device firwmare, needed for the device to participate in the coldwave ecosystem. Without exposing a device-service, a device is not allowed to connect to the backend. In contrast to other services, the device-service itself is only used internally and not exposed via the API.

Service

A Service is an object exposed by a Device, that consists of several Properties. Each Device can expose multiple services in a mixture of different services or services of the same type. A Service is identified by a UUID, called the service identifier. In software development terminology a service can be seen as an instance of an object with a specific interface. The service identifier is a Version 4 UUID, represented as a string according to RFC 4122, which in short (regex form) is as follows:

^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

For example: 00000000-0000-0000-0000-000000000000. Every service with the same identifier is expected to expose the same properties.

Properties

A Property is the most basic entity within the coldwave-stack. It represents a datapoint on a given service and device. Thus, a Property belongs to a service like a service belongs to a device. Every Property is described by a type, a value and certain flags that indicate if it is editable or read-only for the user. the currently supported data-types for properties are:

• INT32, a 32bit signed integer
• INT16, a 16bit signed integer
• INT8, an 8bit signed integer
• UINT32, a 32bit unsigned integer
• UINT16, a 16bit unsigned integer
• UINT8, an 8bit unsigned integer
• FLOAT, a 32bit IEEE floating point number
• DATETIME, a UNIX timestamp
• STRING, an encoding-agnostic string
• BOOL, a boolean value
• UUID, a 128bit unique identifier
• BIN, any binary character sequence, should not exceed 1kB

A Property is identified by a 16 bit unsigned integer, called the property identifier. Throughout the API the property identifier can be represented in hexadecimal-format, e.g. 0x2000, or a decimal , e.g. 8192.

TIP

For a deeper insight, check out the GET Endpoints for the Service API. Furthermore, compare the responses when adding or leaving the query parameter raw. The default response (query parameter raw equals false) returns all properties mapped to the respective schema for the service, set via the Schema API.

Schema

A Schema offers a way to describe a service by adding more information to its properties, such as names, units and descriptions. It also supports enum-type values. In software development terminology a schema can be seen as an interface that a service is expected to adhere to. The Schema is only known to the backend and does not affect what is really exposed by the device. For example, a Property not included in the schema will still be accessible, but only via its property identifier and not a human readable label (i.e. 0x2001.UINT8 instead of temperature e.g.). On the other hand, a property defined as read-only by the schema while actually being editable by the user will not be editable via the backend API anymore. So make sure, the schema definition for a service does match the real service closely.

TIP

For further insight make sure to check out GET Endpoints for the Schema API.