DocsAPIsChangelogEasee
Docs
Start typing to search…

Commissioning for operators (CPOs)

Follow this page if you have an charge point operator (CPO) account registered and want to commission (native) OCPP chargers.

❗️

Disclaimer: OCPP is currently in beta release with firmware version >=328. We strongly recommend using this beta release exclusively in test environments. Your feedback is greatly appreciated and will help us improve the final offering of OCPP. Other features of firmware version 328 can be used in production safely.

OCPP Commissioning API

The Easee OCPP Commissioning API empowers operators to configure connection parameters and activate the native OCPP solution on charging stations. This API facilitates rapid and straightforward commissioning, enabling utility to activate for large sites with a single API call.

The API offers endpoints for setting default connection configurations, applying connection configurations to a charger or site, and retrieving saved connection configurations.

Three main steps:

  1. Store OCPP configuration in operator account
  2. Apply OCPP configuration
  3. Get configuration details (to verify/query stored configuration)

Using OCPP with a cloud OCPP operator account

Operators currently utilising Easee’s cloud OCPP integration may also employ OCPP via the same operator account. Upon pairing a charger with cloud OCPP, a background service verifies whether the paired charger contains any stored configuration or whether the operator possesses any default OCPP configurations for connecting to OCPP. The latter will be automatically provisioned on the charger if the “ApplyToNewDevices” parameter is set to true.

Prerequisites

  1. Easee operator account (you will need your operator account ID). If you don't currently have an operator account, please sign up by using this form. (Please add a note to say OCPP)
  2. The charging site must have your operator selected as the operator before you can apply the configuration to a charger or site.

Authentication

All API endpoints require a Bearer token for authentication, please make sure this is included in the authorization header of your request, additional info on authentication can be found here

Base URL

This is the base URL you will need for all of the OCPP endpoints.

https://api.easee.com/local-ocpp

OCPP chargepoint URL

📘

It’s worth noting that we support IP addresses in URLs when using a non-secure connection, such as ws://192.168.1.101. However, when using a secured connection, we expect a domain name that matches the common name (CN) on the certificate. Ports can be used in both cases, for example, (wss://domain.com:443/16json/…).

Endpoints

The typical usage pattern is to first store a set of configuration and then apply the configuration to a charger or a site. The result of a successful POST operation to store connection details is a version identifier. Use this version identifier to indicate which configuration you want to apply to a charger or a site.


A note on connectivity mode: a value of OcppOff turns native OCPP connections off and DualProtocol turns them on. During the beta release, the charging station will connect to an OCPP server, yet it will also emit telemetry and receive calls, such as firmware versions, from and to Easee Cloud.

1. Store OCPP configuration in operator account

Default operator configuration

Request:

POST /v1/operators/{operatorId}/connection-details

This sets the default OCPP configuration for the operator account, that can later be applied to a charger or site.

Parameters:

  • operatorId (path, required): Operator Id
  • version (query, optional): use to specify the version to get

Request Body:

{
  "basicAuthPassword": "string",
  "websocketConnectionArgs": {
    "url": "string [required]",
    "caCertificate": "string [required if url is wss]",
    "caCertificateDomain": "string [required if url is wss]"
  },
  "connectivityMode": "OcppOff | DualProtocol [required]",
  "applyToNewDevices": "boolean" (default value is false) 
}

// sample full HTTP request
POST /v1/operators/{operatorId}/connection-details
Content-Type: application/json

{
    "connectivityMode": "DualProtocol",
    "websocketConnectionArgs": {
        "url": "wss://your-ocpp-server.com/ocpp",
        "caCertificate": "-----BEGIN CERTIFICATE-----\nYour CA certificate here\n-----END CERTIFICATE-----",
        "caCertificateDomain": "your-ocpp-server.com"
    },
    "basicAuthPassword": "your-password",  // Optional
    "applyToNewDevices": true  // Whether to automatically apply to new chargers
}

Response Body:

{
    "version": "some-string-with-the-version-identifier"
}

Specific configuration for a single charger

Request:

POST /v1/operators/{operatorId}/connection-details/{serialNumber}

This sets a specific OCPP configuration for a singular charger connected to your operator account.

