Application Programming Interfaces (APIs)

Introduction

For GEISA applications to be portable between multiple platforms, GEISA standard establishes a well defined set of APIs between the application and the common operating environment.

The types of communications that applications need fall into several categories:

Platform informational data (inventory and fixed run-time information)
Platform services (application start/stop/status, network updates, etc...)
Network communications (message and/or socket comms)
Environment data (sensors, alarms, etc...)
Basic Metrology data (1-second or better summary data)
Cycle-aligned medium frequency waveform streams
Raw medium/high frequency waveform streams
Hardware accelerators

GEISA applications run in a constrained container environment, the common operating environment provides the resources needed for the application to communicate with the on-device resources as well as the utility infrastructure (if allowed) and the application author’s infrastructure either in a private or public cloud (if allowed).

GEISA applications mostly communicate with the on-device operating environment, but they may communicate directly with off-device endpoints using direct socket connections if available and allowed.

Communications methods

The GEISA application API specification makes a clear distinction between the method of communication and the data communicated over those methods.

By including the method of communication instead of a set of functional API calls there is a well-defined interface between the software the application authors and device manufacturers write using an open protocol.

An application author can implement or import a single communication library that will best fit their application’s software architecture and is free of any device-specific libraries or middleware. The application developer is therefor free to implement their application in any programming language and with any architecture (single or multi process, threading model, event vs procedural, etc...). They are not dependent on a device manufacturer's API SDK or closed source libraries.

A GEISA implementation provides these 4 communications methods to application authors:

Application administration
- Used for start, stop, status, etc...
- Operating environment invokes an executable within the app's container
- Out of band (non message bus) to guarantee completion even if the application is hung/crashed/exited
- Example: /opt/geisa/apps/exampleapp/exec stop
- Exit code used to report result
Message bus
- TBD: decide on mature message bus implementation (examples: zmq, dbus, mqtt, etc...)
- The operating environment:
  - Runs a message bus daemon on host
  - Pre-creates a named AF_UNIX socket inside container filesystem
  - TBD: this may be an AF_INET/INET6 or other shared method, depends on chosen implementation above, assume AF_UNIX for now
- The application:
  - Connects one (or more) times to the named socket using a compatible message bus client library
  - Multi-process or multi-daemon applications may establish more than one connection at a time (proxying should not be required)
- Both request/response and post/notification messages supported
- Used between operating environment and application, and app to app (if allowed).
- Namespace (identifiers assigned to each application and the host) defined by operating environment
- Local to the device, no inter-device communication (ex: meter to meter, or meter to head-end)
Streaming waveform data
- Created on-demand based on subscription requests via the message bus
- Unidirectional, Operating environment to Application
- named AF_UNIX/SOCK_DGRAM socket inside container filesystem
- Data is sent in frames/datagrams
- Metadata (content type and format) sent out-of-band in subscription request/response
Network communication
- Container networking will be provisioned by the Operating environment
- Applications may use outbound-initiated TCP/UDP sockets to communicate with authorized endpoints off-device
- Endpoints may not be reachable if network connectivity is unprovisioned or down
- Operating environment enforces policy (i.e. firewall rules)

Application administration data

As described above, application administration is performed out-of-band from the message bus to start, stop, restart, or reload the application. The Operating environment will invoke an executable within the Application's container to run these actions. That executable is written by the application author and interfaces with their application as needed.

A single executable is invoked to perform any of the actions with the action name provided as a command line argument to that executable.

Command Argument	Action

Command Argument	Action
start	start the application if not already running, blocks until application is running and online
stop	shut down the application, blocks until stopped, max 5 seconds
restart	stop + start
reload	less impacting than restart, actions application dependent

Notably the 'start' and 'restart' messages will block until the application is ready to accept messages via message bus. This implies more than just launching the application, it must be running and operational.

The operating environment will enforce timeouts for each command. If a stop request times out, for example, the operating environment will force stop by destroying the container.

