split into hardware dependent / independent

gem-remotes-lib/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "gem-remotes-lib"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+anyhow = "1.0.86"
+async-channel = "2.3.1"
+log = "0.4.22"
+strum = "0.26.3"
+strum_macros = "0.26.4"

gem-remotes-lib/src/commands.rs

@@ -0,0 +1,62 @@
+/// An enum of all commands passed into and out of the microcontroller
+
+use strum_macros::EnumCount as EnumCountMacro;
+use std::mem::discriminant;
+use std::sync::Arc;
+
+#[derive(Clone, EnumCountMacro, Debug)]
+pub enum Commands {
+    // Use Arc for any data larger than 4 bytes, to keep message passing queue size down.
+
+    // Inputs sent from the PIC microcontroller
+    // TODO: move these to buttons driver, for eventual move to ESP only?
+
+    // PIC button commands are considered "remote" due to the delay in sending notification
+    PicRecvUp {data: Button},
+    PicRecvDown {data: Button},
+    PicRecvStop {data: Button},
+    PicRecvLimitUp {data: Button},   // 0 for not hit, 1 for hit
+    PicRecvLimitDown {data: Button}, // 0 for not hit, 1 for hit
+    PicRecvAutoMode {data: Button},  // 0 for disallowed, 1 for allowed
+
+    // TODO: real hardware buttons - consider re-sending occasionally when pressed, so that transitions like holding up -> stopping -> holding down -> stopped -> (should go down but gets no new notice) work.
+
+    // Inputs from bluetooth
+    BluetoothUp {data: Button}, //TODO change these to real button states and change them on input.
+    BluetoothDown {data: Button},
+    BluetoothStop {data: Button}, // There is no state where releasing the stop button induces a change.
+    BluetoothName {data: Arc<String>},
+    //TODO: Allow auto mode to be set via bluetooth as well
+
+    // Internal messages
+    StopTimerExpired, // Sent when the 2 second stop sequence is complete
+    StopTimerRestart,
+    StopTimerClear,
+    ButtonTimerExpired, // TODO: these won't be necessary for  hardware buttons; rename to PIC timer?
+    ButtonTimerRestart,
+    ButtonTimerClear,
+    PairTimerExpired,
+    AllowPairing, // Also serves as the timer restart command
+    PairTimerClear,
+
+    NotifyMotorUp {data: Button},
+    NotifyMotorDown {data: Button},
+    NotifyMotorStop {data: Button},
+
+    EraseBleBonds,
+}
+
+#[derive(Copy, Clone, Debug)]
+pub enum Button {
+    Released = 0,
+    Pressed =1
+}
+
+pub type CmdType = std::mem::Discriminant<Commands>;
+
+/// Consider commands equal if they have the same command type, but different values
+impl PartialEq for Commands {
+    fn eq(&self, other: &Self) -> bool {
+        discriminant(self) == discriminant(other)
+    }
+}

gem-remotes-lib/src/dispatch.rs

