14.4. Platform and App Status

GEISA Application Programming Interface

While the Platform Discovery data is fixed and does not change during the life of the application, the platform uses the message bus to distribute status to all running applications. Notifications are grouped into 2 topics: application-specific or non-application-specific.

14.4.1. Runtime Mode

Devices may be changed between a normal production operating mode, test modes, and similar states. These states may not apply to a specific GEISA application, but applications can use these notifications to enable or disable their own modes or behaviors, suppress errors and alarms, or connect to different cloud resources (e.g., connect to test vs production service instances). Runtime mode is non-application-specific and determined solely by the device. Runtime mode is platform-scoped and applies uniformly to all applications running on the device.

GEISA defines the following runtime modes:

  • Manufacturing

  • Unprovisioned

  • Normal

  • Test

GEISA Pyramid

14.4.2. Urgent Platform Updates

If the platform encounters an error or edge condition it can inform GEISA applications so they can take appropriate actions. For some conditions, a GEISA application may be able to directly determine the same error or condition, but a platform notification allows for a consistent method of notification and can reduce duplication of effort between platform and applications.

A GEISA conformant implementation MUST provide at a minimum non-application-specific notifications for:

  • Over temperature

  • High CPU usage

  • Low Memory

  • Power Degraded (individual phase loss, under voltage, etc…)

  • Power Loss (running on backup power)

  • Reboot Scheduled

  • Shutdown Scheduled

  • Time Adjustment

When an application receives one of these updates it MAY take an action but SHALL continue operating until a separate application shutdown request is received, if any. The platform will send these updates periodically (at least once per minute) for as long as the condition persists. The platform SHOULD send a final notification when the condition clears.

GEISA Pyramid

14.4.3. Application Updates

GEISA applications should be made aware of their own resource utilization and any events or alarms or commands specific to their application instance.

A GEISA conformant implementation MUST provide at a minimum application-specific notifications for:

  • Resource usage periodically (at least once every 15 seconds)

    • CPU usage

    • Memory usage

    • Persistent storage usage

    • Non-persistent storage usage

  • Control requests for the application:

    • Request application to send status immediately

    • Request application to shut down cleanly

    • Request application to clear PII from memory and storage, if any

Note

What constitutes PII may vary by jurisdiction and operator policy. Application vendors should document what data their applications collect and what data is removed in response to a clear PII request.

The platform MAY request that an application perform a clean shutdown via the message bus, OR it MAY invoke the stop command defined in the application manifest. These mechanisms are considered functionally equivalent from the application’s perspective.

A shutdown request delivered via the message bus is advisory, allowing the application to perform an orderly shutdown (e.g., persist state, close connections, flush logs). The platform remains responsible for enforcing termination using the defined stop and termination behavior if the application does not complete shutdown within the allowed time.

GEISA Pyramid

14.4.4. Timestamps

Most platform-to-application messages, application-to-platform messages, and waveform data include a timestamp representing the time at which the message was generated by the platform or application.

The timestamp SHALL be expressed as UTC epoch time in microseconds.

Applications and Platforms MAY use this timestamp for ordering, correlation, and time-based calculations relative to device-local policy such as daily resource reset intervals.

GEISA platforms SHALL ensure that the timestamp provided is accurate. GEISA platforms SHOULD NOT start GEISA applications until they can provide valid timestamps, whether from a local real-time clock, a network source, global positioning, or an external time source. The platform is responsible for maintaining the timestamp as close as possible with UTC epoch time, synchronizing at least once every twenty-four hours, though continuous clock discipline is preferred.

Under normal operations, small corrections to the timestamp SHOULD be performed by adjusting the frequency at which the timestamp increments, while large corrections are performed by stepping the timestamp. The threshold at which a step is required is implementation specific and GEISA does not specify a that threshold.

Note

