15.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.

15.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

15.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 compliant 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

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.

15.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-compliant 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

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.

15.4.4. Timestamps

All platform-to-application status messages SHALL include a timestamp representing the time at which the message was generated by the platform.

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

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

15.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-compliant implementation MUST accept at a minimum application-specific messages for:

  • Notification that an application startup is complete and now operating

  • Current application status (running, shutting down)

  • Notification that an application is shut down (due to a shutdown request) and ready for termination

  • Request from an application to terminate itself then restart

  • Request from an application to terminate itself without restart

Upon startup of an application, the application MUST send a notification to the platform that it is now operating and its status is RUNNING. In this message, the application MAY indicate whether it expects the platform to provide a keepalive/watchdog mechanism. If so, the application SHALL also send its application status periodically (at a period specified in the most recent message). If the application does not require a keepalive/watchdog mechanism, it MAY omit a timeout value.

If the platform does not receive a status message within the specified timeout period it MUST take the following corrective actions:

  • Send a message to the application requesting its status

  • If the application does not respond within a second timeout period, 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

  • Restart the application using the start command as defined in the application manifest

15.4.6. Connectivity Updates

A GEISA compliant 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 compliant 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

15.4.6.1. MQTT Details

  • QoS: 0 / Unacknowledged

  • Topic: geisa/api/platform/status

  • 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).

15.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/#

15.4.6.3. Transaction Data

  • GeisaPlatformToAppStatus

  • GeisaAppToPlatformStatus

as defined in https://github.com/geisa/schemas

GEISA Pyramid