From fc0705b826cd8b3c458fbb4d512307891486dcc2 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Wed, 26 Jun 2024 17:05:07 +0200 Subject: [PATCH] more examples and documentation --- crates/servicepoint/src/command.rs | 83 ++++++++++++++++++++- crates/servicepoint/src/compression_code.rs | 13 ++++ crates/servicepoint/src/connection.rs | 9 +++ crates/servicepoint/src/data_ref.rs | 3 + crates/servicepoint/src/lib.rs | 17 +++-- 5 files changed, 116 insertions(+), 9 deletions(-) diff --git a/crates/servicepoint/src/command.rs b/crates/servicepoint/src/command.rs index 3bc63b6..d0c5891 100644 --- a/crates/servicepoint/src/command.rs +++ b/crates/servicepoint/src/command.rs @@ -15,10 +15,44 @@ pub type Offset = usize; /// The encoding is currently not enforced. pub type Cp437Grid = PrimitiveGrid; -/// A command to send to the display. +/// A low-level display command. +/// +/// This struct and associated functions implement the UDP protocol for the display. +/// +/// To send a `Command`, use a `Connection`. +/// +/// # Examples +/// +/// ```rust +/// # use servicepoint::{Brightness, Command, Connection, Packet}; +/// +/// // create command +/// let command = Command::Brightness(Brightness::MAX); +/// +/// // turn command into Packet +/// let packet: Packet = command.clone().into(); +/// +/// // read command from packet +/// let round_tripped = Command::try_from(packet).unwrap(); +/// +/// // round tripping produces exact copy +/// assert_eq!(command, round_tripped); +/// +/// // send command +/// # let connection = Connection::open("127.0.0.1:2342").unwrap(); +/// connection.send(command).unwrap(); +/// ``` #[derive(Debug, Clone, PartialEq)] pub enum Command { /// Set all pixels to the off state. Does not affect brightness. + /// + /// # Examples + /// + /// ```rust + /// # use servicepoint::{Command, Connection}; + /// # let connection = Connection::open("127.0.0.1:2342").unwrap(); + /// connection.send(Command::Clear).unwrap(); + /// ``` Clear, /// Show text on the screen. @@ -27,12 +61,31 @@ pub enum Command { /// The library does not currently convert between UTF-8 and CP-437. /// Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now. /// + /// + /// # Examples + /// + /// ```rust + /// # use servicepoint::{Command, Connection, Cp437Grid, Origin}; + /// # let connection = Connection::open("127.0.0.1:2342").unwrap(); + /// let chars = ['H', 'e', 'l', 'l', 'o', 'W', 'o', 'r', 'l', 'd'].map(move |c| c as u8); + /// let grid = Cp437Grid::load(5, 2, &chars); + /// connection.send(Command::Cp437Data(Origin::new(2, 2), grid)).unwrap(); + /// ``` Cp437Data(Origin, Cp437Grid), /// Sets a window of pixels to the specified values BitmapLinearWin(Origin, PixelGrid, CompressionCode), /// Set the brightness of all tiles to the same value. + /// + /// # Examples + /// + /// ```rust + /// # use servicepoint::{Brightness, Command, Connection}; + /// # let connection = Connection::open("127.0.0.1:2342").unwrap(); + /// let command = Command::Brightness(Brightness::MAX); + /// connection.send(command).unwrap(); + /// ``` Brightness(Brightness), /// Set the brightness of individual tiles in a rectangular area of the display. @@ -73,17 +126,43 @@ pub enum Command { /// Kills the udp daemon on the display, which usually results in a restart. /// /// Please do not send this in your normal program flow. + /// + /// # Examples + /// + /// ```rust + /// # use servicepoint::{Command, Connection}; + /// # let connection = Connection::open("127.0.0.1:2342").unwrap(); + /// connection.send(Command::HardReset).unwrap(); + /// ``` HardReset, ///
Untested
/// /// Slowly decrease brightness until off or something like that? + /// + /// # Examples + /// + /// ```rust + /// # use servicepoint::{Command, Connection}; + /// # let connection = Connection::open("127.0.0.1:2342").unwrap(); + /// connection.send(Command::FadeOut).unwrap(); + /// ``` FadeOut, - #[deprecated] /// Legacy command code, gets ignored by the real display. /// /// Might be useful as a noop package. + /// + /// # Examples + /// + /// ```rust + /// # use servicepoint::{Command, Connection}; + /// # let connection = Connection::open("127.0.0.1:2342").unwrap(); + /// // this sends a packet that does nothing + /// # #[allow(deprecated)] + /// connection.send(Command::BitmapLegacy).unwrap(); + /// ``` + #[deprecated] BitmapLegacy, } diff --git a/crates/servicepoint/src/compression_code.rs b/crates/servicepoint/src/compression_code.rs index 44bed3c..0440c4e 100644 --- a/crates/servicepoint/src/compression_code.rs +++ b/crates/servicepoint/src/compression_code.rs @@ -1,4 +1,17 @@ /// Specifies the kind of compression to use. Availability depends on features. +/// +/// # Examples +/// +/// ```rust +/// # use servicepoint::{Command, CompressionCode, Origin, PixelGrid}; +/// // create command without payload compression +/// # let pixels = PixelGrid::max_sized(); +/// _ = Command::BitmapLinearWin(Origin::new(0, 0), pixels, CompressionCode::Uncompressed); +/// +/// // create command with payload compressed with lzma and appropriate header flags +/// # let pixels = PixelGrid::max_sized(); +/// _ = Command::BitmapLinearWin(Origin::new(0, 0), pixels, CompressionCode::Lzma); +/// ``` #[repr(u16)] #[derive(Debug, Clone, Copy, PartialEq)] pub enum CompressionCode { diff --git a/crates/servicepoint/src/connection.rs b/crates/servicepoint/src/connection.rs index d4fa1d5..d18d76b 100644 --- a/crates/servicepoint/src/connection.rs +++ b/crates/servicepoint/src/connection.rs @@ -6,6 +6,15 @@ use log::{debug, info}; use crate::Packet; /// A connection to the display. +/// +/// # Examples +/// ```rust +/// # use servicepoint::Command; +/// let connection = servicepoint::Connection::open("172.23.42.29:2342") +/// .expect("connection failed"); +/// connection.send(Command::Clear) +/// .expect("send failed"); +/// ``` pub struct Connection { socket: UdpSocket, } diff --git a/crates/servicepoint/src/data_ref.rs b/crates/servicepoint/src/data_ref.rs index 94a40b0..b8ff624 100644 --- a/crates/servicepoint/src/data_ref.rs +++ b/crates/servicepoint/src/data_ref.rs @@ -4,6 +4,9 @@ /// metadata needed. pub trait DataRef { /// Get the underlying bytes writable. + /// + /// Note that depending on the struct this is implemented on, writing invalid values here might + /// lead to panics later in the lifetime of the program or on the receiving side. fn data_ref_mut(&mut self) -> &mut [T]; /// Get the underlying bytes read-only. diff --git a/crates/servicepoint/src/lib.rs b/crates/servicepoint/src/lib.rs index 10c5207..d71e1fa 100644 --- a/crates/servicepoint/src/lib.rs +++ b/crates/servicepoint/src/lib.rs @@ -5,13 +5,17 @@ //! ```rust //! use servicepoint::{Command, CompressionCode, Grid, PixelGrid}; //! -//! let connection = servicepoint::Connection::open("172.23.42.29:2342") +//! let connection = servicepoint::Connection::open("127.0.0.1:2342") //! .expect("connection failed"); //! //! // turn off all pixels on display //! connection.send(Command::Clear) //! .expect("send failed"); +//! ``` //! +//! ```rust +//! # use servicepoint::{Command, CompressionCode, Grid, PixelGrid}; +//! # let connection = servicepoint::Connection::open("127.0.0.1:2342").expect("connection failed"); //! // turn on all pixels in a grid //! let mut pixels = PixelGrid::max_sized(); //! pixels.fill(true); @@ -24,8 +28,7 @@ //! ); //! //! // send command to display -//! connection.send(command) -//! .expect("send failed"); +//! connection.send(command).expect("send failed"); //! ``` use std::time::Duration; @@ -73,7 +76,7 @@ pub const TILE_SIZE: usize = 8; pub const TILE_WIDTH: usize = 56; /// Display tile count in the y-direction -/// +/// /// # Examples /// /// ```rust @@ -83,7 +86,7 @@ pub const TILE_WIDTH: usize = 56; pub const TILE_HEIGHT: usize = 20; /// Display width in pixels -/// +/// /// # Examples /// /// ```rust @@ -121,8 +124,8 @@ pub const PIXEL_COUNT: usize = PIXEL_WIDTH * PIXEL_HEIGHT; /// // Change pixels here /// /// connection.send(Command::BitmapLinearWin( -/// Origin::new(0,0), -/// pixels, +/// Origin::new(0,0), +/// pixels, /// CompressionCode::Lzma /// )) /// .expect("send failed");