Connecting a Charger

If you want to now connect a charger to CitrineOS, you can do so without any set up, just point the charger to ws://localhost:8081. Depending on the charger you are using, you may need to append the station id to the url like so ws://localhost:8081/<stationId>. Some chargers take care of this automatically.

In Directus, the Boot table can be used to both review the most recent boot status as well as set a boot status for the next BootNotificationRequest received from the charging station. After a successful boot, the status is set to Accepted. If you wish to fetch the device model from the charger as part of the boot process described in the B02 use case of part 2 of the OCPP 2.0.1 protocol, set the status to Pending and check the ‘Get Base Report On Pending’ option. This will cause the next boot to be responded to with a BootNotificationResponse that has status Pending, then CitrineOS will send a GetBaseReportRequest, triggering a series of NotifyReportRequest messages. After the full report has been sent, the next attempted boot by the charger will be Accepted.

The Boot table has CRUD endpoints in order to be manipulated via REST API, of which the docs can be found here (if you have CitrineOS running locally): localhost:8080/docs Here is an example request for charge point cp001:

curl --location --request PUT 'http://localhost:8080/data/configuration/boot?stationId=cp001' \
--header 'Content-Type: application/json' \
--data '{ "status": "Pending" }'

Using Security Profile 1

There are two layers of security available before the charger has the opportunity to send an OCPP message such as BootNotificationRequest. When the charger attempts to connect, it can be rejected at the transport layer if the websocket server is using security profiles 2 or 3. Otherwise, the http upgrade request occurs. The charger’s upgrade request can be rejected if:

  • The request’s subprotocol header is incorrect. The default websocket servers used by CitrineOS accept only ‘ocpp2.0.1’.

  • The charging station’s Id, as set in the url it connected with, is not known. This option can be toggled in the SystemConfig object used by CitrineOS, and is enabled by default only for the security profile 1 websocket server at :8082. To enter a charger into CitrineOS, use Directus. Navigate to the Charging Station collection, then create and save a new entry for your charging station. Make sure the Id of your new entry is the charging station’s station id as set in the url it uses to connect to CitrineOS.

  • The websocket server is using security profiles 1 or 2 and the request’s Authorization header has an incorrect username or password. The username will be checked against the charging station’s id as set in the url it connected with. The password will be checked against the device model associated with the station id. Specifically, it will be the Actual Variable Attribute’s value that belongs to the BasicAuthPassword Variable on the SecurityCtrlr Component. You can set this VariableAttribute on the CSMS side using the Variable Attribute CRUD endpoints on the Monitoring module. You can set this VariableAttribute on the Charging Station side using the SetVariables message, which can be sent from CitrineOS using the Monitoring module’s message API.

Once a charger has a Charging Station entry and its password has been set, you can connect it to the security profile 1 websocket server at ws://localhost:8082.

If you want to add a password for security profile 1 and 2, send the following request to the CitrineOS API.

curl --location --request POST 'localhost:8080/data/configuration/password?callbackUrl=csms.pro/api/notifications' \
--header 'Content-Type: application/json' \
--data '{
  "stationId": "cp001",
  "password": "DbkTu048=xueA69@-dB94hjV*fGdyQOzgVuhhH1L",
  "setOnCharger": false
}'

Please note that the password should be sent in plain text and should not be hashed.

Set setOnCharger to true if the password has already been updated on the charger and you only need to update the device model associated with the station id. If you need to update the password on the charger (OCPP A01 use case), set setOnCharger to false.

Providing a password is mandatory only when setOnCharger is true. This prevents the possibility of updating the device model with an autogenerated password without updating the charger itself.

If you do not provide a password, it will be automatically generated. If you do provide one, it must comply with the OCPP specification.