Device Catalog

Building automation is about controlling devices such as luminaires, thermostats, fans and roller blinds. BlueRange integrates the underlying technical protocols offering a unified interface for measurement and control applications to work with. The software provides information for visualization and control including metadata such as labels, units and ranges of values. Also, sensor data is historized and aggregated and actuators are grouped. These platform services are build on-top of a device catalog that is queried by a detection mechanism identifying the devices installed.

The idea is to make this description informative enough so that the user can properly connect all devices, using mostly generic models without having to rely on vendor-specific models. For example to avoid creating a vendor-specific model for a ceiling fan with a light bulb but use generic models to describe it and use the device profile JSON to give meaning to the elements.

Catalog data is not intended to be added or modified by users of the platform but provided by M-Way and device manufacturers. If you are a manufacturer, contact us so that we can include your devices in the catalog.

Make sure to take a look at our HowTo about Sensors and Actuators for some examples on how the Device Catalog is intended to be used.

Device Capabilities

The network management facility build into BlueRange mesh gateways constantly monitors devices connected for status information such as the battery power level, device information like family and feature groups and device capabilities. Status information may change relatively frequently and is the major source of device availability state as it is displayed in the platform management UI. The device information on the other hand is static by nature and controls fundamental behaviors of the infrastructure like how a device is connected to the mesh, how frequently the status is polled and what firmware updates apply to it.

Now device capabilities are somewhat in-between in that they change seldom. They describe individual hard- and software components making up the device and come with a version or revision information attached. For example the Solo-Lighting MSLine 1200 initially may be reporting a set of device capabilities containing a BlueRange Node Software 0.8.3300, a Vossloh Firmware 1.144, a Vossloh Bootloader 0.2 and a Vossloh Hardware Revision 1.0. When the lamp is extended by plugging in an additional LED panel that also adds new sensors, the newly attached panel gets reported as a component in the device capability records. At runtime the device initiates an update of its data autonomously.

Mesh gateways automatically query device capabilities and persist the data as part of the device details to the BlueRange server. The IotDeviceDetails.capabilities is an array of records with the properties:

capabilityType: as one of HARDWARE, SOFTWARE or METADATA,
manufacturer: as an arbitrary text like MWAY DIGITAL GmbH, Solo-Lighting or Warema,
model: as a human-readable name like MSLine 1200 or E80A6, and
revision: of hard-, software or metadata as a plain string.

At the simplest, the above allows mapping the capabilityType to an icon and concatenating the remaining information for display purposes serving diagnostics, for example. Furthermore, the system utilizes the manufacturer, model and revision information of the metadata records for querying the device catalog.

To get a better understanding, make sure to see our guide on implementing capabilities.

Capability Sources

Ideally the list of capabilities is exposed by the firmware installed so that auto-detection can correctly identify devices as they are connected. In some cases metadata records may need to be added, either because the device does not know for manufacturing reasons as is the case currently for Solo-Lighting luminaires or because the building automation technology does not provide enough information for automatic detection such as KNX. In those cases metadata capability records are imported from environment profiles.

The list of device capabilities is ordered from least specific to most detailed. This is because firmware most likely returns it this way. Records taken from environment profiles are appended to the end. When merging metadata, for information that can not be integrated later records win and overwrite data from earlier ones. An example is the power curve used for computation of energy consumption from the brightness of a luminaire.

Considering UIs it makes sense displaying the capability list in reverse order so that more information comes towards the top of the list.

Metadata Matching

The device metadata is stored in a catalog repository keyed on the Device Capabilities of type METADATA. The repository is a file system, housing device profile JSON files named {manufacturer}/{model}/{revision}.json that look like the following example. Make sure to take a look at our guide on implementing capabilites to get more information on the used example. Also take a look at our dedicated chapters for sensors and actuators for more information.

// This example describes a luminaire with a main unit and two light heads
// with each of the light heads having a device for regulating the head
// The optional CO2 sensor could be part of a second device catalog entry

