Update motor APIs

editor/extension.ts

@@ -29,14 +29,15 @@ namespace pxt.editor {
     let initPromise: Promise<Ev3Wrapper>
     function initAsync() {
         const forceHexDownload = /forceHexDownload/i.test(window.location.href);
-        if (!initPromise && Cloud.isLocalHost() && Cloud.localToken && !forceHexDownload)
+        if (Cloud.isLocalHost() && Cloud.localToken && !forceHexDownload) {
+            if (!initPromise)
                 initPromise = hf2Async()
                     .catch(err => {
                         initPromise = null
                         noHID = true
                         return Promise.reject(err)
                     })
-        else {
+        } else {
             noHID = true
                 initPromise = Promise.reject(new Error("no HID"))
         }

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

@@ -21,7 +21,23 @@
   "output.createBuffer": "Create a new zero-initialized buffer.",
   "output.createBuffer|param|size": "number of bytes in the buffer",
   "output.getPattern": "Pattern block.",
+  "output.getPattern|param|pattern": "the lights pattern to use. eg: LightsPattern.Green",
   "output.setLights": "Set lights.",
+  "output.setLights|param|pattern": "the lights pattern to use.",
+  "output.setPower": "Set motor power.",
+  "output.setPower|param|out": "the output connection that the motor is connected to",
+  "output.setPower|param|power": "the desired power to use. eg: 100",
+  "output.setSpeed": "Set motor speed.",
+  "output.setSpeed|param|out": "the output connection that the motor is connected to",
+  "output.setSpeed|param|speed": "the desired speed to use. eg: 100",
+  "output.start": "Turn motor on.",
+  "output.start|param|out": "the output connection that the motor is connected to",
+  "output.stop": "Turn motor off.",
+  "output.stop|param|out": "the output connection that the motor is connected to",
+  "output.turn": "Turn a motor on for a specified number of milliseconds.",
+  "output.turn|param|ms": "the number of milliseconds to turn the motor on, eg: 500",
+  "output.turn|param|out": "the output connection that the motor is connected to",
+  "output.turn|param|useBrake": "whether or not to use the brake, defaults to false",
   "screen.clear": "Clear screen and reset font to normal.",
   "screen.doubleIcon": "Double size of an icon.",
   "screen.drawIcon": "Draw an icon on the screen.",

libs/core/_locales/core-strings.json

@@ -3,7 +3,7 @@
   "ButtonEvent.Down|block": "down",
   "ButtonEvent.LongClick|block": "long click",
   "ButtonEvent.Up|block": "up",
-  "control.raiseEvent|block": "raise event|from %src|with value value",
+  "control.raiseEvent|block": "raise event|from %src|with value %value",
   "control|block": "control",
   "input.buttonDown|block": "button down",
   "input.buttonEnter|block": "button enter",
@@ -17,7 +17,12 @@
   "input.remoteTopRight|block": "remote top-right",
   "input|block": "input",
   "output.getPattern|block": "%pattern",
-  "output.setLights|block": "set lights %pattern=led_pattern",
+  "output.setLights|block": "set status light %pattern=led_pattern",
+  "output.setPower|block": "set motor %out| power to %power",
+  "output.setSpeed|block": "set motor %out| speed to %speed",
+  "output.start|block": "turn motor %out| on",
+  "output.stop|block": "turn motor %out| off",
+  "output.turn|block": "turn motor %out| on for %ms| milliseconds",
   "output|block": "output",
   "screen|block": "screen",
   "serial|block": "serial",
@@ -25,5 +30,7 @@
   "{id:category}Input": "Input",
   "{id:category}Output": "Output",
   "{id:category}Screen": "Screen",
-  "{id:category}Serial": "Serial"
+  "{id:category}Serial": "Serial",
+  "{id:group}Lights": "Lights",
+  "{id:group}Motors": "Motors"
 }

libs/core/buttons.ts

@@ -70,6 +70,7 @@ namespace input {
         //% blockGap=8
         //% parts="buttonpair"
         //% blockNamespace=input
+        //% group="Brick buttons"
         //% button.fieldEditor="gridpicker"
         //% button.fieldOptions.width=220
         //% button.fieldOptions.columns=3
@@ -86,6 +87,7 @@ namespace input {
         //% blockId=buttonWasPressed
         //% parts="buttonpair" blockGap=8
         //% blockNamespace=input advanced=true
+        //% group="Brick buttons"
         //% button.fieldEditor="gridpicker"
         //% button.fieldOptions.width=220
         //% button.fieldOptions.columns=3
@@ -105,6 +107,7 @@ namespace input {
         //% blockId=buttonEvent block="on %button|%event"
         //% parts="buttonpair"
         //% blockNamespace=input
+        //% group="Brick buttons"
         //% button.fieldEditor="gridpicker"
         //% button.fieldOptions.width=220
         //% button.fieldOptions.columns=3
@@ -215,8 +218,10 @@ namespace output {
 
     /**
      * Set lights.
+     * @param pattern the lights pattern to use.
      */
-    //% blockId=setLights block="set lights %pattern=led_pattern" 
+    //% blockId=setLights block="set status light %pattern=led_pattern"
+    //% weight=100 group="Lights"
     export function setLights(pattern: number): void {
         if (currPattern === pattern)
             return
@@ -229,6 +234,7 @@ namespace output {
 
     /**
      * Pattern block.
+     * @param pattern the lights pattern to use. eg: LightsPattern.Green
      */
     //% blockId=led_pattern block="%pattern"
     //% shim=TD_ID colorSecondary="#6e9a36"

libs/core/output.ts

@@ -42,6 +42,11 @@ namespace output {
         pwmMM.write(buf)
     }
 
+    function readPWM(buf: Buffer): void {
+        init()
+        pwmMM.read(buf);
+    }
+
     function mkCmd(out: Output, cmd: number, addSize: number) {
         let b = createBuffer(2 + addSize)
         b.setNumber(NumberFormat.UInt8LE, 0, cmd)
@@ -49,12 +54,43 @@ namespace output {
         return b
     }
 
-    export function stop(out: Output, useBreak = false) {
+    /**
+     * Turn a motor on for a specified number of milliseconds.
+     * @param out the output connection that the motor is connected to
+     * @param ms the number of milliseconds to turn the motor on, eg: 500
+     * @param useBrake whether or not to use the brake, defaults to false
+     */
+    //% blockId=output_turn block="turn motor %out| on for %ms| milliseconds"
+    //% weight=100 group="Motors"
+    export function turn(out: Output, ms: number, useBrake = false) {
+        // TODO: use current power / speed configuration
+        output.step(out, {
+            power: 100,
+            step1: 0,
+            step2: ms,
+            step3: 0,
+            useBrake: useBrake
+        })
+    }
+
+    /**
+     * Turn motor off.
+     * @param out the output connection that the motor is connected to
+     */
+    //% blockId=output_stop block="turn motor %out| off"
+    //% weight=90 group="Motors"
+    export function stop(out: Output, useBrake = false) {
         let b = mkCmd(out, DAL.opOutputStop, 1)
-        b.setNumber(NumberFormat.UInt8LE, 2, useBreak ? 1 : 0)
+        b.setNumber(NumberFormat.UInt8LE, 2, useBrake ? 1 : 0)
         writePWM(b)
     }
 
+    /**
+     * Turn motor on.
+     * @param out the output connection that the motor is connected to
+     */
+    //% blockId=output_start block="turn motor %out| on"
+    //% weight=95 group="Motors"
     export function start(out: Output) {
         let b = mkCmd(out, DAL.opOutputStart, 0)
         writePWM(b)
@@ -65,12 +101,34 @@ namespace output {
         writePWM(b)
     }
 
+    /*export function getSpeed(out: Output): number {
+        let b = mkCmd(out, DAL.opOutputSpeed, 0)
+        readPWM(b)
+        return b.getNumber(NumberFormat.Int16LE, 1)
+    }*/
+
+    /**
+     * Set motor speed.
+     * @param out the output connection that the motor is connected to
+     * @param speed the desired speed to use. eg: 100
+     */
+    //% blockId=output_setSpeed block="set motor %out| speed to %speed"
+    //% weight=81 group="Motors"
+    //% speed.min=-100 speed.max=100
     export function setSpeed(out: Output, speed: number) {
         let b = mkCmd(out, DAL.opOutputSpeed, 1)
         b.setNumber(NumberFormat.Int8LE, 2, Math.clamp(-100, 100, speed))
         writePWM(b)
     }
 
+    /**
+     * Set motor power.
+     * @param out the output connection that the motor is connected to
+     * @param power the desired power to use. eg: 100
+     */
+    //% blockId=output_setPower block="set motor %out| power to %power"
+    //% weight=80 group="Motors"
+    //% power.min=-100 power.max=100
     export function setPower(out: Output, power: number) {
         let b = mkCmd(out, DAL.opOutputPower, 1)
         b.setNumber(NumberFormat.Int8LE, 2, Math.clamp(-100, 100, power))
@@ -90,7 +148,7 @@ namespace output {
         step2: number;
         step3: number;
         useSteps?: boolean; // otherwise use milliseconds
-        useBreak?: boolean;
+        useBrake?: boolean;
     }
 
     export function step(out: Output, opts: StepOptions) {
@@ -110,7 +168,7 @@ namespace output {
         b.setNumber(NumberFormat.Int32LE, 4 + 4 * 0, opts.step1)
         b.setNumber(NumberFormat.Int32LE, 4 + 4 * 1, opts.step2)
         b.setNumber(NumberFormat.Int32LE, 4 + 4 * 2, opts.step3)
-        b.setNumber(NumberFormat.Int8LE, 4 + 4 * 3, opts.useBreak ? 1 : 0)
+        b.setNumber(NumberFormat.Int8LE, 4 + 4 * 3, opts.useBrake ? 1 : 0)
         writePWM(b)
     }
 

libs/core/shims.d.ts

@@ -51,7 +51,7 @@ declare namespace control {
      * @param mode optional definition of how the event should be processed after construction.
      */
     //% weight=21 blockGap=12 blockId="control_raise_event"
-    //% block="raise event|from %src|with value value" blockExternalInputs=1 shim=control::raiseEvent
+    //% block="raise event|from %src|with value %value" blockExternalInputs=1 shim=control::raiseEvent
     function raiseEvent(src: int32, value: int32): void;
 
     /**

libs/ev3/ns.ts

@@ -4,6 +4,7 @@ namespace input {
 }
 
 //% color="#8AC044" weight=90 icon="\uf185"
+//% groups="['Lights', 'Motors']"
 namespace output {
 }