Skip to main content

Module engine

Module engine 

Source
Expand description

Layer 2 — the sans-I/O protocol engine.

Engine is a pure state machine. It owns no socket, reads no clock and spawns no task: the driver feeds it Inputs and drains Outputs. That is what makes every timing rule in OCPP — message timeouts, the linear transaction-retry schedule, boot back-off — testable in microseconds, and what lets the same code run on Tokio, inside an embassy firmware loop, or in a browser.

Every entry point takes the driver’s current Instant: the engine has no clock of its own, and a deadline armed against a stale one fires the moment it is armed.

use ocpp_kit::Version;
use ocpp_kit::engine::{Engine, EngineConfig, Input, Instant, Output, Role};
use serde_json::value::RawValue;

let now = Instant::ZERO;
let mut engine = Engine::new(EngineConfig::new(Role::ChargingStation, Version::V2_1));
engine.handle(now, Input::Connected { version: Version::V2_1 });

let payload = RawValue::from_string(
    r#"{"reason":"PowerUp","chargingStation":{"model":"M1","vendorName":"ACME"}}"#.into(),
)
.unwrap();
engine.call(now, "BootNotification", payload).unwrap();

let frame = engine
    .drain()
    .into_iter()
    .find_map(|output| match output {
        Output::Transmit(text) => Some(text),
        _ => None,
    })
    .unwrap();
assert!(frame.starts_with(r#"[2,"#));

In a test, Sim owns the clock for you and the same session reads as a transcript.

§Rules this layer enforces

  • One outstanding CALL per direction (2.x Part 4 §4.1.1 SHALL NOT; 1.6J §4.1.1 SHOULD NOT — hence InboundConcurrency). Our own extra calls are queued, never rejected.
  • SEND is exempt and is never answered (Part 4 §4.2.4, FR.07).
  • Unknown message type numbers are ignored on 1.6J and 2.1 and answered with MessageTypeNotSupported on 2.0.1 (§4.4).
  • Message timeout, freeing the slot and starting the next queued call.
  • Transaction-message retries only, on the linear schedule of 1.6 §3.7.1 and the 2.x MessageAttempts[TransactionEvent] variables, in chronological order, skipping a message once its attempts are exhausted.
  • Durable offline queueing of transaction messages (E04/E08/E12) via MessageStore — MemStore in memory, FileStore on disk, or your own.
  • The boot state machine (B01–B04) on both sides, including the CSMS’s SecurityError answer to an unsolicited call from a Pending station (B02.FR.09).
  • Graceful drain: finish the in-flight call, flush the queue, then close.

Structs§

Backoff
The three OCPPCommCtrlr variables that drive reconnect timing (Part 4 §5.4).
CallOptions
Per-call overrides.
CallOutcome
The final result of a call the application started.
CallToken
A handle to a call the application asked for.
ClockSample
An authoritative timestamp observed in a BootNotificationResponse or HeartbeatResponse.
Engine
The sans-I/O OCPP protocol engine.
EngineConfig
Engine configuration.
FileStore
A MessageStore that survives a power cut, for the station side.
IncomingRequest
A request the peer sent that the application must handle.
Instant
A point on a monotonic clock, in milliseconds since an arbitrary origin.
Jitter
How much of a back-off’s random range to add, as a fraction of u32::MAX.
MemStore
An in-memory MessageStore. The default, and all a CSMS ever needs.
OfflinePolicy
What happens to outgoing calls while the connection is down.
QueuedCall
One queued outgoing message.
RetryPolicy
How often, and how far apart, transaction-related messages are retried.
StoreError
A durable store failed.

Enums§

Answer
How a message the application started ended, when it ended well.
BootState
The boot state machine (OCPP 2.x block B; 1.6 §4.2).
CallFailure
Why a call did not succeed.
CloseReason
Why the engine wants the connection closed.
EngineError
Why a command was refused.
HeartbeatPolicy
Whether the engine sends Heartbeat on its own.
InboundConcurrency
What to do when the peer breaks the one-outstanding-CALL rule.
Input
Events the driver feeds into the engine, via Engine::handle.
Output
What the driver must do next.
ProtocolViolation
Something the peer did that the specification forbids, but which is not fatal.
Role
Which side of the connection this engine is.
Timer
The timers the engine asks the driver to run.

Traits§

MessageStore
Durable storage for transaction-related messages.

Type Aliases§

Seq
Monotonic sequence number of a stored message.