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
[...]