Parameters:

  • operatorId (path, required): Operator Id
  • serialNumber (path, required): Easee's serial number identifying the charger

Request Body:

{
  "chargePointId": "string",
  "basicAuthPassword": "string",
  "websocketConnectionArgs": {
    "url": "string [required]",
    "caCertificate": "string [required if url is wss]",
    "caCertificateDomain": "string [required if url is wss]"
  },
  "connectivityMode": "OcppOff | DualProtocol [required]"
}

Response Body:

{
    "version": "some-string"
}

Note: The chargePointId is not required in this request, if this is omitted it will use the charger point's serial number by default.

2. Apply OCPP configuration

For a singular charger

This applies a specific OCPP configuration version to a charger.

Request:

POST /v1/operators/{operatorId}/connections/chargers/{serialNumber}

Parameters:

  • operatorId (path, required): Operator Id
  • serialNumber (path, required): Easee's serial number identifying the charger

Request Body:

Please paste in the response body (version identifier) that was returned from the store endpoints above. This could be an operator-level configuration or a charger-level configuration. The API will verify if you have applied a charger-level configuration and will modify the chargePointId if it was modified in the preceding step. If the configuration provided was at the operator-level, the operator-level configuration will be applied, and the charger’s serial number will be used for both the chargePointId and the username for the basic authentication password.

{
    "version": "some-string-with-the-version-identifier"
}

For an entire site

This applies an OCPP configuration version to all chargers on a specific site. Only operator-level configuration can be used in this case. If it has a basic auth password configured, the username will be the serial number of the charger and the password will be the same for all connected devices.

Request:

POST /v1/operators/{operatorId}/connections/sites/{siteId}

Parameters:

  • operatorId (path, required): Operator Id
  • siteId (path, required): Site ID

Request Body: The version you input is the response body from the 'Set OCPP Configuration Endpoints' above.

{
    "version": "some-string"
}

3. Get configuration details

For a singular charger

This retrieves latest stored OCPP connection details for a specific charger.

Request:

GET /v1/operators/{operatorId}/connection-details/{serialNumber}

Parameters:

  • operatorId (path, required): Operator Id
  • serialNumber (path, required): Serial number identifying the charger

Response Body:

{
  "chargePointId": "string",
  "basicAuthPassword": "string",
  "websocketConnectionArgs": {
    "url": "string",
    "caCertificate": "string",
    "caCertificateDomain": "string"
  },
  "connectivityMode": "OcppOff | DualProtocol"
}

Default operator configuration

This retrieves the default OCPP connection details for an operator.

Request:

GET /v1/operators/{operatorId}/connection-details

Parameters:

  • operatorId (path, required): Operator Id
  • version (query, optional): use to specify the version to get

Response Body:

{
  "websocketConnectionArgs": {
    "url": "string",
    "caCertificate": "string",
    "caCertificateDomain": "string"
  },
  "connectivityMode": "OcppOff | DualProtocol",
  "basicAuthPassword": "string"
}

Switching off OCPP

To remove a site/charger from OCPP, you have two options during the beta release stage.
Please Note: This may change as our offering evolves.

Option 1.

Navigate to the site you wish to remove from OCPP and change the operator back to Easee or select another operator.

Option 2.

Make a new call to the connection-details endpoint, changing the connectivityMode to OcppOff. All other settings can remain the same. (You can still use the old version to apply the config to other chargers or sites at a later stage).

Request:

POST /v1/operators/{operatorId}/connection-details

This sets the default OCPP configuration for the operator account, that can later be applied to a charger or site.

Parameters:

  • operatorId (path, required): Operator Id

Request Body:

{
  "basicAuthPassword": "string",
  "websocketConnectionArgs": {
    "url": "string [required]",
    "caCertificate": "string [required if url is wss]",
    "caCertificateDomain": "string [required if url is wss]"
  },
  "connectivityMode": "OcppOff"
}

Response Body:

{
    "version": "some-string"
}

Apply this to the charger or site using the endpoints from the previous step

For more detailed information about request and response schemas, please refer to the full API specification.

Updated about 15 hours ago

What’s Next

Learn more..