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 always get sensor_values alone and rely on sensor type specific knowledge coded within your application's source)

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 JSON 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
• check_gude.py's command line parameters --ssl / --username / --password will optionally use 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

• Using the sensor group principles described above, the Expert Power Control 8291 defines outlet groups as 'bank'/'efuse' sensor
• Each bank can have multiple outlets, along with multiple power sensors
• Each device can have multiple banks sensors
• 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               // 0 = off, 1 = on
               101.0.0.0.1 0  Power                 // 0 = 'no Power', 1 = 'Power'
               101.0.0.0.2 0  State                 // 0 = 'normal off', 1 = 'normal on', 2=efuse error1, 3=efuse error2
       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

[...]