Motors cleanup (#192)

* refactoring

* moving chassis into separate project

* added set motors

libs/chassis/README.md

@@ -0,0 +1,3 @@
+# Chassis
+
+A library to control a chassis.

libs/chassis/_locales/chassis-jsdoc-strings.json

@@ -0,0 +1,14 @@
+{
+  "chassis.Chassis": "A differential drive robot",
+  "chassis.Chassis.drive": "Makes a differential drive robot move with a given speed (cm/s) and rotation rate (deg/s)\nusing a unicycle model.",
+  "chassis.Chassis.driveFor": "Makes a differential drive robot move with a given speed (cm/s) and rotation rate (deg/s)\nusing a unicycle model.",
+  "chassis.Chassis.driveFor|param|rotationSpeed": "rotation of the robot around the center point, eg: 30",
+  "chassis.Chassis.driveFor|param|speed": "speed of the center point between motors, eg: 10",
+  "chassis.Chassis.driveFor|param|value": "the amount of movement, eg: 2",
+  "chassis.Chassis.drive|param|rotationSpeed": "rotation of the robot around the center point, eg: 30",
+  "chassis.Chassis.drive|param|speed": "speed of the center point between motors, eg: 10",
+  "chassis.Chassis.setMotors": "Sets the motors used by the chassis, default is B+C",
+  "chassis.Chassis.setProperty": "Sets a property of the robot",
+  "chassis.Chassis.setProperty|param|property": "the property to set",
+  "chassis.Chassis.setProperty|param|value": "the value to set"
+}

libs/chassis/_locales/chassis-strings.json

@@ -0,0 +1,10 @@
+{
+  "ChassisProperty.BaseLength|block": "base length (cm)",
+  "ChassisProperty.WheelRadius|block": "wheel radius (cm)",
+  "chassis.Chassis.driveFor|block": "drive %chassis|at %speed|cm/s|turning %rotationSpeed|deg/s|for %value|%unit",
+  "chassis.Chassis.drive|block": "drive %chassis|at %speed|cm/s|turning %rotationSpeed|deg/s",
+  "chassis.Chassis.setMotors|block": "set %chassis|motors to %motors",
+  "chassis.Chassis.setProperty|block": "set %chassis|%property|to %value",
+  "chassis|block": "chassis",
+  "{id:category}Chassis": "Chassis"
+}

libs/chassis/chassis.ts

@@ -0,0 +1,101 @@
+enum ChassisProperty {
+    //% block="wheel radius (cm)"
+    WheelRadius,
+    //% block="base length (cm)"
+    BaseLength
+}
+
+namespace chassis {
+    /**
+     * A differential drive robot
+     */
+    //% fixedInstances
+    export class Chassis {
+        // the motor pair
+        public motors: motors.SynchedMotorPair;
+        // the radius of the wheel (cm)
+        public wheelRadius: number;
+        // the distance between the wheels (cm)
+        public baseLength: number;
+
+        constructor() {
+            this.motors = motors.largeBC;
+            this.wheelRadius = 3;
+            this.baseLength = 12;
+        }
+
+        /**
+         * Makes a differential drive robot move with a given speed (cm/s) and rotation rate (deg/s)
+         * using a unicycle model.
+         * @param speed speed of the center point between motors, eg: 10
+         * @param rotationSpeed rotation of the robot around the center point, eg: 30
+         */
+        //% blockId=motorDrive block="drive %chassis|at %speed|cm/s|turning %rotationSpeed|deg/s"
+        //% inlineInputMode=inline
+        //% weight=99 blockGap=8
+        drive(speed: number, rotationSpeed: number) {
+            this.driveFor(speed, rotationSpeed, 0, MoveUnit.Degrees);
+        }
+
+        /**
+         * Makes a differential drive robot move with a given speed (cm/s) and rotation rate (deg/s)
+         * using a unicycle model.
+         * @param speed speed of the center point between motors, eg: 10
+         * @param rotationSpeed rotation of the robot around the center point, eg: 30
+         * @param value the amount of movement, eg: 2
+         * @param unit 
+         */
+        //% blockId=motorDriveFor block="drive %chassis|at %speed|cm/s|turning %rotationSpeed|deg/s|for %value|%unit"
+        //% inlineInputMode=inline
+        //% weight=95 blockGap=8
+        driveFor(speed: number, rotationSpeed: number, value: number, unit: MoveUnit) {
+            // speed is expressed in %
+            const R = this.wheelRadius; // cm
+            const L = this.baseLength; // cm
+            const PI = 3.14;
+            const maxw = 170 / 60 * 2 * PI; // rad / s
+            const maxv = maxw * R; // cm / s
+            // speed is cm / s
+            const v = speed; // cm / s
+            const w = rotationSpeed / 360 * 2 * PI; // rad / s
+
+            const vr = (2 * v + w * L) / (2 * R); // rad / s
+            const vl = (2 * v - w * L) / (2 * R); // rad / s
+
+            const sr = vr / maxw * 100; // % 
+            const sl = vl / maxw * 100; // %
+
+            this.motors.tankFor(sr, sl, value, unit)
+        }
+
+        /**
+         * Sets a property of the robot
+         * @param property the property to set
+         * @param value  the value to set
+         */
+        //% blockId=chassisSetProperty block="set %chassis|%property|to %value"
+        //% blockGap=8
+        //% weight=10
+        setProperty(property: ChassisProperty, value: number) {
+            switch (property) {
+                case ChassisProperty.WheelRadius:
+                    this.wheelRadius = Math.max(0.1, value); break;
+                case ChassisProperty.BaseLength:
+                    this.baseLength = Math.max(0.1, value); break;
+            }
+        }
+
+        /**
+         * Sets the motors used by the chassis, default is B+C
+         * @param motors 
+         */
+        //% blockId=chassisSetMotors block="set %chassis|motors to %motors"
+        //% weight=10
+        setMotors(motors: motors.SynchedMotorPair) {
+            this.motors = motors;
+        }
+    }
+
+    //% fixedInstance whenUsed
+    export const chassis = new Chassis();
+}

libs/chassis/pxt.json

@@ -0,0 +1,15 @@
+{
+    "name": "chassis",
+    "description": "Chassis robot support",
+    "files": [
+        "README.md",
+        "chassis.ts"
+    ],
+    "testFiles": [
+        "test.ts"
+    ],
+    "public": true,
+    "dependencies": {
+            "core": "file:../core"
+    }
+}

libs/chassis/test.ts

@@ -0,0 +1 @@
+

libs/core/_locales/core-jsdoc-strings.json

@@ -59,10 +59,6 @@
   "motors.Motor.tacho": "Gets motor tachometer count.",
   "motors.Motor.toString": "Returns the status of the motor",
   "motors.MotorBase.isReady": "Returns a value indicating if the motor is still running a previous command.",
-  "motors.MotorBase.move": "Moves the motor by a number of rotations, degress or seconds",
-  "motors.MotorBase.move|param|speed": "the speed from ``100`` full forward to ``-100`` full backward, eg: 50",
-  "motors.MotorBase.move|param|unit": "the meaning of the value",
-  "motors.MotorBase.move|param|value": "the move quantity, eg: 2",
   "motors.MotorBase.pauseUntilReady": "Pauses the execution until the previous command finished.",
   "motors.MotorBase.pauseUntilReady|param|timeOut": "optional maximum pausing time in milliseconds",
   "motors.MotorBase.reset": "Resets the motor(s).",
@@ -70,23 +66,28 @@
   "motors.MotorBase.setBrake|param|brake": "a value indicating if the motor should break when off",
   "motors.MotorBase.setReversed": "Reverses the motor polarity",
   "motors.MotorBase.setSpeed": "Sets the speed of the motor.",
+  "motors.MotorBase.setSpeedFor": "Sets the motor speed for limited time or distance",
+  "motors.MotorBase.setSpeedFor|param|speed": "the speed from ``100`` full forward to ``-100`` full backward, eg: 50",
+  "motors.MotorBase.setSpeedFor|param|unit": "the meaning of the value",
+  "motors.MotorBase.setSpeedFor|param|value": "the move quantity, eg: 2",
   "motors.MotorBase.setSpeed|param|speed": "the speed from ``100`` full forward to ``-100`` full backward, eg: 50",
   "motors.MotorBase.stop": "Stops the motor(s).",
-  "motors.SynchedMotorPair.drive": "Makes a differential drive robot move with a given speed (%) and rotation rate (deg/s)\nusing a unicycle model.",
-  "motors.SynchedMotorPair.drive|param|rotationSpeed": "rotation of the robot around the center point, eg: 30",
-  "motors.SynchedMotorPair.drive|param|speed": "speed of the center point between motors, eg: 10",
-  "motors.SynchedMotorPair.drive|param|value": "the amount of movement, eg: 2",
-  "motors.SynchedMotorPair.setDimensions": "Sets the wheels radius and base length of a directional drive robot",
-  "motors.SynchedMotorPair.setDimensions|param|wheelRadius": "@param baseLength ",
   "motors.SynchedMotorPair.steer": "Turns the motor and the follower motor by a number of rotations",
+  "motors.SynchedMotorPair.steerFor": "Turns the motor and the follower motor by a number of rotations",
+  "motors.SynchedMotorPair.steerFor|param|speed": "the speed from ``100`` full forward to ``-100`` full backward, eg: 50",
+  "motors.SynchedMotorPair.steerFor|param|turnRatio": "the ratio of power sent to the follower motor, from ``-200`` to ``200``, eg: 0",
+  "motors.SynchedMotorPair.steerFor|param|unit": "the meaning of the value",
+  "motors.SynchedMotorPair.steerFor|param|value": "the move quantity, eg: 2",
   "motors.SynchedMotorPair.steer|param|speed": "the speed from ``100`` full forward to ``-100`` full backward, eg: 50",
   "motors.SynchedMotorPair.steer|param|turnRatio": "the ratio of power sent to the follower motor, from ``-200`` to ``200``, eg: 0",
-  "motors.SynchedMotorPair.steer|param|unit": "the meaning of the value",
-  "motors.SynchedMotorPair.steer|param|value": "the move quantity, eg: 2",
   "motors.SynchedMotorPair.tank": "The Move Tank block can make a robot drive forward, backward, turn, or stop. \nUse the Move Tank block for robot vehicles that have two Large Motors, \nwith one motor driving the left side of the vehicle and the other the right side. \nYou can make the two motors go at different speeds or in different directions \nto make your robot turn.",
+  "motors.SynchedMotorPair.tankFor": "The Move Tank block can make a robot drive forward, backward, turn, or stop. \nUse the Move Tank block for robot vehicles that have two Large Motors, \nwith one motor driving the left side of the vehicle and the other the right side. \nYou can make the two motors go at different speeds or in different directions \nto make your robot turn.",
+  "motors.SynchedMotorPair.tankFor|param|speedLeft": "the speed on the left motor, eg: 50",
+  "motors.SynchedMotorPair.tankFor|param|speedRight": "the speed on the right motor, eg: 50",
+  "motors.SynchedMotorPair.tankFor|param|unit": "the unit of the value",
+  "motors.SynchedMotorPair.tankFor|param|value": "the amount of movement, eg: 2",
+  "motors.SynchedMotorPair.tank|param|speedLeft": "the speed on the left motor, eg: 50",
   "motors.SynchedMotorPair.tank|param|speedRight": "the speed on the right motor, eg: 50",
-  "motors.SynchedMotorPair.tank|param|unit": "@param speedLeft the speed on the left motor, eg: 50",
-  "motors.SynchedMotorPair.tank|param|value": "the amount of movement, eg: 2",
   "motors.SynchedMotorPair.toString": "Returns the name(s) of the motor",
   "motors.mkCmd": "Allocates a message buffer",
   "motors.mkCmd|param|addSize": "required additional bytes",

libs/core/_locales/core-strings.json

@@ -51,14 +51,15 @@
   "motors.Motor.clearCounts|block": "%motor|clear counts",
   "motors.Motor.speed|block": "%motor|speed",
   "motors.Motor.tacho|block": "%motor|tacho",
-  "motors.MotorBase.move|block": "move %motor|for %value|%unit|at %speed|%",
   "motors.MotorBase.pauseUntilReady|block": "%motor|pause until ready",
   "motors.MotorBase.setBrake|block": "set %motor|brake %brake",
   "motors.MotorBase.setReversed|block": "set %motor|reversed %reversed",
-  "motors.MotorBase.setSpeed|block": "set speed of %motor|to %speed|%",
+  "motors.MotorBase.setSpeedFor|block": "set %motor|speed to %speed|%|for %value|%unit",
-  "motors.SynchedMotorPair.drive|block": "drive %chassis|at %speed|cm/s|turning %rotationSpeed|deg/s|for %value|%unit",
+  "motors.MotorBase.setSpeed|block": "set %motor|speed to %speed|%",
-  "motors.SynchedMotorPair.steer|block": "steer %chassis turn by|%turnRatio|at speed %speed|%|for %value|%unit",
+  "motors.SynchedMotorPair.steerFor|block": "steer %chassis|turn ratio %turnRatio|speed %speed|%|for %value|%unit",
-  "motors.SynchedMotorPair.tank|block": "tank %chassis|left %speedLeft|%|right %speedRight|%|for %value|%unit",
+  "motors.SynchedMotorPair.steer|block": "steer %chassis|turn ratio %turnRatio|speed %speed|%",
+  "motors.SynchedMotorPair.tankFor|block": "tank %motors|%speedLeft|%|%speedRight|%|for %value|%unit",
+  "motors.SynchedMotorPair.tank|block": "tank %motors|%speedLeft|%|%speedRight|%",
   "motors.largeAB|block": "large A+B",
   "motors.largeAD|block": "large A+D",
   "motors.largeA|block": "large A",
@@ -88,10 +89,11 @@
   "{id:category}Screen": "Screen",
   "{id:category}Serial": "Serial",
   "{id:group}Buttons": "Buttons",
-  "{id:group}Chassis": "Chassis",
+  "{id:group}Counters": "Counters",
   "{id:group}Light": "Light",
   "{id:group}More": "More",
   "{id:group}Motion": "Motion",
   "{id:group}Screen": "Screen",
-  "{id:group}Sensors": "Sensors"
+  "{id:group}Sensors": "Sensors",
+  "{id:group}Sync Motion": "Sync Motion"
 }

