Skip to main content

🚦 Remote Commands

The Commands module allows an eMSP to remotely control a charge session. Users can start or stop charging, reserve connectors and unlock plugs directly from their mobility app. This reduces friction and eliminates the need for physical cards or dedicated apps【901419033685628†L583-L600】.

Available commands​

OCPI 2.2.1 defines several commands, but only a subset are commonly implemented:

CommandDescriptionNotes
START_SESSIONStarts a charging session on a specific connector. The eMSP must supply the token, location_id, evse_uid and connector_id. In OCPI 2.2.1 a new optional field connector_id was added to the request【826352846409834†L1242-L1247】. Upon success, the CPO will create a Session and push updates to the eMSP.Supported by most platforms.
STOP_SESSIONStops an ongoing session. The eMSP must provide the session_id and may include the authorization_reference. The CPO will finalise the session, generate a CDR and return the result.Supported by most platforms.
RESERVE_NOWReserves a connector for a driver. Requires the reservation expiry time and token.Optional; not all hubs implement reservations【826352846409834†L1228-L1240】.
CANCEL_RESERVATIONCancels a reservation.Optional.
UNLOCK_CONNECTORUnlocks a connector, for example if a cable is stuck.Optional; rarely implemented.

Flow​

  1. eMSP sends command – The eMSP issues a POST /commands/START_SESSION to the CPO’s Commands receiver endpoint. The request body contains the command parameters and a response_url where the CPO should send the asynchronous result.
  2. CPO validates and acts – The CPO validates the token and connector availability. If valid, it sends an ACCEPTED response immediately and instructs the charge point to start charging. If the command cannot be executed (e.g. connector out of order) it returns REJECTED.
  3. Callback – Once the charge point has executed the command, the CPO sends a callback to the response_url provided by the eMSP. The callback includes the final status (ACCEPTED, REJECTED, UNKNOWN) and any associated details.
  4. Session updates – For START_SESSION, the CPO creates a Session object and pushes it to the eMSP (via PUT /sessions). The session is updated throughout the charge and eventually completed when a STOP_SESSION command is issued or charging ends normally【826352846409834†L1254-L1260】.

Best practices​

  • Use X-Request-ID and X-Correlation-ID: Provide unique identifiers in all command calls for traceability【826352846409834†L1224-L1240】.
  • Connector identification: Always include connector_id when starting a session. OCPI 2.2.1 introduced this field to remove ambiguity; older eMSPs running version 2.1.1 may not support it【826352846409834†L1242-L1247】.
  • Error handling: Commands are asynchronous. Check the callback result to determine whether the charger accepted or rejected the command. If the callback times out, use GET /sessions to verify whether a session was started.
  • Store‑and‑forward: If sending commands via a hub, you may need to implement store‑and‑forward logic as described in the Sessions section.

Remote commands empower users to control charging from their app and improve operational efficiency【901419033685628†L626-L652】.