OCPP
Reference for the OCPP driver: the embedded central system, charge point certificates, connector tags and the Meter, Status and Transaction naming rule.
The OCPP driver makes Ganter Lab the central system for EV charge points speaking the Open Charge Point Protocol. As with LoRaWAN, the direction is reversed: the station does not connect to the charger; the charge point connects to Ganter Lab over a WebSocket, registers itself, and pushes its telemetry in.
The embedded central system starts when the first enabled OCPP device is loaded into the running connector, and stops when the last one is removed or disabled: with no charge point configured, nothing listens on the port at all. Adding one brings it back, without restarting the application. Each Device you configure represents one charge point, identified by the id it connects under.
Prepare the charge point
The charge point dials this station, and out of the box it does not know where the station is. The page of each OCPP device carries a Prepare the charge point card with what to enter in the charge point's OCPP settings, written for this station:
| What to configure on the charge point | What the card gives |
|---|---|
| Central system address | wss://<address>:19521/<charge-point-id>, first with the address by this station's name (the "Network name" of the embedded OPC UA server's configuration, or the computer's name while it is empty), then once for each IPv4 address this station has on a network, each with a copy button. A charge point that checks the server's name needs the address by name; one that does not accepts any of them, and then the one on its own network will do. |
| Charge point identity | The device's Identifier, or, while it is empty, the name the station gives the device. Many charge points add their identity to the address themselves: on those, enter the address only up to the port, and the identity in its own field. |
| Security | TLS with a client certificate, which OCPP calls security profile 3. Profiles 1 and 2, which have no client certificate, are not accepted. The charge point's certificate names its identity in its common name or in a DNS alternative name (see Certificates). |
| Root certificate of the central system | The whole path of GanterLabConnector-<station>.pem, this station's root certificate, which the charge point installs to trust the central system, with an Open folder button that shows the file in Windows' file manager. The button works in the station's own window; in a browser on another device it stays greyed and says so. |
The card is open while the charge point has not connected since the station opened, and folds once it has: it stays on the page for the next time the charge point is set up. A charge point whose certificate no root installed in Windows vouches for is refused at its first connection and waits under Equipment access.
The file is written the first time the central system starts, once a charge point is registered, and until then the card says so. It is the same file for every charge point of this station, and it does not change when the station's name or addresses do (see The station's root certificate).
Every charge point that was given a file by an earlier version needs this one, installed once. On the first start of this version, a station whose charge points may hold an earlier file shows a notice on the card, This station's file changed, in that run only. The notice is a reminder, not the instruction: install the new file once on every charge point of a station that already had charge points, whether or not the card shows the notice. A charge point that checks the server's name accepts the station from then on.
Central system and ports
| What | Value |
|---|---|
| Protocol versions | OCPP 1.6, 2.0, 2.0.1 and 2.1 (WebSocket subprotocol negotiation; JSON) |
| Listener | All interfaces, TCP port 19521, TLS only |
| Charge point address | wss://<station-address>:19521/<charge-point-id> |
| Identity | The last part of the WebSocket path is the charge point id |
The listener is always TLS; a plain-HTTP listener is refused anywhere except loopback, which exists only for in-process tests. A charge point registers itself with its BootNotification (answered with a 60-second heartbeat interval), and every badge presented for authorization is accepted: Ganter Lab observes charging, it does not manage tariffs or access.
Certificates
The server side of the TLS handshake presents a certificate signed by this station's own root (see The station's root certificate). Every charge point must present a client certificate:
- It must be trusted in one of two ways: it builds a valid chain on this Windows machine, up to a root installed there, with no TLS policy errors; or you approved this very certificate under Equipment access on this driver's page (below). Either way it must be within its validity dates. A failed check refuses the connection and the journal records which check failed.
- Its subject common name or a DNS subject alternative name must name the charge point id it connects under. A certificate naming a different charge point than the one in the connection path is refused, even an approved one.
A handshake without a client certificate is dropped before any data flows.
The station's root certificate
| What | Value |
|---|---|
| The root | Created once for the profile, the first time the central system or the LoRaWAN network server starts. Its subject is Ganter Lab Connector (<station>), where <station> is the network name on that day. It never expires and is never replaced on its own: renaming the computer, changing the network name or changing the station's addresses leaves it as it is. |
| The file | GanterLabConnector-<station>.pem, the public part only, in the data folder under ua\pki\station. It is the same file for a charge point and for a LoRaWAN gateway, which installs it as tc.trust. |
| The certificate the central system presents | Signed by that root. It names the station's network name (the "Network name" of the embedded OPC UA server's configuration; the computer's name while it is empty), localhost and every IPv4 address of the station, so a charge point that checks the server's name (security profile 3) accepts it. When the network name or an address changes, only this certificate is issued again, by itself, with nothing to do on the charge point. |
| The OPC UA server's certificate | Not used here. The embedded OPC UA server keeps its own certificate for OPC UA clients. |
A root that is stored but can no longer be opened, for example because it was written by another Windows account, is replaced by a new one. Every charge point then needs the new file, once, and the card says so.
Equipment access
A charge point whose certificate no root installed in Windows vouches for, because it is self-signed or issued by the maker's own authority, does not need that root installed on this computer. Its first connection is refused, and its certificate waits under Equipment access at the end of the OCPP driver's page, the same card the OPC UA driver's page carries, until you decide:
| Group | What it lists | What you can do |
|---|---|---|
| Waiting for approval | Each refused certificate, under the charge point id it connected with: its SHA-256 fingerprint, when it last tried and how many times, and its details (subject, issuer, domain names, validity dates). | Approve admits the certificate from the charge point's next connection. Block keeps refusing it without listing it here again. Discard all pending certificates empties the list without approving or blocking anything. |
| Approved equipment | The certificates you approved or imported, with who decided and when. | Withdraw approval closes the charge point's connection and returns its certificate to the list. Import certificate approves a charge point's public certificate before its first connection. |
| Blocked equipment | The certificates you blocked. A blocked certificate is refused even if Windows trusts it. | Unblock returns the certificate to the list, without approving it. |
Each certificate is approved on its own, never the authority that signed it, so a second charge point from the same maker waits for its own approval. Check the fingerprint against the one the charge point reports before you approve it. Approving does not change which charge point the certificate is: it is still admitted only under the charge point id it names, and only within its validity dates. A certificate Windows already trusts is admitted as before and never appears here; nothing is approved automatically.
The decisions are kept in the station's data folder, under ua\pki\ocpp, and survive a
restart. Only a role that may configure the Connector is drawn the verbs, and they act
only in the station's own window: a browser on another device reads the card without
changing it, and no agent tool approves a certificate. The list holds up to 100
certificates waiting for approval; once it is full, a new one is still refused but not
listed, and the card says so.
Connection fields
| Field | What it is | Format | Default |
|---|---|---|---|
| Identifier | The charge point id this Device stands for: the same id the charger puts at the end of its connection URL and carries in its certificate. | Free text, matched ignoring letter case. Empty falls back to the sanitized device name. | empty |
There are no host, port or credential fields: the charger holds the connection details, and this station only needs to know which charge point the Device means. There are also no poll-interval fields. OCPP is push-based (the charge point sends MeterValues and StatusNotification messages on its own schedule), and the tags refresh from the last received data on a fixed one-second cycle.
A charge point that has not connected yet, or a connector that has not reported yet, therefore has no reading, not a failed one. Its tags stay empty and no failure is journaled: a point the charge point has not sent yet is the protocol working.
The charge point's health
Since a charge point sends its points when it has them, the silence of its tags cannot tell one that has not reported yet from one that is gone. Its health, the dot on its row in the tree and the Health column on the driver's page, follows its connection to this station's central system instead:
| Situation | Health |
|---|---|
| Configured, and it has not connected since the station opened | Offline |
| Connected, nothing sent yet | Online |
| Connected and sending | Online, or Partly online when some of the points it sent fail to read |
| It dropped: stopped, unplugged or cut off from the network | Offline, until it connects again |
| The central system not listening | Offline |
| Disabled | Disabled |
While the charge point is connected, a connector it has not reported yet does not count against it. For up to ten seconds after a change to the charge point is saved, or the Connector starts, it reads Not known yet: putting the device back can restart the central system, and the charge point takes a moment to connect again.
Tags
An OCPP tag reads one connector of the charge point (connector in the OCPP sense: one plug position, numbered from 1). On OCPP 2.0, 2.0.1 and 2.1 the number is the EVSE's instead, since connectors there are numbered from 1 again inside each EVSE. Three kinds of tag exist, told apart by the tag name suffix, which is validated:
| Tag name ends in | What it reads | Sensible type |
|---|---|---|
Meter |
The most recent sampled meter value the connector reported (OCPP MeterValues; on OCPP 2.x also the values a TransactionEvent carries during a session). The unit is whatever the charger sends, typically Wh. The server keeps the last 10 samples and the tag reads the newest. A connector that has never reported reads as an empty value, not as zero. | Float or Double |
Status |
The connector state text from the last StatusNotification (for example Available, Faulted). On OCPP 2.x an EVSE with more than one connector reads as the most telling of them: Faulted wins over Occupied, Occupied over Reserved, Reserved over Available, and Available over Unavailable. One that has not reported a status yet reads as an empty value. |
String |
Transaction |
The number of the transaction running on the connector, which the RemoteStopTransaction and GetTransactionStatus commands take: on OCPP 1.6 the number this station handed out when the transaction started, on OCPP 2.x the charging station's own identifier, exactly as it sent it. It is filled when a transaction starts and emptied when it ends, so with none running it reads as empty text. Until a transaction starts or ends after the charge point connects it reads as an empty value, since one may already have been running. | String |
A name with none of these suffixes is refused by validation: name tags like
Connector1Meter, Connector1Status and Connector1Transaction.
| Field | What it does | Values | Default |
|---|---|---|---|
| Connector | The number this tag reads: the connector on OCPP 1.6, the EVSE on OCPP 2.x. | 1 or greater | 1 |
| Data type | The OPC UA type the value is exposed as. | Int32, Float, Double, String | Float |
OCPP tags are read only: the access field offers no writable choice, and a write is refused rather than faked. Commanding a charge point is a command of its own, described next, not a value written to a tag.
Commands
A charge point is commanded as well as read. Each OCPP Device carries the commands below as methods on the device in this station's own OPC UA address space, so an OPC UA client connected to this station issues one by calling it.
Every command takes the charge point id as its first argument, and hands back the charge point's own answer as its result.
| Command | Further arguments | What it does |
|---|---|---|
| ChangeAvailability | ConnectorId, Type (Operative or Inoperative) |
Takes a connector in or out of service. |
| ChangeConfiguration | Key, Value | Sets one configuration key on the charge point (OCPP 1.6). |
| ClearCache | none | Clears the charge point's authorization cache. |
| GetConfiguration | Key | Reads one configuration key (OCPP 1.6). |
| RemoteStartTransaction | IdTag | Starts a charging session for a token. |
| RemoteStopTransaction | TransactionId | Stops a running session. |
| GetTransactionStatus | TransactionId | Asks whether a transaction is still running (OCPP 2.x). |
| Reset | none | Restarts the charge point. |
| UnlockConnector | ConnectorId | Releases the cable from a connector. |
| SetChargingProfile | ConnectorId, Limit, NumberOfPhases | Sets a charging power limit, in watts. ConnectorId 0 limits the whole charge point; another number sets the default limit for the sessions that connector charges. |
| SetVariables | ComponentName, VariableName, AttributeType, AttributeValue | Sets one variable of one component (OCPP 2.x). |
| GetVariables | ComponentName, VariableName, AttributeType | Reads one variable of one component (OCPP 2.x). |
AttributeType is one of Actual, Target, MinSet, MaxSet.
Where the TransactionId comes from. RemoteStopTransaction and GetTransactionStatus act on one transaction, named by its number. Read it from the Transaction tag of the connector the session charges on (the EVSE on OCPP 2.x), for example Connector1Transaction, and pass it on as it reads. Empty text there means no transaction is running on that connector.
One catalogue, every version. The commands keep the names above whatever version the charge point speaks, and the station sends each one in the form that version defines. In OCPP 2.0, 2.0.1 and 2.1 connectors are grouped under EVSEs, and the number given as ConnectorId names the EVSE.
| Command | On OCPP 1.6 | On OCPP 2.0, 2.0.1 and 2.1 |
|---|---|---|
| ChangeAvailability | Acts on the connector given; 0 is the whole charge point. | Acts on the EVSE given; 0 is the whole charging station. |
| RemoteStartTransaction | Sends the IdTag, and the charge point picks the connector. | Goes out as RequestStartTransaction, with the IdTag as a central token and a start id of its own; the charging station picks the EVSE. |
| RemoteStopTransaction | TransactionId is the number this station gave the session when it started. | Goes out as RequestStopTransaction; TransactionId is the charging station's own identifier, passed on as text. |
| Reset | A hard reset. | An immediate reset. |
| UnlockConnector | Releases the connector given. | Releases the first connector of the EVSE given. |
| SetChargingProfile | 0 sets the charge point's maximum profile; another connector gets a default profile. | 0 sets the charging station's maximum profile; another EVSE gets a default profile. |
| ChangeConfiguration, GetConfiguration | As in the table above. | Not part of these versions: the charging station answers with an error, and the command fails. |
| GetTransactionStatus, SetVariables, GetVariables | Not part of this version: the charge point answers with an error, and the command fails. | As in the table above. |
Waiting for the answer. A command is not finished when the station has sent it. The station holds the call open until the charge point answers the very order it sent, matched by the correlation identifier that travels with it, and only then reports success and hands back the answer. Three things end it otherwise, each reported as a failure with its reason:
- The charge point is not connected, or its connection is not open. Nothing is sent.
- The charge point answers with an OCPP error, for example a command it does not implement. The error code is the reason.
- 30 seconds pass with no answer at all. A command nobody answered is a failure, never a success.
A command issued for a charge point that a Device does not carry, or that is not connected, is refused straight away rather than queued.
Discovery
Discover on the OCPP driver lists the charge points currently connected to
the central system, and reading a candidate's channels proposes one Meter, one
Status and one Transaction tag per connector the charge point has reported so far.
The first charge point is always configured by hand. Nothing can connect before the central system listens, and it listens only once an OCPP Device exists here, so a scan of an installation with no charge point configured finds nothing and says so. Add that first Device with the id the charger will connect under; after that, a charger that has connected can be discovered. The general discovery flow is described on the Connector page.
The id is matched ignoring letter case, in the certificate, in the connection
path and against the Device: a charger that connects as cp-a with a certificate
naming CP-A is the same charge point as a Device whose Identifier reads CP-A.
A charge point you already have reads its connectors again from its own page: Discover tags,
on the head of its Tags card, offers the Meter, Status and Transaction tags of each
connector it has reported while connected that the device has no tag for yet (see
Discovering a device's tags).