14.9. Actuator Status & Control¶
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.
14.9.1. Permission and Safety Model¶
Access to actuator status and control is governed by deployment manifest policy and platform policy. When the deployment manifest grants an application access to the control API, the manifest MUST include an array listing which specific actuators the application is allowed to control. Platforms MUST enforce these permissions, ensuring that applications are only allowed to control the specific actuators for which they have been given permission.
Note
GEISA does not provide fine-grained control over actuator status information. Applications either are granted permission to check actuator status or they are not.
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.
14.9.2. 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.
14.9.3. 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.
14.9.4. 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.
14.9.5. 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).
14.9.6. 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>
14.9.7. Transaction Data¶
Actuator payloads are defined by:
GeisaActuatorGet_ReqGeisaActuatorGet_RspGeisaActuatorSet_ReqGeisaActuatorSet_RspGeisaActuatorStatus
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.
GeisaActuatorStatus also includes an optional duration_s field, used
only in set requests. It gives the number of seconds the platform holds the new
setting before its normal control of the actuator resumes. When it is absent,
the platform holds the setting until it is changed. It is not reported in get
responses.
A platform MUST reject a
duration_sof zero withGEISA_STATUS_CODE_REQUEST_INVALID_ARGUMENT.A platform that cannot hold a setting until it is changed MUST reject a setting without
duration_swithGEISA_STATUS_CODE_REQUEST_UNSUPPORTED.A platform that cannot hold a setting for a limited time MUST reject a setting with
duration_swithGEISA_STATUS_CODE_REQUEST_UNSUPPORTED.A platform MUST reject a
duration_slonger than the actuator supports withGEISA_STATUS_CODE_REQUEST_OUT_OF_RANGErather than shorten it.
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/specification/tree/main/schemas
14.9.8. Notes¶
Actuator visibility and availability are platform specific and deployment-specific.