0.2.128

cmds/cmds.ts

@@ -1,8 +1,8 @@
 /// <reference path="../node_modules/pxt-core/built/pxt.d.ts"/>
 
-import * as fs from 'fs';
-import * as path from 'path';
-import * as child_process from 'child_process';
+import * as fs from "fs";
+import * as path from "path";
+import * as child_process from "child_process";
 
 let writeFileAsync: any = Promise.promisify(fs.writeFile)
 let execAsync: (cmd: string, options?: { cwd?: string }) => Promise<Buffer> = Promise.promisify(child_process.exec)
@@ -13,10 +13,10 @@ export function deployCoreAsync(res: ts.pxt.CompileResult) {
             if (drives.length == 0) {
                 console.log("cannot find any drives to deploy to")
             } else {
-                console.log("copy microbit.hex to " + drives.join(", "))
+                console.log(`copy ${ts.pxt.BINARY_HEX} to ` + drives.join(", "))
             }
             return Promise.map(drives, d =>
-                writeFileAsync(d + "microbit.hex", res.outfiles["microbit.hex"])
+                writeFileAsync(d + ts.pxt.BINARY_HEX, res.outfiles[ts.pxt.BINARY_HEX])
                     .then(() => {
                         console.log("wrote hex file to " + d)
                     }))

docs/reference/basic/clear-screen.md

@@ -8,7 +8,7 @@ basic.clearScreen()
 
 ### Example: vanishing heart
 
-The following code displays a heart on the screen and then turns off all the LED lights using `clear screen`:
+The following code shows a heart on the screen and then turns off all the LED lights using `clear screen`:
 
 ```blocks
 basic.showLeds(`

docs/reference/basic/forever.md

@@ -1,6 +1,7 @@
 # Forever
 
-Repeat code [in the background](/reference/control/in-background) forever.
+Keep running part of a program 
+[in the background](/reference/control/in-background).
 
 ```sig
 basic.forever(() => {
@@ -9,7 +10,9 @@ basic.forever(() => {
 
 ### Example: compass
 
-The following example constantly checks the [compass heading](/reference/input/compass-heading) and updates the screen with the direction.
+The following example constantly checks the 
+[compass heading](/reference/input/compass-heading) 
+and updates the screen with the direction.
 
 ```blocks
 basic.forever(() => {
@@ -30,7 +33,9 @@ basic.forever(() => {
 
 ### Example: counter
 
-The following example continually shows the current value of a global variable:
+The following example keeps showing the [number](/reference/types/number) stored in a global variable.
+When you press button `A`, the number gets bigger.
+You can use a program like this to count things with your BBC micro:bit.
 
 ```blocks
 let num = 0
@@ -42,9 +47,12 @@ input.onButtonPressed(Button.A, () => {
 })
 ```
 
-### Contention for the LED display
+### Competing for the LED screen
 
-If you have multiple processes that each show something on the LED screen, you may get unexpected results. Try, for example:
+If different parts of a program are each trying 
+to show something on the LED screen at the same time, 
+you may get unexpected results.
+Try this on your micro:bit:
 
 ```blocks
 basic.forever(() => {

docs/reference/basic/pause.md

@@ -1,6 +1,7 @@
 # Pause
 
-Pause program execution for the specified number of milliseconds. This function is helpful when you need to slow down your program's execution.
+Pause the program for the number of milliseconds you say. 
+You can use this function to slow your program down.
 
 ```sig
 basic.pause(400)
@@ -8,11 +9,13 @@ basic.pause(400)
 
 ### Parameters
 
-* ``ms`` - the number of milliseconds that you want to pause (100 = 1/10 second, 1000 milliseconds = 1 second)
+* ``ms`` is the number of milliseconds that you want to pause (100 milliseconds = 1/10 second, and 1000 milliseconds = 1 second).
 
 ### Example: diagonal line
 
-The following example code turns on LED `0, 0` thru `4, 4`, pausing 500 milliseconds after each LED. Without `pause`, the code would run so fast that you wouldn't see each individual LED turning on.
+This example draws a diagonal line by turning on LED `0, 0` (top left) through LED `4, 4` (bottom right). 
+The program pauses 500 milliseconds after turning on each LED. 
+Without `pause`, the program would run so fast that you would not have time to see each LED turning on.
 
 ```blocks
 for (let i = 0; i < 5; i++) {

docs/reference/input/button-is-pressed.md

@@ -1,6 +1,6 @@
 # Button Is Pressed
 
-Get the state of an input button. The micro:bit has two input buttons: A and B.
+Check whether a button is pressed right now. The micro:bit has two buttons: button `A` and button `B`.
 
 ```sig
 input.buttonIsPressed(Button.A);
@@ -8,24 +8,26 @@ input.buttonIsPressed(Button.A);
 
 ### Parameters
 
-* name - [String](/reference/types/string); input button "A", "B", or "A+B" (both input buttons)
+* ``name`` is a [String](/reference/types/string). You should store `A` in it to check the left button, `B` to check the right button, or `A+B` to check both at the same time.
 
 ### Returns
 
-* [Boolean](/reference/types/boolean) - `true` if pressed, `false` if not pressed
+* [Boolean](/reference/types/boolean) that is `true` if the button you are checking is pressed, `false` if it is not pressed.
 
 ### Example
 
-The following code uses an [if](/reference/logic/if) statement to run code, depending on whether or not the A button is pressed:
+This program uses an [if](/reference/logic/if) to run 
+one part of the program if the `A` button is pressed, and 
+another part if it is not pressed.
 
 ```blocks
 basic.forever(() => {
     let pressed = input.buttonIsPressed(Button.A)
     if (pressed) {
-        // this code runs if the A button is pressed
+        // this part runs if the A button is pressed
         basic.showNumber(1, 150)
     } else {
-        // this code runs if the A button is *not* pressed
+        // this part runs if the A button is *not* pressed
         basic.showNumber(0, 150)
     }
 })

docs/reference/input/light-level.md

@@ -1,8 +1,14 @@
 # Light Level
 
-Gets the light level from ``0`` (dark) to ``255`` (bright). The light is measured by using various LEDs from the screen.
+Find the light level (how bright or dark it is) where you are.
+The light level ``0`` means darkness and ``255`` means bright light. 
+The BBC micro:bit measures the light around it by using some of the
+LEDs on the [LED screen](/device/screen).
 
-This function will return ``0`` on the first call to this method, a light reading will be available after the display has activated the light sensor for the first time.
+The first time you use it, this function will say ``0``.
+After that, it will say the real light level.
+This is because the light sensor (the part that can find the light level)
+has to be turned on first.
 
 ```sig
 input.lightLevel();
@@ -10,11 +16,26 @@ input.lightLevel();
 
 ### Returns
 
-* [Number](/reference/types/number) -  light level from ``0`` (dark) to ``255`` (bright).
+* a [Number](/reference/types/number) that means a light level from ``0`` (dark) to ``255`` (bright).
+
+### Example: show light level
+
+When you press button `B` on the microbit, this
+program shows the light level
+on the [LED screen](/device/screen).
+
+```blocks
+input.onButtonPressed(Button.B, () => {
+    let level = input.lightLevel()
+    basic.showNumber(level)
+})
+```
 
 ### Example: chart light level
 
-Use `plot bar chart` to visual the influence of various light source on the light level.
+This program shows the light level with a [bar chart](/reference/led/plot-bar-graph) on the micro:bit screen.
+If you carry the micro:bit around to different places with different light levels,
+the bar chart will change.
 
 ```blocks
 basic.forever(() => {

docs/reference/input/on-button-pressed.md

@@ -1,6 +1,9 @@
 # On Button Pressed
 
-Register an [event handler](/reference/event-handler) that will execute whenever an input button (A, B, or A and B together) is pressed during program execution. When [running code](/device/simulator) with this function in a web browser, click an on-screen input button - labelled A or B.
+Start an [event handler](/reference/event-handler) (part of the program that will run when something happens, like when a button is pressed). 
+This handler works when button `A` or `B` is pressed, or `A` and `B` together.
+When you are using this function in a web browser, click the buttons on the screen instead of the ones
+on the BBC micro:bit.
 
 ```sig
 input.onButtonPressed(Button.A, () => {})
@@ -8,7 +11,8 @@ input.onButtonPressed(Button.A, () => {})
 
 ### Example: count button clicks
 
-This example counts how many times the left or right input button is pressed. Each time a button is pressed, the global count variable is increased by 1 and displayed on the screen.
+This example counts how many times you press the `A` button. 
+Each time you press the button, the [LED screen](/device/screen) shows the `count` variable getting bigger.
 
 ```blocks
 let count = 0
@@ -19,22 +23,29 @@ input.onButtonPressed(Button.A, () => {
 })
 ```
 
-### Example: roll a dice
+### Example: roll dice
 
-This example generates a random number when you press the B input button, and then displays a random die image:
+This example shows a number from 1 to 6 when you press the `B` button.
 
 ```blocks
 input.onButtonPressed(Button.B, () => {
-    let dice = Math.random(6)
+    let dice = Math.random(6) + 1
     basic.showNumber(dice)
 })
 ```
 
+### ~hint
+
+This program adds a `1` to `random(6)` so the numbers on the dice will come out right.
+Otherwise, sometimes they would show a `0`.
+
+### ~
+
 ### Lessons
 
 [smiley](/lessons/smiley), [answering machine](/lessons/answering-machine), [screen wipe](/lessons/screen-wipe), [rotation animation](/lessons/rotation-animation)
 
 ### See also
 
-[button is pressed](/reference/input/button-is-pressed), [forever](/reference/basic/forever)
+[button is pressed](/reference/input/button-is-pressed), [forever](/reference/basic/forever), [random](/reference/math/math)
 

docs/reference/input/running-time.md

@@ -1,6 +1,6 @@
 # Running Time
 
-Get the number of milliseconds elapsed since the script began. 1,000 milliseconds = 1 second.
+Find how long it has been since the program started.
 
 ```sig
 input.runningTime();
@@ -8,15 +8,20 @@ input.runningTime();
 
 ### Returns
 
-* [Number](/reference/types/number)
+* the [Number](/reference/types/number) of milliseconds since the program started.
+(One second is 1000 milliseconds.)
 
 ### Example: elapsed time
 
-This code gets the elapsed time since the start of the program execution and displays it on the screen.
+When you press button `B` on the microbit, this
+program finds the number of milliseconds since the program started
+and shows it on the [LED screen](/device/screen).
 
 ```blocks
-let now = input.runningTime()
-basic.showNumber(now)
+input.onButtonPressed(Button.B, () => {
+    let now = input.runningTime()
+    basic.showNumber(now)
+})
 ```
 
 ### Lessons

docs/reference/led/brightness.md

@@ -1,6 +1,6 @@
 # Brightness
 
-Set the brightness of the [LED screen](/device/screen).
+Find how bright the [LED screen](/device/screen) is.
 
 ```sig
 led.brightness();
@@ -8,11 +8,11 @@ led.brightness();
 
 ### Returns
 
-* [Number](/reference/types/number) - returns the LCD screen brightness as a number from 0 to 255. A return value of 255 means the screen brightness is at 100% and 127 is about 50% brightness.
+* a [Number](/reference/types/number) that means how bright the screen is, from `0` (darkest) to `255` (brightest). For example, the number `127` means the screen is halfway bright.
 
-### Example: maximum brightness
+### Example: highest brightness
 
-If the screen brightness is < 100%, the following code sets the brightness to 100% (255):
+This program makes the screen completely bright if it is not that way already:
 
 ```blocks
 if (led.brightness() < 255) {

docs/reference/led/plot-bar-graph.md

@@ -1,6 +1,7 @@
 # Plot Bar Graph
 
-Displays a vertical bar graph based on the value and high value.
+Displays a bar graph of the numbers you say.
+A bar graph is a kind of chart that shows numbers as lines with different lengths.
 
 ```sig
 led.plotBarGraph(2, 20);
@@ -8,10 +9,18 @@ led.plotBarGraph(2, 20);
 
 ### Parameters
 
-* value: [Number](/reference/types/number) , high : [Number](/reference/types/number) displays a vertical bar graph based on the value and high value
+* `value` is a [Number](/reference/types/number) that means what you are measuring or trying to show. For example, if you are measuring the temperature of ice with the BBC micro:bit, `value` might be 0 because the temperature might be 0 degrees centigrade.
+* `high` is a [Number](/reference/types/number) that means the highest possible number that the `value` parameter can be. This number is also the tallest that the lines in the bar chart can be.
 
 ### Example: chart acceleration
 
+This program shows a bar graph of the [acceleration](/reference/input/acceleration) 
+in the `x` direction of the micro:bit.
+The micro:bit's `x` direction is from left to right (or right to left).
+The more you speed up moving the micro:bit in this direction,
+the taller the lines in the bar graph will be, 
+until they are as tall as the parameter `high` says they can be.
+
 ```blocks
 basic.forever(() => {
     let a = input.acceleration(Dimension.X);

docs/reference/loops/for.md

@@ -2,17 +2,15 @@
 
 ### @parent blocks/language
  
-Repeat code a fixed number of times.
+Run part of the program the number of times you say.
+
+### Example: Count to 4
+
+This program will show the numbers 0, 1, 2, 3, and 4 one after another on the LED screen.
 
 ```blocks
 for(let i = 0; i < 5; ++i) {
-}
-```
-
-The Block Editor *for* loop is different than the Touch Develop *for* loop in an important way. The above for loop will iterate *five* times, with the loop variable *i* taking on values 0, 1, 2, 3, and 4. The Touch Develop for loop shown below will iterate four times:
-
-```
-for (let k = 0; k < 4; k++) {
+basic.showNumber(i)
 }
 ```
 
@@ -22,5 +20,5 @@ for (let k = 0; k < 4; k++) {
 
 ### See also
 
-[while](/reference/loops/while), [if](/reference/logic/if)
+[repeat](/reference/loops/repeat), [while](/reference/loops/while), [if](/reference/logic/if), [show number](/reference/basic/show-number)
 

docs/reference/loops/repeat.md

@@ -1,19 +1,16 @@
 # Repeat
 
-Repeat code a preset number of times.
+Run part of the program the number of times you say.
 
 ### Block Editor
 
 ![](/static/mb/blocks/contents-0.png)
 
-### Touch Develop
+### Lessons
 
-Touch Develop has no `repeat` loop. Instead you can used a for loop
+[looper](/lessons/looper)
 
-```
-for (let i = 0; i < 5; i++) {
-}
-```
+### See also
 
-The loop above will repeat five (5) times.
+[for](/reference/loops/for), [while](/reference/loops/while), [if](/reference/logic/if), [show number](/reference/basic/show-number)
 

docs/reference/music/play-tone.md

@@ -1,10 +1,10 @@
 # Play Tone
 
-Plays a music tone through pin ``P0`` for the given duration.
+Play a musical tone through pin ``P0`` of the micro:bit for as long as you say.
 
 ## Simulator
 
-Simulation of this function is available in many, but not all browsers.
+This function only works on the micro:bit and in some browsers.
 
 ```sig
 music.playTone(440, 120)
@@ -12,11 +12,14 @@ music.playTone(440, 120)
 
 ### Parameters
 
-* `frequency` : [Number](/reference/types/number) - the frequency of the note (in Herz)
-* `ms`: [Number](/reference/types/number) - the duration of the note (milliseconds)
+* `Hz` is the [Number](/reference/types/number) of Hertz (the frequency, how high or low the tone is).
+* `ms` is the [Number](/reference/types/number) of milliseconds that the tone lasts.
 
 ## Example
 
+This example stores the musical note C in the variable `freq`.
+Next, it plays that note for 1000 milliseconds (one second).
+
 ```blocks
 let freq = music.noteFrequency(Note.C)
 music.playTone(freq, 1000)

docs/reference/music/tempo.md

@@ -1,16 +1,16 @@
 # Tempo
 
-Returns the tempo in beats per minute.
+Finds the tempo (speed of a piece of music).
 
 ```sig
 music.tempo()
 ```
 
-### Parameters
+### Returns
 
-* Returns : [Number](/reference/types/number) - returns the tempo in beats per minute
+* a [Number](/reference/types/number) that means the bpm (beats per minute, or number of beats in a minute of the music that the micro:bit is playing).
 
 ### See also
 
-[play tone](/reference/music/play-tone), [ring tone](/reference/music/ring-tone) , [rest](/reference/music/rest), [set tempo](/reference/music/set-tempo), [change tempo by](/reference/music/change-tempo-by)
+[play tone](/reference/music/play-tone), [ring tone](/reference/music/ring-tone), [rest](/reference/music/rest), [set tempo](/reference/music/set-tempo), [change tempo by](/reference/music/change-tempo-by)
 

libs/microbit/enums.d.ts

@@ -105,6 +105,16 @@ declare namespace basic {
      */
     //% block="free fall"
     FreeFall = 7,  // MICROBIT_ACCELEROMETER_EVT_FREEFALL
+    /**
+     * Raised when a 3G shock is detected
+     */
+    //% block="3g"
+    ThreeG = 8,  // MICROBIT_ACCELEROMETER_EVT_3G
+    /**
+     * Raised when a 6G shock is detected
+     */
+    //% block="6g"
+    SixG = 9,  // MICROBIT_ACCELEROMETER_EVT_6G
     }
 declare namespace input {
 }

libs/microbit/input.cpp

@@ -94,7 +94,17 @@ enum class Gesture {
      * Raised when the board is falling!
      */
     //% block="free fall"
-    FreeFall = MICROBIT_ACCELEROMETER_EVT_FREEFALL
+    FreeFall = MICROBIT_ACCELEROMETER_EVT_FREEFALL,
+    /**
+    * Raised when a 3G shock is detected
+    */
+    //% block="3g"
+    ThreeG = MICROBIT_ACCELEROMETER_EVT_3G,
+    /**
+    * Raised when a 6G shock is detected
+    */
+    //% block="6g"
+    SixG = MICROBIT_ACCELEROMETER_EVT_6G
 };
 
 //% color=300 weight=99
@@ -117,6 +127,10 @@ namespace input {
     //% help=input/on-gesture weight=84 blockGap=8
     //% blockId=device_gesture_event block="on |%NAME" icon="\uf135"
     void onGesture(Gesture gesture, Action body) {
+        if ((int)gesture == MICROBIT_ACCELEROMETER_EVT_3G && uBit.accelerometer.getRange() < 3)
+            uBit.accelerometer.setRange(4);
+        else if ((int)gesture == MICROBIT_ACCELEROMETER_EVT_6G && uBit.accelerometer.getRange() < 6)
+            uBit.accelerometer.setRange(8);            
         registerWithDal(MICROBIT_ID_GESTURE, (int)gesture, body);
     }
 

libs/microbit/music.ts

@@ -83,11 +83,11 @@ namespace music {
 
     /**
      * Plays a tone through pin ``P0`` for the given duration.
-     * @param frequency TODO
-     * @param ms TODO
+     * @param frequency pitch of the tone to play in Hertz (Hz)
+     * @param ms tone duration in milliseconds (ms)
      */
     //% help=music/play-tone weight=90
-    //% blockId=device_play_note block="play|tone (Hz) %note=device_note|for (ms) %duration=device_beat" icon="\uf025" blockGap=8
+    //% blockId=device_play_note block="play|tone %note=device_note|for %duration=device_beat" icon="\uf025" blockGap=8
     export function playTone(frequency: number, ms: number): void {
         pins.analogSetPitchPin(AnalogPin.P0);
         pins.analogPitch(frequency, ms);
@@ -95,7 +95,7 @@ namespace music {
 
     /**
      * Plays a tone through pin ``P0``.
-     * @param frequency TODO
+     * @param frequency pitch of the tone to play in Hertz (Hz)
      */
     //% help=music/ring-tone weight=80
     //% blockId=device_ring block="ring tone (Hz)|%note=device_note" icon="\uf025" blockGap=8
@@ -106,7 +106,7 @@ namespace music {
 
     /**
      * Rests (plays nothing) for a specified time through pin ``P0``.
-     * @param ms TODO
+     * @param ms rest duration in milliseconds (ms)
      */
     //% help=music/rest weight=79
     //% blockId=device_rest block="rest(ms)|%duration=device_beat"
@@ -117,16 +117,16 @@ namespace music {
 
     /**
      * Gets the frequency of a note.
-     * @param name TODO
+     * @param name the note name
      */
     //% weight=50 help=music/note-frequency
     //% blockId=device_note block="%note"
     export function noteFrequency(name: Note): number {
         return name;
     }
-    
+
     function init() {
-        if (beatsPerMinute <= 0) beatsPerMinute = 120;        
+        if (beatsPerMinute <= 0) beatsPerMinute = 120;
     }
 
     /**

package.json

@@ -1,6 +1,6 @@
 {
   "name": "pxt-microbit",
-  "version": "0.2.125",
+  "version": "0.2.128",
   "description": "BBC micro:bit target for PXT",
   "keywords": [
     "JavaScript",
@@ -29,6 +29,6 @@
     "typescript": "^1.8.7"
   },
   "dependencies": {
-    "pxt-core": "0.2.131"
+    "pxt-core": "0.2.138"
   }
 }

pxtarget.json

@@ -63,6 +63,9 @@
         "aspectRatio": 1.22
     },
     "compileService": {
+        "yottaTarget": "bbc-microbit-classic-gcc",
+        "yottaCorePackage": "pxt-microbit-core",
+        "githubCorePackage": "microsoft/pxt-microbit-core",
         "gittag": "v0.1.10",
         "serviceId": "ws"
     },