Utilitarian API is a RESTful API that exposes endpoint for AMR Operations.

The common part deals with general aspects of the API.

Under the Metering part all endpoints for the management of Meter Devices and Meter Readings are gathered.

Under the Jobs part all endpoint for managing the pulling meter data and communication to with Meter Devices are gathered. (Ongoing work)

Each user is given a unique API Key Token to interact with the API. It is also possible to use basic auth but not recomended.

For clients to authenticate, the token key should be included in the Authorization HTTP header. The key should be prefixed by the string literal "Token", with whitespace separating the two strings. For example:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Unauthenticated responses that are denied permission will result in an HTTP 401 Unauthorized response with an appropriate WWW-Authenticate header. For example:

WWW-Authenticate: Token

Note: If you are running an instance of Utilitarian API that is accessable over the Internet you need to make sure that the API is only served under https.

The Pagination scheme used for Utiltiarian API is a Limit/Offset scheme.

By using a limit indicates the maximum number of items to return and the offset indicates the starting position of the query in relation to the complete set of unpaginated items. This makes for a very extensible pagination scheme where the client have better control of the returned values. In all responses the total count of items in the compleate set of unpaginated items are returned to be able to know where in the set a pagination response is located.

The limit and offset is applied in query parameters like:

GET https://api.example.org/accounts/?limit=100&offset=400

The following example shows a common result set.

{
  "count": 1023
  "next": "https://api.example.org/accounts/?limit=100&offset=500",
  "previous": "https://api.example.org/accounts/?limit=100&offset=300",
  "results": [
    …
  ]
}

Note: Having very large result sets can lead to significant performance issues.

Operations on Meter Devices

Meter Devices

Meter Devices are the entity that represents a physical (or logical) meter deployed in the field. They handle all information about how to communicate with the meter and how to interpret the data from the meter.

Operations on Network Interfaces.

Network Interfaces

A NetworkInterface is an object holding information needed for communication to a meter device. You can connect SIM cards to a network interface. Several meter devices can share the same network interface, for example an MBus gateway. It is also possbile for several network interfaces to share the same SIM Card, for example if using the same IP/SIM-card but different devices are under different ports. Then each meter device would have its own network interface specifiying the port but they would all share the same SIM Card to get the IP address.

Some network interfaces only allows for one open connection and when the network interface is used by communication software we want to make sure that no other job is trying to communicate with the meter devcice. This is done by blocking the network interface. When the communication is done the network interface should be unblocked so that other jobs can connect to it.

Tips: The host parameter is only returned in responses and will contain the following data:

1. FQDN. If a meter has a DNS compliant name attached to it we assume we want to use that firstly
2. Static IP Address. If no FQDN is set on the meter it will return the static ip address associated with it.
3. IP of SIM Card. If no static ip address or FQDN is set the meter will return the IP of the SIM Card attached to it.

Operations on SIM Cards

SIM Cards

Utilitarian is focused on IP communication with meters. Many meter have internal or external modems that are used for cellular communications. This require a SIM-card. Many SIM-cards in IoT data plans will give a fixed IP. It is possible to store all your SIM cards in Utiltarian and link them to your meter devices for an easy way of finding the IP for a meter device. If you switch a SIM cards in the field you need to switch it in Utilitarian so that the system can find the meter device.

Tips: It is possible to save a link to the managing software, for example Jasper, of the SIM cards. In future Utilitarian UI this will be rendered as an external link to quickly get access to logs and other SIM cards operations that are not in the scope of Utilitarian.

Operations on Meter Device Types

Meter Device Types

It is possible to have a meter that is of same make and model but differently configured. By adding a different meter type we can have a several different setups of the same manufacturer model.

Operations on Meter Device Configs

Meter Device Configs

A Meter Device Config stores the configurations of a Meter Device Type. As of now this stores mainly what MeteringSeries it has. The metering series list is used to validate if a meter reading from a meter device is allowed to be saved.

The plan later on is have information about what, for example COSEM objects a meter has, or what MBus Vifes etc the meter has. For example can an IDIS complient meter share configuration with other meters of different make. An OMS compliant Mbus meter can also share configuration between different manufacturers.

Operations on Meter Reading Series

Meter Reading Series

A MeterReadingSeries is used for grouping all meter values that should be viewed as a time series of values. It also adds "metadata" about the series so that it is possible to know more about the values contained in it.

In Utilitarian we aim to use OBIS codes as series identifier but there is nothing preventing the use of any identifier for a series. Simple string values like "energy" and "power" could be used or more complex identifiers like from the CIM standard.

Since we might have electricity meters that have current and voltage transformers in their measurement loops we need to specify if the series is affected by either the current transformer and/or the voltage transformer ratio.

Operations on Meter Readings

Meter Readings

Meter Readings are the raw data we receive from meter devices. They are limited to numerical data. Meter Readings table is designed for short term storage of meter values.

Operations on Staged Meter Readings

Staged Meter Readings

Staged Meter Readings are meter readings that when they where received by Utilitarian API did not have a corresponding meter. This might be due to that the meter was set up in the field but was not yet set up in Utilitarian API. To avoid loosing values we save the meter readings for a while and whenever a new meter device is created we will save all staged meter readings as normal meter readings. We also clear the staging table of old values after a set amount of time to make sure the list doesn't grow to large.