Message bus data

The message bus is how most of the application communication occurs. Each application and the operating environment are Endpoints on this bus.

TBD: an important concept that must be determined once picking a message bus implementation is how endpoints are named, this is technology dependent. Add later, for now assume App A can address the operating environment and vice versa, how they are named is TBD.

The content of data transported over the message bus must follow a well defined and open encoding format for both message type and type-specific payload.

TBD: pick an encoding (examples: json, msgpack, XML, etc...)

The Message bus semantics must allow for Endpoints to perform request-response type messages (called R/R below). An Endpoint may pipeline requests to another Endpoint, it need not wait for a response to one message before sending another request. Messages between 2 endpoints must be delivered in the order they were sent.

The Message bus semantics must allow for posted messages from one Endpoint to another without a response. These messages may be sent on a periodic basis.

The operating environment must maintain state on a per Endpoint basis. If an application subscribes to a type of posted message (ex: Metrology data), the operating environment must remember this subscription for the duration of the connection to that Endpoint. The only cases where this state should be cleared is if the peer Endpoint disconnects in a way that the source Endpoint can detect (i.e. a NACK, connection reset, successful or forceful Application stop, etc...) or an Endpoint sends a reset message (described below) such as on a process restart.

R/R requests are commonly sent from Application to operating environment but can for limited types be sent from the operating environment to Application.

The operating environment will respond to R/R requests for

Administrative:
- NULL message (to determine if endpoint is alive)
- Endpoint reset (this clears any state and subscriptions)
Platform informational data (static, cannot be changed without reboot or application restart)
- Meter manufacturer, model, revision, serial number
- Meter form, class
- Service type, phase count and angle, nominal L-N voltage, nominal L-L voltage
- Utility information (if available)
- Network capabilities (hardware presence, not current state of)
- Environment capabilities (sensors, alarms, etc...)
- Basic Metrology capabilities (channel counts & types, update frequency, etc...)
- Waveform streaming capabilities (channel counts & types, capture frequency, data format, etc...)
- Hardware accelerators (if available)
Network communications:
- Current network state, for each interface:
  - state: disabled, enabled-down, or enabled-up
  - protocol availability (ipv4, ipv6, or both)
  - network reachability (public, utility private, etc...)
  - performance capabilities (throughput: unmetered, limited, restricted; availability: real-time, batch)
- Send message to head-end (guaranteed, urgent, or best-effort)
  - response indicates if message was queued not if delivered
- Number of messages pending to head-end from this Application
Environment data (sensors, alarms, etc...)
- TBD
Basic Metrology data:
- subscribe/unsubscribe to Basic Metrology data
  - subscribe response includes the channel counts & types, update frequency, etc...
  - Basic Metrology data is sent via the message bus (not dedicated socket like waveform)
  - Sending this message will cause the operating environment to start/stop sending periodic posted messages
  - The first periodic message must not be sent before the response to the subscription request is sent
Cycle-aligned and Raw frequency waveform streams
- subscribe/unsubscribe to waveform stream
  - subscribe response includes named socket to attach to, channel counts & types, capture frequency, data format, etc...
  - operating environment must setup named socket prior to responding to subscribe request
  - application must close named socket prior to sending unsubscribe request
Hardware accelerators
- TBD

The Application will respond to R/R requests for

Administrative:
- NULL message (to determine if endpoint is alive)
Network communications:
- Network state update (same content as above)
- Receive message from head-end
- Message to head-end result (success or failure)

Network Communications

GEISA allows applications to make use of 2 types of off-device communications:

Message based to the utility head-end

This type of messaging is generally available on every meter and is transported over the proprietary radio technology between meters and other utility equipment.

Users of this type of messaging are limited to a fixed quantity and volume of data per day. Delivery of messages may be significantly delayed or lost. The operating environment is responsible for queuing these messages and reporting back to the Application if and when they are delivered.

Applications use the message bus to send and receive these messages to the operating environment.

