Merge pull request #13 from de-vri-es/refactor

Refactor CanFrame API and some more things.

can-socket/CHANGELOG

@@ -1,4 +1,6 @@
 # Unreleased
+- [change][major] Refactor `CanFrame` API.
+- [change][major] Rename CAN ID structs and values.
 - [add][minor] Add `id!()`, `base_id!()` and `extended_id!()` macros to construct compile time checked CAN IDs.
 
 # Version 0.1.6 - 2024-10-23

can-socket/Cargo.toml

@@ -1,18 +1,22 @@
 [package]
 name = "can-socket"
-description = "no frills CAN sockets (blocking or async with tokio)"
+description = "no frills CAN sockets (synchronous or async with tokio)"
 version = "0.1.6"
 license = "BSD-2-Clause"
 keywords = ["CAN", "SocketCAN", "socket", "CANbus", "network"]
 categories = ["os", "hardware-support", "network-programming", "science::robotics"]
-repository = "https://github.com/de-vri-es/can-socket-rs/tree/main/can-socket"
+repository = "https://github.com/de-vri-es/can-socket-rs"
 documentation = "https://docs.rs/can-socket"
+readme = "README.md"
 
 edition = "2021"
 publish = ["crates-io"]
 
 [features]
 ignore-vcan-tests = []
+tokio = ["dep:tokio"]
+doc = ["tokio", "tokio?/test-util"]
+doc-cfg = []
 
 [dependencies]
 filedesc = "0.6.3"
@@ -24,5 +28,8 @@ assert2 = "0.3.14"
 can-socket = { path = ".", features = ["tokio"] }
 clap = { version = "4.4.4", features = ["derive"] }
 rand = "0.8.5"
-tokio = { version = "1.32.0", features = ["macros", "rt-multi-thread"] }
+tokio = { version = "1.32.0", features = ["macros", "rt-multi-thread", "test-util"] }
 trybuild = { version = "1.0.101", features = ["diff"] }
+
+[package.metadata.docs.rs]
+features = ["doc", "doc-cfg"]

can-socket/README.md

@@ -0,0 +1,21 @@
+CAN socket
+
+This library exposes a [`CanSocket`] and related types,
+allowing you to communicate over a Controller Area Network (CAN) bus.
+
+The is a standard blocking or non-blocking [`CanSocket`],
+and an asynchronous [`tokio::CanSocket`].
+
+This library uses the `SocketCAN` interface and only works on Linux.
+
+Supported features:
+* Bind sockets to specific interfaces by name or index.
+* Bind sockets to *all* CAN interfaces at the same time.
+* Send and receive data frames and RTR frames.
+* Send and receive standard frames and extended frames.
+* Setting per-socket filters.
+* Control over the `loopback` and `recv_own_msgs` options.
+* Constructing compile-time checked CAN IDs.
+
+[`CanSocket`]: https://docs.rs/can-socket/latest/can_socket/struct.CanSocket.html
+[`tokio::CanSocket`]: https://docs.rs/can-socket/latest/can_socket/tokio/struct.CanSocket.html

can-socket/README.tpl

@@ -0,0 +1,4 @@
+{{readme}}
+
+[`CanSocket`]: https://docs.rs/can-socket/latest/can_socket/struct.CanSocket.html
+[`tokio::CanSocket`]: https://docs.rs/can-socket/latest/can_socket/tokio/struct.CanSocket.html

can-socket/examples/write-tokio.rs

@@ -17,14 +17,6 @@ struct Options {
 	#[clap(long)]
 	rtr: Option<u8>,
 
-	/// The data length code to send.
-	///
-	/// May only be specified for messages of size 8,
-	/// and may only be a value from 9 to 15 (inclusive).
-	#[clap(long)]
-	#[clap(conflicts_with = "rtr")]
-	data_length_code: Option<u8>,
-
 	/// Number of times to send the frame.
 	///
 	/// Will keep sending forever if you specify 0.
@@ -47,10 +39,11 @@ async fn main() {
 
 async fn do_main(options: Options) -> Result<(), ()> {
 	let frame = if let Some(len) = options.rtr {
-		CanFrame::new_rtr(options.id, len)
+		CanFrame::new_rtr(options.id)
+			.with_data_length_code(len)
 			.map_err(|e| eprintln!("Invalid input: {e}"))?
 	} else {
-		CanFrame::new(options.id, &options.data, options.data_length_code)
+		CanFrame::try_new(options.id, &options.data)
 			.map_err(|e| eprintln!("Invalid input: {e}"))?
 	};
 

can-socket/examples/write.rs

@@ -16,14 +16,6 @@ struct Options {
 	#[clap(long)]
 	rtr: Option<u8>,
 
-	/// The data length code to send.
-	///
-	/// May only be specified for messages of size 8,
-	/// and may only be a value from 9 to 15 (inclusive).
-	#[clap(long)]
-	#[clap(conflicts_with = "rtr")]
-	data_length_code: Option<u8>,
-
 	/// Number of times to send the frame.
 	///
 	/// Will keep sending forever if you specify 0.
@@ -45,10 +37,11 @@ fn main() {
 
 fn do_main(options: Options) -> Result<(), ()> {
 	let frame = if let Some(len) = options.rtr {
-		CanFrame::new_rtr(options.id, len)
+		CanFrame::new_rtr(options.id)
+			.with_data_length_code(len)
 			.map_err(|e| eprintln!("Invalid input: {e}"))?
 	} else {
-		CanFrame::new(options.id, &options.data, options.data_length_code)
+		CanFrame::try_new(options.id, &options.data)
 			.map_err(|e| eprintln!("Invalid input: {e}"))?
 	};