Timestamps in messages and timestamps obtained directly from the OS (e.g. gettimeofday()) SHALL be derived from the same source. In general, the GEISA platform and applications SHOULD fill message timestamps from the underlying OS which in turn is synchronized to a reliable time source.

Most GEISA platforms and applications should be unaware of frequency based corrections, however a step in the timestamp, either forwards or backwards, may disrupt an Application’s or Platform’s operations.

Platforms SHALL notify applications of time steps that move the system clock forward or backwards by setting sys_time_adjust to the amount of the step in the next platform status message sent after the time adjustment.

The GEISA platform SHALL inform the EMS through a log message whenever a time step occurs including the amount of adjustment that was needed and the duration for which the previous time-base was in use so that the EMS or System Operator MAY make note or correct the timestamps of any previous (or in-flight) communication.

Note

The delivery of a platform status message with a non-zero sys_time_adjust value is asynchronous to the actual underlying step in time. Applications that may be impacted by a time step SHOULD treat the notification as advisory as the time step has already occured and the exact moment when is not specified. Applications SHOULD use this notification (or their own detection mechanism), to handle previously generated stored persistent or non-persistent data, in-application state, and outstanding messages appropriately as they may have past or future timestamp values.

When an application starts, it does not know if a time step occurred since it was last running. If one has occurred persistent and non-persistent stored data may contain invalid timestamps. Applications SHOULD take care when loading stored data from a previous invocation.

A GEISA Platform implementation SHALL handle time steps appropriately including but not limited to: Queued message timestamps and timeouts; Application startup, stop, and watchdog timeouts; and Network communication daily usage and limits.

The platform SHOULD adjust daily network volume quotas upon a step. For example, if the time is stepped within a daily period, the remaining quota could be increased or reduced, or if stepped into a different daily period, the quota reset.

GEISA Pyramid

14.4.5. Application Status

GEISA platforms require visibility into the status and health of each application in order to manage lifecycle and availability.

A GEISA conformant implementation MUST process at a minimum the following application-specific status and lifecycle messages:

  • Notification that an application startup is complete and now operating

  • Current application status (RUNNING or SHUTTING_DOWN)

  • Request from an application to terminate itself then restart

  • Request from an application to terminate itself without restart

Upon startup, the application MUST notify the platform that it is operating by reporting a status of RUNNING.

The watchdog setting in the Vendor Application Manifest indicates whether the application supports the GEISA keepalive/watchdog mechanism and can provide the required periodic status updates. The operator MAY disable watchdog for an application that supports it by setting watchdog to false in the Application Deployment Manifest. The EMS MUST NOT allow watchdog to be enabled in an Application Deployment Manifest unless the corresponding Vendor Application Manifest sets watchdog to true. If watchdog is omitted from either manifest, it is treated as false.

When the watchdog is enabled in the Application Deployment Manifest, the application SHALL send its application status periodically. next_status specifies the number of seconds until the application is expected to send its next periodic status message. next_status_timeout specifies the number of seconds the platform will wait for that message before triggering watchdog handling. While the application is RUNNING and watchdog is enabled, next_status and next_status_timeout MUST both be greater than 0.

A next_status value of 0 means that no next periodic watchdog status is scheduled. When next_status is 0, next_status_timeout MUST also be 0 and the platform MUST ignore both values.

When watchdog is not enabled, the application is not required to send periodic status messages and the platform MUST ignore next_status and next_status_timeout. The platform MAY use directed status requests, local execution or process state, or other platform mechanisms to determine application status.

When the platform sets cmd_send_status to true in a message on geisa/api/platform/app/status/<userid>, the application MUST respond on geisa/api/app/platform/status/<userid> with its current application status. This requirement applies whether or not watchdog is enabled for the application.

After receiving a platform message-bus request to shut down, the application MUST report SHUTTING_DOWN before completing its orderly shutdown, while it is still running and able to communicate.

SHUTTING_DOWN indicates that shutdown is in progress, not that the process has exited. The platform MUST determine when the application has actually stopped using local execution, runtime, or process state.

