Differences for data types / units in Maker API

🧰 Built-In Apps and Drivers Maker API
1

Noticed a couple of inconsistencies when working with the Maker API.

When querying a specific device details with the Get Device Info

http://xxx.xxx.xxx.xxx/apps/api/XXX/devices/[Device ID]?access_token=

the JSON returned for "currentValue" temperature and humidity are encoded as JSON numbers, while the voltage is wrapped as a string. No units are returned.

{
   "id":"154",
   "name":"Temp Sensor",
   "label":"Temp Sensor",
   "type":"SensorPush Sensor",
   "room":null,
   "attributes":[
      {
         "name":"humidity",
         "currentValue":59.5,  <---- value is number
         "dataType":"NUMBER"
      },
      {
         "name":"temperature",
         "currentValue":-12.3,
         "dataType":"NUMBER"
      },
      {
         "name":"batteryVoltage",
         "currentValue":"2.25",
         "dataType":"STRING"
      }
   ]
}

Compare to the POST back message for the same device:

  • Units of measure ARE returned
  • The value element is always a string
{
   "content":{
      "name":"humidity",
      "value":"59.5",    <----- value is text
      "displayName":"Temp Sensor",
      "deviceId":"154",
      "descriptionText":"Temp Sensor: humidity is 59.5%",
      "unit":"%",
      "type":null,
      "data":null
   }
}

Questions:

  • As the system knows the data types, why are the POST JSON "value" elements always encoded as text?
  • Why no unit element in the Get Device Info for current attributes? I notice the *current state *attributes on the device details page doesn't show the units appended, but the events do. Shouldn't units be reflected in the current state attributes?
2

No, units are an element of an event, not an element of an attribute.

3

Is the value of the temperature attribute converted to a consistent unit of measure at storage time? How can one determine the unit of the current (aka most recent) attribute value?

Instead, are there parameters that can be passed into the "Get Event Details" endpoint?

http://xxx.xxx.xxx.xxx/apps/api/XXX/devices/[DeviceId]/events?access_token=

Could one request just the most recent one (limit = 1?) and for a specific attribute name?

4

No. It could possibly be °C or °F or even °K, but that is not an attribute nor stored with the value. Since units are an element of an event, one could store events and look back to see what units were reported.

I don't think that Maker API supports looking at past events. This is certainly possible in Groovy, and done in some apps.

5

It does convert, although it doesn't store the unit. Whatever you have your default temp scale set to (F or C in Hub Details), the attribute value is converted to that unit and stored. So one could mostly assume it matches the default temp unit (unless it was changed since the attribute was stored.)

My solution is to have a similar setting in the external system so that it can infer what the attribute unit was at the time it was stored when using the device details query to get the current attribute value.

the devices/deviceid/events endpoint returns the last 20 events in reverse cron order, including units. It would be helpful if you could pass it parameters to only include the last X events of a specific attribute..

Thanks!

6

This topic was automatically closed 365 days after the last reply. New replies are no longer allowed.