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, ServiceEntry};
43//!
44//! // Build an SD header with a FindService entry
45//! let entries = [Entry::FindService(ServiceEntry::find(0x1234))];
46//! let sd_header = sd::Header::new(sd::Flags::new_sd(false), &entries, &[]);
47//!
48//! // Encode to bytes
49//! let mut buf = [0u8; 64];
50//! let n = sd_header.encode(&mut buf.as_mut_slice()).unwrap();
51//!
52//! // Decode from bytes (zero-copy view)
53//! let view = sd::SdHeaderView::parse(&buf[..n]).unwrap();
54//! assert_eq!(view.entry_count(), 1);
55//! ```
56//!
57//! ### Async client (requires `feature = "client"`)
58//!
59//! ```rust,no_run
60//! # #[cfg(feature = "client")]
61//! # fn wrapper() {
62//! use simple_someip::{Client, ClientUpdate, RawPayload};
63//!
64//! #[tokio::main]
65//! async fn main() {
66//! // Client::new returns a Clone-able handle and an update stream.
67//! let (client, mut updates) = Client::<RawPayload>::new([192, 168, 1, 100].into());
68//! client.bind_discovery().await.unwrap();
69//!
70//! while let Some(update) = updates.recv().await {
71//! match update {
72//! ClientUpdate::DiscoveryUpdated(msg) => { /* SD message received */ }
73//! ClientUpdate::Unicast { message, e2e_status } => { /* unicast reply */ }
74//! ClientUpdate::SenderRebooted(addr) => { /* remote reboot */ }
75//! ClientUpdate::Error(err) => { /* error */ }
76//! }
77//! }
78//! }
79//! # }
80//! ```
81//!
82//! ## References
83//!
84//! - [Open SOME/IP Specification](https://github.com/some-ip-com/open-someip-spec)
85
86#![no_std]
87#![warn(clippy::pedantic)]
88
89#[cfg(feature = "std")]
90extern crate std;
91
92/// SOME/IP client for discovering services and exchanging messages.
93#[cfg(feature = "client")]
94pub mod client;
95/// End-to-end (E2E) protection utilities for SOME/IP payloads.
96pub mod e2e;
97/// SOME/IP protocol primitives: headers, messages, return codes, and service discovery.
98pub mod protocol;
99/// A general-purpose, heap-allocated [`PayloadWireFormat`] implementation.
100#[cfg(feature = "std")]
101mod raw_payload;
102/// SOME/IP server for offering services and handling incoming requests.
103#[cfg(feature = "server")]
104pub mod server;
105mod traits;
106#[cfg(feature = "std")]
107pub use raw_payload::{RawPayload, VecSdHeader};
108#[cfg(feature = "std")]
109pub use traits::OfferedEndpoint;
110pub use traits::{PayloadWireFormat, WireFormat};
111
112#[cfg(feature = "client")]
113pub use client::{Client, ClientUpdate, ClientUpdates, DiscoveryMessage, PendingResponse};
114pub use e2e::{E2ECheckStatus, E2EKey, E2EProfile};
115#[cfg(feature = "server")]
116pub use server::Server;