Skip to main content

oicp_kit/
lib.rs

1//! A Rust toolkit for [OICP](https://github.com/hubject/oicp) (Open InterCharge Protocol), the
2//! roaming protocol that connects Charge Point Operators and e-Mobility Providers through the
3//! Hubject brokering system.
4//!
5//! Unlike OCPI, which is peer-to-peer, OICP is **hub-and-spoke**: every partner talks only to
6//! Hubject, over mutual TLS, and Hubject calls back into the partner for the reverse direction.
7//! Both halves are needed to go live, and this crate ships both.
8//!
9//! # What is here
10//!
11//! | Layer | Feature | What it gives you |
12//! |---|---|---|
13//! | [`types`] | *(always)* | identifiers with both ISO and DIN grammars, `Number`, `Extensions`, RFC 6901 validation |
14//! | [`cpo`] | `cpo` | the CPO half of the OICP 2.3 wire model |
15//! | [`emp`] | `emp` | the EMP half of the OICP 2.3 wire model |
16//! | [`transport`] | `transport` | the endpoint table, page envelope and error mapping |
17//! | [`client`] | `client` | an async client with mutual TLS, paginated crawls and delta pulls |
18//! | [`server`] | `server` | an `axum` router per role — the Hubject-facing half |
19//! | [`sync`] | `sync` | the `LastCall` delta engine, and the minimal-push planner |
20//! | [`eichrecht`] | `eichrecht` | typed calibration-law data, and CDR pre-flight |
21//! | [`testkit`] | `testkit` | samples and `MockHubject` — a broker to test against, offline |
22//!
23//! # Five properties worth knowing about
24//!
25//! **Energy and money are never floats.** Every `number` in every message is a [`types::Number`],
26//! an exact decimal, and every sum, difference and comparison in this crate is decimal arithmetic
27//! — so OICP's own rule, that `ConsumedEnergy` is the difference between `MeterValueEnd` and
28//! `MeterValueStart`, holds exactly. `cargo run -p xtask -- no-floats` fails the build on an
29//! `f32` or `f64` anywhere in `src/`, with one exemption it names: the JSON boundary in
30//! `types::Number` itself, which is exact for every value OICP carries and reports the rest
31//! through [`types::Number::json_round_trips`].
32//!
33//! **Identifiers are parsed, and the wire form survives.** [`types::EvseId`] and its siblings
34//! understand both the ISO 15118 and DIN SPEC 91286 grammars, expose the country and operator, and
35//! compare case-, separator- and `+`-insensitively — but re-serialise byte-identically. Hubject
36//! matches identifiers against your TLS certificate as text; a library that normalises them breaks
37//! production with status code `017`.
38//!
39//! **Parsing and conformance are separate questions.** A `PullEvseData` page carries thousands of
40//! records from dozens of operators. One malformed field cannot make the page undecodable: the
41//! value arrives, and [`types::Validate::validate`] reports it with a JSON Pointer. One malformed
42//! *record* cannot cost the page either — [`client::EmpClient::crawl_evse_data`] decodes the
43//! envelope first and each record on its own, so a crawl loses one charging point rather than
44//! every charging point after it.
45//!
46//! **Nothing a peer sent is thrown away.** OICP 2.3 is edited in place, without version bumps.
47//! Undocumented fields land in [`types::Extensions`] and are written back verbatim; an enum value
48//! this crate has never seen keeps its text in a `Custom` variant.
49//!
50//! **Both directions, one trait each.** Most OICP implementations ship the client half and leave
51//! Hubject's callbacks as an exercise. Here the CPO role is [`client::CpoClient`] plus
52//! [`server::CpoService`]; implement the trait and your Hubject-facing surface is complete.
53//!
54//! # Getting started
55//!
56#![cfg_attr(feature = "cpo", doc = "```rust")]
57#![cfg_attr(not(feature = "cpo"), doc = "```rust,ignore")]
58//! use oicp_kit::types::{EvseId, Validate};
59//!
60//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
61//! // Two ways of writing the same charging spot.
62//! let iso: EvseId = "DE*AB7*E840*6487".parse()?;
63//! let packed: EvseId = "DEAB7E8406487".parse()?;
64//!
65//! assert_eq!(iso, packed);                          // the same EVSE…
66//! assert_eq!(iso.to_string(), "DE*AB7*E840*6487");  // …each written back as it arrived
67//! assert_eq!(iso.operator_id(), packed.operator_id());
68//! # Ok(())
69//! # }
70//! ```
71//!
72//! # Spec traceability
73//!
74//! Public items carry the name of the OICP 2.3 message or type they implement, so a reviewer — or
75//! a partner's compliance team — can go from a Rust type to the document that defines it. Where
76//! Hubject's own documents disagree with one another, [`types::ERRATA`] records the conflict, what
77//! breaks, and which spelling this crate emits.
78//!
79//! OICP is a protocol owned and maintained by [Hubject GmbH](https://www.hubject.com/). This
80//! project is not affiliated with Hubject.
81
82#![cfg_attr(docsrs, feature(doc_cfg))]
83
84/// The README's examples, compiled as doctests.
85///
86/// The front page of a crate is the part most people read and the part nothing checks. This makes
87/// `cargo test --doc` check it: an example that stops compiling is a failing test rather than a
88/// paragraph that quietly stopped being true.
89// The examples reach across the whole crate, so they are checked on the feature set
90// that has all of it.
91#[cfg(all(doctest, feature = "full"))]
92#[doc = include_str!("../README.md")]
93pub struct ReadmeExamples;
94
95pub mod types;
96
97#[cfg(feature = "cpo")]
98#[cfg_attr(docsrs, doc(cfg(feature = "cpo")))]
99pub mod cpo;
100
101#[cfg(feature = "emp")]
102#[cfg_attr(docsrs, doc(cfg(feature = "emp")))]
103pub mod emp;
104
105#[cfg(feature = "transport")]
106#[cfg_attr(docsrs, doc(cfg(feature = "transport")))]
107pub mod transport;
108
109#[cfg(feature = "client")]
110#[cfg_attr(docsrs, doc(cfg(feature = "client")))]
111pub mod client;
112
113#[cfg(feature = "server")]
114#[cfg_attr(docsrs, doc(cfg(feature = "server")))]
115pub mod server;
116
117#[cfg(feature = "sync")]
118#[cfg_attr(docsrs, doc(cfg(feature = "sync")))]
119pub mod sync;
120
121#[cfg(feature = "eichrecht")]
122#[cfg_attr(docsrs, doc(cfg(feature = "eichrecht")))]
123pub mod eichrecht;
124
125#[cfg(feature = "testkit")]
126#[cfg_attr(docsrs, doc(cfg(feature = "testkit")))]
127pub mod testkit;
128
129/// The version of OICP this crate implements.
130///
131/// OICP 2.3 is the last version: in September 2025 Hubject committed to native OCPI support on
132/// intercharge, so there is no 2.4. What does change is the 2.3 documents themselves, which
133/// Hubject edits in place — which is why [`types::Extensions`] and the open enums exist.
134pub const OICP_VERSION: &str = "2.3";