Skip to main content

Crate oicp_kit

Crate oicp_kit 

Source
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

LayerFeatureWhat it gives you
types(always)identifiers with both ISO and DIN grammars, Number, Extensions, RFC 6901 validation
cpocpothe CPO half of the OICP 2.3 wire model
empempthe EMP half of the OICP 2.3 wire model
transporttransportthe endpoint table, page envelope and error mapping
clientclientan async client with mutual TLS, paginated crawls and delta pulls
serverserveran axum router per role — the Hubject-facing half
syncsyncthe LastCall delta engine, and the minimal-push planner
eichrechteichrechttyped calibration-law data, and CDR pre-flight
testkittestkitsamples 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§

clientclient
An async OICP client over mutual TLS: pushes, pulls, streaming crawls.
cpocpo
The CPO half of OICP 2.3: what a Charge Point Operator sends, and what Hubject sends it back.
eichrechteichrecht
German calibration law (Eichrecht), and the CDR pre-flight built on it.
empemp
The EMP half of OICP 2.3: what an e-Mobility Provider asks for, and what Hubject sends it.
serverserver
The half of OICP that Hubject calls: an axum router driven by one trait per role.
syncsync
Keeping two copies of the EVSE world in step — the delta engine, and its mirror image.
testkittestkit
A conformant brokering system and a set of valid objects, so you can test before you onboard.
transporttransport
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.