Application developers make use of Utility run proxies and APIs in the Utility's cloud to receive from and send messages to devices.

IP socket based to private or public clouds

Applications can also make use of traditional IP socket based real-time communications on devices equipped with cellular, WiFi, or other IP connectivity. Applications must specify the endpoints they need to communicate to (IP/Name/Port) in advance so that those policies can be approved by utilities and implemented in the operating environment using firewall rules.

Applications must also specify the expected average and peak volume of data per day. Some devices may be remote and have data limited volume data plans.

Once a network interface is online, the Application may use outbound-initiated AF_INET/AF_INET6 sockets from within the container environment to directly reach the specified endpoints. The operating environment will provide DNS services to processes within the container environment. Devices may or may not have direct Internet reachability, this is Utility specific.

Security considerations

For message based communications, the operating environment will provide encryption and authentication for data passed between the device and head-end, applications may but are not required to perform this function on top of what the operating environment provides.

For socket based communications, the application is responsible for encryption and authentication of data passed between the device and private or public cloud endpoints.

Basic Metrology Data

All GEISA devices are required to offer basic metrology data to applications. This data is passed over the message bus as posted messages between the operating environment and applications after applications subscribe to this data using a R/R message.

Basic Metrology Data is defined as computed periodic summary data provided at least once per second. For example, a meter may compute the the voltage, amperage, and wattage per phase and provide that once per second.

Basic Metrology Data includes:

Item	Required?

Item	Required?
RMS AC Voltage per phase	required
Amperage per phase	required
Real power (W) per phase	required
Apparent power (VA) per phase	optional
Reactive power (VAr) per phase	optional
Power factor per phase	optional
THD per phase	optional
Cumulative Wh imported per phase	required
Cumulative Wh exported per phase	required
Voltage angle relative to phase A per other phases	optional
Current angle relative to phase A per phases	optional

TBD: others that are important? Should we leverage COSEM identifiers?

The operating environment must provide this data at least once per second (1Hz), but may optionally provide it for shorter durations such as every 2Hz, 5Hz, 10Hz, etc...

Waveform streams

GEISA defines two types of waveforms streams devices may provide. Devices are required to provide at least one of these types but may provide both.

Cycle-aligned waveform

Cycle-aligned waveform streams are medium sample frequency waveforms whose data frames are aligned to the start of an AC voltage cycle on the A phase and end on the end of an AC voltage cycle on the same phase. A data frame format is defined that contains a number of AC cycles but that number of cycles is implementation specific. A data frame must be no more than 200msec in duration (10 cycles at 50Hz, 12 cycles at 60Hz) so that real-time applications do not experience excessive delays in data delivery.

Medium sample frequency means sampling at least 128 times per AC cycle (6400hz for 50Hz systems, and 7680hz for 60Hz systems).

The purpose of providing cycle aligned waveform data to applications is so the amount of computation per application can be reduced. If the hardware cannot provide this functionality natively, it may be better for this waveform conversion to be performed centrally in software by the operating environment prior to delivery to each application.

The alignment of a data frame to the beginning of an AC voltage cycle can be difficult to track due to frequency variation, grid faults, series arcing, local oscillator variation, and so on. The metrology hardware must be capable of locking to the AC voltage cycles and tuning its sampling frequency to match a multiple of that. If it is not capable in hardware the operating environment may be able to perform these tasks software.

If the hardware (or software) is unable to lock to the AC voltage cycle such as shortly after power on or during or after a fault, data should still be provided to the applications but those data frames flagged as 'not-locked'. It is important that applications continue to receive data even at times of uncertainty as the application may be looking for faults.

If the underlying hardware samples at a different frequency, or samples at a frequency that does not track a multiple of the AC voltage frequency, the implementation may either choose to not support Cycle-aligned medium frequency waveforms (and only support raw waveform, below) or the operating environment may pre-process that raw data into cycle-aligned data. If the raw sampling rate is much higher than the minimum Cycle-aligned medium frequency requirements above, software may be used to down-sample and re-time the data, however analysis by the implementer must show that doing so will not add artifacts, aliasing, or other errors into the resulting waveforms.

