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 operator 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.
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, 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 pub/sub 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)
Provide security, isolation, and traceability :
App A cannot see messages destined to App B
App A cannot spoof messages from App B
Operators and developers can log/monitor/troubleshoot content of the message bus
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)
Static Data via Config/Data file
Platform informational data and other static data can be read by an app from a operating environment generated file
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 |
|---|---|
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.
Some types of data are fixed and do not change for the life of the application. This type of data is written to a file by the operating environment prior to application start. The application can then read it without having to send messages over the Message bus.
This static data includes:
Platform informational data
Meter manufacturer, model, revision, serial number
Meter form, class
Service type, phase count and angle, nominal L-N voltage, nominal L-L voltage
operator 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)
In the unlikely event that this data must change, the operating environment software either needs to restart all apps with new static data, or perform a system reboot. This could occur for cases where the deviece is provisioned, re-configured, or upgraded.
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: msgpack, protobuf, 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 (pub/sub) 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.
Administrative:
NULL message (to determine if endpoint is alive)
Endpoint reset (this clears any state and subscriptions)
Network communications:
Current network state, for each interface:
state: disabled, enabled-down, or enabled-up
protocol availability (ipv4, ipv6, or both)
network reachability (public, operator private, etc...)
performance capabilities (throughput: unmetered, limited, restricted; availability: real-time, batch)
Send message upstream via LwM2M (guaranteed, urgent, or best-effort)
response indicates if message was queued not if delivered
Number of messages pending via LwM2M 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 in pub/sub messages
Cycle-aligned and Raw waveform streams
subscribe/unsubscribe to waveform stream
subscribe response includes channel counts & types, capture frequency, data format, etc...
Waveform data is sent via the message bus in pub/sub messages
Hardware accelerators
TBD
Administrative:
NULL message (to determine if endpoint is alive)
Network communications:
Network state update (same content as above)
Receive message from LwM2M
Message to LwM2M result (success or failure)
See Network Communications sub-page.
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? |
|---|---|
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...
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 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 latency of 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 applications.
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 in 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 message bus identifier to subscribe 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 samples each including:
An array of channels in the data format specified at registration
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 message bus identifier to subscribe 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 samples each including:
An array of channels in the data format specified at registration
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)
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.
The meter provides applications the following in it's raw waveform streaming capabilities R/R response message:
channel 1: Voltage A-B, 15360hz, 16-bit signed integer, 0.01220703 multiplier
channel 2: Current A, 7680hz, 16-bit signed integer, 0.00915527 multiplier
channel 3: Current B, 7680hz, 16-bit signed integer, 0.00915527 multiplier
The voltage multiplier of 0.01220703 is 400/32768
The current multiplier of 0.00915527 is 300/32768
A data frame covering 100msec and all 3 channels, would be 3072 samples or 6144 bytes (not including header)