From e81a577f143c9ed4d9352b1e6e009602f715b5bf Mon Sep 17 00:00:00 2001 From: Ryan Summers Date: Wed, 28 Aug 2024 18:06:05 +0200 Subject: [PATCH 1/4] Preping for serial-settings release --- serial-settings/Cargo.toml | 13 +++++++++- serial-settings/README.md | 42 ++++++++++++++++++++++++++++++++ serial-settings/src/lib.rs | 49 +------------------------------------- 3 files changed, 55 insertions(+), 49 deletions(-) create mode 100644 serial-settings/README.md diff --git a/serial-settings/Cargo.toml b/serial-settings/Cargo.toml index c081b88eb..fd5a40c14 100644 --- a/serial-settings/Cargo.toml +++ b/serial-settings/Cargo.toml @@ -2,8 +2,19 @@ name = "serial-settings" version = "0.1.0" edition = "2021" +readme = "README.md" +authors = [ + "Robert Jördens ", + "Ryan Summers ", +] +description = "Persistent settings management over serial interfaces" +categories = ["embedded", "no-std", "config", "command-line-interface"] +license = "MIT OR Apache-2.0" +keywords = ["ethernet", "stm32h7", "adc", "dac", "physics"] +repository = "https://github.com/quartiq/stabilizer" -# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html +[badges] +maintenance = { status = "actively-developed" } [dependencies] miniconf = { version = "0.13", features = ["json-core", "postcard"] } diff --git a/serial-settings/README.md b/serial-settings/README.md new file mode 100644 index 000000000..66640d178 --- /dev/null +++ b/serial-settings/README.md @@ -0,0 +1,42 @@ +# Persistent Settings Management Serial Interface + +## Description +This crate provides a simple means to load, configure, and store device settings over a serial +(i.e. text-based) interface. It is ideal to be used with serial ports and terminal emulators, +and exposes a simple way to allow users to configure device operation. + +## Example +Let's assume that your settings structure looks as follows: +```rust +#[derive(miniconf::Tree, ...)] +struct Settings { + broker: String, + id: String, +} +``` + +A user would be displayed the following terminal interface: +``` + help +AVAILABLE ITEMS: + get [path] + set + store [path] + clear [path] + platform + help [ ] + +> get +Available settings: +/broker: "test" [default: "mqtt"] [not stored] +/id: "04-91-62-d2-a8-6f" [default] [not stored] +``` + +## Design +Settings are specified in a [`miniconf::TreeKey`] settings tree and are transferred over the +serial interface using JSON encoding. This means that things like strings must be encased in +qutoes. + +## Limitations +Currently, there is a hardcoded limit of 128-bytes on the settings path. This is arbitrary and +can be changed if needed. diff --git a/serial-settings/src/lib.rs b/serial-settings/src/lib.rs index d4223d348..c1e84b4f9 100644 --- a/serial-settings/src/lib.rs +++ b/serial-settings/src/lib.rs @@ -1,51 +1,4 @@ -//! Persistent Settings Management Serial Interface -//! -//! # Description -//! This crate provides a simple means to load, configure, and store device settings over a serial -//! (i.e. text-based) interface. It is ideal to be used with serial ports and terminal emulators, -//! and exposes a simple way to allow users to configure device operation. -//! -//! # Example -//! Let's assume that your settings structure looks as follows: -//! ```rust -//! #[derive(miniconf::Tree, ...)] -//! struct Settings { -//! broker: String, -//! id: String, -//! } -//! ``` -//! -//! A user would be displayed the following terminal interface: -//! ``` -//!> help -//! AVAILABLE ITEMS: -//! get [path] -//! set -//! store [path] -//! clear [path] -//! platform -//! help [ ] -//! -//! > plaform dfu -//! Reset to DFU is not supported -//! -//! > plaform service -//! Service data not available -//! -//! > get -//! Available settings: -//! /broker: "test" [default: "mqtt"] [not stored] -//! /id: "04-91-62-d2-a8-6f" [default: "04-91-62-d2-a8-6f"] [not stored] -//! ``` -//! -//! # Design -//! Settings are specified in a [`miniconf::Tree`] settings tree and are transferred over the -//! serial interface using JSON encoding. This means that things like strings must be encased in -//! qutoes. -//! -//! # Limitations -//! Currently, there is a hardcoded limit of 64-bytes on the settings path. This is arbitrary and -//! can be changed if needed. +#![doc = include_str!("../README.md")] #![no_std] use embedded_io::{ErrorType, Read, ReadReady, Write}; From 762ba38db61b53796ac87c4bb247e82df5bad512 Mon Sep 17 00:00:00 2001 From: Ryan Summers Date: Wed, 28 Aug 2024 18:09:07 +0200 Subject: [PATCH 2/4] fixing clippy --- serial-settings/src/lib.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/serial-settings/src/lib.rs b/serial-settings/src/lib.rs index c1e84b4f9..ec8147a0f 100644 --- a/serial-settings/src/lib.rs +++ b/serial-settings/src/lib.rs @@ -600,11 +600,11 @@ impl<'a, P: Platform, const Y: usize> Runner<'a, P, Y> { /// /// # Args /// * `platform` - The platform associated with the serial settings, providing the necessary - /// context and API to manage device settings. + /// context and API to manage device settings. /// * `line_buf` - A buffer used for maintaining the serial menu input line. It should be at - /// least as long as the longest user input. + /// least as long as the longest user input. /// * `serialize_buf` - A buffer used for serializing and deserializing settings. This buffer - /// needs to be at least as big as twice the biggest serialized setting plus its path. + /// needs to be at least as big as twice the biggest serialized setting plus its path. pub fn new( platform: P, line_buf: &'a mut [u8], From 74ee2e12be8296973d66fb89af4aad7f8c94cc4a Mon Sep 17 00:00:00 2001 From: Ryan Summers Date: Wed, 28 Aug 2024 18:10:10 +0200 Subject: [PATCH 3/4] fixing keywords --- serial-settings/Cargo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/serial-settings/Cargo.toml b/serial-settings/Cargo.toml index fd5a40c14..2a4ed61ad 100644 --- a/serial-settings/Cargo.toml +++ b/serial-settings/Cargo.toml @@ -10,7 +10,7 @@ authors = [ description = "Persistent settings management over serial interfaces" categories = ["embedded", "no-std", "config", "command-line-interface"] license = "MIT OR Apache-2.0" -keywords = ["ethernet", "stm32h7", "adc", "dac", "physics"] +keywords = ["serial", "settings", "cli", "management", "async"] repository = "https://github.com/quartiq/stabilizer" [badges] From 95c768c280aa3a74cd04e1b83c957b461f0b52ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20J=C3=B6rdens?= Date: Wed, 28 Aug 2024 19:28:05 +0000 Subject: [PATCH 4/4] doc links --- src/bin/dual-iir.rs | 4 ++-- src/bin/lockin.rs | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/bin/dual-iir.rs b/src/bin/dual-iir.rs index fa28ebb4a..ea566e149 100644 --- a/src/bin/dual-iir.rs +++ b/src/bin/dual-iir.rs @@ -20,11 +20,11 @@ //! application. //! //! ## Telemetry -//! Refer to [Telemetry] for information about telemetry reported by this application. +//! Refer to [stabilizer::net::telemetry::Telemetry] for information about telemetry reported by this application. //! //! ## Stream //! This application streams raw ADC and DAC data over UDP. Refer to -//! [stabilizer::net::data_stream](../stabilizer/net/data_stream/index.html) for more information. +//! [stabilizer::net::data_stream] for more information. #![no_std] #![no_main] diff --git a/src/bin/lockin.rs b/src/bin/lockin.rs index 75cef184a..3ddecd7cc 100644 --- a/src/bin/lockin.rs +++ b/src/bin/lockin.rs @@ -19,11 +19,11 @@ //! for this application. //! //! ## Telemetry -//! Refer to [Telemetry] for information about telemetry reported by this application. +//! Refer to [stabilizer::net::telemetry::Telemetry] for information about telemetry reported by this application. //! //! ## Stream //! This application streams raw ADC and DAC data over UDP. Refer to -//! [stabilizer::net::data_stream](../stabilizer/net/data_stream/index.html) for more information. +//! [stabilizer::net::data_stream] for more information. #![no_std] #![no_main]