Commands
CSMS-initiated OCPP commands. Each blocks until the charging station answers (up to ~35s) or the request times out — see each endpoint's own status codes for how a charging station's answer, timeout, or disconnection are told apart.
17 endpoints
Cancels a reservation on a charging_station.
post/v1/charging-stations/{charging_station_id}/commands/cancel-reservationRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| charging_station_id* | path | string<uuid> | ChargingStation id |
Request bodyCancelReservationRequest
| Field | Type | Description |
|---|---|---|
| reservation_id* | integer<int32> | The id reserve-now returned. |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | CancelReservationResponse | The charging_station answered — including 'rejected', meaning it holds no such reservation |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the charging_station's organization but below the required role |
| 404 | ErrorBody | No charging_station with this id exists, or the caller cannot access its environment |
| 409 | ErrorBody | The charging_station is not connected to the CSMS |
| 502 | ErrorBody | The charging_station gave no usable answer |
| 503 | ErrorBody | The command could not be sent |
| 504 | ErrorBody | The charging_station did not answer in time |
Asks a charging_station to change a connector's (or the whole charging_station's) operative/inoperative availability.
post/v1/charging-stations/{charging_station_id}/commands/change-availabilityRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| charging_station_id* | path | string<uuid> | ChargingStation id |
Request bodyChangeAvailabilityRequest
| Field | Type | Description |
|---|---|---|
| connector_id* | integer<int32> | The station's own wire-level connector number, or 0 for the whole
charging_station and all its connectors (1.6 spec §6.7) — not a db
connector row id. |
| evse_id | integer | null<int32> | Which EVSE to target, for a 2.0.1 charging_station — omit to target the
whole charging station (2.0.1 spec Part 2 §1.6). Ignored by a 1.6
gateway, which uses connector_id alone. |
| type* | AvailabilityType | The API's own mirror of [AvailabilityKind].
Duplicated rather than reused because csms-domain deliberately carries
no utoipa dependency — see [crate::commands::reset::ResetType] for
the same reasoning. The From impl below is where the two are kept in
step; adding a variant to either without the other won't compile. |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | ChangeAvailabilityResponse | The charging_station answered |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the charging_station's organization but below the required role |
| 404 | ErrorBody | No charging_station with this id exists, or the caller cannot access its environment |
| 409 | ErrorBody | The charging_station is not connected to the CSMS |
| 502 | ErrorBody | The charging_station gave no usable answer |
| 503 | ErrorBody | The command could not be sent |
| 504 | ErrorBody | The charging_station did not answer in time |
Asks a charging_station to change one configuration setting.
post/v1/charging-stations/{charging_station_id}/commands/change-configurationRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| charging_station_id* | path | string<uuid> | ChargingStation id |
Request bodyChangeConfigurationRequest
| Field | Type | Description |
|---|---|---|
| key* | string | — |
| value* | string | — |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | ChangeConfigurationResponse | The charging_station answered |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the charging_station's organization but below the required role |
| 404 | ErrorBody | No charging_station with this id exists, or the caller cannot access its environment |
| 409 | ErrorBody | The charging_station is not connected to the CSMS |
| 422 | ErrorBody | The key or value is not expressible in the charging_station's OCPP version |
| 502 | ErrorBody | The charging_station gave no usable answer |
| 503 | ErrorBody | The command could not be sent |
| 504 | ErrorBody | The charging_station did not answer in time |
Asks a charging_station to clear its local Authorization Cache.
post/v1/charging-stations/{charging_station_id}/commands/clear-cacheRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| charging_station_id* | path | string<uuid> | ChargingStation id |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | ClearCacheResponse | The charging_station answered |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the charging_station's organization but below the required role |
| 404 | ErrorBody | No charging_station with this id exists, or the caller cannot access its environment |
| 409 | ErrorBody | The charging_station is not connected to the CSMS |
| 502 | ErrorBody | The charging_station gave no usable answer |
| 503 | ErrorBody | The command could not be sent |
| 504 | ErrorBody | The charging_station did not answer in time |
Sends a vendor-specific `DataTransfer` message to a charging_station.
post/v1/charging-stations/{charging_station_id}/commands/data-transferRequires a bearer token
This CSMS does not interpret the payload — see the audit trail (GET
/charging-stations/{charging_station_id}/commands) for the only record of what was sent.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| charging_station_id* | path | string<uuid> | ChargingStation id |
Request bodyDataTransferRequest
| Field | Type | Description |
|---|---|---|
| data | string | null | The message body, passed through verbatim. Its format is between the caller and the vendor; this service never interprets it. |
| message_id | string | null | Identifies a specific message within that implementation. A charging_station
that doesn't recognize it answers unknown_message_id. |
| vendor_id* | string | Identifies the vendor-specific implementation being addressed. 1.6
spec §4.3: it SHOULD be a reversed-DNS name, e.g.
com.example.charging_stations. |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | DataTransferResponse | The charging_station answered |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the charging_station's organization but below the required role |
| 404 | ErrorBody | No charging_station with this id exists, or the caller cannot access its environment |
| 409 | ErrorBody | The charging_station is not connected to the CSMS |
| 422 | ErrorBody | The request is not expressible in the charging_station's OCPP version |
| 502 | ErrorBody | The charging_station gave no usable answer |
| 503 | ErrorBody | The command could not be sent |
| 504 | ErrorBody | The charging_station did not answer in time |
Asks a charging_station to report its configuration settings — a live round-trip, unlike `GET /charging-stations/{charging_station_id}/configuration`'s cached read.
post/v1/charging-stations/{charging_station_id}/commands/get-configurationRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| charging_station_id* | path | string<uuid> | ChargingStation id |
Request bodyGetConfigurationRequest
| Field | Type | Description |
|---|---|---|
| keys | array<string> | The settings to look up. Empty or omitted asks for every setting the charging_station has (1.6 spec §5.8). |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | GetConfigurationResponse | The charging_station answered |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the charging_station's organization but below the required role |
| 404 | ErrorBody | No charging_station with this id exists, or the caller cannot access its environment |
| 409 | ErrorBody | The charging_station is not connected to the CSMS |
| 502 | ErrorBody | The charging_station gave no usable answer |
| 503 | ErrorBody | The command could not be sent |
| 504 | ErrorBody | The charging_station did not answer in time |
Asks a charging_station what limit is currently in effect.
post/v1/charging-stations/{charging_station_id}/commands/get-effective-limitRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| charging_station_id* | path | string<uuid> | ChargingStation id |
Request bodyGetEffectiveLimitRequest
| Field | Type | Description |
|---|---|---|
| duration_seconds* | integer<int32> | — |
| scope* | EffectiveLimitScope | What to ask about — a station-wide total, or one connector. Only two
variants, unlike ChargingLimitScope's three: this isn't about a
charging profile's purpose, only about which physical thing the answer
describes. |
| unit | null | ChargingRateUnitApi | — |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | GetEffectiveLimitResponse | The charging_station answered |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the charging_station's organization but below the required role |
| 404 | ErrorBody | No charging_station with this id exists, the caller cannot access it, or scope names an unknown connector |
| 409 | ErrorBody | The charging_station is not connected to the CSMS |
| 502 | ErrorBody | The charging_station gave no usable answer |
| 503 | ErrorBody | The command could not be sent |
| 504 | ErrorBody | The charging_station did not answer in time |
Asks a charging_station for its local authorization list version.
post/v1/charging-stations/{charging_station_id}/commands/get-local-list-versionRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| charging_station_id* | path | string<uuid> | ChargingStation id |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | GetLocalListVersionResponse | The charging_station answered |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the charging_station's organization but below the required role |
| 404 | ErrorBody | No charging_station with this id exists |
| 409 | ErrorBody | The charging_station is not connected to the CSMS |
| 502 | ErrorBody | The charging_station gave no usable answer |
| 503 | ErrorBody | The command could not be sent |
| 504 | ErrorBody | The charging_station did not answer in time |
Asks a 2.0.1 charging_station to report one or more Device Model variables.
post/v1/charging-stations/{charging_station_id}/commands/get-variablesRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| charging_station_id* | path | string<uuid> | ChargingStation id |
Request bodyGetVariablesRequest
| Field | Type | Description |
|---|---|---|
| skip_device_model_check | boolean | Relay without first checking the requested Component/Variable pairs
against the charging_station's cached Device Model. Defaults to false — see
[crate::commands::set_variables::SetVariablesRequest] for when to
set it, and [crate::commands::device_model_validation] for why the
escape hatch exists at all. |
| variables* | array<VariableTargetView> | — |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | GetVariablesResponse | The charging_station answered |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the charging_station's organization but below the required role |
| 404 | ErrorBody | No charging_station with this id exists, or the caller cannot access its environment |
| 409 | ErrorBody | The charging_station is not connected to the CSMS |
| 422 | ErrorBody | Either the request names a Component/Variable absent from the charging_station's cached Device Model (unknown_variable, refused locally with nothing sent), or it is not expressible in the charging_station's OCPP version (unsupported) |
| 502 | ErrorBody | The charging_station gave no usable answer |
| 503 | ErrorBody | The command could not be sent |
| 504 | ErrorBody | The charging_station did not answer in time |
Asks a charging_station to remotely stop a running transaction.
post/v1/charging-stations/{charging_station_id}/commands/remote-stop-transactionRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| charging_station_id* | path | string<uuid> | ChargingStation id |
Request bodyRemoteStopTransactionRequest
| Field | Type | Description |
|---|---|---|
| transaction_id* | TransactionIdentifier | The transaction to stop, as the charging_station knows it — for an OCPP 1.6
charging_station, the integer this CSMS allocated and returned in
StartTransaction. |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | RemoteStopTransactionResponse | The charging_station answered |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the charging_station's organization but below the required role |
| 404 | ErrorBody | No charging_station with this id exists, or the caller cannot access its environment |
| 409 | ErrorBody | The charging_station is not connected to the CSMS |
| 422 | ErrorBody | The request is not expressible in the charging_station's OCPP version |
| 502 | ErrorBody | The charging_station gave no usable answer |
| 503 | ErrorBody | The command could not be sent |
| 504 | ErrorBody | The charging_station did not answer in time |
Asks a charging_station to reserve a connector.
post/v1/charging-stations/{charging_station_id}/commands/reserve-nowRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| charging_station_id* | path | string<uuid> | ChargingStation id |
Request bodyReserveNowRequest
| Field | Type | Description |
|---|---|---|
| connector_number* | integer<int32> | The station's own connector number. `0` reserves the charging_station rather than a named connector (§6.37) — see the module docs for why this is a number rather than a connector id. |
| expires_at* | string<date-time> | When the reservation lapses. Enforced by the station, not by this CSMS (§5.13). |
| id_token* | string | The token the connector is held for. Capped at 20 characters by the wire (§7.14); a longer one is refused before anything is sent. |
| parent_id_token | string | null | Optional group token. A station may admit any token sharing this parent, which is why this CSMS cannot second-guess a start. |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | ReserveNowResponse | The charging_station answered |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the charging_station's organization but below the required role |
| 404 | ErrorBody | No charging_station with this id exists, or the caller cannot access its environment |
| 409 | ErrorBody | The charging_station is not connected to the CSMS |
| 422 | ErrorBody | A token is too long for OCPP 1.6's 20-character bound |
| 502 | ErrorBody | The charging_station gave no usable answer |
| 503 | ErrorBody | The command could not be sent |
| 504 | ErrorBody | The charging_station did not answer in time |
Asks a charging_station to reboot, soft or hard.
post/v1/charging-stations/{charging_station_id}/commands/resetRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| charging_station_id* | path | string<uuid> | ChargingStation id |
Request bodyResetChargerRequest
| Field | Type | Description |
|---|---|---|
| evse_id | integer | null<int32> | Which EVSE to reset, for a 2.0.1 charging_station — omit to reset the whole charging station. Ignored by a 1.6 gateway, which has no per-EVSE reset. |
| schedule | null | ResetSchedule | — |
| type* | ResetType | The API's own mirror of [ResetKind].
Duplicated rather than reused because csms-domain deliberately carries
no utoipa dependency — the domain model exists to be free of transport
concerns, and OpenAPI is one. Same reason EvseSummary mirrors
stations::evse::Evse. The From impls below are where the two are kept
in step; adding a variant to either without the other won't compile. |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | ResetChargerResponse | The charging_station answered |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the charging_station's organization but below the required role |
| 404 | ErrorBody | No charging_station with this id exists, or the caller cannot access its environment |
| 409 | ErrorBody | The charging_station is not connected to the CSMS |
| 502 | ErrorBody | The charging_station gave no usable answer |
| 503 | ErrorBody | The command could not be sent |
| 504 | ErrorBody | The charging_station did not answer in time |
Pushes a charging_station's local authorization list to it.
post/v1/charging-stations/{charging_station_id}/commands/send-local-listRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| charging_station_id* | path | string<uuid> | ChargingStation id |
Request bodySendLocalListRequest
| Field | Type | Description |
|---|---|---|
| update_type* | UpdateTypeRequest | The API's mirror of [LocalListUpdateType] — duplicated because
csms-domain carries no utoipa dependency. |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | SendLocalListResponse | The charging_station answered |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the charging_station's organization but below the required role |
| 404 | ErrorBody | No charging_station with this id exists, or it has no list |
| 409 | ErrorBody | The charging_station is not connected to the CSMS |
| 422 | ErrorBody | The list cannot be pushed: too large for the charging_station, or it names tokens with no recoverable value |
| 502 | ErrorBody | The charging_station gave no usable answer |
| 503 | ErrorBody | The command could not be sent |
| 504 | ErrorBody | The charging_station did not answer in time |
Asks a 2.0.1 charging_station to write one or more Device Model variables.
post/v1/charging-stations/{charging_station_id}/commands/set-variablesRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| charging_station_id* | path | string<uuid> | ChargingStation id |
Request bodySetVariablesRequest
| Field | Type | Description |
|---|---|---|
| skip_device_model_check | boolean | Relay without first checking the requested Component/Variable pairs
against the charging_station's cached Device Model.
Defaults to false. Set it when the cache is known to be stale (a
firmware change can add variables before the next report lands), or
to deliberately exercise a station's UnknownComponent handling —
sending an arbitrary Component/Variable is a legal OCPP operation
whose authority is the charging_station, not this cache. See
[crate::commands::device_model_validation]. |
| variables* | array<VariableValueView> | — |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | SetVariablesResponse | The charging_station answered |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the charging_station's organization but below the required role |
| 404 | ErrorBody | No charging_station with this id exists, or the caller cannot access its environment |
| 409 | ErrorBody | The charging_station is not connected to the CSMS |
| 422 | ErrorBody | Either the request names a Component/Variable absent from the charging_station's cached Device Model (unknown_variable, refused locally with nothing sent), or it is not expressible in the charging_station's OCPP version (unsupported) |
| 502 | ErrorBody | The charging_station gave no usable answer |
| 503 | ErrorBody | The command could not be sent |
| 504 | ErrorBody | The charging_station did not answer in time |
Asks a charging_station to (re-)send a specific message type, e.g. a fresh `StatusNotification` or `BootNotification`.
post/v1/charging-stations/{charging_station_id}/commands/trigger-messageRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| charging_station_id* | path | string<uuid> | ChargingStation id |
Request bodyTriggerMessageRequest
| Field | Type | Description |
|---|---|---|
| connector_id | integer | null<int32> | Which connector the request is about. Omitting this is not the
same as naming every connector: §5.17 reads an absent
connector_id as "for all allowed connectorId values", so a
triggered status_notification without one asks for the charge
point's own status *plus* one per connector. Connector numbering is
the charging_station's own and must be greater than 0 here (§6.51) — unlike
change-availability, 0 is not meaningful and comes back as a 422. |
| custom_trigger | string | null | The vendor-specific trigger name, for requested_message: "custom"
on an OCPP 2.1 charging_station (2.1 spec F06, max 50 characters).
Passed through opaquely — the CSMS never interprets it; what it
means is between operator and vendor, the same stance
data-transfer takes. Required with custom, and rejected without
it: either half alone reaches the charging_station as a request it cannot
act on, so both come back as a 422 rather than being sent. |
| evse_id | integer | null<int32> | Which EVSE the request is about, for a 2.0.1 charging_station — omit to ask about the whole charging station. Ignored by a 1.6 gateway, which has no EVSE concept. |
| requested_message* | MessageTriggerType | The API's own mirror of [commands::MessageTrigger].
Duplicated rather than reused because csms-domain deliberately carries
no utoipa dependency — see [crate::commands::reset::ResetType] for
the same reasoning.
This enum used to omit OCPP's two firmware-profile triggers, on the
grounds that the Firmware Management profile is out of scope and
ocpp-gateway answered both of those messages with a CallError — so
asking for a message we would then refuse was not a request worth being
able to make. The premise was true and the conclusion was wrong: the
two triggers belong to *Remote Trigger*, not Firmware Management (1.6
§7.32 conditions its enum on nothing), and the gateway now answers both
messages. See specs/009-ocpp16-certification-hardening/. |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | TriggerMessageResponse | The charging_station answered |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the charging_station's organization but below the required role |
| 404 | ErrorBody | No charging_station with this id exists, or the caller cannot access its environment |
| 409 | ErrorBody | The charging_station is not connected to the CSMS |
| 422 | ErrorBody | The request may not be sent to this charging_station, or is not expressible in its OCPP version |
| 502 | ErrorBody | The charging_station gave no usable answer |
| 503 | ErrorBody | The command could not be sent |
| 504 | ErrorBody | The charging_station did not answer in time |
Asks a charging_station to remotely start a transaction on one connector.
post/v1/connectors/{connector_id}/commands/start-transactionRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| connector_id* | path | string<uuid> | Connector id |
Request bodyStartTransactionRequest
| Field | Type | Description |
|---|---|---|
| charging_limit | null | SessionChargingLimitRequest | — |
| transaction_limit | null | SetTransactionLimitRequest | — |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | StartTransactionResponse | The charging_station answered |
| 400 | ErrorBody | Request body present but not valid JSON |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the charging_station's organization but below the required role |
| 404 | ErrorBody | No connector with this id exists, or the caller cannot access its environment |
| 409 | ErrorBody | The charging_station is not connected to the CSMS |
| 422 | ErrorBody | charging_limit is not a valid TxProfile, its recurrence and schedule.anchor contradict each other, it is not expressible in the charging_station's OCPP version, or transaction_limit states no ceiling |
| 502 | ErrorBody | The charging_station gave no usable answer |
| 503 | ErrorBody | The command could not be sent |
| 504 | ErrorBody | The charging_station did not answer in time |
Asks a charging_station to unlock one connector.
post/v1/connectors/{connector_id}/commands/unlockRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| connector_id* | path | string<uuid> | Connector id |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | UnlockResponse | The charging_station answered |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the charging_station's organization but below the required role |
| 404 | ErrorBody | No connector with this id exists, or the caller cannot access its environment |
| 409 | ErrorBody | The charging_station is not connected to the CSMS |
| 502 | ErrorBody | The charging_station gave no usable answer |
| 503 | ErrorBody | The command could not be sent |
| 504 | ErrorBody | The charging_station did not answer in time |