Device IDs

examples/device-metadata/README.md

@@ -5,7 +5,6 @@
 This application prints all that a device knows
 about the device and the running program
 at startup to the debug console.
-It needs to be run within a debug session.
 
 ## How to run
 

examples/device-metadata/laze.yml

@@ -3,3 +3,5 @@ apps:
     selects:
       - ?release
       - sw/threading
+    depends:
+      - debug-console

src/riot-rs-embassy-common/src/identity.rs

@@ -1,29 +1,29 @@
 //! Tools and traits for describing device identities.
 //!
-//! See `riot_rs::identity` for general documentation.
+//! See `riot_rs::identity` for general documentation; that module also represents the public parts
+//! of this API.
 #![deny(missing_docs)]
 
-/// Trait describing the unique identifier available on a board.
+/// Trait describing the unique identifier available on a device.
 ///
 /// See the module level documentation on the characteristics of the identifier.
 ///
 /// # Evolution
 ///
-/// In its current state, this type is mainly a wrapper around a binary identifier with a
-/// length constant at build time.
+/// In its current state, this type is mainly a wrapper around a binary identifier.
 ///
 /// As it is used more, additional methods can be provided for concrete types of identifiers, such
 /// as MAC addresses. By default, those would be generated in some way from what is available in
-/// the identifier -- but boards where the identifier already *is* a MAC address (or possibly a
+/// the identifier -- but devices where the identifier already *is* a MAC address (or possibly a
 /// range thereof) can provide their official addresses.
 pub trait DeviceId: Sized {
     /// Some `[u8; N]` type, returned by [`.bytes()`][Self::bytes].
     ///
-    /// This may not represent all the identifying information available on the board, but can
+    /// This may not represent all the identifying information available on the device, but can
     /// represent a unique portion thereof.
     ///
     /// (For example, if a device has two consecutive MAC addresses assigned, the type as a whole
-    /// may represent both, but the conventional serialized identity of the board may just be one
+    /// may represent both, but the conventional serialized identity of the device may just be one
     /// of them).
     ///
     /// # Evolution
@@ -35,9 +35,6 @@ pub trait DeviceId: Sized {
 
     /// Obtains a unique identifier of the device.
     ///
-    /// For callers, there is the convenience function `riot_rs::identity::device_identity()`
-    /// available, which just calls this trait method on `riot_rs::arch::identity::DeviceId`.
-    ///
     /// # Errors
     ///
     /// This produces an error if no device ID is available on this board, or is not implemented.
@@ -74,25 +71,25 @@ impl<E: core::error::Error + Default> DeviceId for NoDeviceId<E> {
     }
 }
 
-/// Error indicating that a [`DeviceId`] may be available on this platform, but is not implemented.
+/// Error indicating that a [`DeviceId`] may be available on this device, but is not implemented.
 #[derive(Debug, Default)]
 pub struct NotImplemented;
 
 impl core::fmt::Display for NotImplemented {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
-        f.write_str("Device ID not implemented on this platform")
+        f.write_str("Device ID not implemented on this device")
     }
 }
 
 impl core::error::Error for NotImplemented {}
 
-/// Error indicating that a [`DeviceId`] is not available on this platform.
+/// Error indicating that a [`DeviceId`] is not available on this device.
 #[derive(Debug, Default)]
 pub struct NotAvailable;
 
 impl core::fmt::Display for NotAvailable {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
-        f.write_str("Device ID not available on this platform")
+        f.write_str("Device ID not available on this device")
     }
 }
 

src/riot-rs/src/identity.rs

@@ -11,19 +11,20 @@
 //! * The scope of the identifier is within a RIOT-rs board. Their scope may be broader, eg. when
 //!   a identifier is unique per MCU family, or even globally.
 //!
-//! * Identifiers do not change during regular development with a board, which includes the use of
+//! * Identifiers do not change during regular development with a device, which includes the use of
 //!   a programmer. Identifiers may change under deliberate conditions, eg. when a device has a
 //!   one-time programmable identity, or when there is a custom functionality to overwrite the
 //!   built-in identifier that is not triggered by the device erase that is performed as part of
 //!   programming the device.
 //!
-//! Constructing an identifier fails rather than producing a dummy identifier.
+//! Constructing an identifier fails rather than produce a dummy identifier.
 //!
-//! It is considered a breaking change in a board or this module if a board's identifier changes or
-//! becomes an error as result of an update to RIOT-rs. Errors changing to valid identifiers is a
-//! compatible change.
+//! It is considered a breaking change in RIOT-rs if a a device's identifier changes or becomes an
+//! error. Errors changing to valid identifiers is a compatible change.
 
 /// Obtains a unique identifier of the device in its byte serialized form.
+///
+/// See module level documentation for that identifier's properties.
 pub fn device_id_bytes() -> Result<impl AsRef<[u8]>, impl core::error::Error> {
     use riot_rs_embassy_common::identity::DeviceId;