Connect a real charger

A station needs three things to reach you: a URL, credentials, and agreement on a protocol version. Get those right and it connects on power-up. Get any one wrong and it fails in a way that looks like the others.

This page covers all three, plus what happens after the socket opens.

Before you start#

Provision the charger first, and keep two things from the response: its charge point id and its authorization key. See Set up your workspace — the key is returned exactly once.

The charge point id you provision must match what the station is configured with, exactly, including case. This is the single most common commissioning mistake.

The connection URL#

wss://gateway.flowion.io/ocpp/{org_slug}/{charge_point_id}
wss://gateway.flowion.io/ocpp/{org_slug}/{env_slug}/{charge_point_id}

The first form targets your organization's default environment. The second names an environment explicitly.

For acme, a charger CP-01, and the default environment:

wss://gateway.flowion.io/ocpp/acme/CP-01

In staging instead:

wss://gateway.flowion.io/ocpp/acme/staging/CP-01

Use the explicit form if you run more than one environment. The short form follows whichever environment is currently default, so changing the default silently moves every charger using it.

Some firmware wants the URL split into a "base URL" and an identity it appends itself. In that case the base is everything up to and including the organization (and environment) segment, and the identity is the charge point id — the station adds the final /.

Always wss://, never ws://.

Credentials#

OCPP 1.6 Security Profile 2: HTTP Basic authentication over TLS.

Firmware calls these different things — "Authorization Key", "Basic Auth Password", "Security Password". It is the same field.

The key is a 40-character hex string. Some firmware expects hex text, some expects it decoded to 20 bytes; the specification's own example uses the hex form. If authentication fails with a key you are sure of, this is worth checking.

Security Profile 3 — TLS client certificates instead of a password — is not supported yet. Hardware that requires it will not connect.

Unencrypted OCPP is not supported at all.

Protocol version#

The station offers versions in the WebSocket handshake; we pick one. Acceptable values are ocpp1.6, ocpp2.0.1 and ocpp2.1.

Most firmware exposes this as an "OCPP version" or "protocol" setting. If it offers a version we do not accept, the handshake completes without agreeing a subprotocol and the connection closes immediately — which looks exactly like a crash loop and is not an authentication problem.

See Which OCPP version am I dealing with? for which version you will actually get.

Settings to check#

Names vary by manufacturer; the concepts do not.

Two of these deserve a note.

Heartbeat interval. Whatever the station is configured with, our BootNotification response overrides it. Do not tune it on the station.

Sampled data. This decides what telemetry you get. Without an energy register measurand you will have transactions with no consumption in them, and you will not notice until you try to bill from them.

What happens on power-up#

1. The station resolves DNS, opens a TLS connection, and performs the WebSocket handshake with its credentials and offered versions.
2. It sends BootNotification describing itself.
3. We answer Accepted, Pending or Rejected.
4. On Accepted, it adopts our heartbeat interval, syncs its clock to our timestamp, and starts reporting connector statuses.

Until step 3 succeeds, the station may send nothing else at all — including anything it had queued from before a reboot.

Confirm it arrived:

curl https://api.flowion.io/v1/chargers/$CHARGER \
  -H "Authorization: Bearer $TOKEN"

status should be online, last_boot_at recent, ocpp_version populated with what it actually negotiated, and boot_report filled in with the vendor, model and firmware the station reported.

Commissioning checklist#

Once it is online, before you call the site live:

• Check the clock. Compare a last_seen timestamp against reality. A station with a wrong clock writes wrong timestamps into transactions, and the damage is retrospective.
• Confirm the EVSE and connector count matches the physical hardware. If a two-cable post reports two EVSEs rather than one EVSE with two connectors, its firmware is modelling itself in a way that will confuse load management. See The vocabulary.
• Run one real session, with a real card and a real vehicle, and check the transaction has an energy figure.
• Check meter values arrive during that session, not only at its end.
• Pull the network — physically, or by blocking the gateway — and confirm the station reconnects on its own.

When it does not connect#

Work down in order. Each step assumes the ones above it passed.

Nothing reaches us at all. DNS, firewall, or the station cannot do TLS. Many stations on mobile connections sit behind carrier NAT with restrictive egress. Confirm outbound 443 is open to the gateway host.

It connects and immediately disconnects. Almost always a version mismatch. Check which OCPP versions the firmware offers.

Repeated authentication failures. The charge point id in the URL does not match a provisioned charger, the slug is wrong, or the key is wrong. Remember the id is unique per environment: connecting to the default environment when the charger was provisioned in staging fails exactly like a bad password.

It connects but nothing else happens. Look at registration_status. A Rejected charger stops responding entirely until its retry interval elapses; a Pending one stays connected but volunteers nothing.

It connects, boots, then goes quiet. Heartbeat or ping handling. Check whether an intermediate proxy is closing idle connections faster than the heartbeat interval.

Next#

• Lifecycle of a charging session — what the station does once it is live.
• Core concepts — sites and circuits, once you have more than one charger.
• API reference — every endpoint.