Expand description
A Rust toolkit for OICP (Open InterCharge Protocol), the roaming protocol that connects Charge Point Operators and e-Mobility Providers through the Hubject brokering system.
Unlike OCPI, which is peer-to-peer, OICP is hub-and-spoke: every partner talks only to Hubject, over mutual TLS, and Hubject calls back into the partner for the reverse direction. Both halves are needed to go live, and this crate ships both.
§What is here
| Layer | Feature | What it gives you |
|---|---|---|
types | (always) | identifiers with both ISO and DIN grammars, Number, Extensions, RFC 6901 validation |
cpo | cpo | the CPO half of the OICP 2.3 wire model |
emp | emp | the EMP half of the OICP 2.3 wire model |
transport | transport | the endpoint table, page envelope and error mapping |
client | client | an async client with mutual TLS, paginated crawls and delta pulls |
server | server | an axum router per role — the Hubject-facing half |
sync | sync | the LastCall delta engine, and the minimal-push planner |
eichrecht | eichrecht | typed calibration-law data, and CDR pre-flight |
testkit | testkit | samples and MockHubject — a broker to test against, offline |
§Five properties worth knowing about
Energy and money are never floats. Every number in every message is a types::Number,
an exact decimal, and every sum, difference and comparison in this crate is decimal arithmetic
— so OICP’s own rule, that ConsumedEnergy is the difference between MeterValueEnd and
MeterValueStart, holds exactly. cargo run -p xtask -- no-floats fails the build on an
f32 or f64 anywhere in src/, with one exemption it names: the JSON boundary in
types::Number itself, which is exact for every value OICP carries and reports the rest
through types::Number::json_round_trips.
Identifiers are parsed, and the wire form survives. types::EvseId and its siblings
understand both the ISO 15118 and DIN SPEC 91286 grammars, expose the country and operator, and
compare case-, separator- and +-insensitively — but re-serialise byte-identically. Hubject
matches identifiers against your TLS certificate as text; a library that normalises them breaks
production with status code 017.
Parsing and conformance are separate questions. A PullEvseData page carries thousands of
records from dozens of operators. One malformed field cannot make the page undecodable: the
value arrives, and types::Validate::validate reports it with a JSON Pointer. One malformed
record cannot cost the page either — client::EmpClient::crawl_evse_data decodes the
envelope first and each record on its own, so a crawl loses one charging point rather than
every charging point after it.
Nothing a peer sent is thrown away. OICP 2.3 is edited in place, without version bumps.
Undocumented fields land in types::Extensions and are written back verbatim; an enum value
this crate has never seen keeps its text in a Custom variant.
Both directions, one trait each. Most OICP implementations ship the client half and leave
Hubject’s callbacks as an exercise. Here the CPO role is client::CpoClient plus
server::CpoService; implement the trait and your Hubject-facing surface is complete.
§Getting started
use oicp_kit::types::{EvseId, Validate};
// Two ways of writing the same charging spot.
let iso: EvseId = "DE*AB7*E840*6487".parse()?;
let packed: EvseId = "DEAB7E8406487".parse()?;
assert_eq!(iso, packed); // the same EVSE…
assert_eq!(iso.to_string(), "DE*AB7*E840*6487"); // …each written back as it arrived
assert_eq!(iso.operator_id(), packed.operator_id());§Spec traceability
Public items carry the name of the OICP 2.3 message or type they implement, so a reviewer — or
a partner’s compliance team — can go from a Rust type to the document that defines it. Where
Hubject’s own documents disagree with one another, types::ERRATA records the conflict, what
breaks, and which spelling this crate emits.
OICP is a protocol owned and maintained by Hubject GmbH. This project is not affiliated with Hubject.
Modules§
- client
client - An async OICP client over mutual TLS: pushes, pulls, streaming crawls.
- cpo
cpo - The CPO half of OICP 2.3: what a Charge Point Operator sends, and what Hubject sends it back.
- eichrecht
eichrecht - German calibration law (Eichrecht), and the CDR pre-flight built on it.
- emp
emp - The EMP half of OICP 2.3: what an e-Mobility Provider asks for, and what Hubject sends it.
- server
server - The half of OICP that Hubject calls: an
axumrouter driven by one trait per role. - sync
sync - Keeping two copies of the EVSE world in step — the delta engine, and its mirror image.
- testkit
testkit - A conformant brokering system and a set of valid objects, so you can test before you onboard.
- transport
transport - Addressing, paging and error mapping: what sits between the wire model and a socket.
- types
- The types every OICP message is built from: identifiers, numbers, text, validation.
Macros§
- oicp_
enum - Defines a closed OICP enum: a fixed set of strings, where anything else is an error.
- oicp_
open_ enum - Defines an OICP enum that keeps values it does not know.
Constants§
- OICP_
VERSION - The version of OICP this crate implements.