15.8. Actuator Status & Control

GEISA Application Programming Interface

15.8.1. Summary

The actuator API allows authorized applications to query actuator state and request actuator state changes.

Actuators are optional and platform/device-specific. Examples include a service switch, DER switch, and load-control or auxiliary relays.

15.8.2. Permission and safety model

Access to actuator status and control is governed by deployment manifest policy and platform policy.

A platform MUST reject unauthorized actuator requests.

A platform MAY reject otherwise well-formed requests if the actuator is unavailable, unsupported, malfunctioning, unsafe to operate, interlocked, administratively disabled, or otherwise denied by policy.

This API defines message structure and request/response behavior. It does not define detailed utility switching workflows, sequencing, tariff behavior, customer notice behavior, or physical interlock behavior.

15.8.3. Actuator targets

This version names the following actuator targets:

  • service switch

  • DER switch

  • load-control relays 0-3

Platforms may expose only a subset of these targets.

Future versions of this specification may add additional actuator types as appropriate, especially as GEISA is expanded to support distribution automation devices.

15.8.4. Getting actuator status

The application publishes GeisaActuatorGet_Req on:

geisa/api/actuator/get/req/<userid>

The platform responds with GeisaActuatorGet_Rsp on:

geisa/api/actuator/get/rsp/<userid>

The response includes GeisaStatus and GeisaActuatorStatus values.

15.8.5. Setting actuator state

The application publishes GeisaActuatorSet_Req on:

geisa/api/actuator/set/req/<userid>

The request may include one or more desired actuator settings.

The platform responds with GeisaActuatorSet_Rsp on:

geisa/api/actuator/set/rsp/<userid>

The response status indicates request outcome. A set response does not by itself guarantee completed physical motion; applications should query current status after a request when confirmation of state is required or desired.

15.8.6. MQTT Details

QoS: 1 / Acknowledged R/R

Get:

  • request: geisa/api/actuator/get/req/<userid>

  • response: geisa/api/actuator/get/rsp/<userid>

Set:

  • request: geisa/api/actuator/set/req/<userid>

  • response: geisa/api/actuator/set/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).

15.8.7. API Permissions

Application permissions:

  • Publish geisa/api/actuator/get/req/<userid>

  • Publish geisa/api/actuator/set/req/<userid>

  • Subscribe geisa/api/actuator/get/rsp/<userid>

  • Subscribe geisa/api/actuator/set/rsp/<userid>

Platform permissions:

  • Wildcard Subscribe geisa/api/actuator/get/req/#

  • Wildcard Subscribe geisa/api/actuator/set/req/#

  • Publish geisa/api/actuator/get/rsp/<userid>

  • Publish geisa/api/actuator/set/rsp/<userid>

15.8.8. Transaction Data

Actuator payloads are defined by:

  • GeisaActuatorGet_Req

  • GeisaActuatorGet_Rsp

  • GeisaActuatorSet_Req

  • GeisaActuatorSet_Rsp

  • GeisaActuatorStatus

GeisaActuatorStatus includes discrete state and optional position fields. Position is meaningful only for actuator types and platforms that support a position or analog setting. Where position is not present, applications should rely on discrete state and response status.

Note that JSON examples and JSON schema are human-readable schema representations, while runtime API payloads are protobuf.

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

15.8.9. Notes

Actuator visibility and availability are platform specific and deployment-specific.

GEISA Pyramid