HTTP JSON Sensor Data

Preface

This document tries to explain how to get sensor data by HTTP/Json for programmers.

• All sensor data is available in a generic JSON Object, presented by status.json
• There are two relevant sub-objects: sensor_values and sensor_descr
• sensor_descr can tell
  • What sensor types are actually relevant
  • What is the field description of each of those sensor types
  • How many sensors of each type are actually present
  • What are the names of each of those sensors
• sensor_values carries all measured sensor values, matching the description explained above, in the same order
• It's common practice to get sensor_descr+sensor_values once, and poll sensor_values only subsequently with much less payload
  • It's perfectly legit to get sensor_values alone and rely on sensor type specific knowledge coded within your application

This empowers you to write small code supporting all products and all sensors in one single future-proof approach, without the need for sensor specific knowledge.

So your software is already prepared for new gude-devices, and prepared for new sensor Add-Ons.

To give an example, this documentation will highly depend on check_gude.py, our HTTP sensor data swiss-knife tool.

Getting data by HTTP

• HTTP-Get status.json?components=8470528
  • for more info about status.json components flags, refer to EPC HTTP Interface
  • 8470528 sums up sensor_values (16384 aka 0x10000) plus sensor_descr (65536 aka 0x4000), plus the ‘extended’ marker (0x800000) to get both simple sensors and (more complex) sensor groups
  • 8470528 = 0x814000 = 0x4000 + 0x10000 + 0x800000

Example data

sensor_descr

 [
   {
     "type": 664,
     "num": 2,
     "fields": [
        {"name": "Voltage", "unit": "V", "decPrecision": 3},
        {"name": "Current", "unit": "A", "decPrecision": 1}
     ],
     "properties": [
       { "id": "L1", "name": "Meter1"},
       { "id": "L2", "name": "Meter2"}
     ]
   },
   {
     "type": 665,
     "num": 1,
     "fields": [
        {"name": "Temperature", "unit": "C", "decPrecision": 1},
        {"name": "Humidity",    "unit": "%", "decPrecision": 1}
     ],
     "properties": [
       { "id": "6102", "name": "Server-Rack"}
     ]
   }
 ]

This tells you:

• There a two sensors of type 664, and one of type 665
• A type-664 sensor has two Fields, Voltage 'V' and Current 'A'
  • Voltage is measured with a decimal precision of 3, Ampere with a decimal precision of 1
• The two type-664 sensors (L1 and L2) are named 'Meter1' and 'Meter2'
• The one type-665 sensor is named 'Sever-Rack', and has two fields 'Temperature' and 'Humidity'

sensor_values

 [
   {
     "type": 664,
     "num": 2,
     "values": [
       [{"v": 233.19}, {"v": 3.2}],
       [{"v": 226.2},  {"v": 0.3}]
     ]
   },
   {
     "type": 665,
     "num": 1,
     "values": [
       [{"v": 27.1}, {"v": 40.3}]
     ]
   }
 ]

sensor_descr / sensor_values

Bringing together both objects will assemble the complete sensor information:

 L1/Meter1         233.19 V (Voltage),        3.2 A (Ampere)
 L2/Meter2         226.20 V (Voltage),        0.3 A (Ampere)
 6102/Server-Rack:   27.1 C (Temperature),   40.3 % (Humidity)

Common sensor type IDs

  1  Line power meter
  9  Line power meter with residual current
  8  Outlet power meter

  7  Digital Inputs

 20  System Data (sensor group)

 51  Temperature Sensor
 52  Temperature/Humidity Sensor
 53  Temperature/Humidity/AirPressure Sensor

101  Bank (eFuses Port-groups) Sensor  (e.g. used at 8291 PDUs)
102  (DC) Power Sources                (e.g. used at 8291 PDUs)

check_gude.py in action

• check_gude.py is a demo code to show how sensor_descr and sensor_values can be assembled generically to make use of all our devices / sensors
• so when new devices and sensors are coming up, check_gude.py is already prepared to deal with it
• install python along with the python module requests, to run check_gude.py
• feel free to use check_gude.py as you need it and to rewrite the given code to any language desired

Show all Sensor Data

• Here a device with hostname 8041.demo.gude.info is queried to dump all sensor data
• with check_gude.py can use --ssl / --username / --password to benefit from HTTP encryption and user authentification

show CGI-Get / JSON Data

when using --verbose check_gude.py will print out the full URL and the JSON return data:

Sensor groups

