Add StopByBrake and StopByFloat, Guarding

- BasicMotor StopByBrake and StopByFloat
- Guarding for methods whether device/hub is connected
- Fix naming of parameter

sharpbrick#8

Author: tthiery

Diff for: examples/SharpBrick.PoweredUp.Examples/ExampleMotorControl.cs

@@ -14,8 +14,8 @@ public static async Task ExecuteAsync()
                 var motor = technicMediumHub.A.GetDevice<TechnicXLargeLinearMotor>();
 
                 await motor.SetAccelerationTimeAsync(3000);
-                await motor.SetDeccelerationTimeAsync(1000);
-                await motor.StartSpeedForTimeAsync(6000, 90, 100, SpecialSpeed.Hold, SpeedProfiles.AccelerationProfile | SpeedProfiles.DeccelerationProfile);
+                await motor.SetDecelerationTimeAsync(1000);
+                await motor.StartSpeedForTimeAsync(6000, 90, 100, SpecialSpeed.Hold, SpeedProfiles.AccelerationProfile | SpeedProfiles.DecelerationProfile);
 
                 await Task.Delay(10_000);
 

Diff for: src/SharpBrick.PoweredUp/Devices/AbsoluteMotor.cs

@@ -15,6 +15,7 @@ public abstract class AbsoluteMotor : TachoMotor
 
         public AbsoluteMotor()
         { }
+
         protected AbsoluteMotor(IPoweredUpProtocol protocol, byte hubId, byte portId)
             : base(protocol, hubId, portId)
         {
@@ -23,8 +24,21 @@ protected AbsoluteMotor(IPoweredUpProtocol protocol, byte hubId, byte portId)
             ObserveOnLocalProperty(AbsolutePositionObservable, v => AbsolutePosition = v.SI, v => AbsolutePositionPct = v.Pct);
         }
 