@@ -0,0 +1,78 @@
+/// Acts as a queue multiplexer.  Accepts messages from entities that have taken an endpoint, and 
+/// broadcasts them to any entity that has subscribed for them.
+
+
+use std::mem::discriminant;
+use std::collections::HashMap;
+use std::vec::Vec;
+use async_channel::{unbounded, Receiver, Sender};
+use strum::EnumCount;
+
+use crate::commands::{Commands, CmdType};
+use log::*; //{trace, debug, info, warn, error}
+
+pub type DispatchSendQ = Sender<Commands>;
+pub type DispatchRecvQ = Receiver<Commands>;
+
+//TODO: Making this generic over a <C> for commands would make it a useful small event handler.
+
+pub struct Dispatch {
+    callbacks: HashMap<CmdType, Vec<DispatchSendQ> >,
+    recv: DispatchRecvQ, // Channel to listen to incomming commands
+    endpoint: DispatchSendQ, // Endpoint to clone to hand to other modules, so that they can send commands
+}
+
+impl Dispatch {
+    pub fn new() -> Dispatch {
+        let (s, r) = unbounded(); //This should always be unbounded, because some callbacks have to send_blocking to it, and if the thread blocks, other tasks can't empty the queue!
+        let mut hmap = HashMap::new();
+        hmap.reserve(Commands::COUNT);
+        Dispatch { callbacks: hmap, recv: r, endpoint: s}
+    }
+
+    /// Get a channel receiver that will get callbacks for all commands in the listen_for vec.
+    pub fn get_callback_channel(&mut self, listen_for: &Vec<Commands>) -> DispatchRecvQ {
+        let (send, rec) = unbounded(); // TODO: these could be bounded instead, as these calls are all non-blocking.
+        for cmd in listen_for {
+            let callback_list = self.callbacks.get_mut(&discriminant(&cmd));
+            match callback_list {
+                Some(callback) => {
+                    callback.push(send.clone());
+                    trace!("Adding {:?} to callbacks", cmd);
+                }
+                None => {
+                    let mut callback = Vec::new();
+                    callback.push(send.clone());
+                    self.callbacks.insert(discriminant(&cmd), callback);
+                    trace!("Created {:?} callback", cmd);
+                }
+            }
+        }
+        rec
+    }
+
+    /// Get a channel sender that will send commands to this dispatcher
+    pub fn get_cmd_channel(&self) -> DispatchSendQ {
+        self.endpoint.clone()
+    }
+
+    /// Wait on incomming commands and dispatch them
+    pub async fn cmd_loop(&self) -> anyhow::Result<()> {
+        loop {
+            debug!("Dispatch waiting on commands");
+            let cmd = self.recv.recv().await.expect("Incoming event queue failed unexpectedly");
+            debug!("Dispatch got command {:?}", cmd);
+            let cmd_type = discriminant(&cmd);
+            let found_listeners = self.callbacks.get(&cmd_type);
+            match found_listeners {
+                Some(listeners) => {
+                    for listener in listeners {
+                        trace!("Sending cmd {:?}", cmd);
+                        listener.send(cmd.clone()).await.expect("Outgoing event queue failed unexpectedly");
+                    }
+                }
+                None => {debug!("Dispatch found no listeners for a command")}
+            }
+        }
+    }
+}

gem-remotes-lib/src/lib.rs

@@ -0,0 +1,45 @@
+
+/// Business logic (independent of hardware) for Gem Remotes ESP32 controller
+
+// Modules in this crate
+pub mod commands;
+pub mod dispatch;
+pub mod motor_controller;
+
+// Re-published items
+pub use commands::{
+    Button, 
+    Commands
+};
+pub use motor_controller::{
+    AutoMode,
+    Controller,
+    LimitState,
+    MotorCommands,
+    MotorRecvQ,
+    MotorSendQ,
+};
+pub use dispatch::{
+    Dispatch,
+    DispatchSendQ,
+    DispatchRecvQ,
+};
+
+
+
+// Test Code for whole module
+
+pub fn add(left: u64, right: u64) -> u64 {
+    left + right
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn it_works() {
+        let result = add(2, 2);
+        assert_eq!(result, 4);
+    }
+}

gem-remotes-lib/src/motor_controller.rs