When an application subscribes to cycle-aligned waveform streams using a R/R message, the response message includes:

The named socket to attach to
Channel counts & types (ex: 3 channels, voltage A-B, current A, current B)
Sampling frequency in hz
The data frame length in samples per channel
Sample data format (ex: 16-bit signed integer, 32-bit float, etc...)
A voltage multiplier
A current multiplier

Each data frame includes:

a sequence number
a timestamp of the beginning of the data frame in the form of a Linux CLOCK_MONOTONIC struct timespec
a 'locked' bit indicating a lock to the AC cycle or not
An array of channels each including:
- An array of samples in the data format specified at registration

Raw waveform

Raw waveform streams provide application access to the underlying waveform data at the native sampling frequencies of the device.

GEISA supports a variety of hardware with a variety of capabilities. For example, a device may sample voltage channels at a different sampling frequency than current channels, or a device may have multiple channels of data for the same signal at different sampling rates (ex: a medium frequency ADC and a high frequency ADC both monitoring the same voltage waveform).

While the waveform data is considered ‘raw’, the data between channels must still be synchronized, that being the start of the channel data in each data frame is at the same timestamp.

Applications should use a Platform informational R/R message to determine the capabilities of the device.

The waveform streaming capabilities R/R message response includes:

List of hardware channels, each containing:
- What it is monitoring (ex: voltage A-N, voltage A-B, Current B, etc...)
- Sampling rate
- Sample data format (ex: 16-bit signed integer, 32-bit float, etc...)
- A multiplier

The application may choose which set of channels to subscribe to and is not required to subscribe to every channel. For example, an application may only want voltage waveforms and have no need for current waveforms, or it may want to pick a specific set of channels based on its needs.

When an application subscribes to raw waveform streams using a R/R message, the request includes:

A list of which channels to subscribe to

and response message includes:

The named socket to attach to
Channel counts & types (should match the request)

Each data frame includes:

a sequence number
a timestamp of the beginning of the data frame in the form of a Linux CLOCK_MONOTONIC struct timespec
An array of channels each including:
- An array of samples in the data format specified at registration

Consider the following hypothetical metering devices

Meter A

A poly-phase 9S CL20 meter that samples 3 voltage channels and 3 current channels. All 6 channels sample at a raw rate of 24000hz using 16bit ADCs. The voltage ADC covers a range of +- 600Vp (non-RMS), and the current ADCs cover an range of +- 32A. The meter is installed with 400:5 CTs on a 480Y/277 3 phase 4 wire system.

The meter provides applications the following in it's raw waveform streaming capabilities R/R response message:

channel 1: Voltage A-N, 24000hz, 16-bit signed integer, 0.01831055 multiplier
channel 2: Voltage B-N, 24000hz, 16-bit signed integer, 0.01831055 multiplier
channel 3: Voltage C-N, 24000hz, 16-bit signed integer, 0.01831055 multiplier
channel 4: Current A, 24000hz, 16-bit signed integer, 0.07812500 multiplier
channel 5: Current B, 24000hz, 16-bit signed integer, 0.07812500 multiplier
channel 6: Current C, 24000hz, 16-bit signed integer, 0.07812500 multiplier

The voltage multiplier of 0.01831055 is 600/32768
The current multiplier of 0.07812500 is (32/32768)*(400/5)

A data frame covering 100msec and all 6 channels, would be 14400 samples or 28800 bytes (not including header)

Meter B

A single-phase 2S CL200 meter that samples 1 voltage channel and 2 current channels. The voltage channel samples at 15360hz and the current channel samples at 7680hz using 16bit ADCs. The voltage ADC covers a range of +- 400Vp (non-RMS), and the current ADCs cover a range of +- 300A.