Pull request

drivers/drmem-drv-weather-wu/README.md

@@ -17,7 +17,7 @@ These are the configuration parameters for an instance of the driver.
 - `interval` is the number of minutes between each update. If a
   personal key isn't specified, the interval can't be less than 10
   minutes. If this parameter isn't provided, 10 minutes is used.
-- `units` can be either "metric" or "imperial" and determines how the
+- `units` can be either "Metric" or "English" and determines how the
   device data is scaled (i.e. Celsius or Fahrenheit, etc.)
 
 ## Devices

drivers/drmem-drv-weather-wu/src/lib.rs

@@ -263,19 +263,11 @@ impl Instance {
             };
 
         if let Some(dewpt) = dewpt {
-            if (0.0..=200.0).contains(&dewpt) {
-                devices.dewpt.report_update(dewpt).await
-            } else {
-                warn!("ignoring bad dew point value: {:.1}", dewpt)
-            }
+            devices.dewpt.report_update(dewpt).await
         }
 
         if let Some(htidx) = htidx {
-            if (0.0..=200.0).contains(&htidx) {
-                devices.htidx.report_update(htidx).await
-            } else {
-                warn!("ignoring bad heat index value: {:.1}", htidx)
-            }
+            devices.htidx.report_update(htidx).await
         }
 
         if let (Some(prate), Some(ptotal)) = (prate, ptotal) {

drmem-api/src/driver/classes/dimmer_type.rs

@@ -17,7 +17,7 @@
 //! ```
 
 use crate::driver::{
-    ro_device::ReadOnlyDevice, shared_rw_device::SharedReadWriteDevice,
+    overridable_device::OverridableDevice, ro_device::ReadOnlyDevice,
     DriverConfig, Registrator, RequestChan, Result,
 };
 use tokio::time::Duration;
@@ -29,10 +29,10 @@ pub struct Dimmer {
     pub error: ReadOnlyDevice<bool>,
     /// Controls the brightness setting of the dimmer. Off is 0.0 and
     /// full-on is 100.0.
-    pub brightness: SharedReadWriteDevice<f64>,
+    pub brightness: OverridableDevice<f64>,
     /// A product might include an indicator. If the hardware does,
     /// this device can turn it on and off.
-    pub indicator: SharedReadWriteDevice<bool>,
+    pub indicator: OverridableDevice<bool>,
 }
 
 impl Registrator for Dimmer {
@@ -45,15 +45,15 @@ impl Registrator for Dimmer {
         Ok(Dimmer {
             error: drc.add_ro_device("error", None, max_history).await?,
             brightness: drc
-                .add_shared_rw_device(
+                .add_overridable_device(
                     "brightness",
                     Some("%"),
                     override_timeout,
                     max_history,
                 )
                 .await?,
             indicator: drc
-                .add_shared_rw_device(
+                .add_overridable_device(
                     "indicator",
                     None,
                     override_timeout,

drmem-api/src/driver/classes/switch_type.rs

@@ -17,7 +17,7 @@
 //! ```
 
 use crate::driver::{
-    ro_device::ReadOnlyDevice, shared_rw_device::SharedReadWriteDevice,
+    overridable_device::OverridableDevice, ro_device::ReadOnlyDevice,
     DriverConfig, Registrator, RequestChan, Result,
 };
 use tokio::time::Duration;
@@ -29,10 +29,10 @@ pub struct Switch {
     pub error: ReadOnlyDevice<bool>,
     /// Indicates the state of the switch. Writing `true` or `false`
     /// turns the switch on and off, respectively.
-    pub state: SharedReadWriteDevice<bool>,
+    pub state: OverridableDevice<bool>,
     /// A product might include an indicator. If the hardware does,
     /// this device can turn it on and off.
-    pub indicator: SharedReadWriteDevice<bool>,
+    pub indicator: OverridableDevice<bool>,
 }
 
 impl Registrator for Switch {
@@ -45,15 +45,15 @@ impl Registrator for Switch {
         Ok(Switch {
             error: drc.add_ro_device("error", None, max_history).await?,
             state: drc
-                .add_shared_rw_device(
+                .add_overridable_device(
                     "state",
                     None,
                     override_timeout,
                     max_history,
                 )
                 .await?,
             indicator: drc
-                .add_shared_rw_device(
+                .add_overridable_device(
                     "indicator",
                     None,
                     override_timeout,

drmem-api/src/driver/mod.rs

@@ -18,17 +18,17 @@ pub type Name = Arc<str>;
 
 pub mod classes;
 mod config;
+mod overridable_device;
 mod ro_device;
 mod rw_device;
-mod shared_rw_device;
 
 pub use config::DriverConfig;
+pub use overridable_device::OverridableDevice;
 pub use ro_device::{ReadOnlyDevice, ReportReading};
 pub use rw_device::{
     ReadWriteDevice, RxDeviceSetting, SettingRequest, SettingResponder,
     TxDeviceSetting,
 };
-pub use shared_rw_device::SharedReadWriteDevice;
 
 /// Defines the requests that can be sent to core. Drivers don't use
 /// this type directly. They are indirectly used by `RequestChan`.
@@ -233,13 +233,13 @@ impl RequestChan {
     /// `InternalError`, then the core has exited and the
     /// `RequestChan` has been closed. Since the driver can't report
     /// any more updates or accept new settings, it may as well shutdown.
-    pub async fn add_shared_rw_device<T, N>(
+    pub async fn add_overridable_device<T, N>(
         &self,
         name: N,
         units: Option<&str>,
         override_duration: Option<Duration>,
         max_history: Option<usize>,
-    ) -> Result<SharedReadWriteDevice<T>>
+    ) -> Result<OverridableDevice<T>>
     where
         T: device::ReadWriteCompat,
         N: TryInto<Base>,
@@ -263,7 +263,7 @@ impl RequestChan {
         if result.is_ok() {
             if let Ok(v) = rx.await {
                 return v.map(|(rr, rs, prev)| {
-                    SharedReadWriteDevice::new(
+                    OverridableDevice::new(
                         rr,
                         rs,
                         prev.and_then(|v| T::try_from(v).ok()),
@@ -291,6 +291,43 @@ pub trait ResettableState {
 /// The only function in this trait is one to register the device(s)
 /// with core and return the set of handles.
 pub trait Registrator: ResettableState + Sized + Send {
+    /// Before a driver is run, the set of devices it uses needs to be
+    /// registered. The structure that holds the registered device
+    /// channels should implement this trait.
+    ///
+    /// `drc` is a communication channel with which the driver makes
+    /// requests to the core. Its typical use is to register devices
+    /// with the framework, which is usually done in this method. As
+    /// other request types are added, they can be used while the
+    /// driver is running.
+    ///
+    /// `cfg` holds the configuration parameters for the instance of
+    /// the driver. This parameter is also passed to the driver's
+    /// `create_instance` method where it is more useful. Since the
+    /// purpose of this trait is to register devices, the other useful
+    /// configuration paramters would be ones that manipulate the
+    /// names of devices. This method should not use this parameter to
+    /// set up resouces (like sockets) for the driver instance.
+    ///
+    /// `override_timeout` is used to set how long a device can be
+    /// overridden. Some drivers control devices that can also be
+    /// controlled by other means than DrMem. When those devices
+    /// recognize they've been controlled externally, they go into
+    /// "override" mode in which settings are remembered but not
+    /// forwarded to the hardware. When override mode is entered, a
+    /// timer is set to expire at which the devices are again
+    /// controlled by DrMem .
+    ///
+    /// `max_history` is specified in the configuration file. It is a
+    /// hint as to the maximum number of data point to save for each
+    /// of the devices created by this driver. A backend can choose to
+    /// interpret this in its own way. For instance, the simple
+    /// backend can only ever save one data point. Redis will take
+    /// this as a hint and will choose the most efficient way to prune
+    /// the history. That means, if more than the limit is present,
+    /// redis won't prune the history to less than the limit. However
+    /// there may be more than the limit -- it just won't grow without
+    /// bound.
     fn register_devices<'a>(
         drc: &'a mut RequestChan,
         cfg: &'a DriverConfig,
@@ -316,23 +353,6 @@ pub trait API: Send + Sync {
     /// validate the parameters and convert them into forms useful to
     /// the driver. By convention, if any errors are found in the
     /// configuration, this method should return `Error::BadConfig`.
-    ///
-    /// `drc` is a communication channel with which the driver makes
-    /// requests to the core. Its typical use is to register devices
-    /// with the framework, which is usually done in this method. As
-    /// other request types are added, they can be used while the
-    /// driver is running.
-    ///
-    /// `max_history` is specified in the configuration file. It is a
-    /// hint as to the maximum number of data point to save for each
-    /// of the devices created by this driver. A backend can choose to
-    /// interpret this in its own way. For instance, the simple
-    /// backend can only ever save one data point. Redis will take
-    /// this as a hint and will choose the most efficient way to prune
-    /// the history. That means, if more than the limit is present,
-    /// redis won't prune the history to less than the limit. However
-    /// there may be more than the limit -- it just won't grow without
-    /// bound.
     fn create_instance(
         cfg: &DriverConfig,
     ) -> impl Future<Output = Result<Box<Self>>> + Send;

drmem-api/src/driver/shared_rw_device.rs → drmem-api/src/driver/overridable_device.rs

@@ -5,7 +5,7 @@
 /// users outside of DrMem. LED WiFi light bulbs are one, obvious
 /// example. For devices that can be controlled outside of DrMem, we
 /// need a way to cooperatively control them. That's what
-/// `SharedReadWriteDevice`s do.
+/// `OverridableDevice`s do.
 ///
 /// A driver that uses this type of device must do these steps in
 /// their main loop:
@@ -16,8 +16,8 @@
 /// - after setting the hardware to a new value, a poll should
 ///   immediately be done followed by a `.report_update()`
 ///
-/// `SharedReadWriteDevice`s implement a simple state machine to know
-/// how to handle incoming incoming settings.
+/// `OverridableDevice`s implement a simple state machine to know how
+/// to handle incoming incoming settings.
 use crate::{
     device,
     driver::{rw_device, ReportReading, RxDeviceSetting, SettingResponder},
@@ -62,14 +62,14 @@ enum State<T: device::ReadWriteCompat> {
     },
 }
 
-pub struct SharedReadWriteDevice<T: device::ReadWriteCompat> {
+pub struct OverridableDevice<T: device::ReadWriteCompat> {
     state: State<T>,
     override_duration: Option<tokio::time::Duration>,
     report_chan: ReportReading,
     set_stream: rw_device::SettingStream<T>,
 }
 
-impl<T> SharedReadWriteDevice<T>
+impl<T> OverridableDevice<T>
 where
     T: device::ReadWriteCompat,
 {
@@ -79,7 +79,7 @@ where
         desired_value: Option<T>,
         override_duration: Option<tokio::time::Duration>,
     ) -> Self {
-        SharedReadWriteDevice {
+        OverridableDevice {
             state: desired_value
                 .map(|value| State::SettingTrans {
                     value: (value, None),
@@ -453,7 +453,7 @@ where
     }
 }
 
-impl<T> super::ResettableState for SharedReadWriteDevice<T>
+impl<T> super::ResettableState for OverridableDevice<T>
 where
     T: device::ReadWriteCompat,
 {
@@ -476,23 +476,23 @@ mod tests {
         time::{timeout, Duration},
     };
 
-    // Helper function that creates a `SharedReadWriteDevice`.
+    // Helper function that creates a `OverridableDevice`.
 
     fn mk_device<T: device::ReadWriteCompat>(
         init: Option<T>,
         tmo: Option<Duration>,
     ) -> (
         TxDeviceSetting,
         mpsc::Receiver<device::Value>,
-        SharedReadWriteDevice<T>,
+        OverridableDevice<T>,
     ) {
         let (rrtx, rrrx) = mpsc::channel(20);
         let (srtx, srrx) = mpsc::channel(20);
 
         (
             srtx,
             rrrx,
-            SharedReadWriteDevice::new(
+            OverridableDevice::new(
                 Box::new(move |v| {
                     let rrtx = rrtx.clone();