+        /// <summary>
+        /// Start the motor with a speed of Speed using a maximum power of MaxPower and GOTO the Absolute position AbsPos. After position is reached the motor is stopped using the EndState mode of operation.
+        /// </summary>
+        /// <param name="absolutePosition">Absolute Position (0 is the position at the start of the motor)</param>
+        /// <param name="speed">The speed used to move to the absolute position.</param>
+        /// <param name="maxPower">Maximum Power level used.</param>
+        /// <param name="endState">After time has expired, either Float, Hold or Brake.</param>
+        /// <param name="profile">The speed profiles used (as flags) for acceleration and deceleration</param>
+        /// <returns></returns>
         public async Task GotoAbsolutePositionAsync(int absolutePosition, sbyte speed, byte maxPower, SpecialSpeed endState, SpeedProfiles profile)
         {
+            AssertValidSpeed(speed, nameof(speed));
+            AssertValidMaxPower(maxPower, nameof(maxPower));
+            AssertIsConnected();
+
             await _protocol.SendMessageAsync(new PortOutputCommandGotoAbsolutePositionMessage()
             {
                 HubId = _hubId,
@@ -39,8 +53,23 @@ await _protocol.SendMessageAsync(new PortOutputCommandGotoAbsolutePositionMessag
             });
         }
 
+        /// <summary>
+        /// Start the motors with individual speeds calculated from the common given Speed using a powerlevel limited to the MaxPower value. And the GOTO the Absolute positions: AbsPos1 and AbsPos2.
+        /// </summary>
+        /// <param name="absolutePosition1">Absolute Position of motor 1 (0 is the position at the start of the motor)</param>
+        /// <param name="absolutePosition2">Absolute Position of motor 2 (0 is the position at the start of the motor)</param>
+        /// <param name="speed">The speed used to move to the absolute position.</param>
+        /// <param name="maxPower">Maximum Power level used.</param>
+        /// <param name="endState">After time has expired, either Float, Hold or Brake.</param>
+        /// <param name="profile">The speed profiles used (as flags) for acceleration and deceleration</param>
+        /// <returns></returns>
         public async Task GotoAbsolutePositionAsync(int absolutePosition1, int absolutePosition2, sbyte speed, byte maxPower, SpecialSpeed endState, SpeedProfiles profile)
         {
+            AssertValidSpeed(speed, nameof(speed));
+            AssertValidMaxPower(maxPower, nameof(maxPower));
+            AssertIsConnected();
+            AssertIsVirtualPort();
+
             await _protocol.SendMessageAsync(new PortOutputCommandGotoAbsolutePosition2Message()
             {
                 HubId = _hubId,

Diff for: src/SharpBrick.PoweredUp/Devices/BasicMotor.cs

@@ -24,8 +24,20 @@ public BasicMotor(IPoweredUpProtocol protocol, byte hubId, byte portId)
             ObserveOnLocalProperty(PowerObservable, v => Power = v.SI, v => PowerPct = v.Pct);
         }
 
+        /// <summary>
+        /// Starts the motor with full speed at the given power level.
+        /// </summary>
+        /// <param name="power">
+        /// - Power levels in percentage: 1 - 100 (CW), -1 - -100 (CCW)
+        /// - Stop Motor (floating): 0 
+        /// - Stop Motor (breaking): 127
+        /// </param>
+        /// <returns>An awaitable Task.</returns>
         public async Task StartPowerAsync(sbyte power)
         {
+            AssertValidPower(power, nameof(power));
+            AssertIsConnected();
+
             await _protocol.SendMessageAsync(new PortOutputCommandStartPowerMessage()
             {
                 HubId = _hubId,
@@ -36,15 +48,61 @@ await _protocol.SendMessageAsync(new PortOutputCommandStartPowerMessage()
             });
         }
 
-        public Task StartPowerAsync(sbyte power1, sbyte power2)
-            => _protocol.SendMessageAsync(new PortOutputCommandStartPower2Message()
+        /// <summary>
+        /// Stops the motor (brake; no movement afterwards)
+        /// </summary>
+        /// <returns></returns>
+        public Task StopByBrakeAsync()
+            => StartPowerAsync((sbyte)SpecialSpeed.Brake);
+
+        /// <summary>
+        /// Stops the motor (float; freely floating by inertia)
+        /// </summary>
+        /// <returns></returns>
+        public Task StopByFloatAsync()
+            => StartPowerAsync((sbyte)SpecialSpeed.Float);
+
+        /// <summary>
+        /// Start the pair on motors with full speed on given power values.
+        /// </summary>
+        /// <param name="powerOnMotor1">
+        /// - Power levels in percentage: 1 - 100 (CW), -1 - -100 (CCW)
+        /// - Stop Motor (floating): 0 
+        /// - Stop Motor (breaking): 127
+        /// </param>
+        /// <param name="powerOnMotor2">
+        /// - Power levels in percentage: 1 - 100 (CW), -1 - -100 (CCW)
+        /// - Stop Motor (floating): 0 
+        /// - Stop Motor (breaking): 127
+        /// </param>
+        /// <returns></returns>
+        public async Task StartPowerAsync(sbyte powerOnMotor1, sbyte powerOnMotor2)
+        {
+            AssertValidPower(powerOnMotor1, nameof(powerOnMotor1));
+            AssertValidPower(powerOnMotor2, nameof(powerOnMotor2));
+            AssertIsConnected();
+            AssertIsVirtualPort();
+
+            await _protocol.SendMessageAsync(new PortOutputCommandStartPower2Message()
             {
                 HubId = _hubId,
                 PortId = _portId,
                 StartupInformation = PortOutputCommandStartupInformation.ExecuteImmediately,
                 CompletionInformation = PortOutputCommandCompletionInformation.CommandFeedback,
-                Power1 = power1,
-                Power2 = power2,
+                Power1 = powerOnMotor1,
+                Power2 = powerOnMotor2,
             });
+        }
+
+        protected void AssertValidPower(sbyte power, string argumentName)
+        {
+            if (
+                  power < -100 ||
+                  (power > 100 && power != 127)
+              )
+            {
+                throw new ArgumentOutOfRangeException(argumentName);
+            }
+        }
     }
 }

Diff for: src/SharpBrick.PoweredUp/Devices/Device.cs

@@ -77,6 +77,19 @@ await _protocol.SendMessageAsync(new PortInputFormatSetupSingleMessage()
             });
         }
 
+        protected void AssertIsConnected()
+        {
+            if (!IsConnected)
+            {
+                throw new InvalidOperationException("The device needs to be connected to a protocol.");
+            }
+        }
+
+        protected void AssertIsVirtualPort()
+        {
+            //TODO
+        }
+
         #region Disposable Pattern
         private bool disposedValue;
         protected virtual void Dispose(bool disposing)

Diff for: src/SharpBrick.PoweredUp/Devices/RgbLight.cs

@@ -19,6 +19,8 @@ public RgbLight(IPoweredUpProtocol protocol, byte hubId, byte portId)
 
         public async Task SetRgbColorNoAsync(PoweredUpColor color)
         {
+            AssertIsConnected();
+
             await _protocol.SendMessageAsync(new PortOutputCommandSetRgbColorNoMessage()
             {
                 HubId = _hubId,
@@ -30,6 +32,8 @@ await _protocol.SendMessageAsync(new PortOutputCommandSetRgbColorNoMessage()
         }
         public async Task SetRgbColorsAsync(byte red, byte green, byte blue)
         {
+            AssertIsConnected();
+
             await _protocol.SendMessageAsync(new PortInputFormatSetupSingleMessage()
             {
                 HubId = _hubId,