//(M) is mandatory, (O) is optional
{
    //(M) Defines the version of this profile definition (how to interpret the following data, for future releases of the profile definition)
    "deviceProfileSchema": 1,

    //(M) repeats data encoded in filename for validation
    "manufacturer": "The Light Company",
    "model": "SuperLum 2000",
    "revision": "1",

    //(O) additional capability requirements tested for via regex that need to be present for the profile to apply
    "requirements": [
        {
            "capabilityType": "HARDWARE",
            "manufacturer": "The Light Company",
            "model": "Main Control Unit",
            "revision": "2\..+" //Matches any revision, e.g. 2.0, 2.123 that starts with "2."
        }, {
            "capabilityType": "SOFTWARE",
            "manufacturer": "The Light Company",
            "model": "Main Control Unit",
            "revision": ".+" //Matches any revision which is also the default
        }
    ],

    //(M) describes the purpose if this thing in its whole guiding UIs
    "archetype": "LIGHT",

    //(M) adds some user readable description and images
    "name": "SuperLum 2000 by the Light Company",
    //(O) Array of images, first image should be most important as apps might only display a single one
    "image": [ "super_lum_2000_main.jpg" ],
    //(O) icon must be postfixed with its size, minimum size is 256x256
    "icon": [ "super_lum_2000_ico_256x256.png" ],
    //(O) human-readable description
    "description": "This is a luminaire with two light heads that have a temperature and an optional CO2 sensor.",

    //(O) actual device profile metadata content
    "sensors": [
        {
            "description": "Brightness sensor for light head 0",
            "type": "BRIGHTNESS",
            "index": 0,
            "module": "0xABCD01F0", //Could also be e.g. "status" for well-known modules
            "component": 1,
            "register": 1,
            "offset": 0,
            "length": 4,
            "dataType": "UINT32"
        },
        {
            "description": "Brightness sensor for light head 1",
            "type": "BRIGHTNESS",
            "index": 1,
            "module": "0xABCD01F0",
            "component": 2,
            "register": 1,
            "offset": 0,
            "length": 4,
            "dataType": "UINT32"
        },
        {
            "description": "Main Unit Ambient Temperature Sensor",
            "type": "TEMPERATURE",
            "index": 0,
            "module": "0xABCD01F0",
            "component": 0,
            "register": 500,
            "offset": 0,
            "length": 2,
            "unit": "CELSIUS",
            "dataType": "UINT16"
        }
    ],
    "actuators": [
        {
            "description": "Set the brightness both light heads",
            "type": "SET_BRIGHTNESS_ALL", //Use a different type for aggregated types
            "index": 0,
            "module": "0xABCD01F0",
            "component": 0,
            "register": 1122,
            "offset": 0,
            "length": 2,
            "unit": "PERCENT",
            "dataType": "UINT16"
        },
        {
            "description": "Set the brightness for light head 0",
            "type": "SET_BRIGHTNESS",
            "index": 0,
            "module": "0xABCD01F0",
            "component": 1,
            "register": 123,
            "offset": 0,
            "length": 2,
            "unit": "PERCENT",
            "dataType": "UINT16"
        }
        // ... more
    ],
    "indicators": [
        {
            "description": "Report an error condition of the Main Unit",
            "type": "SUPERLUM_MAIN_UNIT_FAILURE",
            "index": 0,
            "module": "0xABCD01F0",
            "component": 1,
            "register": 100,
            "offset": 0,
            "length": 2,
            "bitmask": "//8=" //Triggers if any of the bits are set (bitmask: 11111111 11111111)
        },
    ],
    "power": {
        // power curve...
    }
}

Be aware that you should not report accumulated sensor values using the same sensor type that you are already using for individual sensors as our platform will already aggregate the individual values and will return e.g. the average over all sensors.

In the metadata the manufacturer, model and revision is repeated at the top for validation purposes. The optional capabilities array may require additional matching capabilities that need to be present on the device for the metadata to apply.

An archetype may be given to guide the user interface when it comes to grouping user controls, etc. For example a luminaire might have an on/off switch and a brightness slider nicely arranged. Upon profile merging, the archetypes given become a set. The catalog supports a well-defined list of possible archetypes only (e.g. BLIND, LIGHT, …).

The remaining properties sensors, actuators and power store the actual profile data. Given a device the platform uses all applicable metadata profiles.

Offline usage

The above profile metadata provides device descriptions for offline use, e.g. for a technician that starts to plan the building in advance but does not yet have access to the devices. Also, we want to be able to describe a device to the user.

Accessing the catalog

The device profile data is stored on the BlueRange server as it needs the information for preparing preprocessed data on sensors and actuators for clients and application to consume easier. Also, the mesh gateway can download the metadata relevant to its devices easily. That way changing the catalog does not require updating all gateways installed into the building.

Device Archetypes

Our list of supported archetypes can be found on the archetypes page. The archetype property must use one of the predefined values.

Actuator / Sensor definition

Derived from the DeviceCatalog, the Actuator- and SensorDefinitions are created. The two definitions are designed to match each other and applied will reverse each other’s transformation (with some exceptions).

Take a look at our sensor definitions documentation for a more complete look on what is available.

type: gives a logical name to an actuator or sensor. For actuators the type name used should follow the pattern DO_WHAT, e.g. TURN_ON, DRIVE_UP, SET_TEMPERATURE. Sensor names use nouns, e.g. BRIGHTNESS. Use unqualified nouns for primary data in building automation, e.g. TEMPERATURE for room temperatures but COOLING_TEMPERATURE for refrigerators. The naming needs to be consistent regarding range, unit and meaning because sensors of same name are subject to aggregation. E.g. do not use Celsius somewhere and Fahrenheit elsewhere, but stick to standard SI units.

unit: Take a look at our list of supported units and the units listed for the different archetypes below.
scale: If your raw value needs scaling as the sensor delivers the raw data e.g. in 1/5th degree celsius or if you need to convert from kilometers to meters, use the scaling factor. For simple use-cases, it should be preferred over the formula.
formula: is a field in metadata of both actuators and sensors and allows transformation of the values. An example use is mapping a brightness value to an LED power level. Please notice that sensor values should use a linear gradient so that aggregations such as averaging make some sense. (see mXparser documentation)

The core software system does not hard-code any of the names defined herein. However, clients are expected to use these names as translation keys at least. Notice, clients must be prepared dealing with newly introduced names and behave gracefully e.g. by displaying the untranslated key name directly in case it does not match any existing translation.

Numeric values

If the value is numeric, the mathematically parameters (scale, min, max, formula) to transform the value can be applied.

Transformation order for Sensors

take input
apply formula
apply scale
clamp to max
clamp to min

Transformation order for Actuators

take input
clamp to min
clamp to max
apply scale
apply formula