A simple sensor has one single field description, as shown above, where a sensor group is a bundle of different field descriptions.

So instead of presenting 'fields', it has 'groups' as list of 'fields'

Sensor group example

• This is a virtual sensor 'engine'
• Each engine has a certain amount of cylinders, and a certain amount of telemetry sensors
• Each vehicle can have multiple engines
• In this example, our car (device) has two engines, Front Engine and Rear Engine
  • Front-engine has 4 cylinders, and 1 telemetry sensor
  • Rear-engine has 2 cylinders, and no telemetry sensor

sensor_descr

  {
    "type": 666,
    "num": 2,
    "groups": [
       {
         "name": "cylinder",
         "fields" : [
           {"name": "flux",   "unit": "milli-brown", "decPrecision": 0},
           {"name": "Power",  "unit": "W",           "decPrecision": 1}
         ]
       },
       {
         "name": "telemetry",
         "fields" : [
           {"name": "Temperature",    "unit": "C",   "decPrecision": 1}
         ]
       }
    ],
    "properties": [
      {
        "id": "E1",
        "name": "Front Engine",
        "groups": [
          [
            {"id": "C1", "name": "Cylinder1"},
            {"id": "C2", "name": "Cylinder2"},
            {"id": "C3", "name": "Cylinder3"},
            {"id": "C4", "name": "Cylinder4"}
          ],
          [
            {"id": "T1", "name": "Temperature1"}
          ]
        ]
      },
      {
        "id": "E2",
        "name": "Rear Engine",
        "groups": [
          [
            {"id": "C1", "name": "Cylinder1"},
            {"id": "C2", "name": "Cylinder2"}
          ],
          [
          ]
        ]
      }
    ]
  }

sensor_values

{
  "type": 666,
  "num": 2,
  "values": [
    [
      [
        [{"v": 12.3}, {"v": 12.3}],
        [{"v": 35.1}, {"v": 0.3}],
        [{"v": 25.6}, {"v": 0.4}],
        [{"v":  4.5}, {"v": 1.5}]
      ],
      [
        [{"v": 83.9}]
      ]
    ],
    [
      [
        [{"v": 12.3}, {"v": 12.3}],
        [{"v": 35.1}, {"v": 0.3}],
      ],
      [
      ]
    ]
  ]
}

check_gude.py with sensor groups

check_gude.py would compile both objects like this:

./check_gude.py -H mycar.local.net

 E1 Engine 1
       C1 Cylinder1
               666.0.0.0.0 12.3 milli-brown flux
               666.0.0.0.1  2.5 W power
       C2 Cylinder2
               666.0.0.1.0 35.1 milli-brown flux
               666.0.0.1.1  0.3 W power
       C3 Cylinder3
               666.0.0.2.0 25.6 milli-brown flux
               666.0.0.2.1  0.4 W power
       C4 Cylinder4
               666.0.0.4.0 4.5 milli-brown flux
               666.0.0.4.1 1.5 W power
       T1 Temperature1
               666.0.1.0.0 83.9 C Temperature

E2 Engine 2
       C1 Cylinder1
               666.1.0.0.0 46.1 milli-brown flux
               666.1.0.0.1  8.6 W power
       C2 Cylinder2
               666.1.0.1.0 13.4 milli-brown flux
               666.1.0.1.1  4.3 W power

Expert Power Control 8291

• The Expert Power Control 8291 defines outlet groups as 'bank'/'efuse' sensor
• Each bank can have multiple outlets, and multiple power sensors
• Each device can have multiple banks
• In this example
  • The device has two banks, A and B
  • Bank A has two outlets (A1, A2) with one power sensors S1.
  • Bank B has one outlets (B1) with one power sensors S2

./check_gude.py -H 8291.demo.gude.info

[...]
Bank A
       1 A1
               101.0.0.0.0 0  Enabled
               101.0.0.0.1 0  Power
               101.0.0.0.2 0  State
       2 A2
               101.0.0.1.0 0  Enabled
               101.0.0.1.1 0  Power
               101.0.0.1.2 0  State
       S1 5V
               101.0.1.0.0 DC
               101.0.1.0.1 4.988 V Voltage
               101.0.1.0.2 0 A Current
Bank B
       3 B1
               101.1.0.0.0 0  Enabled
               101.1.0.0.1 0  Power
               101.1.0.0.2 0  State
       S2 DC 12V
               101.1.1.0.0 DC
               101.1.1.0.1 12.036 V Voltage
               101.1.1.0.2 0 A Current

[...]