Expand description
§ocpp-kit
An Open Charge Point Protocol toolkit for Rust — OCPP 1.6J, 2.0.1 and 2.1 over JSON/WebSocket, for charging stations, CSMS backends and local controllers.
The crate is five independent layers. Each one is useful on its own, and you pay only for the ones you turn on: with default features there is no async runtime, no TLS and no domain logic in your binary.
| Layer | Module | What it gives you | no_std |
|---|---|---|---|
| L0 | v1_6, v2_0_1, v2_1 | Typed, validated payloads for all 39 / 64 / 91 actions, generated from the official OCA JSON schemas | ✅ alloc |
| L1 | rpc | OCPP-J framing: CALL, CALLRESULT, CALLERROR, CALLRESULTERROR, SEND, with version-exact error codes, plus JWS signed messages | ✅ alloc |
| L2 | engine | A sans-I/O protocol engine: correlation, the one-outstanding-CALL rule, timeouts, transaction retries, the offline queue, the boot state machine | ✅ alloc |
| L3 | [transport] | Tokio + rustls, with its own RFC 6455 WebSocket and RFC 7692 compression: Station, Csms, LocalController, security profiles 0 (1.6 only) to 3, network failover | – |
| L4 | [station], [csms] | Opt-in building blocks: device model, 1.6 configuration keys, transaction rules, local authorization, composite schedules, an idempotent CSMS ledger, version-agnostic events | partial |
| — | standard | The catalogues that live outside the schemas: security events with their criticality, 74 standardized components, 458 variables, reason codes | ✅ alloc |
| — | metering | Signed meter values: the record a customer may be billed for, in every version’s hiding place | ✅ alloc |
§Getting started
A Charging Station that boots and then talks to its CSMS:
use ocpp_kit::transport::{BasicAuthPassword, ClientTls, SecurityProfile, Station};
use ocpp_kit::{Version, v2_1};
let handle = Station::builder()
.identity("CS-0001")?
.url("wss://csms.example.com/ocpp")
// Part 4 §3.2 recommends that a 2.1 station also offer 2.0.1.
.versions([Version::V2_1, Version::V2_0_1])
.security_profile(SecurityProfile::TlsBasicAuth)
.password(BasicAuthPassword::utf8("a-sixteen-plus-character-secret")?)
.tls(ClientTls::with_webpki_roots()?)
.build()?
.spawn()?;
let boot = handle
.call(v2_1::BootNotificationRequest::new(
v2_1::ChargingStation::new("Model-1", "ACME"),
v2_1::BootReason::PowerUp,
))
.await?;
println!("{:?}, heartbeat every {}s", boot.status, boot.interval);The CSMS side is the mirror image — see [transport::Csms]. The guide at
https://hupe1980.github.io/ocpp-kit/docs/ walks through each layer with the specification
citations.
§What is different about this crate
Error codes are exact. OCPP does not have one “bad payload” error; it has five, and
answering with the wrong one is a conformance failure. A missing member is an
OccurrenceConstraintViolation, a string where an integer belongs is a
TypeConstraintViolation, an over-long string is a PropertyConstraintViolation, and a
payload that is not an object at all is a FormatViolation — spelled FormationViolation
when you are talking 1.6. See decode and rpc::ErrorCode.
The value that pays for the electricity. An OCPP meter value is telemetry; under German
calibration law a customer may only be billed for the record the meter signed, which is not
the protocol’s own number and often not even the same quantity. metering is the protocol
knowledge around it: 1.6 hides the whole 2.x SignedMeterValueType inside the value string
of a SignedData sample, and the publicKey field is an envelope whose specification and
whose own example message disagree. Both shapes are read, and every signed record reaches the
[csms::events] funnel untouched.
Nothing that decides money fails silently. A station that claims to send signed meter data
and sends something unparseable is otherwise indistinguishable from one sending none, so every
such drop raises an Observed::warnings entry naming what arrived.
The funnel also carries the charging_state and the EVSE a session is at — the facts a meter
reading cannot supply and a CDR needs.
Numbers are exact, not f64. Every OCPP number — a meter register, a charging limit, a
2.1 tariff price — is a types::Decimal: a mantissa and a decimal scale. A
meter reporting 2935.600 kWh is claiming three decimals of resolution, and it goes back out
as 2935.600; a session’s energy, which OCPP defines as a difference of two registers, is
that difference exactly rather than 10.000000000000002. Literals are written
decimal!(32.5), and the f64 conversions are named to_f64_lossy /
from_f64_lossy so a signature says what it costs. cargo xtask no-floats keeps them out of
the public API, and CI runs it.
The protocol logic has no I/O. engine::Engine is a pure state machine: you feed it
Inputs — each with the driver’s current Instant — and
drain Outputs. Every timing rule in OCPP is therefore testable in
microseconds rather than minutes, and the same code runs on Tokio, in an embassy firmware
loop and in WebAssembly. testkit::Sim owns the clock so a test reads as a
transcript.
A SEND cannot be awaited. OCPP 2.1’s SEND is never answered (Part 4 §4.2.4), so
Handle::call is bounded by Confirmed,
which the code generator implements for exactly the actions whose schemas define a response.
Unconfirmed messages go through Handle::send.
Both sides, and the middle. Charging Station, CSMS and the Part 4 chapter 6 Local Controller are all built from the same engine, down to Part 4 §5.3’s ping/pong check, which a Local Controller runs on each of its two legs separately.
The offline queue survives a power cut. E04/E08/E12 require a station to replay the
transaction messages an outage interrupted, so FileStore ships alongside
MemStore: an append-only journal, flushed to the device before a write is
reported as successful.
Compression, because 2.1 requires it. Part 4 §3.4 makes RFC 7692 permessage-deflate
required for a CSMS and a Local Controller, and no general-purpose Rust WebSocket crate
implements it — RFC 6455 obliges one that does not to reject the RSV1 bit a compressed
message sets. So [transport] contains a focused RFC 6455 implementation with compression,
checked against an independent one in both directions and fuzzed.
The types are checked against the schemas. Every action’s request and response is round-tripped through pseudo-random schema-valid payloads in CI, and the output is validated back against the official schema — so the types cannot quietly drop a member, widen a constraint, or miss an enumeration value.
Version differences are modelled, not averaged. 1.6 and 2.x really do differ:
FormationViolation vs FormatViolation, OccurenceConstraintViolation (one r, as the
1.6 specification prints it) vs OccurrenceConstraintViolation, an unknown message type
being ignored on 1.6J and 2.1 but answered on 2.0.1, SEND and CALLRESULTERROR existing
only in 2.1. All of it is in the code, with the citation next to it.
§Feature flags
| Feature | Default | What it turns on |
|---|---|---|
std | ✅ | std types and std::error::Error; off gives alloc-only L0–L2 |
v1_6, v2_0_1, v2_1 | ✅ | The per-version types and dispatch tables |
tokio | – | L3: the Tokio + WebSocket transport |
rustls | – | TLS for security profiles 2 and 3 |
compression | – | RFC 7692 permessage-deflate, required of a CSMS by 2.1 |
getrandom | – | An entropy source, so MessageIds are UUIDs. Implied by tokio |
signed-messages | – | JWS signed messages (Part 4 ch. 7) |
jws-es256 | – | A ready-made software ES256 signer and verifier |
station | – | L4 Charging Station blocks |
csms | – | L4 CSMS blocks |
tracing | – | tracing spans and events in the transport |
cli | – | The ocpp-cli binary |
testkit | – | Sim, Recorder and mock peers, for your [dev-dependencies] |
full | – | Everything above |
§The JSON schemas
The OCPP JSON schemas are published by the Open Charge Alliance and are redistributed
unmodified in the repository’s schemas/ directory; see schemas/NOTICE. They are not
covered by this crate’s license. Generated code is committed, so building ocpp-kit needs
neither the schemas nor a network connection.
Re-exports§
pub use version::Subprotocol;pub use version::Version;
Modules§
- actions
- Version-aware action metadata, without generics.
- decode
- Payload decoding with spec-exact failure classification.
- engine
- Layer 2 — the sans-I/O protocol engine.
- message
- The traits that tie a payload type to its action, direction and message kind.
- metering
- Signed meter values: the record a customer may actually be billed for.
- rpc
- Layer 1 — OCPP-J framing.
- standard
- The catalogues OCPP 2.x defines outside the JSON schemas.
- types
- Primitive types shared by every OCPP version.
- v1_6
- OCPP 1.6 messages, generated from the official OCA JSON schemas.
- v2_0_1
- OCPP 2.0.1 messages, generated from the official OCA JSON schemas.
- v2_1
- OCPP 2.1 messages, generated from the official OCA JSON schemas.
- validate
- Constraint validation, kept deliberately separate from
serde. - version
- OCPP protocol versions and WebSocket subprotocol negotiation.
Macros§
Structs§
- RawValue
- An unparsed JSON value.
Constants§
- VERSION
- The version of this crate.