simple_someip/lib.rs
1//! # Simple SOME/IP
2//!
3//! [](https://github.com/luminartech/simple_someip/actions/workflows/ci.yml)
4//! [](https://app.codecov.io/gh/luminartech/simple_someip)
5//! [](https://crates.io/crates/simple-someip)
6//!
7//! A Rust implementation of the [SOME/IP](https://github.com/some-ip-com/open-someip-spec)
8//! automotive communication protocol — remote procedure calls, event notifications, service
9//! discovery, and wire-format serialization.
10//!
11//! The core protocol layer (`protocol`, `e2e`, and trait modules) is `no_std`-compatible with
12//! zero heap allocation, making it suitable for embedded targets. Optional `client` and `server`
13//! modules provide async tokio-based networking for `std` environments.
14//!
15//! ## Modules
16//!
17//! | Module | `no_std` | Description |
18//! |--------|----------|-------------|
19//! | [`protocol`] | Yes | Wire format: headers, messages, message types, return codes, and service discovery (SD) entries/options |
20//! | [`e2e`] | Yes | End-to-End protection — Profile 4 (CRC-32) and Profile 5 (CRC-16) |
21//! | [`WireFormat`] / [`PayloadWireFormat`] | Yes | Traits for serializing messages and defining custom payload types |
22//! | [`client`] | No | Async tokio client — service discovery, subscriptions, and request/response (feature `client`) |
23//! | [`server`] | No | Async tokio server — service offering, event publishing, and subscription management (feature `server`) |
24//!
25//! ## Feature Flags
26//!
27//! | Feature | Default | Description |
28//! |---------|---------|-------------|
29//! | `client` | no | Async tokio client; implies `std` + tokio + socket2 |
30//! | `server` | no | Async tokio server; implies `std` + tokio + socket2 |
31//! | `std` | no | Enables std-dependent helpers |
32//!
33//! By default only the `protocol`, trait, and `e2e` modules are compiled, and the crate
34//! builds in `no_std` mode with no allocator requirement.
35//!
36//! ## Examples
37//!
38//! ### Encoding a SOME/IP-SD header (`no_std`)
39//!
40//! ```rust
41//! use simple_someip::WireFormat;
42//! use simple_someip::protocol::sd::{self, Entry, RebootFlag, ServiceEntry};
43//!
44//! // Build an SD header with a FindService entry
45//! let entries = [Entry::FindService(ServiceEntry::find(0x1234))];
46//! // A fresh process should set RebootFlag::RecentlyRebooted until its
47//! // session counter wraps past 0xFFFF for the first time.
48//! let sd_header =
49//! sd::Header::new(sd::Flags::new_sd(RebootFlag::RecentlyRebooted), &entries, &[]);
50//!
51//! // Encode to bytes
52//! let mut buf = [0u8; 64];
53//! let n = sd_header.encode(&mut buf.as_mut_slice()).unwrap();
54//!
55//! // Decode from bytes (zero-copy view)
56//! let view = sd::SdHeaderView::parse(&buf[..n]).unwrap();
57//! assert_eq!(view.entry_count(), 1);
58//! ```
59//!
60//! ### Async client (requires `feature = "client"`)
61//!
62//! ```rust,no_run
63//! # #[cfg(feature = "client")]
64//! # fn wrapper() {
65//! use simple_someip::{Client, ClientUpdate, RawPayload};
66//!
67//! #[tokio::main]
68//! async fn main() {
69//! // Client::new returns a Clone-able handle and an update stream.
70//! let (client, mut updates) = Client::<RawPayload>::new([192, 168, 1, 100].into());
71//! client.bind_discovery().await.unwrap();
72//!
73//! while let Some(update) = updates.recv().await {
74//! match update {
75//! ClientUpdate::DiscoveryUpdated(msg) => { /* SD message received */ }
76//! ClientUpdate::Unicast { message, e2e_status } => { /* unicast reply */ }
77//! ClientUpdate::SenderRebooted(addr) => { /* remote reboot */ }
78//! ClientUpdate::Error(err) => { /* error */ }
79//! }
80//! }
81//! }
82//! # }
83//! ```
84//!
85//! ## References
86//!
87//! - [Open SOME/IP Specification](https://github.com/some-ip-com/open-someip-spec)
88
89#![no_std]
90#![warn(clippy::pedantic)]
91
92#[cfg(feature = "std")]
93extern crate std;
94
95/// SOME/IP client for discovering services and exchanging messages.
96#[cfg(feature = "client")]
97pub mod client;
98/// End-to-end (E2E) protection utilities for SOME/IP payloads.
99pub mod e2e;
100/// SOME/IP protocol primitives: headers, messages, return codes, and service discovery.
101pub mod protocol;
102/// A general-purpose, heap-allocated [`PayloadWireFormat`] implementation.
103#[cfg(feature = "std")]
104mod raw_payload;
105/// SOME/IP server for offering services and handling incoming requests.
106#[cfg(feature = "server")]
107pub mod server;
108mod traits;
109#[cfg(feature = "std")]
110pub use raw_payload::{RawPayload, VecSdHeader};
111#[cfg(feature = "std")]
112pub use traits::OfferedEndpoint;
113pub use traits::{PayloadWireFormat, WireFormat};
114
115#[cfg(feature = "client")]
116pub use client::{Client, ClientUpdate, ClientUpdates, DiscoveryMessage, PendingResponse};
117pub use e2e::{E2ECheckStatus, E2EKey, E2EProfile};
118#[cfg(feature = "server")]
119pub use server::Server;