libs/core/output.ts

@@ -204,7 +204,7 @@ namespace motors {
          * Sets the speed of the motor.
          * @param speed the speed from ``100`` full forward to ``-100`` full backward, eg: 50
          */
-        //% blockId=motorSetSpeed block="set speed of %motor|to %speed|%"
+        //% blockId=motorSetSpeed block="set %motor|speed to %speed|%"
         //% on.fieldEditor=toggleonoff
         //% weight=99 blockGap=8
         //% speed.min=-100 speed.max=100
@@ -219,16 +219,16 @@ namespace motors {
         }
 
         /**
-         * Moves the motor by a number of rotations, degress or seconds
+         * Sets the motor speed for limited time or distance
+         * @param speed the speed from ``100`` full forward to ``-100`` full backward, eg: 50
          * @param value the move quantity, eg: 2
          * @param unit the meaning of the value
-         * @param speed the speed from ``100`` full forward to ``-100`` full backward, eg: 50
          */
-        //% blockId=motorMove block="move %motor|for %value|%unit|at %speed|%"
+        //% blockId=motorMove block="set %motor|speed to %speed|%|for %value|%unit"
         //% weight=98 blockGap=8
         //% speed.min=-100 speed.max=100    
         //% group="Motion"
-        move(value: number, unit: MoveUnit, speed: number) {
+        setSpeedFor(speed: number, value: number, unit: MoveUnit) {
             this.init();
             speed = Math.clamp(-100, 100, speed >> 0);
             if (!speed) {
@@ -333,7 +333,7 @@ namespace motors {
         //% blockId=motorSpeed block="%motor|speed"
         //% weight=72 
         //% blockGap=8
-        //% group="Sensors"
+        //% group="Counters"
         speed(): number {
             this.init();
             return getMotorData(this._port).actualSpeed;
@@ -345,7 +345,8 @@ namespace motors {
          */
         //% blockId=motorAngle block="%motor|angle"
         //% weight=70
-        //% group="Sensors"
+        //% blockGap=8
+        //% group="Counters"
         angle(): number {
             this.init();
             return getMotorData(this._port).count;
@@ -359,7 +360,7 @@ namespace motors {
         //% blockId=motorTachoCount block="%motor|tacho"
         //% weight=69
         //% blockGap=8
-        //% group="Sensors"
+        //% group="Counters"
         tacho(): number {
             this.init();
             return getMotorData(this._port).tachoCount;
@@ -371,7 +372,7 @@ namespace motors {
         //% blockId=motorClearCount block="%motor|clear counts"
         //% weight=68
         //% blockGap=8
-        //% group="Sensors"
+        //% group="Counters"
         clearCounts() {
             this.init();
             const b = mkCmd(this._port, DAL.opOutputClearCount, 0)
@@ -418,13 +419,9 @@ namespace motors {
 
     //% fixedInstances
     export class SynchedMotorPair extends MotorBase {
-        private wheelRadius: number;
-        private baseLength: number;
 
         constructor(ports: Output) {
             super(ports, () => this.__init(), (speed) => this.__setSpeed(speed), (steps, stepsOrTime, speed) => this.__move(steps, stepsOrTime, speed));
-            this.wheelRadius = 3;
-            this.baseLength = 12;
             this.markUsed();
         }
 
@@ -460,24 +457,41 @@ namespace motors {
             });
         }
 
+
         /**
          * The Move Tank block can make a robot drive forward, backward, turn, or stop. 
          * Use the Move Tank block for robot vehicles that have two Large Motors, 
          * with one motor driving the left side of the vehicle and the other the right side. 
          * You can make the two motors go at different speeds or in different directions 
          * to make your robot turn.
-         * @param value the amount of movement, eg: 2
-         * @param unit 
          * @param speedLeft the speed on the left motor, eg: 50
          * @param speedRight the speed on the right motor, eg: 50
          */
-        //% blockId=motorPairTank block="tank %chassis|left %speedLeft|%|right %speedRight|%|for %value|%unit"
+        //% blockId=motorPairTank block="tank %motors|%speedLeft|%|%speedRight|%"
-        //% weight=9 blockGap=8
+        //% weight=20 blockGap=8
+        //% group="Sync Motion"
+        tank(speedLeft: number, speedRight: number) {
+            this.tankFor(speedLeft, speedRight, 0, MoveUnit.Degrees);
+        }
+
+        /**
+         * The Move Tank block can make a robot drive forward, backward, turn, or stop. 
+         * Use the Move Tank block for robot vehicles that have two Large Motors, 
+         * with one motor driving the left side of the vehicle and the other the right side. 
+         * You can make the two motors go at different speeds or in different directions 
+         * to make your robot turn.
+         * @param speedLeft the speed on the left motor, eg: 50
+         * @param speedRight the speed on the right motor, eg: 50
+         * @param value the amount of movement, eg: 2
+         * @param unit the unit of the value
+         */
+        //% blockId=motorPairTankFor block="tank %motors|%speedLeft|%|%speedRight|%|for %value|%unit"
+        //% weight=19
         //% speedLeft.min=-100 speedLeft=100
         //% speedRight.min=-100 speedRight=100
         //% inlineInputMode=inline
-        //% group="Chassis"
+        //% group="Sync Motion"
-        tank(speedLeft: number, speedRight: number, value: number, unit: MoveUnit) {
+        tankFor(speedLeft: number, speedRight: number, value: number, unit: MoveUnit) {
             this.init();
 
             speedLeft = Math.clamp(-100, 100, speedLeft >> 0);
@@ -487,41 +501,25 @@ namespace motors {
             const turnRatio = speedLeft == speed
                 ? (100 - speedRight / speedLeft * 100)
                 : (speedLeft / speedRight * 100 - 100);
-            this.steer(turnRatio, speed, value, unit);
+
+            this.steerFor(turnRatio, speed, value, unit);
         }
 
+        
         /**
-         * Makes a differential drive robot move with a given speed (%) and rotation rate (deg/s)
+         * Turns the motor and the follower motor by a number of rotations
-         * using a unicycle model.
+         * @param turnRatio the ratio of power sent to the follower motor, from ``-200`` to ``200``, eg: 0
-         * @param speed speed of the center point between motors, eg: 10
+         * @param speed the speed from ``100`` full forward to ``-100`` full backward, eg: 50
-         * @param rotationSpeed rotation of the robot around the center point, eg: 30
+         * @param value the move quantity, eg: 2
-         * @param value the amount of movement, eg: 2
+         * @param unit the meaning of the value
-         * @param unit 
          */
-        //% blockId=motorDrive block="drive %chassis|at %speed|cm/s|turning %rotationSpeed|deg/s|for %value|%unit"
+        //% blockId=motorPairSteer block="steer %chassis|turn ratio %turnRatio|speed %speed|%"
+        //% weight=7 blockGap=8
+        //% turnRatio.min=-200 turnRatio=200
         //% inlineInputMode=inline
-        //% group="Chassis"
+        //% group="Sync Motion"
-        //% weight=8 blockGap=8
+        steer(turnRatio: number, speed: number) {
-        drive(speed: number, rotationSpeed: number, value: number, unit: MoveUnit) {
+            this.steer(turnRatio, speed);
-            this.init();
-
-            // speed is expressed in %
-            const R = this.wheelRadius; // cm
-            const L = this.baseLength; // cm
-            const PI = 3.14;
-            const maxw = 170 / 60 * 2 * PI; // rad / s
-            const maxv = maxw * R; // cm / s
-            // speed is cm / s
-            const v = speed; // cm / s
-            const w = rotationSpeed / 360 * 2 * PI; // rad / s
-
-            const vr = (2 * v + w * L) / (2 * R); // rad / s
-            const vl = (2 * v - w * L) / (2 * R); // rad / s
-
-            const sr = vr / maxw * 100; // % 
-            const sl = vl / maxw * 100; // %
-
-            this.tank(sr, sl, value, unit)
         }
 
         /**
@@ -531,12 +529,12 @@ namespace motors {
          * @param value the move quantity, eg: 2
          * @param unit the meaning of the value
          */
-        //% blockId=motorPairTurn block="steer %chassis turn by|%turnRatio|at speed %speed|%|for %value|%unit"
+        //% blockId=motorPairSteerFor block="steer %chassis|turn ratio %turnRatio|speed %speed|%|for %value|%unit"
         //% weight=6 blockGap=8
         //% turnRatio.min=-200 turnRatio=200
         //% inlineInputMode=inline
-        //% group="Chassis"
+        //% group="Sync Motion"
-        steer(turnRatio: number, speed: number, value: number, unit: MoveUnit) {
+        steerFor(turnRatio: number, speed: number, value: number, unit: MoveUnit) {
             this.init();
             speed = Math.clamp(-100, 100, speed >> 0);
             if (!speed) {
@@ -571,17 +569,6 @@ namespace motors {
             });
         }        
 
-        /**
-         * Sets the wheels radius and base length of a directional drive robot
-         * @param wheelRadius 
-         * @param baseLength 
-         */
-        //% group="Chassis"
-        setDimensions(wheelRadius: number, baseLength: number): void {
-            this.wheelRadius = wheelRadius;
-            this.baseLength = baseLength;
-        }
-
         /**
          * Returns the name(s) of the motor
          */

libs/ev3/ns.ts

@@ -14,11 +14,16 @@ namespace sensors {
 }
 
 //% color="#A5CA18" weight=90 icon="\uf10d"
-//% groups='["Motion", "Sensors", "Chassis"]'
+//% groups='["Motion", "Counters", "Sync Motion"]'
 //% labelLineWidth=0
 namespace motors {
 }
 
+//% labelLineWidth=0
+namespace chassis {
+
+}
+
 //% labelLineWidth=0
 namespace behaviors {
 }

pxtarget.json

@@ -15,6 +15,7 @@
         "libs/ultrasonic-sensor",
         "libs/infrared-sensor",
         "libs/gyro-sensor",
+        "libs/chassis",
         "libs/ev3",
         "libs/tests",
         "libs/behaviors"