refactor(breaking): Motor API

CHANGELOG.md

@@ -22,13 +22,39 @@ Before releasing:
 ## [Unreleased]
 
 ### Added
+- New Motor API (**Breaking Change**) (#66)
+  - Added `MotorControl` enum for controlling motor targets (#66).
+  - Added support for onboard velocity and position control in motors (#66).
+  - Added missing motor telemetry functions `velocity`, `efficiency`, `gearset`, `current_limit`.
+  - Added support for current and voltage limiting in motors.
+  - Added `Motor::raw_position` for getting raw IME ticks at a given timestamp.
+  - Added support for getting motor fault flags (e.g. over-temperature, over-current, H-bridge faults).
+  - Added support for internal motor PID tuning. Feature gated behind `dangerous_motor_tuning`, as this can cause hardware damage and is not recommended.
+  - Added various constants for convenience around `Motor` and `Gearset`.
 
 ### Fixed
 
+- `pros_sys` bindings to the Motors C API now takes the correct port type (`i8`) as of PROS 4 (**Breaking Change**) (#66).
+
 ### Changed
 
+- Refactored the Motor API (**Breaking Change**) (#66)
+  - Adjusts constructor arguments for `Motor` to allow passing `Gearset` and a direction instead of `brake_mode` at construction. (**Breaking Change**) (#66)
+  - Renamed `Motor::get_state` to `Motor::state`. (**Breaking Change**) (#66)
+  - Changed `Motor::reversed` to return `Result<bool, _>`` rather than just `false` if `PROS_ERR` is returned. (**Breaking Change**) (#66)
+  - Adjusted motor targeting to work around the `MotorControl` enum.
+  - Adjusted motor reverse flag to use `Direction` enum rather than a boolean.
+  - Motor braking is now stateless and requires an explicit method to be called to use `BrakeMode`s other than `BrakeMode::Coast`.
+  - Renamed `Motor::current_draw` to `Motor::current`.
+  - Renamed `Motor::get_state` to `Motor::status`.
+- Status structs containing device bits now use the `bitflags!` crate. (**Breaking Change**) (#66)
+- Renamed `InertialSensor::calibrating` to `InertialSensor::calibrating` (**Breaking CHange**) (#66)
+
 ### Removed
 
+- Removed `MotorStoppedFuture`, as it was broken due to hardware not returning the `stopped` flag (**Breaking Change**) (#66).
+- Removed `Motor::set_output` and `Motor::set_raw_output` in favor of `set_voltage`.
+
 ## [0.8.0]
 
 ### Added
@@ -40,6 +66,8 @@ Before releasing:
 - Added `AdiSolenoid`, a wrapper over `AdiDigitalOut` for actuating SMC pneumatic solenoids. (#61)
 - Added `AdiSwitch`, another `AdiDigitalOut` wrapper that abstracts bumper switches and limit switches. (#61)
 - Added `AdiLineTracker` for abstracting the EDR line tracker sensor.
+- Implements TryFrom for Gearset.
+- Adds support for getting brake modes from motors. (#66)
 
 ### Fixed
 

packages/pros-devices/Cargo.toml

@@ -27,6 +27,10 @@ snafu = { version = "0.8.0", default-features = false, features = [
     "unstable-core-error",
 ] }
 no_std_io = { version = "0.6.0", features = ["alloc"] }
+bitflags = "2.4.2"
 
 [lints]
 workspace = true
+
+[features]
+dangerous_motor_tuning = []

packages/pros-devices/src/smart/imu.rs

@@ -6,6 +6,7 @@ use core::{
     time::Duration,
 };
 
+use bitflags::bitflags;
 use pros_core::{
     bail_on,
     error::{take_errno, FromErrno, PortError},
@@ -56,8 +57,8 @@ impl InertialSensor {
     }
 
     /// Check if the Intertial Sensor is currently calibrating.
-    pub fn calibrating(&mut self) -> Result<bool, InertialError> {
-        Ok(self.status()?.calibrating())
+    pub fn is_calibrating(&mut self) -> Result<bool, InertialError> {
+        Ok(self.status()?.contains(InertialStatus::CALIBRATING))
     }
 
     /// Get the total number of degrees the Inertial Sensor has spun about the z-axis.
@@ -103,7 +104,11 @@ impl InertialSensor {
 
     /// Read the inertial sensor's status code.
     pub fn status(&self) -> Result<InertialStatus, InertialError> {
-        unsafe { pros_sys::imu_get_status(self.port.index()).try_into() }
+        let bits = bail_on!(pros_sys::E_IMU_STATUS_ERROR, unsafe {
+            pros_sys::imu_get_status(self.port.index())
+        });
+
+        Ok(InertialStatus::from_bits_retain(bits))
     }
 
     /// Get a quaternion representing the Inertial Sensor’s orientation.
@@ -376,22 +381,12 @@ impl TryFrom<pros_sys::imu_raw_s> for InertialRaw {
     }
 }
 
-/// Represents a status code returned by the Inertial Sensor.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct InertialStatus(pub u32);
-
-impl InertialStatus {
-    /// Determine if the sensor is currently calibrating.
-    pub const fn calibrating(&self) -> bool {
-        self.0 & pros_sys::E_IMU_STATUS_CALIBRATING != 0
-    }
-}
-
-impl TryFrom<pros_sys::imu_status_e_t> for InertialStatus {
-    type Error = InertialError;
-
-    fn try_from(value: pros_sys::imu_status_e_t) -> Result<Self, Self::Error> {
-        Ok(Self(bail_on!(pros_sys::E_IMU_STATUS_ERROR, value)))
+bitflags! {
+    /// The status bits returned by an [`InertialSensor`].
+    #[derive(Debug, Clone, Copy, Eq, PartialEq)]
+    pub struct InertialStatus: u32 {
+        /// The sensor is currently calibrating.
+        const CALIBRATING = pros_sys::E_IMU_STATUS_CALIBRATING;
     }
 }
 

packages/pros-devices/src/smart/mod.rs

@@ -30,6 +30,8 @@ pub mod optical;
 pub mod rotation;
 pub mod vision;
 
+use core::fmt;
+
 pub use distance::DistanceSensor;
 pub use expander::AdiExpander;
 pub use gps::GpsSensor;
@@ -238,3 +240,23 @@ impl From<SmartDeviceType> for pros_sys::apix::v5_device_e_t {
         value as _
     }
 }
+
+/// Represents a timestamp on a smart device's internal clock. This type offers
+/// no guarantees that the device's clock is in sync with the internal clock of
+/// the brain, and thus cannot be safely compared with [`pros_core::time::Instant`]s.
+///
+/// There is additionally no guarantee that this is in sync with other smart devices,
+/// or even the same device if a disconnect occurred causing the clock to reset. As such,
+/// this is effectively a newtype wrapper of `u32`.
+///
+/// # Precision
+///
+/// This type has a precision of 1 millisecond.
+#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct SmartDeviceTimestamp(pub u32);
+
+impl fmt::Debug for SmartDeviceTimestamp {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        self.0.fmt(f)
+    }
+}