# OCPP Gateway

[OCPP](https://www.openchargealliance.org/) (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](https://www.openchargealliance.org/protocols/ocpp-16/), 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](https://github.com/0721Betty/ocpp-js) to simulate a charge point and test the connection.

1. Set up an MQTT client such as [MQTTX](https://mqttx.app/downloads) 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.

   <img src="./_assets/ocpp-mqttx-create-conn.png" alt="ocpp-mqttx-create-conn" style="zoom:67%;" />

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

   ```shell
   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:

   ```shell
   cp env.template .env.local
   ```

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

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

   ::: tip 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:

   ```shell
   npm start
   ```

   Or run it directly with Node.js:

   ```shell
   node client.js
   ```

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

   ```bash
   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`:

   ```json
   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`.

   :::

   ```json
   {
     "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:

   ```json
   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.

![ocpp_client](./_assets/ocpp_client.png)