Initial connection to ChargePilot®

To enable a successful connection between ChargePilot® and an Upstream system, please ensure all required implementations on the customer end, based on the following VDV 463 specification: https://knowhow.vdv.de/documents/463/ (Available in English & German)

To establish an encrypted connection to ChargePilot via a WebSocket TLS handshake, please adhere to the following steps:

Get API access credentials

Step 1

Customer requests to set up a ChargePilot® site using the VDV 463 interface.

Step 2

The Mobility House configures the site setup for a customer and enables the VDV 463 functionality for ChargePilot®. This process also includes the generation of customer specific VDV 463 credentials (username & password).

Step 3

Customer specific VDV 463 credentials and the recommended certificate, that is required to connect to ChargePilot®, are provided to the customer.

Make your first VDV 463 call - system handshake

Step 4: WebSocket Handshake

After providing the required credentials and the certificate a connection between ChargePilot® and an Upstream System can be established via a WebSocket handshake. Customers identify themselves by using HTTP Basic Authentication, containing the credentials (username and password) encoded in Base64 format. As already mentioned it is highly recommended to use the provided TMH certificate in order to prevent any unauthorized access.

Step 6: Successful connection

After the WebSocket handshake a connection to ChargePilot® is established.

Step 7: BootNotification

To ensure a proper data exchange, the Upstream System will send send an initial BootNotification.req message to ChargePilot® as soon as the handshake between the two system was successful. This BootNotification.req message is the starting point of any additional API operation. Without a Boot.Notification.conf message by ChargePilot®, no further messages can be exchanged.

Step 8: ProvideChargingInformation

ChargePilot® starts sending ProvideChargingInformation.req messages to the upstream system to ensure that any ChargingRequest, sent by the upstream system, is created based on the current depot setup.

Step 9: ProvideChargingRequest

After a first ProvideChargingInformation.req message sent by ChargePilot®, the upstream system can start sending ProvideChargingRequests.req messages.

Step 10: VDV 463 bi-directional data exchange

ChargePilot® continues to send updated ProvideChargingInformation.req messages (MUST) every 15sec and awaits ProvideChargingRequests.req messages (OPTIONAL) from the upstream system. Step 6 repeats continuously, until the WebSocket connection is closed (e.g. due to internet connection issues).

Connection issues

In case of internet issues, the WebSocket connection with ChargePilot® may be interrupted. To establish a a connection again start the process by repeating Step 4.

During periods of an unstable internet connection, messages may get lost. To avoid information/data loss the following mechanism is implemented based on the VDV 463 requirements:

Every message request needs a confirmation message.

BootNotification message

A successful BootNotification process is the starting point for every further message exchange between ChargePilot® and the corresponding Upstream system.

Why is a BootNotification message required?

BootNotification.req message sent from upstream system is used to inform ChargePilot® that it is up and ready to exchange messages.

What is the typical structure of a BootNotification message flow?

The Upstream system sends BootNotification.req message and ChargePilot® responds by sending BootNotification.conf message.

Without a successful BootNotification process, no further messages can be exchanged between the systems.

BootNotification - Example Payloads

BootNotification.req message sent from Upstream System:

[
    1,
    "BMS",
    "Presystem1",
    "2020-07-17T08:38:00Z",
    "baf4ad01-d220-4430-a3eb-b31e4999720e",
    "BootNotification",
    {
        "systemType": "BMS"
    }
]

BootNotification.conf message sent from ChargePilot®:

[
    2,
    "CMS",
    "Presystem1",
    "2023-09-11T17:10:40.316Z",
    "baf4ad01-d220-4430-a3eb-b31e4999720e",
    "BootNotification",
    {
        "status": "Accepted"
    }
]