Copyright (c) 2010-2012 AMEE UK Limited.
AMON is a data format suitable for the description and exchange of metering/monitoring device data. AMON is available to be used, free of charge, by anyone who has a need to describe or exchange, in a computer readable format, metering or monitoring device data.
The AMON standard has been primarily developed by AMEE UK Limited with the assistance of a number of other parties in the metering/monitoring device industry. If you would like to participate in the further development of the AMON standard, please see the Contributing to AMON section.
AMEE has developed a storage platform for metering/monitoring device data and a RESTful, web-based API for storing and retrieving this data using the AMON data format. However, the use of AMON is not limited to this context, and a key aim of the AMON data format is to advocate an open way of describing and exchanging metering/monitoring data that is independent of any API or system. The use of AMON in metering/monitoring devices and/or other systems is encouraged.
The AMON standard is licensed under a Creative Commons Attribution 2.0 UK: England & Wales License.
The AMON data format has been developed with the following goals in mind:
To this end:
The the full AMON data format is shown below. A full description of the format follows, along with examples of realistic AMON formatted data.
{
"devices": [
{
"deviceId": required string UUID,
"entityId": required string UUID,
"parentId": optional string UUID,
"meteringPointId": optional string UUID,
"description": optional string,
"privacy": required string, either "private" or "public",
"location": {
"name": optional string,
"latitude": optional latitude in degrees,
"longitude": optional longitude in degrees
},
"metadata": {
optional JSON object
},
"readings": [
{
"type": required string,
"unit": optional string,
"resolution": optional number,
"accuracy": optional number,
"period": required string, either "INSTANT", "CUMULATIVE" or "PULSE",
"min": optional number,
"max": optional number,
"correction": optional boolean,
"correctedUnit": optional string,
"correctionFactor": optional number,
"correctionFactorBreakdown": optional string
},
],
"measurements": [
{
"type": required string, must match a defined reading type,
"timestamp": required RFC 3339 string,
"value": number, boolean or string, required unless "error" (below) is present,
"error": string, required unless "value" (above) is present,
"aggregated": optional boolean
},
]
}
],
"meteringPoints": [
{
"meteringPointId": required string UUID,
"entityId": required string UUID,
"description": optional string,
"metadata": {
optional JSON object
}
}
],
"entities": [
{
"entityId": required string UUID,
"deviceIds": [ optional array of string UUIDs, empty array permitted ],
"meteringPointIds": [ optional array of string UUIDs, empty array permitted ]
}
]
}The AMON data format describes metering/monitoring devices, their data, and their relationship with other entities in a JSON encoded [1] string with structure as shown above.
The AMON data format consists of three main sections:
Where a string UUID is defined in the data format, a standard Universally Unique Identifier [3] should be used.
Where a number is defined in the data format, positive and negative integers and floating point numbers are acceptable. Numbers may be defined in either normal numeric or scientific notation. (It is left up to the implementation of devices/systems that use AMON regarding the precision of floating point numbers.)
In the AMON data format, the “devices” section is used to represent physical or virtual metering/monitoring devices and their data. This is done via three sub-sections. Firstly, a series of fields that define details about the physical or virtual device itself, such as a UUID for the “device”, if the device’s data should be considered to be public or private, the location of the device, and optional metadata about the device. Secondly, a series of fields (the “readings” section) which defines what the device records measurements of – so, for example, if a device monitors temperature and relative humidity, then the “readings” section would define this. Finally, a series of fields (the “measurements” section) which defines actual metering/monitoring data from the device.
All of the fields for the “devices” section of the AMON data format are discussed in more detail below.
deviceId: A UUID for the “device”. Required for a “device”; however, systems that implement the AMON data format may relax this requirement to make the field optional for AMON formatted messages that are requesting that a “device” be created.
parentId: A UUID for the device’s “parent”. Presence of this value indicates this device is a sub-meter.
description: An optional textual description of the device. Commonly used for an in-house device ID and/or other useful identifier.
meteringPointId: An optional UUID of a “meteringPoint”, if this “device” is to be considered part of that “meteringPoint”.
privacy: Should the information about this device and its data be considered private, or public? Optional – systems that implement the AMON data format should assume a default of “private” if not specified.
location:
metadata: An optional JSON object of metadata about the “device”. This allows the AMON data format to handle any type of metadata relating to the “device”.
readings: The “readings” section defines what type of readings the “device” validly produces. An array of zero or more sets of values.
measurements: The “measurements” section defines actual data measurements from the “device”. An array of zero or more sets of values.
In the AMON data format, the “meteringPoints” section is used to represent physical or virtual metering points. Note that because the relationship between a “device” and a “meteringPoint” is defined in the “device” section of the data format, a “meteringPoint” may have one or more “devices”; but a “device” may belong to at most one “meteringPoint”.
All of the fields for the “meteringPoints” section of the AMON data format are discussed in more detail below.
In the AMON data format, the “entities” section is used to represent physical or virtual entities which may have a relationship with a “device” or “meteringPoint”.
All of the fields for the “entities” section of the AMON data format are discussed in more detail below.
All “devices” in the AMON data format must, in order to be able to describe/exchange metering/monitoring data, define “readings”, to which “measurements” can then be associated via the defined “type”.
As mentioned above, the AMON data format does not specify any requirement regarding what “reading” “types” must be. However, the following table represents “types” that are commonly used in the metering/monitoring field. If a “type” exists in the following table, it is recommended that this be used when using the data format, as this will improve the ability to interchange AMON formatted data between different systems.
Each of the standard “types” below is listed with a proposed default “reading” “unit”, which systems implementing AMON should use in the event that no unit is defined in a “device” “reading” section for that “type”.
| Type Name | Default Unit | JSON Type |
|---|---|---|
| absoluteHumidity | g/Kg | Number |
| barometricPressure | mbar | Number |
| co2 | ppm | Number |
| currentSignal | mA | Number |
| electricityAmps | Amps | Number |
| electricityConsumption | kWh | Number |
| electricityExport | kWh | Number |
| electricityFrequency | Hz | Number |
| electricityGeneration | kWh | Number |
| electricityImport | kWh | Number |
| electricityKiloVoltAmpHours | kVArh | Number |
| electricityKiloWatts | kW | Number |
| electricityVolts | V | Number |
| electricityVoltAmps | VA | Number |
| electricityVoltAmpsReactive | VAr | Number |
| flowRateAir | m^3/h | Number |
| flowRateLiquid | Ls^-1 | Number |
| gasConsumption | m^3, ft^3, kWh | Number |
| heatConsumption | kWh | Number |
| heatExport | kWh | Number |
| heatGeneration | kWh | Number |
| heatImport | kWh | Number |
| heatTransferCoefficient | W/m^2.K | Number |
| liquidFlowRate | Litres/5min | Number |
| oilConsumption | m^3, ft^3, kWh | Number |
| powerFactor | Number (0-1) | |
| pulseCount | Number | |
| relativeHumidity | %RH | Number |
| relativeHumidity | wm-2 | Number |
| solarRadiation | W/m^2 | Number |
| status | Number (0/1) | |
| temperatureAir | C | Number |
| temperatureAmbient | C | Number |
| temperatureFluid | C | Number |
| temperatureGround | C | Number |
| temperatureRadiant | C | Number |
| temperatureSurface | C | Number |
| thermalEnergy | kWhth | Number |
| time | millisecs | Number |
| voltageSignal | mV | Number |
| waterConsumption | L | Number |
| windDirection | degrees | Number |
| windSpeed | ms^-1 | Number |
This example shows a “device”, with UUID “d46ec860-fc7d-012c-25a6-0017f2cd3574”.
The device is associated with the entity with UUID “50af27e0-e61a-11e1-aff1-0800200c9a66”.
The “device” has a “location”, and has been defined with one “reading”.
Two “measurements” for the defined “reading” exist.
{
"devices": [
{
"deviceId": "d46ec860-fc7d-012c-25a6-0017f2cd3574",
"entityId": "50af27e0-e61a-11e1-aff1-0800200c9a66",
"description": "Example 1 Device",
"location": {
"name": "kitchen"
},
"readings": [
{
"type": "temperature",
"unit": "C",
"accuracy": 0.01
}
],
"measurements": [
{
"type": "temperature",
"timestamp": "2010-07-02T11:39:09Z",
"value": 23.5
},
{
"type": "temperature",
"timestamp": "2010-07-02T11:44:09Z",
"value": 23.8
}
]
}
]
}This example shows a “device”, with UUID “c1810810-0381-012d-25a8-0017f2cd3574”, as well as a “meteringPoint” with UUID “c1759810-90f3-012e-0404-34159e211070”.
The device is associated with the entity with UUID “50af27e0-e61a-11e1-aff1-0800200c9a66”.
The “device” belongs to the “meteringPoint”, and has been defined with two “readings”.
One “measurements” for each of the defined “readings” exist.
{
"devices": [
{
"deviceId": "c1810810-0381-012d-25a8-0017f2cd3574",
"entityId": "50af27e0-e61a-11e1-aff1-0800200c9a66",
"description": "Example 2 Device",
"meteringPointId": "c1759810-90f3-012e-0404-34159e211070",
"readings": [
{
"type": "apparentPower",
"unit": "kVAh",
"accuracy": 0.01
},
{
"type": "reactivePower",
"unit": "kVArh",
"accuracy": 0.2
}
],
"measurements": [
{
"type": "apparentPower",
"timestamp": "2010-07-02T11:39:09Z",
"value": 7.23
},
{
"type": "reactivePower",
"timestamp": "2010-07-02T11:44:09Z",
"value": 6.8
}
]
}
],
"meteringPoints": [
{
"meteringPointId": "c1759810-90f3-012e-0404-34159e211070",
"description": "Example 2 Metering Point"
}
]
}This example shows two “devices”, the first with UUID “82621440-fc7f-012c-25a6-0017f2cd3574” and the second with UUID “d1635430-0381-012d-25a8-0017f2cd3574”.
The devices are associated with the entity with UUID “50af27e0-e61a-11e1-aff1-0800200c9a66”.
The first “device” has been defined with three different “readings”, and one “measurements” for each of the defined “readings” exist.
The second “device” has been defined with one “reading”, and one “measurements” for that “readings” exists.
{
"devices": [
{
"deviceId": "82621440-fc7f-012c-25a6-0017f2cd3574",
"entityId": "50af27e0-e61a-11e1-aff1-0800200c9a66",
"description": "Example 3 Device #1",
"readings": [
{
"type": "electricalInput"
},
{
"type": "electricalOutput"
},
{
"type": "electricalExport"
}
],
"measurements": [
{
"type": "electricalInput",
"timestamp": "2010-07-02T11:39:09Z",
"value": 0.6
},
{
"type": "electricalOutput",
"timestamp": "2010-07-02T11:39:09Z",
"value": 4.5
},
{
"type": "electricalExport",
"timestamp": "2010-07-02T11:39:09Z",
"value": 3.9
}
]
},
{
"deviceId": "d1635430-0381-012d-25a8-0017f2cd3574",
"entityId": "50af27e0-e61a-11e1-aff1-0800200c9a66",
"description": "Example 3 Device #2",
"readings": [
{
"type": "windDirection"
}
],
"measurements": [
{
"type": "windDirection",
"timestamp": "2010-07-02T11:39:09Z",
"value": 243
}
]
}
]
}This example shows an “entity”, with UUID “0636240-0381-012d-25a8-0017f2cd3574”.
The entity is defined as being associated with two “devices”, those with UUIDs “c1810810-0381-012d-25a8-0017f2cd3574” and “d46ec860-fc7d-012c-25a6-0017f2cd3574”, and also with one “meteringPoint”, with UUID “c1759810-90f3-012e-0404-34159e211070”.
{
"entities": [
{
"entityId": "90636240-0381-012d-25a8-0017f2cd3574",
"description": "Example 4 Entity",
"deviceIds": [
"c1810810-0381-012d-25a8-0017f2cd3574",
"d46ec860-fc7d-012c-25a6-0017f2cd3574"
],
"meteringPointIds": [
"c1759810-90f3-012e-0404-34159e211070"
]
}
]
}This example shows a “device”, with UUID “ed221bf0-d075-012d-287e-0017f2cd3574”.
The device is associated with the entity with UUID “50af27e0-e61a-11e1-aff1-0800200c9a66”.
The “device” has been defined with one “reading”, and two “measurements” for that “readings” exists. Note, however, that the “value” of the “measurements” in this case are boolean values.
{
"devices": [
{
"deviceId": "ed221bf0-d075-012d-287e-0017f2cd3574",
"entityId": "50af27e0-e61a-11e1-aff1-0800200c9a66",
"description": "Example 5 Device",
"readings": [
{
"type": "windowOpen"
}
],
"measurements": [
{
"type": "windowOpen",
"timestamp": "2010-11-12T13:51:43Z",
"value": true
},
{
"type": "windowOpen",
"timestamp": "2010-11-12T17:51:53Z",
"value": false
}
]
}
]
}««<« HEAD
Version 3.1: * Updated standard reading types.
Version 3.0:
a32fd12… Update standard reading types. MM-749
Version 2.0: 2011-09-12 - Andrew Hill
Version 0.9: 2011-08-15 - Andrew Hill
Version 0.8: 2011-05-12 - Andrew Hill
Version 0.7: 2010-11-26 - Paul Carey
Version 05 - 0.6: 2010-11-12 - Paul Carey
Version 0.4: 2010-08-16 - Paul Carey
Version 0.1 - 0.3: 2010-07-02 - Paul Carey
Contributions to the AMON data format are welcome! If you would like to participate in the development of the AMON data format, please see the following: