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
- (while 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 0x4000) plus sensor_descr (65536 aka 0x10000), plus the ‘extended’ marker (8388608 aka 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 12 Bender RCMB Module 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.3.0 4.5 milli-brown flux
666.0.0.3.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 outlet (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
[...]