Merge pull request #944 from quartiq/feature/serial-settings-release

Preping for serial-settings release

serial-settings/Cargo.toml

@@ -2,15 +2,20 @@
 name = "serial-settings"
 version = "0.1.0"
 edition = "2021"
+readme = "README.md"
 description = "Embedded device settings management over serial terminal and flash"
 authors = [
 	"Robert Jördens <[email protected]>",
 	"Ryan Summers <[email protected]>",
 ]
-categories = ["embedded", "no-std", "hardware-support"]
+categories = ["embedded", "no-std", "config", "command-line-interface"]
 license = "MIT OR Apache-2.0"
+keywords = ["serial", "settings", "cli", "management", "async"]
 repository = "https://github.com/quartiq/stabilizer"
 
+[badges]
+maintenance = { status = "actively-developed" }
+
 [dependencies]
 miniconf = { version = "0.13", features = ["json-core", "postcard"] }
 menu = { version = "0.5", features = ["echo"] }

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 <path> <value>
+  store [path]
+  clear [path]
+  platform <cmd>
+  help [ <command> ]
+
+> 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.

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 <path> <value>
-//!   store [path]
-//!   clear [path]
-//!   platform <cmd>
-//!   help [ <command> ]
-//!
-//! > 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};

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]
 

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]