Sensor Data Guide

Prerequisites: Device Sensor Capabilities

Before using sensor data APIs, devices must meet specific requirements:

1. Required Device Traits

Devices must include the Sensor trait in their supported traits list to provide sensor data.

2. Required Device Attributes

Devices must have a sensorProfile attribute that defines the types of sensors available and their configurations.

Available Sensor Types

The system supports a comprehensive range of sensor types as defined in the device's sensorProfile. Each sensor type has specific Min/Max ranges and units:

Environmental Sensors

temp - Temperature sensor (typically °C)
rh - Relative humidity sensor (%)
lux - Illumination/light sensor (lux)
noise - Noise level sensor (dB)

Air Quality Sensors

pm2_5 - PM2.5 particulate matter sensor
pm1_0 - PM1.0 particulate matter sensor
pm10 - PM10 particulate matter sensor
co - Carbon monoxide sensor
co2 - Carbon dioxide sensor
hcho - Formaldehyde sensor
h2s - Hydrogen sulfide sensor
nh3 - Ammonia sensor
o2 - Oxygen sensor
o3 - Ozone sensor
tvoc - Total volatile organic compounds sensor

Power and Electrical Sensors

watt - Power consumption sensor (Watts)
watt_hour - Energy consumption sensor (kWh). watt_hour is accumulated value
voltage - Voltage sensor (V)
current - Current sensor (mA or A)
power - General power sensor
apparent_power - Apparent power sensor
real_power - Real power sensor
reactive_power - Reactive power sensor

Motion and Physical Sensors

mr - Magnetic reed sensor
vib - Vibration sensor

Health and Biometric Sensors

sbp - Systolic blood pressure
dbp - Diastolic blood pressure
map - Mean arterial pressure
pulse - Pulse rate sensor
glucose - Blood glucose sensor
chol - Cholesterol sensor
body_temp - Body temperature sensor
height - Height measurement
weight - Weight measurement
bmi - Body mass index
bmr - Basal metabolic rate
bf - Body fat percentage
bm - Body muscle percentage
bn - Body bone percentage
bw - Body water percentage
vfr - Visceral fat rating
amr - Active metabolic rate
ma - Metabolic age
spo2 - Blood oxygen saturation

System and Maintenance Sensors

fan_hour - Fan operation hours (for filter replacement indicators)
bucket - Water bucket level sensor
filter - Filter status sensor
failed_sensors - Failed sensors indicator
rssi - Signal strength indicator
tds - Total dissolved solids sensor

Device Discovery and Validation

Identifying Sensor-Capable Devices

Use the GetGroupDevices API to discover devices with sensor capabilities:

curl -X POST "https://api.ultroncloud.com/usr/v5/GetGroupDevices" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Ultron-Cloud-Appid: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": "YOUR_LOCATION_ID"
  }'

Response Analysis for Sensor Devices

{
  "result": 0,
  "devices": {
    "SMART_PLUG_001": {
      "sn": "SMART_PLUG_001",
      "displayName": "Living Room Smart Plug",
      "activated": true,
      "models": {
        "Ultron Device": {
          "type": "ULTRON",
          "traits": [
            "UltronCommand",    "BluetoothGateway", "ReportState",
            "UltronConfig"
          ],
          "disabled": false,
          "attrs": [
            {"name": "rebootTime", "value": 20},
            {"value": 60, "name": "fwUpgradeTime"},
            {"value": true, "name": "iotConfigurableIntervals"},
            {
              "value": { "1": ["OnOff"] },
              "name": "schedulable"
            },
            {"name": "schedulableVersion", "value": 1},
            {"name": "periodicity", "value": true},
            {"name": "aperiodicity", "value": true},
            {
              "name": "supportDefaultActions",
              "value": {
                "1": {
                  "cmdNames"  : ["OnOff"           ],
                  "situations": ["power", "network"]
                }
              }
            }
          ]
        },
        "1": {
          "type": "SWITCH",
          "traits": ["Sensor", "OnOff", "CustomModes"],
          "disabled": false,
          "attrs": [
            {
              "name": "sensorProfile", // target attribute, valid for all sensor data APIs
              "value": {
                "current"       : {"Min": 0, "Max": 20000, "Unit": "mA"  },
                "voltage"       : {"Min": 0, "Max":   240, "Unit": "V"   },
                "watt_hour"     : {"Min": 0, "Max": 50000, "Unit": "kWh" },
                "watt"          : {"Min": 0, "Max":  4800, "Unit": "Watt"},
                "apparent_power": {"Min": 0, "Max":  4800, "Unit": "VA"  }
              }
            },
            {"name": "intermittent", "value": true},
            {
              "name": "timeStepRange",
              "value": {"max": 86400, "min": 0.1, "step": 0.1}
            },
            {
              "name": "availableCustomModes",
              "value": [
                { "name": "reset1", "settings": ["0"], "ordered": true }
              ]
            }
          ]
        }
      },
      "createdTime": "2023-01-01T00:00:00Z"
    },
    "TEMP_SENSOR_001": {
      "sn": "TEMP_SENSOR_001",
      "displayName": "Bedroom Temperature Sensor",
      "activated": true,
      "models": {
        "temp_main": {
          "type": "SENSOR",
          "traits": ["Sensor", "TemperatureControl"],
          "nickname": "Temperature Sensor",
          "disabled": false,
          "attrs": [
            {
              "name": "sensorProfile", // target attribute, valid for all sensor data APIs
              "value": {
                "temp": {"Min": -40, "Max":  85, "Unit": "°C"},
                "rh"  : {"Min":   0, "Max": 100, "Unit": "%" }
              }
            }
          ]
        }
      },
      "createdTime": "2023-01-01T00:00:00Z"
    }
  }
}

Understanding Accumulated Values

Certain sensor types, such as watt_hour (Energy), provide accumulated values rather than instantaneous readings.

Energy Consumption (watt_hour)

The watt_hour sensor represents the total energy consumed by the device since its last internal reset or activation.

Accumulated Total: The value returned is the current meter reading.
Calculating Usage: To determine the energy used during a specific period, subtract the minimum value (start of period) from the maximum value (end of period):
- Usage ≈ Max(Value) - Min(Value)
Reset handling: If the device's internal counter resets (e.g., due to a factory reset or power cycle depending on hardware), the value will start from 0 again.