OCPP Gateway

OCPP (Open Charge Point Protocol) is an open communication protocol that connects charging stations with central management systems, aiming to provide a unified communication standard for electric vehicle charging infrastructure. The OCPP gateway acts as a protocol translator, bridging the gap between OCPP and MQTT protocols, thus enabling clients that use these protocols to communicate with each other.

EMQX Platform has added a protocol gateway for OCPP 1.6-J, capable of connecting to charging station equipment of various brands that comply with the OCPP specifications. It integrates with management systems (Central System) through rule engines, data integration, REST APIs, and other methods, helping users quickly build electric vehicle charging infrastructure.

This page introduces how to configure and use the OCPP gateway in EMQX Platform.

Basic Settings

To configure the basic settings of the OCPP Gateway, click the Settings button in the Actions column.

• MountPoint: A prefix added to all MQTT topics for publishing and subscribing. This enables message routing isolation between protocols, by default, ocpp/.
• Default Heartbeat Interval: The default interval for heartbeat messages sent by charge points, default: 60s.
• Heartbeat Checking Times Backoff: Multiplier used for backoff in heartbeat timeout checks, default: 1.
• Message Format Checking: Whether to enable message format validity checking. EMQX checks the message format of the upload stream and download stream against the format defined in JSON schema. When the check fails, EMQX will reply with a corresponding answer message. Options:
  • all: Check all messages.
  • upstream_only: Check upload stream messages only.
  • dnstream_only: Check download stream messages only.
  • disable: Do not check any messages.
• JSON Schema ID Prefix: Prefix used to identify the OCPP JSON Schema documents, default: urn:OCPP:1.6:2019:12:.
• Idle Timeout: Set the maximum amount of time in seconds that the gateway will wait for an OCPP frame before closing the connection due to inactivity.
• Upstream: The Upload stream configuration group (Charge Point -> EMQX).
  • Topic: The topic for upload stream Call Request messages, default: cp/${cid}.
  • Reply Topic: The topic for Upload stream Reply messages, default: cp/${cid}/Reply.
  • Error Topic: The topic for Upload stream Error messages, default: cp/${cid}/Reply.
  • Topic Override Mapping: Upload stream topic override mapping by Message Name.
• Downstream: The Download stream configuration group. (EMQX -> Charge Point)
  • Topic: Download stream topic to receive request/control messages from EMQX. This value is a wildcard topic name that is subscribed by every connected Charge Point. The default value is: cs/${cid}.
  • Max Message Queue Length: The maximum message queue length for download stream message delivery. The default value is: 100.

Authentication

While OCPP 1.6-J does not define a built-in authentication mechanism, it is common practice to authenticate clients during the WebSocket handshake using HTTP Basic Authentication. The OCPP Gateway adopts this approach to extract client credentials when a charge point connects.

The gateway uses the following information from the connection request:

• Client ID: Extracted from the WebSocket connection URL after the fixed path prefix (e.g., /ocpp/chargePointSim -> chargePointSim).
• Username and Password: Decoded from the Authorization header using HTTP Basic Authentication.

These credentials are then matched against entries in the EMQX Platform console under OCPP -> Authentication. To allow a client to connect, you must first add its username and password on that page.

Test the OCPP Gateway Using OCPP Client Tool

Once the OCPP gateway is up and running, you can verify the setup by connecting an OCPP client. This section demonstrates how to use the open-source tool ocpp-js to simulate a charge point and test the connection.

1. Set up an MQTT client such as MQTTX to monitor messages exchanged through the OCPP gateway.

   • Connect MQTTX to your EMQX deployment.
   • Subscribe to the wildcard topic: ocpp/#.

   This allows you to observe all OCPP-related messages.

   

2. Clone and set up the ocpp-js client:

   git clone https://github.com/0721Betty/ocpp-js.git
   cd ocpp-js
   npm install

3. Configure the environment variables. Copy the environment template and update it with your actual settings:

   cp env.template .env.local

   Edit .env.local with your deployment-specific information:

   OCPP_USERNAME=your_username
   OCPP_PASSWORD=your_password
   OCPP_CLIENT_ID=chargePointSim
   EMQX_CLOUD_DEPLOYMENT_ADDRESS=your_deployment_address

   Note

   • You can find your deployment address on the Overview page in the EMQX Platform console.
   • Make sure the username and password match the credentials configured in OCPP -> Authentication.

4. Launch the OCPP client to connect to the EMQX OCPP Gateway:

   npm start

   Or run it directly with Node.js:

   node client.js

   If successful, you’ll see log output similar to:

   Connected to Central System
   Client ID: chargePointSim
   Username: your_username
   Sending: ......

5. In MQTTX, you should receive a message like this on topic ocpp/cp/chargePointSim:

   Topic: ocpp/cp/chargePointSim
   {
     "UniqueId": "1200012677",
     "Payload": {
       "chargePointVendor": "vendor1",
       "chargePointModel": "model1"
     },
     "Action": "BootNotification"
   }

   This confirms that the simulated charge point has connected and initiated a BootNotification request.

6. In MQTTX, send a reply to the topic ocpp/cs/chargePointSim. Replace the UniqueId with the one received in the previous message:

   TIP

   The UniqueId must match the one from the original BootNotification.

   {
     "MessageTypeId": 3,
     "UniqueId": "***",
     "Payload": {
       "currentTime": "2023-12-01T14:20:39+00:00",
       "interval": 300,
       "status": "Accepted"
     },
     "Action": "BootNotification"
   }

7. After responding to the BootNotification, you should see a StatusNotification message arrive in MQTTX:

   Topic: ocpp/cp/chargePointSim
   Payload:
   {
     "UniqueId": "3062609974",
     "Payload": {
       "status": "Available",
       "errorCode": "NoError",
       "connectorId": 0
     },
     "MessageTypeId": 2,
     "Action": "StatusNotification"
   }

This indicates that the OCPP client has successfully established communication with the gateway and reported its current status.

Clients

In the Clients tab of the OCPP page, you can view the basic information of all currently connected OCPP clients. In the Actions column, you can kick out a client.