15.3. Platform Discovery¶
Different hardware platform implementers may choose to offer different capabilities. With this in mind, the GEISA API provides a mechanism for describing or enumerating the specific hardware platform’s capabilities. This platform discovery capability allows the application to discover what a given platform offers in order to potentially adjust behavior, or just for logging and awareness purposes.
The Platform Discovery data is typically constant and is not expected to change during an application’s runtime execution. It SHOULD be retrieved by a GEISA application during startup after the application becomes operational. Although the Platform Discovery content is platform-wide rather than application-specific, it is retrieved using application-instance request/response topics so that each running application instance can obtain the current discovery snapshot for its device without broadcasting responses to other applications that may still be subscribed.
After receiving this data, an application MAY unsubscribe from the Platform Discovery response topic for the remainder of that execution instance, as the data will not change during runtime.
Applications MUST re-run Platform Discovery on each startup; if platform capabilities change, the platform will restart applications so they retrieve an updated snapshot during startup.
Dynamic updates and state are provided in Platform and App Status.
Platform Discovery metadata may be truly static, where a platform implementer generates the platform metadata as part of a build process. This may be true, for example, for a fixed function device with no installation variants. It is also possible that a platform vendor may dynamically generate the platform metadata at the time of device installation or first boot. This may be true if the GEISA platform is hosted on an edge card that needs to be married to a device, or a device whose realized capabilities may be activated as part of the installation process. How the platform metadata is generated is outside the scope of GEISA. However, because platform metadata is expected to be static, GEISA platforms MUST facilitate restarting all running applications in the event that the platform metadata changes; applications will be shut down by the platform and subsequently started with the updated Platform Discovery responses, so on startup applications are again aware of any changes/current platform capabilities.
15.3.1. Hardware, Firmware, and Platform Software¶
The Platform Discovery API includes the following data so applications are able to determine the realized hardware and software environment available on the device:
Device Type - returns the type of the device or module, e.g. electric meter, EV charger, etc.
Device Info - returns manufacturer name, model, revision, serial number(s)
Device Firmware - returns a list of the device platform/OS firmware versions (including notable libraries and firmware and versions)
Platform Software Environment - returns notable platform software and runtime components and their versions
Operator Information - if provisioned, the operator name and operator-assigned device identifier. If the device is not provisioned to an operator, the Operator Information MAY be omitted from the Platform Discovery response.
Note
The platform vendor determines what information is included in the Device Firmware information. However, GEISA mandates that it MUST include, at a minimum, the versions of:
the base host OS
the GEISA API implementation
the GEISA platform runtime environment in use, such as LEE or VEE where implemented
15.3.2. Application Information¶
Because an application’s Deployment Manifest may differ from the Vendor Application Manifest originally supplied by the application vendor, applications MUST be able to retrieve their own current Application Deployment Manifest as described in Application Manifests.
15.3.3. Metrology Hardware¶
For Meter type devices, the platform MUST provide at a minimum:
Meter Rating/Class
Meter Form
Number of Phases and if Neutral is connected
Nominal Phase Angle
Nominal Frequency
Nominal Phase-to-Phase and Phase-to-Neutral Voltage (when applicable)
15.3.4. Sensor Hardware¶
A GEISA EE compliant platform can optionally provide one or more sensors.
Some example sensors that may be provided include:
Temperature Sensor and Alarm
Humidity Sensor
Switch Sensor
Orientation or Motion/Vibration Sensor
GNSS
Note this list is not exhaustive, and specific sensor types and accuracy will be device-dependent.
Platform Discovery MAY include a list of available sensor descriptors so that applications can enumerate which sensors exist on the platform at startup. Runtime sensor readings and application-directed sensor queries are defined by the Sensors API (Sensors).
15.3.5. Network Hardware¶
Status: Reserved for Future Definition
Network hardware discovery remains reserved for future definition.
Implementations SHALL NOT assume behavior, interface, or data structure beyond what is explicitly defined elsewhere in this specification.
The Application SHALL assume that network permissions and volume restrictions described in it’s Deployment Manifest are valid and realizable on the device
15.3.6. Waveform Discovery¶
Platform Discovery describes the available waveform streams and their
characteristics. Platforms that support waveform data SHALL expose a baseline
waveform stream with the identifier waveform-base.
Discovery SHALL include only static metadata. Applications SHALL use waveform metadata to interpret a stream and SHALL NOT infer stream characteristics by parsing the stream identifier.
Runtime access details and application-specific state are defined by the Waveform Data API.
15.3.7. Application Deployment Manifest¶
Each GEISA application may retrieve its own Application Deployment Manifest. This manifest is also constant and not expected to change during runtime.
Like the Platform Discovery metadata, the Application Deployment Manifest may be truly static; however, it is also possible that the operator of the platform changes this data at runtime on an infrequent basis.
Because the Application Deployment Manifest content is expected to be static, GEISA platforms MUST ensure a running application is restarted in the event of a manifest change.
Warning
Application designers should consider the impact of placing configuration-type data in their application manifest to minimize the occurences where an operator needs to change the manifest. Frequently updated values or parameters should be sent over another mechanism such as the application message based communication with the ADM system.
15.3.7.1. MQTT Details¶
QoS: 1 / Acknowledged R/R
Req Topic:
geisa/api/platform/discovery/req/<userid>andgeisa/api/app/manifest/req/<userid>Rsp Topic:
geisa/api/platform/discovery/rsp/<userid>andgeisa/api/app/manifest/rsp/<userid>
Note
In the topic definitions, <userid> refers to the platform-local
identifier of the requesting GEISA application instance (see Glossary for
additional information).
The MQTT topics for geisa/api/app/manifest/* are used to retrieve the Application Deployment Manifest for the requesting application instance.
15.3.7.2. API Permissions¶
Application:
Publish:
geisa/api/platform/discovery/req/<userid>Subscribe:
geisa/api/platform/discovery/rsp/<userid>Publish:
geisa/api/app/manifest/req/<userid>Subscribe:
geisa/api/app/manifest/rsp/<userid>
Platform:
Wildcard Subscribe:
geisa/api/platform/discovery/req/#Publish:
geisa/api/platform/discovery/rsp/<userid>Wildcard Subscribe:
geisa/api/app/manifest/req/#Publish:
geisa/api/app/manifest/rsp/<userid>
15.3.7.3. Transaction Data¶
GeisaPlatformDiscovery_ReqGeisaPlatformDiscovery_RspGeisaApplicationDeploymentManifest_ReqGeisaApplicationDeploymentManifest_Rsp
As defined in https://github.com/geisa/schemas