@@ -0,0 +1,445 @@
+/// State machine of the motor's current state, that takes as inputs
+/// command messages.
+
+use log::*; //{trace, debug, info, warn, error}
+use anyhow::Result;
+use async_channel::{Receiver, Sender};
+use crate::commands::{Commands, Button};
+use crate::dispatch::{Dispatch, DispatchRecvQ, DispatchSendQ};
+
+// The main internal state of the controller, representing the current control method of the motors.
+#[derive(Clone, Copy, Debug, PartialEq)]
+enum ControllerStates {
+    Stopped,
+    Stopping,
+    GoingUp,
+    AutoUp,
+    GoingDown,
+    AutoDown,
+}
+
+
+#[derive(Clone, Copy, Debug)]
+pub enum MotorCommands {
+    StartUp,
+    StartDown,
+    Stop
+}
+
+pub type MotorSendQ = Sender<MotorCommands>;
+pub type MotorRecvQ = Receiver<MotorCommands>;
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum AutoMode {
+    Disallowed = 0,
+    Allowed = 1,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum LimitState {
+    NoLimitsHit,
+    UpperHit,
+    LowerHit,
+    BothHit,
+}
+
+pub struct Controller {
+    state: ControllerStates,
+    recv: DispatchRecvQ,
+    send: DispatchSendQ,
+    motor_q: MotorSendQ,
+    auto_mode: AutoMode,
+    limit_state: LimitState,
+}
+
+impl Controller {
+    pub fn new(recv: DispatchRecvQ, send: DispatchSendQ, motor_q: MotorSendQ) -> Self {
+        Controller {
+            state: ControllerStates::Stopping,
+            recv: recv,
+            send: send,
+            motor_q: motor_q,
+            auto_mode: AutoMode::Disallowed,  // Use safe default
+            limit_state: LimitState::BothHit, // Use safe default
+        }
+    }
+
+    /// Tell the message dispatch which messages we are interested in receiving, and get
+    /// a callback channel that receives those messages.
+    pub fn prepare_controller(dp: &mut Dispatch) -> DispatchRecvQ {
+        let cmds = vec![
+            Commands::PicRecvUp{data: Button::Released},
+            Commands::PicRecvDown{data: Button::Released},
+            Commands::PicRecvStop{data: Button::Released},
+            Commands::BluetoothUp{data: Button::Released},
+            Commands::BluetoothDown{data: Button::Released},
+            Commands::BluetoothStop{data: Button::Released},
+            Commands::PicRecvLimitUp{data: Button::Released},
+            Commands::PicRecvLimitDown{data: Button::Released},
+            Commands::PicRecvAutoMode{data: Button::Released},
+            Commands::StopTimerExpired,
+            Commands::ButtonTimerExpired,
+        ];
+        dp.get_callback_channel(&cmds)
+    }
+
+    async fn enter_state(&mut self, new_s: &ControllerStates) -> Result<()> {
+        match new_s {
+            ControllerStates::Stopped => {
+                // Other notify commands are sent directly from the motor controller
+                self.send.send(Commands::NotifyMotorStop{data: Button::Released}).await?;
+            }
+            ControllerStates::Stopping => {
+                self.send.send(Commands::StopTimerRestart).await?;
+                self.motor_q.send(MotorCommands::Stop).await?;
+                self.send.send(Commands::NotifyMotorStop{data: Button::Pressed}).await?;
+            }
+            ControllerStates::GoingUp => {
+                self.send.send(Commands::ButtonTimerRestart).await?;
+                self.motor_q.send(MotorCommands::StartUp).await?;
+                self.send.send(Commands::NotifyMotorUp{data: Button::Pressed}).await?;
+            }
+            ControllerStates::AutoUp => {
+                self.motor_q.send(MotorCommands::StartUp).await?;
+                self.send.send(Commands::NotifyMotorUp{data: Button::Pressed}).await?;
+            }
+            ControllerStates::GoingDown => {
+                self.send.send(Commands::ButtonTimerRestart).await?;
+                self.motor_q.send(MotorCommands::StartDown).await?;
+                self.send.send(Commands::NotifyMotorUp{data: Button::Pressed}).await?;
+            }
+            ControllerStates::AutoDown => {
+                self.motor_q.send(MotorCommands::StartDown).await?;
+                self.send.send(Commands::NotifyMotorUp{data: Button::Pressed}).await?;
+            }
+        }
+        Ok(())
+    }
+
+    async fn exit_state(&mut self, old_s: &ControllerStates) -> Result <()> {
+        match old_s {
+            ControllerStates::Stopped => {}
+            ControllerStates::Stopping => {
+                self.send.send(Commands::StopTimerClear).await?;
+            }
+            ControllerStates::GoingUp => {
+                self.send.send(Commands::ButtonTimerClear).await?;
+                self.send.send(Commands::NotifyMotorUp{data: Button::Released}).await?;
+            }
+            ControllerStates::AutoUp => {
+                self.send.send(Commands::NotifyMotorUp{data: Button::Released}).await?;
+            }
+            ControllerStates::GoingDown => {
+                self.send.send(Commands::ButtonTimerClear).await?;
+                self.send.send(Commands::NotifyMotorDown{data: Button::Released}).await?;
+            }
+            ControllerStates::AutoDown => {
+                self.send.send(Commands::NotifyMotorDown{data: Button::Released}).await?;
+            }
+        }
+        Ok(())
+    }
+
+    fn change_state_if_released(&self, data: &Button, new_state: ControllerStates) -> ControllerStates {
+        match data {
+            Button::Released => {new_state}
+            Button::Pressed => {self.state.clone()}
+        }
+    }
+
+    fn change_state_if_pressed(&self, data: &Button, new_state: ControllerStates) -> ControllerStates {
+        match data {
+            Button::Released => {self.state.clone()}
+            Button::Pressed => {new_state}
+        }
+    }
+
+    /// Determines the state the controller should be in based on the command received.
+    async fn handle_cmd(&mut self, cmd: &Commands) -> ControllerStates {
+        match cmd {
+            Commands::PicRecvUp { data } | Commands::BluetoothUp { data }=> {
+                match self.state {
+                    ControllerStates::Stopped => {return self.change_state_if_pressed(data, self.remote_up_or_auto_up())}
+                    ControllerStates::Stopping => {}
+                    ControllerStates::GoingUp => {
+                        self.send.send(Commands::ButtonTimerRestart).await.expect("Failed to necessary timer");
+                        return self.change_state_if_released(data, ControllerStates::Stopping)
+                    }
+                    ControllerStates::AutoUp => {} // Don't stop auto on button release
+                    ControllerStates::GoingDown | 
+                    ControllerStates::AutoDown => {
+                        return self.change_state_if_pressed(data, ControllerStates::Stopping)
+                    }
+                }
+            }
+            Commands::PicRecvDown { data } | Commands::BluetoothDown { data } => {
+                match self.state {
+                    ControllerStates::Stopped => {return self.change_state_if_pressed(data, self.remote_down_or_auto_down())}
+                    ControllerStates::Stopping => {}
+                    ControllerStates::GoingUp | 
+                    ControllerStates::AutoUp => {
+                        return self.change_state_if_pressed(data, ControllerStates::Stopping)
+                    }
+                    ControllerStates::GoingDown => {
+                        self.send.send(Commands::ButtonTimerRestart).await.expect("Failed to necessary timer");
+                        return self.change_state_if_released(data, ControllerStates::Stopping)
+                    }
+                    ControllerStates::AutoDown => {}
+                }
+            }
+            Commands::PicRecvStop { data } | Commands::BluetoothStop { data } => {
+                match self.state {
+                    ControllerStates::Stopped => {}
+                    ControllerStates::Stopping => {}
+                    ControllerStates::GoingUp |
+                    ControllerStates::AutoUp | 
+                    ControllerStates::GoingDown |
+                    ControllerStates::AutoDown => {
+                        return self.change_state_if_pressed(data, ControllerStates::Stopping)
+                    }
+                }
+            }
+            Commands::PicRecvLimitUp { data } => {
+                self.adjust_limit(LimitState::UpperHit, data);
+                match self.state {
+                    ControllerStates::Stopped => {} // Ignore; this could just be our initial notification on startup.
+                    ControllerStates::Stopping => {}
+                    ControllerStates::GoingUp | 
+                    ControllerStates::AutoUp=> {
+                        released_warning(data, "Limit switches may be installed incorrectly!");
+                        return self.change_state_if_pressed(data, ControllerStates::Stopping)
+                    }
+                    ControllerStates::GoingDown | 
+                    ControllerStates::AutoDown=> {
+                        pressed_warning(data, "Limit switches may be installed incorrectly!");
+                        // Stop out of an abundance of caution.  We should not get a limit press, even if it's the wrong one.
+                        return self.change_state_if_pressed(data, ControllerStates::Stopping)
+                    } 
+                }
+            }
+            Commands::PicRecvLimitDown { data } => {
+                self.adjust_limit(LimitState::LowerHit, data);
+                match self.state {
+                    ControllerStates::Stopped => {} // Ignore; this could just be our initial notification on startup.
+                    ControllerStates::Stopping => {}
+                    ControllerStates::GoingUp |
+                    ControllerStates::AutoUp => {
+                        pressed_warning(data, "Limit switches may be installed incorrectly!");
+                        // Stop out of an abundance of caution.  We should not get a limit press, even if it's the wrong one.
+                        return self.change_state_if_pressed(data, ControllerStates::Stopping)
+                    }
+                    ControllerStates::GoingDown |
+                    ControllerStates::AutoDown => {
+                        released_warning(data, "Limit switches may be installed incorrectly!");
+                        return self.change_state_if_pressed(data, ControllerStates::Stopping)
+                    }
+                }
+            }
+            Commands::PicRecvAutoMode { data } => {self.set_auto(data);}
+            Commands::StopTimerExpired => {
+                match self.state {
+                    ControllerStates::Stopped => {}
+                    ControllerStates::Stopping => {return ControllerStates::Stopped}
+                    ControllerStates::GoingUp |
+                    ControllerStates::AutoUp |
+                    ControllerStates::GoingDown |
+                    ControllerStates::AutoDown => {
+                        warn!("Stop timer returned in an inappropriate state! {:?}", self.state)
+                    }
+                }
+            }
+            Commands::ButtonTimerExpired => {
+                match self.state {
+                    ControllerStates::Stopped => {}
+                    ControllerStates::Stopping => {}
+                    ControllerStates::GoingUp => {return ControllerStates::Stopping}
+                    ControllerStates::AutoUp => {}
+                    ControllerStates::GoingDown => {return ControllerStates::Stopping}
+                    ControllerStates::AutoDown => {}
+                }
+            }
+            // Commands we should ignore (not using _ because we want to ensure all commands are accounted for!)
+            Commands::StopTimerRestart | 
+            Commands::StopTimerClear | 
+            Commands::ButtonTimerRestart |
+            Commands::ButtonTimerClear |
+            Commands::PairTimerClear |
+            Commands::PairTimerExpired |
+            Commands::AllowPairing |
+            Commands::EraseBleBonds => {
+                warn!("Unexpected command received by motor controller") // TODO: internal "us" error.
+            }
+            Commands::NotifyMotorDown { data } |
+            Commands::NotifyMotorStop { data } |
+            Commands::NotifyMotorUp { data } => {
+                warn!("Unexpected command received by motor controller {:?}", data) // TODO: internal "us" error.
+            }
+            Commands::BluetoothName { data } => {
+                warn!("Unexpected command received by motor controller {:?}", data) // TODO: internal "us" error.
+            }
+        }
+        self.state.clone() // Don't transition by default
+    }
+
+    async fn transition_state(&mut self, old_s: &ControllerStates, new_s: &ControllerStates) -> Result<()> {
+        if old_s != new_s {
+            self.exit_state(&old_s).await?;
+            self.enter_state(&new_s).await?;
+        }
+        self.state = new_s.clone();
+        Ok(())
+    }
+
+    pub async fn run(&mut self) -> Result<()> {
+        // On entry, assume initial stopping state
+        debug!("Setting motor controller initial state to stopping");
+        self.state = ControllerStates::Stopping;
+        self.enter_state(&ControllerStates::Stopping).await?;
+        loop {
+            let cmd = self.recv.recv().await.expect("Motor controller command queue unexpectedly failed");
+            trace!("Got command {:?}",cmd);
+            let new_s = self.handle_cmd(&cmd).await;
+            trace!("State current {:?} new {:?}", self.state, new_s);
+            self.transition_state(&self.state.clone(), &new_s).await.expect("Unexpected state change failure in motor controller");
+        }
+    }
+
+    fn remote_up_or_auto_up(&self) -> ControllerStates {
+        self.up_or_auto_up(ControllerStates::GoingUp)
+    }
+
+    fn up_or_auto_up(&self, up: ControllerStates) -> ControllerStates {
+        // Assume that checking the limit against the direction has already been performed.
+        match self.auto_mode {
+            AutoMode::Disallowed => {
+                up // TODO: this allows manual buttons to override limits as long as "auto" mode is off.
+            }
+            AutoMode::Allowed => {
+                match self.limit_state {
+                    LimitState::NoLimitsHit | LimitState::LowerHit=> {
+                        ControllerStates::AutoUp
+                    }
+                    LimitState::UpperHit => {
+                        ControllerStates::Stopping // Failsafe as we are already at our upper limit. TODO: maybe should be manual up?
+                    }
+                    LimitState::BothHit => {
+                        up
+                    }
+                }
+            }
+        }
+    }
+
+    fn remote_down_or_auto_down(&self) -> ControllerStates {
+        self.down_or_auto_down(ControllerStates::GoingDown)
+    }
+
+    fn down_or_auto_down(&self, down: ControllerStates) -> ControllerStates {
+        // Assume that checking the limit against the direction has already been performed.
+        match self.auto_mode {
+            AutoMode::Disallowed => {
+                down // TODO: this allows manual buttons to override limits as long as "auto" mode is off.
+            }
+            AutoMode::Allowed => {
+                match self.limit_state {
+                    LimitState::NoLimitsHit | LimitState::LowerHit=> {
+                        ControllerStates::AutoDown
+                    }
+                    LimitState::UpperHit => {
+                        ControllerStates::Stopping // Failsafe as we are already at our upper limit. TODO: Maybe should be manual down?
+                    }
+                    LimitState::BothHit => {
+                        down
+                    }
+                }
+            }
+        }
+    }
+
+    fn set_auto(&mut self, data: &Button) {
+        match data {
+            Button::Released => {
+                self.auto_mode = AutoMode::Disallowed;
+            }
+            Button::Pressed => {
+                if self.limit_state == LimitState::BothHit {
+                    warn!("Limit switches not detected.  Aborting auto  mode.");
+                } else {
+                    self.auto_mode = AutoMode::Allowed;
+                }
+            }
+        }
+    }
+
+    fn adjust_limit(&mut self, limit: LimitState, pressed: &Button) {
+        match pressed {
+            Button::Released => {
+                match limit {
+                    LimitState::NoLimitsHit => {
+                        unreachable!("There is no way to press NoLimits")
+                    }
+                    LimitState::LowerHit => {
+                        match self.limit_state {
+                            LimitState::NoLimitsHit |
+                            LimitState::UpperHit => {warn!("removed limit we never hit {:?}", LimitState::LowerHit);} //TODO intenral error
+                            LimitState::LowerHit => {self.limit_state = LimitState::NoLimitsHit;}
+                            LimitState::BothHit => {self.limit_state = LimitState::UpperHit;}
+                        }
+                    }
+                    LimitState::UpperHit => {
+                        match self.limit_state {
+                            LimitState::NoLimitsHit |
+                            LimitState::LowerHit => {warn!("removed limit we never hit {:?}", LimitState::UpperHit);} //TODO intenral error
+                            LimitState::UpperHit => {self.limit_state = LimitState::NoLimitsHit;}
+                            LimitState::BothHit => {self.limit_state = LimitState::LowerHit;}
+                        }
+                    }
+                    LimitState::BothHit => {
+                        unreachable!("There is no way to press BothHit")
+                    }
+                }
+            }
+            Button::Pressed => {
+                match limit {
+                    LimitState::NoLimitsHit => {
+                        unreachable!("There is no way to press BothHit")
+                    }
+                    LimitState::LowerHit => {
+                        match self.limit_state {
+                            LimitState::NoLimitsHit => {self.limit_state = LimitState::LowerHit;}
+                            LimitState::LowerHit => {}
+                            LimitState::UpperHit => {self.limit_state = LimitState::BothHit;}
+                            LimitState::BothHit => {}
+                        }
+                    }
+                    LimitState::UpperHit => {
+                        match self.limit_state {
+                            LimitState::NoLimitsHit => {self.limit_state = LimitState::UpperHit;}
+                            LimitState::LowerHit => {self.limit_state = LimitState::BothHit;}
+                            LimitState::UpperHit => {}
+                            LimitState::BothHit => {}
+                        }
+                    }
+                    LimitState::BothHit => {
+                        unreachable!("There is no way to press BothHit")
+                    }
+                }
+            }
+        }
+    }
+
+}
+
+fn pressed_warning(data: &Button, warn: &str) {
+    match data {
+        Button::Pressed => {warn!("{}", warn);} // TODO: user warning, not intenral
+        Button::Released => {}
+    }
+}
+
+fn released_warning(data: &Button, warn: &str) {
+    match data {
+        Button::Released => {warn!("{}", warn);} // TODO: user warning, not intenral
+        Button::Pressed => {}
+    }
+}