Concepts

To help you use our API it is helpful to know the following terminologies.

%%{init: {'theme': 'dark'}}%%
graph TD
    subgraph "Site: Restaurant 1" 
        subgraph "Real Device Gateway"
            GW["Device"]:::deviceClass
        end

        subgraph "Real Sensor Door Contact"
            DS["Sensor"]:::sensorClass
            PC_Door["⚡ Physical Channel:<br>Door State"]:::physicalChannelClass
        end

        subgraph "Real Device Logger"
            LG["Device"]:::deviceClass
            LS["Sensor"]:::deviceClass
            PC_Temp["⚡ Physical Channel:<br/>Temperature"]:::physicalChannelClass
            PC_Humid["⚡ Physical Channel: Humidity"]:::physicalChannelClass
        end

        subgraph "Measurement Object Fridge"
            MO["❄️ Fridge"]:::objectClass
            LC_Temp["🔗 Logical Channel:<br/>Internal Temperature"]:::logicChannelClass
            LC_Door["🔗 Logical Channel: Door State"]:::logicChannelClass
            AC["Measurement Object:<br/>Alarm Config"]:::alarmClass
            CAC["Channel Alarm Config:<br/>Internal Temperature"]:::alarmConfigClass
            IS["Measurement Object<br/>Instruction Set"]:::measurementObjectConfigClass
        end
    end

    GW --- DS
    DS --- PC_Door
    LS --- PC_Temp
    LS --- PC_Humid
    LG --- LS

    MO --- LC_Temp
    MO --- LC_Door

    PC_Temp -. "Maps to" .-> LC_Temp
    PC_Door -. "Maps to" .-> LC_Door

    MO --- AC
    AC --- CAC
    MO --- IS

    classDef deviceClass stroke:#2D333B,stroke-width:2px,color:#fff
    classDef sensorClass stroke:#2D333B,stroke-width:2px,color:#fff
    classDef logicChannelClass stroke:#F9A825,stroke-width:2px,color:#fff,stroke-dasharray:3
    classDef physicalChannelClass stroke:#41B883,stroke-width:2px,color:#fff,stroke-dasharray:3
    classDef objectClass stroke:#2D333B,stroke-width:2px,color:#fff
    classDef alarmClass stroke:#E74C3C,stroke-width:2px,color:#fff
    classDef alarmConfigClass stroke:#E74C3C,stroke-width:2px,color:#fff,stroke-dasharray:3
    classDef measurementObjectConfigClass stroke:#878787,stroke-width:2px,color:#fff,stroke-dasharray:3

Site

A site is an abstract concept representing a physical location where your devices are situated, such as a restaurant or a warehouse. Each site is linked to a unique connect key, which allows for the registration of devices at that site.

Devices

In the Device Management API, Devices represent top-level hardware entities to which sensors are attached. For example, gateways and loggers are interpreted as devices that possess sensors.

Sensors

Sensors are components that measure specific environmental parameters, such as temperature or humidity. These measurements are represented as "sensor channels" within the sensor structure. In some cases, sensors are integrated directly into loggers rather than existing as separate physical devices like standalone sensors or gateways. For example, a logger with built-in temperature sensors can directly monitor the temperature of a storage area. In the device management API, this would be represented as a device with an associated sensor that has a temperature channel.

Channel

A channel represents a measurement property and can be either logical or physical. A physical channel is directly connected to a real sensor or logger and provides actual measurement values. A logical channel, on the other hand, is always associated with a measuring object and represents a specific property of that object, such as its temperature. Logical channels always receive their values from physical channels that are mapped to them. This mapping allows measurement data from physical sensors to be associated with logical properties of a measuring object.

Measuring Objects

A measuring object is the specific physical location or concept being monitored by a sensor at a site. For example, if a temperature sensor is placed inside a freezer, the freezer is the measuring object, while the restaurant where it is located is the site. This concept helps users associate specific sensors with their monitoring locations, enhancing data organization and management.

Alarm Configurations

Each measurement object is always assigned an alarm configuration, which contains by default no channel alarm configurations. You can add to this configuration alarm channel configurations for each logical channel to define specific thresholds that, when exceeded, will trigger an alarm.

Measurement Object Instruction Set

This contains settings like measurement interval for each logical channel. These settings will be propagated to the related physical channel and will overwrite the settings on channel sensor or device level.