The platform MUST act on an application request to terminate itself with or without restart. It determines the resulting application state using local runtime or execution state and, where applicable, application status messages or a later RUNNING notification. The platform MUST apply the effective restart policy in the current Application Deployment Manifest when handling a terminate-and-restart request. For a terminate-without-restart request, the platform MUST leave the application stopped.

When the platform monitors periodic status messages for watchdog handling and does not receive a status message within the specified timeout period, it MUST take the following corrective actions:

  • Send a directed status request by setting cmd_send_status to true on geisa/api/platform/app/status/<userid>

  • If the application does not respond within the platform-defined timeout following this request, run the stop command specified in the application manifest

  • If the stop command itself times out (as defined in the application manifest), terminate the application

The timeout following the directed status request is platform-defined in this version of the specification.

Note

A future specification version may define subsequent timeout or backoff behavior more precisely.

After stopping or terminating the application following watchdog failure, the platform MUST apply the effective restart policy in the Application Deployment Manifest. The platform MUST NOT restart the application when that policy prohibits a restart.

GEISA Pyramid

14.4.6. Connectivity Updates

A GEISA conformant implementation MUST provide at a minimum non-application-specific notifications for:

  • Message-based communication:

    • status: disabled, enabled-down, or enabled-up

  • Operator network IP communication:

    • status: disabled, enabled-down, or enabled-up

    • protocol: ipv4, ipv6, or both

    • latency: real-time, delayed

  • Internet IP communication:

    • status: disabled, enabled-down, or enabled-up

    • protocol: ipv4, ipv6, or both

    • latency: real-time, delayed

  • Local network communication:

    • status: disabled, enabled-down, or enabled-up

    • protocol: ipv4, ipv6, or both

    • latency: real-time, delayed

A GEISA conformant implementation MUST provide at a minimum application-specific notifications for:

  • Time of next daily volume reset

  • Message based communication:

    • Previous day messages used

    • Daily messages used & remaining

  • Operator based IP communication:

    • Volume state: zero, metered, unlimited

    • Previous day volume used while unlimited

    • Previous day volume used while metered

    • Daily volume used while unlimited

    • Daily volume used & remaining while metered

  • Internet based IP communication:

    • Volume state: zero, metered, unlimited

    • Previous day volume used while unlimited

    • Previous day volume used while metered

    • Daily volume used while unlimited

    • Daily volume used & remaining while metered

  • Local based IP communication:

    • Volume state: zero, metered, unlimited

    • Previous day volume used while unlimited

    • Previous day volume used while metered

    • Daily volume used while unlimited

    • Daily volume used & remaining while metered

14.4.6.1. MQTT Details

  • QoS: 0 / Unacknowledged

    • Topic: geisa/api/platform/status

  • QoS: 1 / Acknowledged

    • Topic: geisa/api/platform/app/status/<userid>

    • Topic: geisa/api/app/platform/status/<userid>

Note

In the topic definitions, <userid> refers to the platform-local identifier of the requesting GEISA application instance (see Glossary for additional information).

14.4.6.2. API Permissions

  • Application:

    • Subscribe: geisa/api/platform/status

    • Subscribe: geisa/api/platform/app/status/<userid>

    • Publish: geisa/api/app/platform/status/<userid>

  • Platform:

    • Publish: geisa/api/platform/status

    • Publish: geisa/api/platform/app/status/<userid>

    • Subscribe: geisa/api/app/platform/status/#

14.4.6.3. Transaction Data

  • GeisaPlatformStatus

  • GeisaPlatformToAppStatus

  • GeisaAppToPlatformStatus

as defined in https://github.com/geisa/specification/tree/main/schemas

Note

Within the GEISA schemas, geisa-status.proto defines that canonical response codes used by all GEISA applications. conn-status.proto has the GEISA PlatformStatus, PlatformtoAppStatus, and AppToPlatformStatus definitions.

GEISA Pyramid