0.2.191

fixing more help broken links

.gitignore

@@ -1,6 +1,7 @@
 node_modules
 yotta_modules
 yotta_targets
+pxt_modules
 built
 typings
 tmp
@@ -18,4 +19,4 @@ clients/**/obj/**
 *.tgz
 *.db
 *.suo
-*.log
+*.log

.travis.yml

@@ -5,7 +5,7 @@ script:
   - "node node_modules/pxt-core/built/pxt.js travis"  
   - "(cd libs/lang-test0; node ../../node_modules/pxt-core/built/pxt.js run)"
   - "node node_modules/pxt-core/built/pxt.js uploaddoc"
-  - "(cd libs/hello; node ../../node_modules/pxt-core/built/pxt.js testconv ../../testconv.json)"
+  - "(cd libs/hello; node ../../node_modules/pxt-core/built/pxt.js testconv https://az851932.vo.msecnd.net/files/td-converter-tests-v0.json)"
 sudo: false
 notifications:
   email:
@@ -14,4 +14,5 @@ cache:
   directories:
     - node_modules
     - built/cache
+    - libs/hello/built/cache
 

cmds/cmds.ts

@@ -6,6 +6,8 @@ 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)
+let readDirAsync = Promise.promisify(fs.readdir)
+
 
 export function deployCoreAsync(res: ts.pxt.CompileResult) {
     return getBitDrivesAsync()
@@ -37,6 +39,10 @@ function getBitDrivesAsync(): Promise<string[]> {
                 })
                 return res
             })
+    }
+    else if (process.platform == "darwin") {
+        return readDirAsync("/Volumes")
+            .then(lst => lst.filter(s => /MICROBIT/.test(s)).map(s => "/Volumes/" + s + "/"))
     } else {
         return Promise.resolve([])
     }

docs/about.md

@@ -31,11 +31,11 @@ Just like Arduino, the micro:bit can be connected to and interact with sensors,
 
 ## Hardware: The Device
 
-Learn about about the [hardware components](/device) of the micro:bit to make the most of it!
+Learn about the [hardware components](/device) of the micro:bit to make the most of it!
 
 ## Programming: Blocks or JavaScript
 
-The student can program the BBC micro:bit using [Blocks](/blocks) or [JavaScript](/javascript), via the [micro:bit APIs](/reference):
+You can program the micro:bit using [Blocks](/blocks) or [JavaScript](/javascript), via the [micro:bit APIs](/reference):
 
 ```blocks
 basic.showString("Hi!");
@@ -43,21 +43,19 @@ basic.showString("Hi!");
 
 ## Compile and Flash: Your Program!
 
-When a user has her code ready, she can connect her BBC micro:bit to a computer via a USB cable, so it appears as a mounted drive (named MICROBIT). 
+When you have your code ready, you connect your micro:bit to a computer via a USB cable, so it appears as a mounted drive (named MICROBIT). 
 
-Compilation to ARM thumb machine code from [Blocks](/blocks) or [JavaScript](/javascript) happens in the browser.
-
-The student is prompted to save the ARM binary program to a file, which she then simply drags to the micro:bit mounted drive, 
-which flashes the micro:bit device with the new program.
+Compilation to ARM thumb machine code from [Blocks](/blocks) or [JavaScript](/javascript) happens in the browser. You save the ARM binary 
+program to a file, which you then copy to the micro:bit drive, which flashes the micro:bit device with the new program.
 
 ## Simulator: Test Your Code
 
-Before a student compiles her code for the micro:bit, she can run it using the micro:bit simulator, all within the confines of a web browser. 
+You can run your code using the micro:bit simulator, all within the confines of a web browser. 
 The simulator has support for the LED screen, buttons, as well as compass, accelerometer, and digital I/O pins.
 
 ## C++ Runtime
 
-The [C++ BBC micro:bit runtime](http://lancaster-university.github.io/microbit-docs/), created at [Lancaster University](http://www.lancaster.ac.uk/), provides access to the hardware functions of the micro:bit, 
+The [C++ micro:bit runtime](http://lancaster-university.github.io/microbit-docs/), created at [Lancaster University](http://www.lancaster.ac.uk/), provides access to the hardware functions of the micro:bit, 
 as well as a set of helper functions (such as displaying a number/image/string on the LED screen). 
 
 The [micro:bit library](/reference) mirrors the functions of the C++ library. 
@@ -65,4 +63,4 @@ When code is compiled to ARM machine code, the calls to JavaScript micro:bit fun
 
 ## Open Source
 
-The editor for the BBC micro:bit is [open source](/open-source) on GitHub. Contributors are welcome!
+The code for the micro:bit is [open source](/open-source) on GitHub. Contributors are welcome!

docs/blocks/variables.md

@@ -1,4 +1,4 @@
-## Variables
+# Variables
 
 [Assign](/blocks/variables/assign) (set) a variable's value
 

docs/device.md

@@ -1,6 +1,6 @@
 # Device
 
-All the bits and pieces that make up your BBC micro:bit
+All the bits and pieces that make up the BBC micro:bit
 
 ![](/static/mb/device-0.png)
 
@@ -77,7 +77,7 @@ You can attach an external device such as a motor to these and power it using th
 
 ### Serial Communication
 
-The BBC micro:bit can send an receive data via [serial communication](/device/serial). The serial data can be transfered via USB or BLE.
+The micro:bit can send an receive data via [serial communication](/device/serial). The serial data can be transfered via USB or BLE.
 
 ### Bluetooth Low Energy (BLE) Antenna
 

docs/device/serial.md

@@ -29,13 +29,21 @@ Unfortunately, using the serial library requires quite a bit of a setup.
 If you are using the Google Chrome browser, you can use our extension to get serial data streaming in the editor.
 
 * Install the [Extension for BBC micro:bit](https://chrome.google.com/webstore/detail/extension-for-bbc-microbi/cihhkhnngbjlhahcfmhekmbnnjcjdbge?hl=en-US) on the Chrome Web Store.
-* Restart Chrome and open the web editor.
+* Restart Chrome and open the [web editor](https://codethemicrobit.com)
+* The serial data will show below the simulator
 
 ### Windows
 
-You must install a device driver (for the computer to recognize the serial interface of the micro:bit); then, you must also install a terminal emulator (which is going to connect to the micro:bit and read its output). Here's how to do it:
+You must install a device driver (for the computer to recognize the
+serial interface of the micro:bit); then, you must also install a
+terminal emulator (which is going to connect to the micro:bit and read
+its output).
 
-* Follow instructions at https://developer.mbed.org/handbook/Windows-serial-configuration in order to install the device driver
+* Follow the instructions at
+  https://developer.mbed.org/handbook/Windows-serial-configuration to
+  install the device driver.
+
+* Instructions for installing a terminal emulator are below.
 
 #### Windows > Tera Term
 
@@ -66,14 +74,16 @@ If you prefer another terminal emulator (such as [PuTTY](http://www.putty.org/))
 
 ### Linux
 
-(Untested).
+* Install the program `screen` if it is not already installed.
+* Plug in the micro:bit.
+* Open a terminal.
+* Find which device node the micro:bit was assigned to with the command `ls /dev/ttyACM*`.
+* If it was `/dev/ttyACM0`, type the command `screen /dev/ttyACM0 115200`. If it was some other device node,
+  use that one in the command instead. **Note:** You may need root access to run `screen`
+  successfully. You can probably use the command `sudo` like this: `sudo screen /dev/ttyACM0 115200`.
+* To exit `screen`, type `Ctrl-A` `Ctrl-D`.
 
-* Plug in the micro:bit
-* Open a terminal
-* `dmesg | tail` will show you which `/dev/` node the micro:bit was assigned (e.g. `/dev/ttyUSB0`)
-* Then, do: `screen /dev/ttyUSB0 115200` (install the `screen` program if you don't have it). To exit, run `Ctrl-A` `Ctrl-D`.
-
-Alternative programs include minicom, etc.
+Alternative programs include `minicom` and so on.
 
 ### Mac OS
 

docs/docs.md

@@ -1,36 +1,26 @@
 # Documentation
 
-```sim
-basic.forever(() => {
-  basic.showString("DOCS ");
-})
-input.onButtonPressed(Button.A, () => {
-    led.stopAnimation();
-    basic.showLeds(`
-. . . . .
-. # . # .
-. . . . .
-# . . . #
-. # # # .`);
-});
-input.onButtonPressed(Button.B, () => {
-    led.stopAnimation();
-    basic.showLeds(`
-. # . # .
-# . # . #
-# . . . #
-. # . # .
-. . # . .`);
-});
-``` 
+### Things to do
 
-* **[getting started](/getting-started)**
-* Get started with [projects](/projects)
-* Browse the [micro:bit APIs](/reference)
-* Learn more about the [micro:bit device](/device)
-* Frequently Asked Question [faq](/faq)
-* Follow up with the [release notes](/release-notes)
+* **[Getting Started](/getting-started)**
+* [Ten projects](/projects)
+
+### Micro:bit reference
+
+* [The micro:bit APIs](/reference)
+* [The micro:bit device](/device)
+
+### Language and data reference
+
+* [Blocks language](/blocks)
+* [JavaScript language](/javascript)
+* [Streaming data](/streaming)
+
+### More questions?
+
+* [Frequently Asked Question](/faq)
+* [Release notes](/release-notes)
 
 ### Developers
 
-* Learn about [packages](/packages) (possibly using C++ or ARM thumb)
+* Learn about [packages](/packages)

docs/getting-started.md

@@ -2,16 +2,13 @@
 
 ## ~avatar
 
-Are you ready to build cool BBC micro:bit programs?
-
 Here are some challenges for you. Arrange the blocks in the editor
 to make real programs that work!
 
 ## ~
 
-Use the **Basic** drawer in the editor (to the left) 
-to drag out and arrange three blocks (two `show leds` and one `forever` block)
-to create this program:
+Use the **Basic** drawer in the editor
+to drag out and arrange three blocks to create this program:
 
 ```blocks
 basic.forever(() => {
@@ -39,4 +36,6 @@ screen, then a smiley again -- it never stops! (That's because of the
 Click **Compile** to move your program to the BBC micro:bit! 
 Make sure to follow the instructions.
 
-## [NEXT: THE SCREEN](/getting-started/screen)
+### ~button /getting-started/screen
+NEXT: THE SCREEN
+### ~

docs/getting-started/buttons.md

@@ -76,4 +76,6 @@ your handshake to make it happen!
 
 ## ~
 
-## [NEXT: SHAKE](/getting-started/shake)
+### ~button /getting-started/shake
+NEXT: SHAKE
+### ~

docs/getting-started/coin-flipper.md

@@ -73,4 +73,6 @@ input.onButtonPressed(Button.AB, () => {
 
 Flip until your thumbs get tired!
 
-## [NEXT: ROCK PAPER SCISSORS](/getting-started/rock-paper-scissors)
+### ~button /getting-started/rock-paper-scissors
+NEXT: ROCK PAPER SCISSORS
+### ~

docs/getting-started/rock-paper-scissors.md

@@ -200,4 +200,6 @@ input.onButtonPressed(Button.B, () => {
 ```
 Click **Compile** to move your program to the BBC micro:bit!
 
-## [NEXT: PROJECTS!](/projects)
+### ~button /projects
+NEXT: PROJECTS!
+### ~

docs/getting-started/screen.md

@@ -93,4 +93,6 @@ You can find the ``show leds`` block in the **Basic** part of the editor.
 
 #### ~
 
-## [NEXT: BUTTONS](/getting-started/buttons)
+### ~button /getting-started/buttons
+NEXT: BUTTONS
+### ~

docs/getting-started/shake.md

@@ -19,4 +19,6 @@ input.onGesture(Gesture.Shake, () => {
 ```
 Click **Compile** to move your program to the BBC micro:bit!
 
-## [NEXT: COIN FLIPPER GAME](/getting-started/coin-flipper)
+### ~button /getting-started/coin-flipper
+NEXT: COIN FLIPPER GAME
+### ~

docs/javascript.md

@@ -1,75 +1,15 @@
 # JavaScript
 
-You can write micro:bit programs in a subset of [TypeScript](https://www.typescriptlang.org), a superset of JavaScript.
-Many micro:bit programs, especially at the beginner's level, are just plain JavaScript. TypeScript introduces class-based 
-object-oriented programming, such as:
+If you already know some JavaScript, you might be interested in [the JavaScript and TypeScript languages](/js/lang).
+Otherwise, visit the cards below to starting programming JavaScript with the micro:bit:
 
-```typescript
-class Greeter {
-    greeting: string;
-    constructor(message: string) {
-        this.greeting = message;
-    }
-    greet() {
-        return "Hello, " + this.greeting;
-    }
+```codecard
+[{
+  "name": "Calling Functions",
+  "url":"/js/call"
+},{
+  "name": "Sequencing Commands",
+  "url":"/js/sequence"
 }
-
-let greeter = new Greeter("world");
-basic.showString(greeter.greet())
-```
-
-This site is meant for teaching programming first, and JavaScript second. For this
-reason, we have stayed away from concepts that are specific to JavaScript (for
-example, prototype inheritance), and instead focused on ones common to most
-modern programming languages (for example, loops, lexically scoped variables,
-functions, classes, lambdas).
-
-We leverage TypeScript's [type inference](http://www.typescriptlang.org/docs/handbook/type-inference.html) so that
-students need not specify types when clear from context.
-
-## Supported language features
-
-* top-level code in the file: "Hello world!" really is just `basic.showString("Hello world!")`
-* [basic types](http://www.typescriptlang.org/docs/handbook/basic-types.html)
-* [variable declarations](http://www.typescriptlang.org/docs/handbook/variable-declarations.html): `let`, `const`, and `var`
-* [functions](http://www.typescriptlang.org/docs/handbook/functions.html) with lexical scoping and recursion
-
-### User-defined types and modules
-
-* [classes](http://www.typescriptlang.org/docs/handbook/classes.html) with fields, methods and constructors; `new` keyword
-* [enums](http://www.typescriptlang.org/docs/handbook/enums.html)
-* [namespaces](http://www.typescriptlang.org/docs/handbook/namespaces.html)  (a form of modules) 
-
-### Control-flow constructs
-
-* `if ... else if ... else` statements
-* `while` and `do ... while` loops
-* `for(;;)` loops (see below about `for ... in/of`)
-* `break/continue`; also with labeled loops
-* `switch` statement (on numbers only)
-* `debugger` statement for breakpoints
-
-### Expressions
-
-* conditional operator `? :`; lazy boolean operators
-* all arithmetic operators (including bitwise operators); note that in microcontroller targets
-  all arithmetic is performed on integers, also when simulating in the browser
-* strings (with a few common methods)
-* [string templates](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) (`` `x is ${x}` ``)
-* arrow functions `() => ...`
-* array literals `[1, 2, 3]`
-
-
-## Unsupported language features
-
-We generally stay away from the more dynamic parts of JavaScript. 
-Things you may miss and we may implement:
-
-* exceptions (`throw`, `try ... catch`, `try ... finally`)
-* `for ... of` statements
-* object literals `{ foo: 1, bar: "two" }`
-* method-like properties (get/set accessors)
-* class inheritance
-
-If there is something you'd like to see, please file an issue at [GitHub](http://github.com/microsoft/pxt/issues).
+]
+```

docs/js/call.md

@@ -0,0 +1,58 @@
+# Call a function
+
+The simplest way to get started in JavaScript with your micro:bit is to
+call one of the micro:bit's built-in JavaScript functions. Just like Blocks
+are organized into categories/drawers, the micro:bit functions are organized by
+namespaces, with names corresponding to the drawer names.  
+The `basic` namespace contains a number of very helpful functions:
+
+```typescript
+basic.showString("Hello!")
+```
+
+If you want to see all functions available in the `basic` namespace, simply type `basic`
+followed by `.` and a list of all the functions will appear. 
+
+![](/static/mb/js/basicFuns.png)
+
+This feature is known as "Intellisense". Continue typing to select one of the functions, 
+or click on one of the functions to select. You also narrow down the set of functions by typing, as below:
+
+![](/static/mb/js/basicIntell.png)
+
+You can type anything to see what Intellisense will find for you. Here's an example
+of what happens when you type the word `for`:
+![](/static/mb/js/forIntell.png)
+
+## Function parameter values
+
+You might have noticed that the call `showString` above takes one parameter value, 
+the string to be scrolled on the LED screen. There is a second (optional)
+parameter that controls the speed of the scroll. Try this:
+
+```typescript
+basic.showString("Hello!",50)
+```
+
+Intellisense shows all the available parameters for a function. 
+
+## Left and right parentheses, please!
+
+Whenever you want to call a function, you give the name of the function
+followed by `(` and ending with `)`. Inbetween the left and right
+parentheses go the function arguments.  If a function has zero arguments, you still
+need the parentheses in order to call the function. For example
+
+```typescript
+basic.clearScreen()
+```
+
+It's a syntax error to have a left parenthesis without the "closing" right parenthesis:
+
+```typescript
+basic.clearScreen(
+```
+
+### ~button /js/sequence
+NEXT: Sequencing Commands
+### ~

docs/js/lang.md

@@ -0,0 +1,75 @@
+# JavaScript and TypeScript
+
+You can write micro:bit programs in a subset of [TypeScript](https://www.typescriptlang.org), a superset of JavaScript.
+Many micro:bit programs, especially at the beginner's level, are just plain JavaScript. TypeScript introduces class-based 
+object-oriented programming, such as:
+
+```typescript
+class Greeter {
+    greeting: string;
+    constructor(message: string) {
+        this.greeting = message;
+    }
+    greet() {
+        return "Hello, " + this.greeting;
+    }
+}
+
+let greeter = new Greeter("world");
+basic.showString(greeter.greet())
+```
+
+This site is meant for teaching programming first, and JavaScript second. For this
+reason, we have stayed away from concepts that are specific to JavaScript (for
+example, prototype inheritance), and instead focused on ones common to most
+modern programming languages (for example, loops, lexically scoped variables,
+functions, classes, lambdas).
+
+We leverage TypeScript's [type inference](http://www.typescriptlang.org/docs/handbook/type-inference.html) so that
+students need not specify types when clear from context.
+
+## Supported language features
+
+* top-level code in the file: "Hello world!" really is just `basic.showString("Hello world!")`
+* [basic types](http://www.typescriptlang.org/docs/handbook/basic-types.html)
+* [variable declarations](http://www.typescriptlang.org/docs/handbook/variable-declarations.html): `let`, `const`, and `var`
+* [functions](http://www.typescriptlang.org/docs/handbook/functions.html) with lexical scoping and recursion
+
+### User-defined types and modules
+
+* [classes](http://www.typescriptlang.org/docs/handbook/classes.html) with fields, methods and constructors; `new` keyword
+* [enums](http://www.typescriptlang.org/docs/handbook/enums.html)
+* [namespaces](http://www.typescriptlang.org/docs/handbook/namespaces.html)  (a form of modules) 
+
+### Control-flow constructs
+
+* `if ... else if ... else` statements
+* `while` and `do ... while` loops
+* `for(;;)` loops (see below about `for ... in/of`)
+* `break/continue`; also with labeled loops
+* `switch` statement (on numbers only)
+* `debugger` statement for breakpoints
+
+### Expressions
+
+* conditional operator `? :`; lazy boolean operators
+* all arithmetic operators (including bitwise operators); note that in microcontroller targets
+  all arithmetic is performed on integers, also when simulating in the browser
+* strings (with a few common methods)
+* [string templates](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) (`` `x is ${x}` ``)
+* arrow functions `() => ...`
+* array literals `[1, 2, 3]`
+
+
+## Unsupported language features
+
+We generally stay away from the more dynamic parts of JavaScript. 
+Things you may miss and we may implement:
+
+* exceptions (`throw`, `try ... catch`, `try ... finally`)
+* `for ... of` statements
+* object literals `{ foo: 1, bar: "two" }`
+* method-like properties (get/set accessors)
+* class inheritance
+
+If there is something you'd like to see, please file an issue at [GitHub](http://github.com/microsoft/pxt/issues).

docs/js/sequence.md

@@ -0,0 +1,25 @@
+# Sequencing commands
+
+By calling one function after another, you can create an animation:
+
+```typescript
+basic.showLeds(`
+    . # . # .
+    . . . . .
+    . . # . .
+    # . . . #
+    . # # # .
+    `)
+basic.showLeds(`
+    . # . # .
+    . . . . .
+    . . . . .
+    . # # # .
+    # . . . #
+    `)
+```
+
+## The Semicolon
+
+Coming soon...
+

docs/lessons/bop-it/activity.md

@@ -41,7 +41,7 @@ Now let's add some more types of instructions for the player to follow. Let's ad
 /**
  * {highlight}
  */
-export function newAction_() {
+export function newAction() {
     action = Math.random(4) // ***
     if (action == 0) {
         basic.showString("PUSH A", 150) // ***

docs/lessons/speed-button/quiz-answers.md

@@ -21,10 +21,10 @@ let count = 0
 ## 3. If the rectangle below represents the BBC micro:bit, shade the areas that will be displayed after two button presses on Button A. Explain why that particular area is shaded.
 
 ```blocks
-let count_ = 0
+let count = 0
 input.onButtonPressed(Button.A, () => {
-    count_ = count_ + 1
-    basic.showNumber(count_, 100)
+    count = count + 1
+    basic.showNumber(count, 100)
 })
 ```
 
@@ -37,10 +37,10 @@ After two button presses, **count** will be equal to 2.
 ## 5. If the rectangle below represents the BBC micro:bit, shade the areas that will be displayed after five button presses on Button A. Explain why that particular area is shaded.
 
 ```blocks
-let count_ = 0
+let count = 0
 input.onButtonPressed(Button.A, () => {
-    count_ = count_ + 1
-    basic.showNumber(count_, 100)
+    count = count + 1
+    basic.showNumber(count, 100)
 })
 ```
 

docs/lessons/speed-button/quiz.md

@@ -23,10 +23,10 @@ let count = 0
 ## 3. Draw which LED is ON after running this code and pressing Button A twice. Explain why you chose to draw that number 
 
 ```blocks
-let count_ = 0
+let count = 0
 input.onButtonPressed(Button.A, () => {
-    count_ = count_ + 1
-    basic.showNumber(count_, 100)
+    count = count + 1
+    basic.showNumber(count, 100)
 })
 ```
 
@@ -37,10 +37,10 @@ input.onButtonPressed(Button.A, () => {
 ## 4. Draw which LED is ON after running this code and pressing Button A five times. Explain why you chose to draw that number.
 
 ```blocks
-let count_ = 0
+let count = 0
 input.onButtonPressed(Button.A, () => {
-    count_ = count_ + 1
-    basic.showNumber(count_, 100)
+    count = count + 1
+    basic.showNumber(count, 100)
 })
 ```
 

docs/lessons/zoomer/quiz-answers.md

@@ -15,7 +15,7 @@ Write the line of code to measure the acceleration and then store in it a variab
 <br/>
 
 ```blocks
-let accX_ = input.acceleration("x")
+let accX = input.acceleration("x")
 ```
 
 Note: acceleration does not have be measured in the "x" direction. It can also be in the "y" or "z" direction.

docs/projects/banana-keyboard-challenges.md

@@ -59,5 +59,6 @@ input.onPinPressed(TouchPin.P2, () => {
 
 * click *run* to see if the code works as expected.
 
-
-
+### ~button /projects/telegraph
+NEXT: Telegraph
+### ~

docs/projects/compass.md

@@ -104,3 +104,6 @@ basic.forever(() => {
 });
 ```
 
+### ~button /projects/hack-your-headphones
+NEXT: Hack Your Headphones
+### ~

docs/projects/flashing-heart.md

@@ -112,4 +112,8 @@ basic.pause(500);
 basic.clearScreen();
 basic.pause(500);
 })
-```
+```
+
+### ~button /projects/smiley-buttons
+NEXT: Smiley Buttons
+### ~

docs/projects/hack-your-headphones-challenges.md

@@ -71,3 +71,6 @@ input.onButtonPressed(Button.A, () => {
 
 * click *compile* and run your code on the micro:bit.
 
+### ~button /projects/banana-keyboard
+NEXT: Banana Keyboard
+### ~

docs/projects/love-meter.md

@@ -47,4 +47,8 @@ input.onPinPressed(TouchPin.P2, () => {
         . . # . .
         `);
 });
-```
+```
+
+### ~button /projects/rock-paper-scissors
+NEXT: Rock Paper Scissors
+### ~

docs/projects/radio-challenges.md

@@ -86,3 +86,7 @@ Have fun reviewing your simulation and analyze the acceleration by chart the Exc
 * The first person and second person take turns tilting the micro:bit in the "x" direction while the other player charts the data on the micro:bit!
 * Review and analyze the actual micro:bit device acceleration data on Excel
 * Display acceleration with y or z using plot bar graph by changing acceleration from "x" to "y" or "z" 
+
+### ~button /projects/the-watch
+NEXT: The Watch
+### ~

docs/projects/rock-paper-scissors.md

@@ -235,3 +235,7 @@ input.onButtonPressed(Button.B, () => {
 
 How else can you make your game better?
 Ever hear of [Rock Paper Scissors Spock Lizard](http://www.samkass.com/theories/RPSSL.html)?
+
+### ~button /projects/compass
+NEXT: Compass
+### ~

docs/projects/smiley-buttons.md

@@ -66,4 +66,8 @@ input.onButtonPressed(Button.B, () => {
     # . . . #
     . # # # .`);
 });
-```
+```
+
+### ~button /projects/love-meter
+NEXT: Love Meter
+### ~

docs/projects/telegraph-challenges.md

@@ -108,3 +108,7 @@ Your telegraph is ready!
 * Connect the first micro:bit to your computer using your USB cable and put the telegraph script on it.
 * Connect the second micro:bit to your computer using your USB cable and run the telegraph script on it.
 * The first person and second person take turns pressing button A to play the telegraph game!
+
+### ~button /projects/radio
+NEXT: Radio
+### ~

docs/reference/basic/show-string.md

@@ -9,7 +9,7 @@ basic.showString("Hello!")
 ### Parameters
 
 * `text` is a [String](/reference/types/string). It can contain letters, numbers, and punctuation.
-* `ms` is an optional [Number](/reference/types/number). It means the number of milliseconds before sliding the [String](/reference/types/string) left by one LED each time. Bigger intervals make the sliding slower.
+* `interval` is an optional [Number](/reference/types/number). It means the number of milliseconds before sliding the [String](/reference/types/string) left by one LED each time. Bigger intervals make the sliding slower.
 
 ### Examples:
 

docs/reference/bluetooth/about-bluetooth.md

@@ -0,0 +1,99 @@
+# About Bluetooth
+
+![](/static/bluetooth/Bluetooth_SIG.png)
+
+## Introduction
+
+Bluetooth is a wireless communications technology which allows devices to communicate with each other without the need for a central device like a router or access point.
+
+Bluetooth has a special "low energy feature" which means it can be used without requiring much power from the devices using it. It's the Bluetooth low energy feature which the micro:bit uses.
+
+In the world of Bluetooth low energy, a device has something called a "profile" which defines the way other devices are able to communicate over Bluetooth with it. In a way, the Bluetooth profile defines the way a device appears to other devices in terms of its features and the things it can do.
+
+To put it another way, a Bluetooth profile is really an interface specification. It defines the data which a device has, what another device can do with that data over a Bluetooth connection and how the device with the profile should respond when a connected device acts upon its data in some way. Let's look at that description in a little more technical detail.
+
+## Basic Concepts
+
+A Bluetooth device contains a table of data called an Attribute Table which can be accessed by other connected devices in various possible ways. That table of data and the ways in which it can be exploited falls into a technical area of Bluetooth called the Generic Attribute profile or "GATT" for short and you may see the term GATT in some of the documentation for APIs such as those provided by the Android platform.
+
+The Attribute Table contains something like a series of records of various types. The main types are called Services, Characteristics and Descriptors. Let's look at each of these terms in turn.
+
+### Attributes
+
+Services, Characteristics and Descriptors are all types of Attribute. Hence Generic Attribute Profile, Attribute Table and something called the Attribute Protocol. All attributes have a type which is identified by a UUID (Universally Unique Identifer). Some Attributes are defined by the Bluetooth SIG, the technical standards body for Bluetooth and these have UUIDs which are 16 bits in length. Some Attributes are custom designed for a particular device by the product team and these have 128 bit UUIDs. The micro:bit uses a mixture of 16 bit and 128 bit UUIDs.
+
+### Structure
+
+Services, Characteristics and Descriptors are organised in a hierarchy with Services at the top and Descriptors at the bottom. Services contain one or more Characteristics. A Characteristic owns zero or more Descriptors. Zero because Descriptors are completely optional whereas a Service must contain at least one Characteristic.
+
+![](/static/bluetooth/gatt_hierarchy.png)
+  
+### Services
+
+A Service is a container for logically related Bluetooth data items. Those data items are in fact called Characteristics. A Service can be thought of as the owner of the Characteristics inside it. Often a Service represents a particular feature (e.g. a hardware feature) of a device like the buttons or a particular sensor. An example of a Bluetooth SIG defined Service is the Device Information Service which, as the name suggests, is a container for various items of information about the device such as its manufacturer and serial number. The micro:bit has this service.
+
+### Characteristics
+
+Characteristics are items of data which relate to a particular internal state of the device or perhaps some state of the environment which the device can measure using a sensor. The current battery level is an example of internal state data whereas the ambient temperature could perhaps be measured by a sensor. Sometimes Characteristics represent configuration data such as the frequency at which you want something to be measured. In any of these cases, the way a device can expose such data to other devices to use via Bluetooth is by making them available as a Characteristic. An example of a Bluetooth SIG defined Characteristic is the Serial Number String which you'll find inside the Device Information service.
+
+Characteristics contain various parts. They have a type, a value, some properties and some permissions.
+
+Type is something already explained above, a UUID value which indicates which particular type of Characteristic an Attribute is. Value is the value of the associated state data item.
+
+Properties define what another device can do with the characteristic over Bluetooth in terms of various defined operations such as READ, WRITE or NOTIFY. Reading a characteristic means transferring its current value from the attribute table to the connected device over Bluetooth. Writing allows the connected device to change that value in the state table. Notifications are a special message type which a device like the micro:bit can send to a connected device whenever the value of the associated characteristic changes or perhaps periodically, controlled by a timer. Not all Characteristics support all operations. The Characteristic's properties tell you which operations are supported.
+
+Sometimes the device will have been programmed to respond in a special way when it processes an operation like reading or writing a value from the attribute table so operations can result in more happening than simply transferring data across the connection. Perhaps changing the value of a Characteristic will result in the device changing the frequency with which it samples readings from the device accelerometer for example.
+
+Permissions are to do with security and further describe the security conditions that must be met before read or write access to the characteristic is to be granted.
+
+### Descriptors
+
+Descriptors contain meta data which either augments the details relating to the Characteristic which the Descriptor belongs to or allows the configuration of a behaviour involving that Characteristic. Notification messages are switched on or off using a special descriptor called the Client Characteristic Configuration Descriptor for example.
+
+### Profile
+
+A Bluetooth profile is a specification which pulls together all the required information about how a device behaves, how it can be accessed in terms of its services, characteristics and descriptors, security rules, concurrency limitations and so on.
+
+## Client Server Architecture
+
+When a smartphone application interacts with a device like the micro:bit over a Bluetooth connection we have a client/server architecture. The phone application is usually the GATT client and the micro:bit is usually the GATT server. They communicate using a protocol called the Attribute Protocol or just ATT for short. As a smartphone developer you work with APIs and do not have to worry about formulating ATT protocol data units and so on.
+
+![](/static/bluetooth/services_and_GATT.png)
+
+## Device Discovery
+
+Everything described above relates to devices which are connected and communicating as GATT client and server. But there's a stage which precedes this where the two devices are not yet connected. How do they find each other and connect? The answer to this question is termed 'Device Discovery' and is the responsibility of another part of the Bluetooth architecture called the Generic Access Profile (GAP).
+
+In GAP, one devices advertises, emitting small packets of data periodically. These packets contain information about the device doing the advertising. Other devices looking for devices to connect to perform something called scanning, receiving and processing advertising packets and filtering out those that come from devices of a type that are not of interest. Usually the user is given information about devices which are discovered and they then select one to be connected to. The device which advertises is called a Bluetooth Peripheral whereas the one doing the scanning is a Bluetooth Central device. micro:bit is a Bluetooth peripheral.
+
+Bluetooth on the BBC micro:bit
+
+Full documentation for the BBC micro:bit Bluetooth profile as used by this application can be found at the [Lancaster University documentation](http://lancaster-university.github.io/microbit-docs/ble/profile/) web site.
+
+The micro:bit's accelerometer (motion detector), magnetometer (digital compass), two buttons on the front, LED Display, IO pins on the edge connector, internal message bus and internal temperature sensor are all exposed as Services so that applications can exploit these features of the device. In addition: 
+
+* the Bluetooth SIG defined Device Information Service is included to allow applications to obtain information such as firmware version details over Bluetooth
+* there's a Device Firmware Update (DFU) service which allows new micro:bit code to be flahsed to the device over Bluetooth instead of over USB
+* there's a UART service which allows arbitrary data to be exchanged with the micro:bit in a way resembling traditional serial communications.
+
+Everything you can do with the micro:bit over Bluetooth is achieved through read, write and notify operations. Not all characteristics support all three so check the profile documentation. Often there are Characteristics whose purpose is to allow you to write configuration values which control other behviours. Technically these are called Control Points. For example you can specify the frequency with which accelerometer data is sampled before it is transmitted as a Notification message to your application.
+
+## Want to Know More?
+
+The Bluetooth SIG web site at http://www.bluetooth.com is a good place for further information about Bluetooth in general. You'll find all the SIG defined profiles, services, characteristics and descriptors there as well as the core specification for all Bluetooth technology.
+
+That's it! Enjoy using Bluetooth on the BBC micro:bit!
+
+Martin Woolley, Bluetooth SIG. Twitter: @bluetooth_mdw
+
+#### Video
+https://www.youtube.com/watch?v=aep_GVowKfs
+
+
+### See also
+
+[About Bluetooth](/reference/bluetooth/about-bluetooth), [micro:bit Bluetooth profile overview ](http://lancaster-university.github.io/microbit-docs/ble/profile/), [micro:bit Bluetooth profile reference](http://lancaster-university.github.io/microbit-docs/resources/bluetooth/microbit-profile-V1.9-Level-2.pdf),  [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html), [Bluetooth SIG](https://www.bluetooth.com)
+
+```package
+microbit-bluetooth
+```

docs/reference/bluetooth/bluetooth-pairing.md

@@ -92,7 +92,8 @@ If you do find yourself needing to pair again you will first need to remove the
 
 ### See also
 
-[Bluetooth SIG](https://www.bluetooth.com), [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html)
+[About Bluetooth](/reference/bluetooth/about-bluetooth), [micro:bit Bluetooth profile overview ](http://lancaster-university.github.io/microbit-docs/ble/profile/), [micro:bit Bluetooth profile reference](http://lancaster-university.github.io/microbit-docs/resources/bluetooth/microbit-profile-V1.9-Level-2.pdf),  [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html), [Bluetooth SIG](https://www.bluetooth.com)
+
 
 ```package
 microbit-bluetooth

docs/reference/bluetooth/on-bluetooth-connected.md

@@ -30,7 +30,7 @@ http://www.youtube.com/watch?v=HyBcsD9Eh6I
 
 ### See also
 
-[Bluetooth SIG](https://www.bluetooth.com), [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html)
+[About Bluetooth](/reference/bluetooth/about-bluetooth), [micro:bit Bluetooth profile overview ](http://lancaster-university.github.io/microbit-docs/ble/profile/), [micro:bit Bluetooth profile reference](http://lancaster-university.github.io/microbit-docs/resources/bluetooth/microbit-profile-V1.9-Level-2.pdf),  [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html), [Bluetooth SIG](https://www.bluetooth.com)
 
 ```package
 microbit-bluetooth

docs/reference/bluetooth/on-bluetooth-disconnected.md

@@ -30,7 +30,7 @@ http://www.youtube.com/watch?v=HyBcsD9Eh6I
 
 ### See also
 
-[Bluetooth SIG](https://www.bluetooth.com), [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html)
+[About Bluetooth](/reference/bluetooth/about-bluetooth), [micro:bit Bluetooth profile overview ](http://lancaster-university.github.io/microbit-docs/ble/profile/), [micro:bit Bluetooth profile reference](http://lancaster-university.github.io/microbit-docs/resources/bluetooth/microbit-profile-V1.9-Level-2.pdf),  [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html), [Bluetooth SIG](https://www.bluetooth.com)
 
 ```package
 microbit-bluetooth

docs/reference/bluetooth/start-accelerometer-service.md

@@ -35,7 +35,7 @@ For more advanced information on the micro:bit Bluetooth accelerometer service i
 
 ### See also
 
-[Bluetooth SIG](https://www.bluetooth.com), [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html)
+[About Bluetooth](/reference/bluetooth/about-bluetooth), [micro:bit Bluetooth profile overview ](http://lancaster-university.github.io/microbit-docs/ble/profile/), [micro:bit Bluetooth profile reference](http://lancaster-university.github.io/microbit-docs/resources/bluetooth/microbit-profile-V1.9-Level-2.pdf),  [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html), [Bluetooth SIG](https://www.bluetooth.com)
 
 ```package
 microbit-bluetooth

docs/reference/bluetooth/start-button-service.md

@@ -39,7 +39,7 @@ For more advanced information on the micro:bit Bluetooth button service includin
 
 ### See also
 
-[Bluetooth SIG](https://www.bluetooth.com),[Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html)
+[About Bluetooth](/reference/bluetooth/about-bluetooth), [micro:bit Bluetooth profile overview ](http://lancaster-university.github.io/microbit-docs/ble/profile/), [micro:bit Bluetooth profile reference](http://lancaster-university.github.io/microbit-docs/resources/bluetooth/microbit-profile-V1.9-Level-2.pdf),  [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html), [Bluetooth SIG](https://www.bluetooth.com)
 
 ```package
 microbit-bluetooth

docs/reference/bluetooth/start-io-pin-service.md

@@ -33,7 +33,7 @@ For more advanced information on the micro:bit Bluetooth IO pin service includin
 
 ### See also
 
-[Bluetooth SIG](https://www.bluetooth.com), [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html)
+[About Bluetooth](/reference/bluetooth/about-bluetooth), [micro:bit Bluetooth profile overview ](http://lancaster-university.github.io/microbit-docs/ble/profile/), [micro:bit Bluetooth profile reference](http://lancaster-university.github.io/microbit-docs/resources/bluetooth/microbit-profile-V1.9-Level-2.pdf),  [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html), [Bluetooth SIG](https://www.bluetooth.com)
 
 ```package
 microbit-bluetooth

docs/reference/bluetooth/start-led-service.md

@@ -35,7 +35,7 @@ For more advanced information on the micro:bit Bluetooth LED service including i
 
 ### See also
 
-[Bluetooth SIG](https://www.bluetooth.com), [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html)
+[About Bluetooth](/reference/bluetooth/about-bluetooth), [micro:bit Bluetooth profile overview ](http://lancaster-university.github.io/microbit-docs/ble/profile/), [micro:bit Bluetooth profile reference](http://lancaster-university.github.io/microbit-docs/resources/bluetooth/microbit-profile-V1.9-Level-2.pdf),  [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html), [Bluetooth SIG](https://www.bluetooth.com)
 
 ```package
 microbit-bluetooth

docs/reference/bluetooth/start-magnetometer-service.md

@@ -35,7 +35,7 @@ For more advanced information on the micro:bit Bluetooth magnetometer service in
 
 ### See also
 
-[Bluetooth SIG](https://www.bluetooth.com), [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html)
+[About Bluetooth](/reference/bluetooth/about-bluetooth), [micro:bit Bluetooth profile overview ](http://lancaster-university.github.io/microbit-docs/ble/profile/), [micro:bit Bluetooth profile reference](http://lancaster-university.github.io/microbit-docs/resources/bluetooth/microbit-profile-V1.9-Level-2.pdf),  [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html), [Bluetooth SIG](https://www.bluetooth.com)
 
 
 ```package

docs/reference/bluetooth/start-temperature-service.md

@@ -35,7 +35,7 @@ For more advanced information on the micro:bit Bluetooth temperature service inc
 
 ### See also
 
-[Bluetooth SIG](https://www.bluetooth.com), [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html)
+[About Bluetooth](/reference/bluetooth/about-bluetooth), [micro:bit Bluetooth profile overview ](http://lancaster-university.github.io/microbit-docs/ble/profile/), [micro:bit Bluetooth profile reference](http://lancaster-university.github.io/microbit-docs/resources/bluetooth/microbit-profile-V1.9-Level-2.pdf),  [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html), [Bluetooth SIG](https://www.bluetooth.com)
 
 
 ```package

docs/reference/bluetooth/start-uart-service.md

@@ -37,7 +37,7 @@ For more advanced information on the micro:bit Bluetooth UART service including
 
 ### See also
 
-[Bluetooth SIG](https://www.bluetooth.com), [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html)
+[About Bluetooth](/reference/bluetooth/about-bluetooth), [micro:bit Bluetooth profile overview ](http://lancaster-university.github.io/microbit-docs/ble/profile/), [micro:bit Bluetooth profile reference](http://lancaster-university.github.io/microbit-docs/resources/bluetooth/microbit-profile-V1.9-Level-2.pdf),  [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html), [Bluetooth SIG](https://www.bluetooth.com)
 
 ```package
 microbit-bluetooth

docs/reference/bluetooth/uart-read.md

@@ -18,16 +18,15 @@ bluetooth.uartRead("");
 ### Example: Starting the Bluetooth UART service and then reading data received from another device which is terminated by ":" character and then displaying it
 
 ```blocks
-let uart_data: string = "";
+let uartData = "";
 let connected = 0;
 basic.showString("UART");
-bluetooth.startUartService();
 bluetooth.onBluetoothConnected(() => {
     basic.showString("C");
     connected = 1;
     while (connected == 1) {
-        uart_data = bluetooth.uartRead(":");
-        basic.showString(uart_data);
+        uartData = bluetooth.uartRead(":");
+        basic.showString(uartData);
     }
 });
 bluetooth.onBluetoothDisconnected(() => {
@@ -46,7 +45,7 @@ For more advanced information on the micro:bit Bluetooth UART service including
 
 ### See also
 
-[Bluetooth SIG](https://www.bluetooth.com), [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html)
+[About Bluetooth](/reference/bluetooth/about-bluetooth), [micro:bit Bluetooth profile overview ](http://lancaster-university.github.io/microbit-docs/ble/profile/), [micro:bit Bluetooth profile reference](http://lancaster-university.github.io/microbit-docs/resources/bluetooth/microbit-profile-V1.9-Level-2.pdf),  [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html), [Bluetooth SIG](https://www.bluetooth.com)
 
 ```package
 microbit-bluetooth

docs/reference/bluetooth/uart-write.md

@@ -27,7 +27,6 @@ bluetooth.onBluetoothDisconnected(() => {
     basic.showString("D");
     connected = 0;
 });
-bluetooth.startUartService();
 input.onButtonPressed(Button.A, () => {
     if (connected == 1) {
         bluetooth.uartWrite("HELLO");
@@ -45,7 +44,7 @@ For more advanced information on the micro:bit Bluetooth UART service including
 
 ### See also
 
-[Bluetooth SIG](https://www.bluetooth.com), [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html)
+[About Bluetooth](/reference/bluetooth/about-bluetooth), [micro:bit Bluetooth profile overview ](http://lancaster-university.github.io/microbit-docs/ble/profile/), [micro:bit Bluetooth profile reference](http://lancaster-university.github.io/microbit-docs/resources/bluetooth/microbit-profile-V1.9-Level-2.pdf),  [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html), [Bluetooth SIG](https://www.bluetooth.com)
 
 ```package
 microbit-bluetooth

docs/reference/control/device-name.md

@@ -0,0 +1,11 @@
+# Device Name
+
+Gets a friendly name for the device derived from the its serial number.
+
+```sig
+control.deviceName();
+```
+
+**This is an advanced API.**  For more information, see the
+[micro:bit runtime messageBus documentation](https://lancaster-university.github.io/microbit-docs/ubit/messageBus/).
+

docs/reference/control/device-serial-number.md

@@ -0,0 +1,10 @@
+# Device Serial Number
+
+Derive a unique, consistent serial number of this device from internal data.
+
+```sig
+control.deviceSerialNumber();
+```
+
+**This is an advanced API.**  For more information, see the
+[micro:bit runtime messageBus documentation](https://lancaster-university.github.io/microbit-docs/ubit/messageBus/).

docs/reference/control/event-source-id.md

@@ -0,0 +1,10 @@
+# Event Source ID
+
+Return a code representing the origin of the event on the bus (button, pin, radio, and so on).
+
+```sig
+control.eventSourceId(EventBusSource.MICROBIT_ID_BUTTON_A);
+```
+
+**This is an advanced API.**  For more information, see the
+[micro:bit runtime messageBus documentation](https://lancaster-university.github.io/microbit-docs/ubit/messageBus/)

docs/reference/control/event-timestamp.md

@@ -0,0 +1,10 @@
+# Event Timestamp
+
+Get the timestamp of the last event executed on the bus
+
+```sig
+control.eventTimestamp();
+```
+
+**This is an advanced API.**  For more information, see the
+[micro:bit runtime messageBus documentation](https://lancaster-university.github.io/microbit-docs/ubit/messageBus/).

docs/reference/control/event-value-id.md

@@ -0,0 +1,12 @@
+# Event Value ID
+
+Return a code representing the type of the event (button click, device gesture, and so on). 
+
+```sig
+control.eventValueId(EventBusValue.MICROBIT_EVT_ANY);
+```
+
+
+**This is an advanced API.**  For more information, see the
+[micro:bit runtime messageBus documentation](https://lancaster-university.github.io/microbit-docs/ubit/messageBus/).
+

docs/reference/control/event-value.md

@@ -0,0 +1,12 @@
+# Event Value
+
+Get the value of the last event executed on the bus.
+
+```sig
+control.eventValue();
+```
+
+
+**This is an advanced API.**  For more information, see the
+[micro:bit runtime messageBus documentation](https://lancaster-university.github.io/microbit-docs/ubit/messageBus/).
+

docs/reference/control/in-background.md

@@ -1,15 +1,25 @@
-# In Background
+# Run In Background
 
-Run code in the background as a separate process or thread; for more information on this advanced construct, see [the micro:bit - a reactive system](/device/reactive).
+Run part of a program while the rest of it is doing something else.
 
 ```sig
 control.inBackground(() => {
 })
 ```
 
+### ~hint
+
+For more information, read 
+[The micro:bit - a reactive system](/device/reactive).
+It is pretty advanced!
+
+### ~
+
 ### Example
 
-The example below shows how a background process can be used to display the current value of the global variable `num`, while code (like the `on button pressed` handler) can change the value of the variable.
+This program shows how running in the background can say what is
+stored in a variable like `num`, while another part (``on button pressed``)
+changes what is stored there.
 
 ```blocks
 let num = 0
@@ -24,7 +34,8 @@ input.onButtonPressed(Button.A, () => {
 })
 ```
 
-The code below using the `forever` loop is equivalent to the code above
+This program does the same thing, but in a more usual way,
+with a ``forever`` loop.
 
 ```blocks
 let num = 0
@@ -36,20 +47,8 @@ input.onButtonPressed(Button.A, () => {
 })
 ```
 
-### Contention for the LED display
-
-If you have multiple processes that each show something on the LED screen, you may get unexpected results. Try, for example:
-
-```blocks
-basic.forever(() => {
-    basic.showNumber(6789, 150)
-})
-input.onButtonPressed(Button.A, () => {
-    basic.showNumber(2, 150)
-})
-```
-
 ### See also
 
-[while](/blocks/loops/while), [forever](/reference/basic/forever), [on button pressed](/reference/input/on-button-pressed)
+[while](/blocks/loops/while), [forever](/reference/basic/forever),
+[on button pressed](/reference/input/on-button-pressed)
 

docs/reference/control/on-event.md

@@ -0,0 +1,11 @@
+# On Event
+
+Raise an event in the event bus.
+
+```sig
+control.onEvent(control.eventSourceId(EventBusSource.MICROBIT_ID_BUTTON_A), control.eventValueId(EventBusValue.MICROBIT_EVT_ANY), () => { });
+```
+
+**This is an advanced API.**  For more information, see the
+[micro:bit runtime messageBus documentation](https://lancaster-university.github.io/microbit-docs/ubit/messageBus/).
+

docs/reference/control/raise-event.md

@@ -0,0 +1,10 @@
+# Raise Event
+
+Raise an event in the event bus.
+
+```sig
+control.raiseEvent(control.eventSourceId(EventBusSource.MICROBIT_ID_BUTTON_A), control.eventValueId(EventBusValue.MICROBIT_EVT_ANY));
+```
+
+**This is an advanced API.**  For more information, see the
+[micro:bit runtime messageBus documentation](https://lancaster-university.github.io/microbit-docs/ubit/messageBus/)

docs/reference/game/change-sprite-property.md

@@ -0,0 +1,37 @@
+# Get Sprite Property
+
+Change the kind of [number](/reference/types/number) you say for a [sprite](/reference/game/create-sprite).
+
+```sig
+let item: game.LedSprite = null;
+item.set(LedSpriteProperty.X, 0);
+```
+
+### Parameters
+
+* the **sprite** you want to change
+* the kind of [number](/reference/types/number) you want to change for the sprite, like
+    * ``x``, how far up or down the sprite is on the screen (`0`-`4`)
+    * ``y``, how far left or right the sprite is on the screen (`0`-`4`)
+    * ``direction``, which way the sprite is pointing (this works the same way as the [turn](/reference/game/turn) function)
+    * ``brightness``, how bright the LED sprite is (this works the same way as the [brightness](/reference/led/brightness) function)
+    * ``blink``, how fast the sprite is blinking (the bigger the number is, the faster the sprite is blinking)
+
+### Example
+
+This program makes a sprite on the left side of the screen,
+waits two seconds (2000 milliseconds),
+and then moves it to the middle of the screen.
+
+```blocks
+let ball = game.createSprite(0, 2);
+basic.pause(2000);
+ball.change(LedSpriteProperty.X, 2);
+```
+
+### See also
+
+[turn](/reference/game/turn),
+[brightness](/reference/led/brightness),
+[get sprite property](/reference/game/get-sprite-property),
+[set sprite property](/reference/game/set-sprite-property)

docs/reference/game/change.md

@@ -1,21 +0,0 @@
-# Change
-
-Sprite will change the x position by this number
-
-### Block Editor
-
-![](/static/mb/change-0.png)
-
-### JavaScript
-
-Sprite will change the x position by this number
-
-```
-export function changeXBy(_this: micro_bitSprites.LedSprite, x: number)
-```
-
-Sprite will change the y position by this number
-
-```
-export function changeYBy(_this: micro_bitSprites.LedSprite, y: number)
-```

docs/reference/game/create-sprite.md

@@ -0,0 +1,37 @@
+# Create Sprite
+
+Create a new LED sprite pointing to the right.
+
+A sprite is like a little LED creature you can tell what to do.
+You can tell it to move, turn, and check whether it has bumped
+into another sprite.
+
+```sig
+game.createSprite(2, 2);
+```
+
+### Parameters
+
+* ``x``: The left-to-right place on the LED screen where the sprite will start out.
+* ``y``: The top-to-bottom place on the LED screen where the sprite will start out.
+
+`0` and `4` mean the edges of the screen, and `2` means in the middle.
+
+### Example
+
+This program starts a sprite in the middle of the screen.
+Next, the sprite turns toward the lower-right corner.
+Finally, it moves two LEDs away to the corner.
+
+```blocks
+let item = game.createSprite(2, 2);
+item.turn(Direction.Right, 45);
+item.move(2);
+```
+
+### See also
+
+[move](/reference/game/move),
+[turn](/reference/game/turn),
+[touching](/reference/game/touching)
+

docs/reference/game/game-library.md

@@ -86,7 +86,7 @@ Sprite - If the sprite is on the edge, the sprite will bounce
 ![](/static/mb/game-library/if-on-edge-bounce-0.png)
 
 ```
-export function ifOnEdge_Bounce(_this: micro_bitSprites.LedSprite)
+export function ifOnEdgeBounce(_this: micro_bitSprites.LedSprite)
 ```
 
 ### [Change score by](/reference/game/change-score-by)

docs/reference/game/game-over.md

@@ -2,6 +2,10 @@
 
 End the game and show the score.
 
+```sig
+game.gameOver();
+```
+
 ### Example
 
 This program asks you to pick a button.

docs/reference/game/get-sprite-property.md

@@ -0,0 +1,39 @@
+# Get Sprite Property
+
+Find something out about a [sprite](/reference/game/create-sprite).
+
+```sig
+let item: game.LedSprite = null;
+item.get(LedSpriteProperty.X);
+```
+
+### Parameters
+
+* the **sprite** you want to know something about
+* the kind of [number](/reference/types/number) you want to know about the sprite, like
+    * ``x``, how far up or down the sprite is on the screen (`0`-`4`)
+    * ``y``, how far left or right the sprite is on the screen (`0`-`4`)
+    * ``direction``, which way the sprite is pointing (this works the same way as the [turn](/reference/game/turn) function)
+    * ``brightness``, how bright the LED sprite is (this works the same way as the [brightness](/reference/led/brightness) function)
+    * ``blink``, how fast the sprite is blinking (the bigger the number is, the faster the sprite is blinking)
+
+### Returns
+
+The [number](/reference/types/number) you asked for.
+
+### Example
+
+This program makes a sprite and shows the number of its brightness on the screen. 
+
+```blocks
+let ball = game.createSprite(0, 2);
+basic.showNumber(ball.get(LedSpriteProperty.Brightness));
+```
+
+### See also
+
+[turn](/reference/game/turn),
+[brightness](/reference/led/brightness),
+[change sprite property](/reference/game/change-sprite-property),
+[set sprite property](/reference/game/set-sprite-property)
+

docs/reference/game/if-on-edge-bounce.md

@@ -0,0 +1,34 @@
+# If On Edge, Bounce
+
+Make a [sprite](/reference/game/create-sprite) on the edge of the
+[LED screen](/device/screen) bounce away.
+
+```sig
+let item = game.createSprite(0, 2);
+item.ifOnEdgeBounce();
+```
+
+### Parameters
+
+* a **sprite** that might be on the edge of the LED screen.
+
+### Example
+
+This program makes a sprite on the right edge of the screen with a
+direction of 90 degrees, and bounces it so it has a direction of -90
+degrees -- exactly the opposite direction.
+
+```blocks
+let ball = game.createSprite(4, 2);
+basic.showNumber(ball.get(LedSpriteProperty.Direction));
+input.onButtonPressed(Button.B, () => {
+    ball.ifOnEdgeBounce();
+    basic.showNumber(ball.get(LedSpriteProperty.Direction));
+});
+```
+
+### See also
+
+[create sprite](/reference/game/create-sprite),
+[touching](/reference/game/touching),
+[touching edge](/reference/game/touching-edge)

docs/reference/game/move.md

@@ -1,7 +1,29 @@
 # Move
 
-Sprite move by a certain number of LEDs
+Move the sprite the number of LEDs you say.
 
+```sig
+let item: game.LedSprite = null;
+item.move(1);
 ```
-export function move(_this: micro_bitSprites.LedSprite, leds: number)
+
+### Parameters
+
+* a [number](/reference/types/number) that means how many LEDs the sprite should move
+
+### Example
+
+This program starts a sprite in the middle of the screen.
+Next, the sprite turns toward the lower-right corner.
+Finally, it moves two LEDs away to the corner.
+
+```blocks
+let item = game.createSprite(2, 2);
+item.turn(Direction.Right, 45);
+item.move(2);
 ```
+
+### See also
+
+[turn](/reference/game/turn),
+[create sprite](/reference/game/create-sprite)

docs/reference/game/set-sprite-property.md

@@ -0,0 +1,37 @@
+# Set Sprite Property
+
+Make a [sprite](/reference/game/create-sprite) store the kind of [number](/reference/types/number) you say.
+
+```sig
+let item: game.LedSprite = null;
+item.set(LedSpriteProperty.X, 0);
+```
+
+### Parameters
+
+* the **sprite** you want to make store the number you say
+* the kind of [number](/reference/types/number) you want to store in the sprite, like
+    * ``x``, how far up or down the sprite is on the screen (`0`-`4`)
+    * ``y``, how far left or right the sprite is on the screen (`0`-`4`)
+    * ``direction``, which way the sprite is pointing (this works the same way as the [turn](/reference/game/turn) function)
+    * ``brightness``, how bright the LED sprite is (this works the same way as the [brightness](/reference/led/brightness) function)
+    * ``blink``, how fast the sprite is blinking (the bigger the number is, the faster the sprite is blinking)
+
+### Example
+
+This program makes a sprite on the left side of the screen,
+waits two seconds (2000 milliseconds),
+and then moves it to the right side of the screen.
+
+```blocks
+let ball = game.createSprite(0, 2);
+basic.pause(2000);
+ball.set(LedSpriteProperty.X, 4);
+```
+
+### See also
+
+[turn](/reference/game/turn),
+[brightness](/reference/led/brightness),
+[change sprite property](/reference/game/change-sprite-property),
+[get sprite property](/reference/game/get-sprite-property)

docs/reference/game/start-countdown.md

@@ -8,7 +8,7 @@ game.startCountdown(1000)
 
 ### Parameters
 
-* a [number](/reference/types/number) that means how many milliseconds to count down (one second is 1000 milliseconds)
+* ``ms`` is a [number](/reference/types/number) that says how many milliseconds to count down (one second is 1000 milliseconds)
 
 ### Examples
 

docs/reference/game/touching-edge.md

@@ -0,0 +1,40 @@
+# Touching Edge
+
+Find whether the sprite is touching the edge of the [LED screen](/device/screen).
+
+Sprites are touching the edge if they overlap with an LED on the edge
+of the screen.
+
+```sig
+let item: game.LedSprite = null;
+item.isTouchingEdge();
+```
+
+### Parameters
+
+* a **sprite** that might be touching the edge of the screen
+
+### Returns
+
+`true` if the sprite is touching the edge of the screen
+
+### Example
+
+This program makes a sprite in the middle of the left edge of the LED screen.
+Then it says `EDGY!` if it's on the edge (which it is!), and `SAFE!` if it's
+not on the edge.
+
+```blocks
+let item = game.createSprite(0, 2);
+if (item.isTouchingEdge()) {
+    basic.showString("EDGY!");
+} else {
+    basic.showString("SAFE!");
+}
+```
+	
+### See also
+
+[create sprite](/reference/game/create-sprite),
+[touching](/reference/game/touching),
+[if on edge, bounce](/reference/game/if-on-edge-bounce)

docs/reference/game/touching.md

@@ -1,8 +1,41 @@
 # Touching
 
-Reports true if sprite is touching specified sprite
+Find whether the sprite is touching another sprite you say.
 
-```
-export function isTouching(_this: micro_bitSprites.LedSprite, other: micro_bitSprites.LedSprite) : boolean
+Sprites are touching if they share the same LED.
+
+```sig
+let item: game.LedSprite = null;
+item.isTouching(null);
 ```
 
+### Parameters
+
+* a **sprite** you are checking
+* another **sprite** that might be touching the one you are checking
+
+### Returns
+
+`true` if the two sprites are touching.
+
+### Example
+
+This program creates two sprites called ``matter`` and ``antimatter``,
+and then checks whether they are touching.  If they are, there is an
+explosion.
+
+```blocks
+let matter = game.createSprite(2, 2);
+let antimatter = game.createSprite(2, 2);
+if (matter.isTouching(antimatter)) {
+    basic.pause(500);
+    basic.clearScreen();
+    basic.showString("BOOM!");
+}
+```
+
+### See also
+
+[create sprite](/reference/game/create-sprite),
+[touching edge](/reference/game/touching-edge),
+[if on edge, bounce](/reference/game/if-on-edge-bounce)

docs/reference/game/turn.md

@@ -1,14 +1,33 @@
 # Turn
 
-Rotates a sprite to the right by a certain number of degrees
+Turn the sprite as much as you say in the direction you say.
 
-```
-export function turnRight(_this: micro_bitSprites.LedSprite, degrees: number)
+```sig
+let item: game.LedSprite = null;
+item.turn(Direction.Right, 45);
 ```
 
-Rotates a sprite to the left by a certain number of degrees
+### Parameters
 
-```
-export function turnLeft(_this: micro_bitSprites.LedSprite, degrees: number)
+* a choice whether the sprite should turn **left** or **right**
+* a [number](/reference/types/number) that means how much the sprite should turn.
+  This number is in **degrees**, so a straight left or right turn is 90 degrees.
+
+### Example
+
+
+This program starts a sprite in the middle of the screen.
+Next, the sprite turns toward the lower-right corner.
+Finally, it moves two LEDs away to the corner.
+
+```blocks
+let item = game.createSprite(2, 2);
+item.turn(Direction.Right, 45);
+item.move(2);
 ```
 
+### See also
+
+
+[move](/reference/game/move),
+[create sprite](/reference/game/create-sprite)

docs/reference/images/create-big-image.md

@@ -4,7 +4,7 @@ Make a big [image](/reference/images/image) (picture) for the micro:bit
 [LED screen](/device/screen). The big image made of two squares.
 Each of the squares is five LEDs on a side, like a regular image.
 
-```blocks
+```sig
 images.createBigImage(`
     . . # . .   . . # . .
     . # # # .   . . # . .
@@ -14,6 +14,12 @@ images.createBigImage(`
     `);
 ```
 
+### Parameters
+
+* ``leds`` is a [string](/reference/types/string) that says which LEDs
+on the screen should be on and which should be off.
+
+
 ### Example: Flip-flopping arrow
 
 This program makes a big image with a picture of an arrow pointing up,

docs/reference/images/create-image.md

@@ -13,6 +13,11 @@ images.createImage(`
 `)
 ```
 
+### Parameters
+
+* ``leds`` is a [string](/reference/types/string) that says which LEDs
+on the screen should be on and which should be off.
+
 ### Example: Flip-flopping arrow
 
 If you press button `A`, this program will make a picture of an

docs/reference/images/scroll-image.md

@@ -3,9 +3,14 @@
 Scroll (slide) an [image](/reference/images/image) (picture) from one
 side to the other of the [LED screen](/device/screen).
 
+```sig
+let item: Image = null;
+item.scrollImage(5, 200);
+```
+
 ### Parameters
 
-* ``offset`` is a [number](/reference/types/number) that means
+* a [number](/reference/types/number) that means
   how many LEDs to scroll at a time, from right to left or
   left to right. If you use a positive number like `2`, the image
   will scroll from the right side of the screen to the left.
@@ -15,7 +20,7 @@ side to the other of the [LED screen](/device/screen).
   image. It is a square with five LEDs on a side). This is
   useful for **animation**.
 
-* ``interval (ms)`` is a [number](/reference/types/number) that means
+* a [number](/reference/types/number) that means
   how many milliseconds to wait before scrolling the amount that
   ``offset`` says. (1000 milliseconds is one second.) The bigger you
   make this number, the slower the image will scroll.

docs/reference/images/show-image.md

@@ -4,6 +4,11 @@ Show an [image](/reference/images/image) (picture) on the
 [LED screen](/device/screen).  After the micro:bit shows an image, it
 will pause for 400 milliseconds (1000 milliseconds is one second).
 
+```sig
+let item: Image = null;
+item.showImage(0);
+```
+
 ### Parameters
 
 * an [image](/reference/images/image) (picture). It is usually a square with five LEDs on a side, but it might be wider. 

docs/reference/input/acceleration.md

@@ -19,7 +19,7 @@ A **g** is as much acceleration as you get from Earth's gravity.
 
 ### Parameters
 
-* which direction you are checking for acceleration, either `Dimension.X` (left and right), `Dimension.Y` (forward and backward), or `Dimension.Z` (up and down)
+* ``dimension`` means which direction you are checking for acceleration, either `Dimension.X` (left and right), `Dimension.Y` (forward and backward), or `Dimension.Z` (up and down)
 
 ### Returns
 
@@ -38,5 +38,7 @@ basic.forever(() => {
 
 ### See also
 
-[compass-heading](/reference/input/compass-heading), [lightlevel](/reference/input/light-level)
+[set accelerometer range](/reference/input/set-accelerometer-range),
+[compass heading](/reference/input/compass-heading),
+[light level](/reference/input/light-level)
 

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

@@ -8,7 +8,7 @@ input.buttonIsPressed(Button.A);
 
 ### Parameters
 
-* ``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.
+* ``button`` 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
 

docs/reference/input/magnetic-force.md

@@ -15,7 +15,10 @@ The micro:bit measures magnetic force with **microteslas**.
 
 ### Parameters
 
-* a [string](/reference/types/string) that says which direction the micro:bit should measure magnetic force in: either `x` (the left-right direction), `y` (the forward/backward direction), or `z` (the up/down direction)
+* ``dimension`` means which direction the micro:bit should measure
+  magnetic force in: either `Dimension.X` (the left-right direction),
+  `Dimension.Y` (the forward/backward direction), or `Dimension.Z`
+  (the up/down direction)
 
 ### Returns
 

docs/reference/input/on-gesture.md

@@ -2,14 +2,18 @@
 
 Start an [event handler](/reference/event-handler) (part of the
 program that will run when something happens) This handler works when
-you do a **gesture** (like shake, tilt, or drop the micro:bit).
+you do a **gesture** (like shaking the micro:bit).
 
 ```sig
 input.onGesture(Gesture.Shake,() => {
 })
 ```
 
-## Example: random number
+### Parameters
+
+* ``gesture`` means the way you hold or move the micro:bit. This can be `shake`, `logo up`, `logo down`, `screen up`, `screen down`, `tilt left`, `tilt right`, `free fall`, `3g`, or `6g`.
+
+### Example: random number
 
 This program shows a number from `0` to `9` when you shake the micro:bit.
 

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

@@ -1,14 +1,16 @@
 # On Pin Pressed
 
-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 you press pin `0`, `1`, or `2` together with `GND`.
-When you are using this function in a web browser, click the pins on the screen instead of the ones
-on the BBC micro:bit.
+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 you press pin `0`, `1`, or `2`
+together with `GND`.  When you are using this function in a web
+browser, click the pins on the screen instead of the ones on the BBC
+micro:bit.
 
-If you hold the `GND` pin with one hand and touch pin `0`, `1`, or `2` with the other,
-a very small (safe) amount of electricity will flow through your body and back into
-the micro:bit. This is called **completing a circuit**. It's like you're a big wire!
+If you hold the `GND` pin with one hand and touch pin `0`, `1`, or `2`
+with the other, a very small (safe) amount of electricity will flow
+through your body and back into the micro:bit. This is called
+**completing a circuit**. It's like you're a big wire!
 
 ```sig
 input.onPinPressed(TouchPin.P0, () => {
@@ -22,6 +24,10 @@ instead of the USB cable.
 
 ## ~
 
+## Parameters
+
+* ``name`` means the pin that is being pressed, either `P0`, `P1`, or `P2`
+
 ### Example: pin pressed counter
 
 This program counts how many times you press the `P0` pin. 

docs/reference/input/rotation.md

@@ -15,7 +15,7 @@ check how the micro:bit is moving.
 
 ### Parameters
 
-* which direction you are checking: `Rotation.Pitch` (up and down) or `Rotation.Roll` (left and right)
+* ``kind`` means which direction you are checking: `Rotation.Pitch` (up and down) or `Rotation.Roll` (left and right)
 
 ### Returns
 

docs/reference/input/set-accelerometer-range.md

@@ -0,0 +1,41 @@
+# Set Accelerometer Range
+
+Set up the part of the micro:bit that measures
+[acceleration](/reference/input/acceleration) (how much the microbit
+is speeding up or slowing down), in case you need to measure high
+or low acceleration.
+
+```sig
+input.setAccelerometerRange(AcceleratorRange.OneG);
+```
+
+### Parameters
+
+* ``range`` means the biggest number of gravities of acceleration you
+  will be measuring (either `1g`, `2g`, `4g`, or `8g`).  Any bigger numbers
+  will be ignored by your micro:bit, both when you are picking a
+  number of gravities, and when you are measuring acceleration.
+
+### Example
+
+This program says the highest acceleration that your micro:bit
+will measure is 4G. Then it measures acceleration from side to side
+until you stop the program.
+
+```blocks
+input.setAccelerometerRange(AcceleratorRange.FourG);
+basic.forever(() => {
+    basic.showNumber(input.acceleration(Dimension.X));
+});
+```
+
+#### ~hint
+
+This program does not work in the simulator, only in a micro:bit.
+
+#### ~
+
+### See Also
+
+[compass heading](/reference/input/compass-heading),
+[light level](/reference/input/light-level)

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

@@ -9,8 +9,13 @@ led.plotBarGraph(2, 20);
 
 ### Parameters
 
-* `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.
+* ``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
 

docs/reference/led/plot.md

@@ -14,8 +14,11 @@ Use [unplot](/reference/led/unplot) to turn **off** an LED.
 
 ### Parameters
 
-* **x** is a [number](/reference/types/number) that means the horizontal spot on the LED screen (from left to right: 0, 1, 2, 3, or 4)
-* **y** is a [number](/reference/types/number) that means the vertical spot on the LED screen (from top to bottom: 0, 1, 2, 3, or 4)
+* ``x`` is a [number](/reference/types/number) that means the
+  horizontal spot on the LED screen (from left to right: 0, 1, 2, 3,
+  or 4)
+* ``y`` is a [number](/reference/types/number) that means the vertical
+  spot on the LED screen (from top to bottom: 0, 1, 2, 3, or 4)
 
 If a parameter is [out of bounds](/reference/out-of-bounds) (a value
 other than 0 to 4), then this function will do nothing.

docs/reference/led/point.md

@@ -9,8 +9,11 @@ led.point(0,0);
 
 ### Parameters
 
-* **x** is a [number](/reference/types/number) that means the horizontal spot on the LED screen (from left to right: 0, 1, 2, 3, or 4)
-* **y** is a [number](/reference/types/number) that means the vertical spot on the LED screen (from top to bottom: 0, 1, 2, 3, or 4)
+* ``x`` is a [number](/reference/types/number) that means the
+  horizontal spot on the LED screen (from left to right: 0, 1, 2, 3,
+  or 4)
+* ``y`` is a [number](/reference/types/number) that means the vertical
+  spot on the LED screen (from top to bottom: 0, 1, 2, 3, or 4)
 
 If a parameter is [out of bounds](/reference/out-of-bounds) (a value
 other than 0 to 4), this function will return `false`.

docs/reference/led/set-brightness.md

@@ -9,13 +9,16 @@ led.setBrightness(121)
 
 ### Parameters
 
-* a [number](/reference/types/number) that means how bright the screen is when it is turned on, from `0` (darkest) to `255` (brightest). For example, the number `127` means the screen is halfway bright when it is turned on.
+* ``value`` is a [number](/reference/types/number) that means how
+  bright the screen is when it is turned on, from `0` (darkest) to
+  `255` (brightest). For example, the number `127` means the screen is
+  halfway bright when it is turned on.
 
 ### Example: change brightness
 
-This program makes the screen brightness 100% (255).  Then it turns on
+This program makes the screen brightness 100% (`255`).  Then it turns on
 the center LED (`2, 2`), waits for one second, and then sets the screen
-brightness to 50% (128):
+brightness to 50% (`128`):
 
 ```blocks
 led.setBrightness(255)
@@ -27,4 +30,3 @@ led.setBrightness(led.brightness() / 2)
 ### See also
 
 [brightness](/reference/led/brightness), [fade in](/reference/led/fade-in), [fade out](/reference/led/fade-out), [LED screen](/device/screen)
-

docs/reference/led/stop-animation.md

@@ -1,8 +1,22 @@
 # Stop Animation
 
-Cancels the current animation and clears other pending animations .
+Stop the animation that is playing and any animations that are waiting to
+play.
 
 ```sig
 led.stopAnimation()
 ```
 
+### Example
+
+This program...
+
+```blocks
+basic.showString("STOP ME! STOP ME! PLEASE, WON'T SOMEBODY STOP ME?");
+input.onButtonPressed(Button.B, () => {
+    led.stopAnimation();
+});
+'```
+### See Also
+
+

docs/reference/led/unplot.md

@@ -14,8 +14,11 @@ Use [plot](/reference/led/plot) to turn **on** an LED.
 
 ### Parameters
 
-* **x** is a [number](/reference/types/number) that means the horizontal spot on the LED screen (from left to right: 0, 1, 2, 3, or 4)
-* **y** is a [number](/reference/types/number) that means the vertical spot on the LED screen (from top to bottom: 0, 1, 2, 3, or 4)
+* ``x`` is a [number](/reference/types/number) that means the
+  horizontal spot on the LED screen (from left to right: 0, 1, 2, 3,
+  or 4)
+* ``y`` is a [number](/reference/types/number) that means the vertical
+  spot on the LED screen (from top to bottom: 0, 1, 2, 3, or 4)
 
 If a parameter is [out of bounds](/reference/out-of-bounds) (a value
 other than 0 to 4), then this function will do nothing.

docs/reference/music/change-tempo-by.md

@@ -13,7 +13,9 @@ music.changeTempoBy(20)
 
 ### Parameters
 
-* a [number](/reference/types/number) that says how much to change the bpm (beats per minute, or number of beats in a minute of the music that the micro:bit is playing).
+* ``bpm`` is a [number](/reference/types/number) that says how much to
+  change the bpm (beats per minute, or number of beats in a minute of
+  the music that the micro:bit is playing).
 
 ### Examples
 

docs/reference/music/play-tone.md

@@ -12,8 +12,8 @@ music.playTone(440, 120)
 
 ### Parameters
 
-* `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.
+* ``frequency`` is the [number](/reference/types/number) of Hertz (how high or low the tone is).
+* ``ms`` is the [number](/reference/types/number) of milliseconds that the tone lasts
 
 ## Example
 

docs/reference/music/rest.md

@@ -12,7 +12,9 @@ music.rest(400)
 
 ### Parameters
 
-* a [number](/reference/types/number) saying how many milliseconds the micro:bit should rest. One second is 1000 milliseconds.
+* ``ms`` is a [number](/reference/types/number) saying how many
+  milliseconds the micro:bit should rest. One second is 1000
+  milliseconds.
 
 ## Example
 

docs/reference/music/ring-tone.md

@@ -13,8 +13,8 @@ music.ringTone(440)
 
 ### Parameters
 
-* a [number](/reference/types/number) that says the tone's
-**frequency** (how high-pitched or low-pitched the tone is).  This
+* ``frequency`` is a [number](/reference/types/number) that says
+how high-pitched or low-pitched the tone is.  This
 number is in **Hz** (**Hertz**), which is a measurement of frequency
 or pitch.
 

docs/reference/music/set-tempo.md

@@ -11,7 +11,7 @@ This function only works on the micro:bit and in some browsers.
 
 ### Parameters
 
-* a [number](/reference/types/number) that means the bpm you want (beats per minute, or number of beats in a minute of the music that the micro:bit is playing).
+* ``bpm`` is a [number](/reference/types/number) that means the beats per minute you want (the number of beats in a minute of the music that the micro:bit is playing).
 
 ### See also
 

docs/reference/music/tempo.md

@@ -8,7 +8,8 @@ music.tempo()
 
 ### Returns
 
-* 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).
+* a [number](/reference/types/number) that means the beats per minute (number of
+  beats in a minute of the music that the micro:bit is playing).
 
 ### See also
 

docs/reference/pins/analog-pitch.md

@@ -1,6 +1,6 @@
 # Analog Pitch
 
-Emits a Pulse With Modulation (PWM) signal to the current pitch [pin](/device/pins). Use [analog set pitch pin](/reference/pins/analog-set-pitch-pin) to set the pitch pin.
+Emits a Pulse With Modulation (PWM) signal to the current pitch [pin](/device/pins). Use [analog set pitch pin](/reference/pins/analog-set-pitch-pin) to set the current pitch pin.
 
 ```sig
 pins.analogPitch(440, 300)

docs/reference/pins/analog-read-pin.md

@@ -9,7 +9,7 @@ pins.analogReadPin(AnalogPin.P0)
 
 ### Parameters
 
-* a [string](/reference/types/string) that stores the name of the pin
+* ``name`` is a [string](/reference/types/string) with the name of the pin
   you say (`P0` through `P4`, or `P10`)
 
 ### Returns
@@ -26,6 +26,12 @@ basic.forever(() => {
 });
 ```
 
+#### ~hint
+
+If you are using **analog read pin** with another micro:bit running **analog write pin**, then things can get tricky. Remember that the micro:bit that runs **analog set pin** writes 0's and 1's at a very high frequency to achieve an average of the desired value. Sadly, if you try to read that average from another micro:bit, then the micro:bit will either read 0 or 1023. You could try to read a higher number of values (e.g. a million) in a loop, then computer then average. Alternatively, you can plug in a capacitor in-between the two micro:bits.
+
+#### ~
+
 ### See also
 
 [micro:bit pins](/device/pins),

docs/reference/pins/analog-set-period.md

@@ -1,6 +1,8 @@
 # Analog Set Period
 
-Configures the period of the Pulse Width Modulation (PWM) on the specified analog [pin](/device/pins) (``P0``, ``P1`` or ``P2``). Prior to calling this function, the given pin should be set as analog.
+Configure the period of Pulse Width Modulation (PWM) on the specified 
+analog [pin](/device/pins).
+Before you call this function, you should set the specified pin as analog.
 
 ```sig
 pins.analogSetPeriod(AnalogPin.P0, 20000)
@@ -8,10 +10,11 @@ pins.analogSetPeriod(AnalogPin.P0, 20000)
 
 ### Parameters
 
-* `name` - [String](/reference/types/string); the pin name ("P0", "P1", or "P2")
-* `micros` - a [Number](/reference/types/number) representing the micro-seconds of the analog period.
+* ``name``: a [string](/reference/types/string) that specifies the pin to configure (`P0` through `P4`, or `P10`)
+* ``micros``: a [number](/reference/types/number) that specifies the analog period in microseconds.
 
-The following code
+The following code first sets `P0` to analog with **analog write
+pin**, and then sets the PWM period of `P0` to 20,000 microseconds.
 
 ```blocks
 pins.analogWritePin(AnalogPin.P0, 512)
@@ -20,5 +23,9 @@ pins.analogSetPeriod(AnalogPin.P0, 20000)
 
 ### See also
 
-[micro:bit pins](/device/pins), [on pin pressed](/reference/input/on-pin-pressed), [analog read pin](/reference/pins/analog-read-pin), [digital read pin](/reference/pins/digital-read-pin), [digital write pin](/reference/pins/digital-write-pin)
-
+[micro:bit pins](/device/pins),
+[on pin pressed](/reference/input/on-pin-pressed),
+[analog read pin](/reference/pins/analog-read-pin),
+[analog write pin](/reference/pins/analog-write-pin),
+[digital read pin](/reference/pins/digital-read-pin),
+[digital write pin](/reference/pins/digital-write-pin)

docs/reference/pins/analog-write-pin.md

@@ -1,6 +1,7 @@
 # Analog Write Pin
 
-Write to the specified [pin](/device/pins) (P0, P1, P2) as analog.
+Write an **analog** signal (`0` through `1023`) to the
+[pin](/device/pins) you say.
 
 ```sig
 pins.analogWritePin(AnalogPin.P0, 400)
@@ -8,15 +9,25 @@ pins.analogWritePin(AnalogPin.P0, 400)
 
 ### Parameters
 
-* `name` - [String](/reference/types/string); the pin name ("P0", "P1", or "P2")
-* `value` - a [Number](/reference/types/number) between 0 and 1023 included
+* ``name`` is a [string](/reference/types/string) that is the pin name you say (`P0` through `P4`, or `P10`)
+* ``value`` is a [number](/reference/types/number) from `0` through `1023`
 
-The following code writes `1023` to the `P0` pin:
+### Example
+
+This program writes `1023` to pin `P0`.
 
 ```blocks
 pins.analogWritePin(AnalogPin.P0, 1023)
 ```
 
+#### ~hint
+
+When you tell it to write `256` (for example), this function does not
+_really_ write `256`.  Instead, it writes a lot of different numbers,
+and their average is `256`.
+
+#### ~
+
 ### See also
 
 [micro:bit pins](/device/pins), [on pin pressed](/reference/input/on-pin-pressed), [analog read pin](/reference/pins/analog-read-pin), [digital read pin](/reference/pins/digital-read-pin), [digital write pin](/reference/pins/digital-write-pin)

docs/reference/pins/digital-read-pin.md

@@ -16,7 +16,7 @@ Please read the [page about pins](/device/pins) carefully.
 
 ### Parameters
 
-* a [string](/reference/types/string) that stores the name of the pin (``P0``, ``P1``, or ``P2``, up through ``P20``)
+* ``name`` is a [string](/reference/types/string) that stores the name of the pin (``P0``, ``P1``, or ``P2``, up through ``P20``)
 
 ### Returns
 

docs/reference/pins/digital-write-pin.md

@@ -16,8 +16,8 @@ Please read the [page about pins](/device/pins) carefully.
 
 ### Parameters
 
-* a [string](/reference/types/string) that stores the name of the pin (``P0``, ``P1``, or ``P2``, up through ``P20``)
-* a [number](/reference/types/number) that can be either `0` or `1`
+* ``name`` is a [string](/reference/types/string) that stores the name of the pin (``P0``, ``P1``, or ``P2``, up through ``P20``)
+* ``value`` is a [number](/reference/types/number) that can be either `0` or `1`
 
 ### Example: football score keeper
 

docs/reference/pins/i2c-read-number.md

@@ -0,0 +1,32 @@
+# I2C Read Number
+
+Read one number from the specified 7-bit I2C address, in the specified
+number format.
+
+```sig
+pins.i2cReadNumber(0, NumberFormat.Int8LE);
+```
+
+### Parameters
+
+* ``address``: the 7-bit I2C address from which to read the number.
+* ``format``: the number format. Formats include
+  **Int8LE**, **UInt8LE**, **Int16LE**, **UInt16LE**, **Int32LE**,
+  **Int8BE**, **UInt8BE**, **Int16BE**, **UInt16BE**, and
+  **Int32BE**.
+  * **Int** stands for "integer", and **UInt** stands for "unsigned integer".
+  * **LE** stands for "little-endian" and **BE** stands for "big-endian".
+  * The number in each format name stands for the number of bits in the format.
+
+### Example
+
+The following example reads a number in big-endian, 16-bit, unsigned integer
+format from the 7-bit I2C address `32`.
+
+```blocks
+pins.i2cReadNumber(32, NumberFormat.UInt16BE);
+```
+
+### See also
+
+[I2C](https://en.wikipedia.org/wiki/I%C2%B2C)

docs/reference/pins/i2c-write-number.md

@@ -0,0 +1,32 @@
+# I2C Write Number
+
+Write the specified number to the specified 7-bit I2C address in the
+specified number format.
+
+```sig
+pins.i2cWriteNumber(0, 0, NumberFormat.Int8LE);
+```
+
+### Parameters
+
+* ``address``: the 7-bit I2C address to which to send ``value``
+* ``value``: the number to send to ``address``
+* ``format``: the number format for ``value``. Formats include
+  **Int8LE**, **UInt8LE**, **Int16LE**, **UInt16LE**, **Int32LE**,
+  **Int8BE**, **UInt8BE**, **Int16BE**, **UInt16BE**, and
+  **Int32BE**.
+  * **Int** stands for "integer", and **UInt** stands for "unsigned integer".
+  * **LE** stands for "little-endian" and **BE** stands for "big-endian".
+  * The number in each format name stands for the number of bits in the format.
+
+### Example
+
+The following example sends the value `2055` to the 7-bit I2C
+address `32` in big-endian 32-bit integer format.
+
+```blocks
+pins.i2cWriteNumber(32, 2055, NumberFormat.Int32BE);
+```
+### See also
+
+[I2C](https://en.wikipedia.org/wiki/I%C2%B2C)

docs/reference/pins/map.md

@@ -1,8 +1,14 @@
 # Map
 
-Re-maps a number from one range to another. That is, a value of ``from low`` would get mapped to ``to low``, a value of ``from high`` to ``to high``, values in-between to values in-between, etc.
+Remaps the specified value from one range to another. This function
+maps the value of ``from low`` to the value of ``to low``, the value
+of ``from high`` to the value of ``to high``, and intermediate values
+to intermediate values.
 
-Does not constrain values to within the range, because out-of-range values are sometimes intended and useful. The `math->clamp` function may be used either before or after this function, if limits to the ranges are desired.
+This function does not constrain values to the ranges, because
+out-of-range values are sometimes intended and useful.  If you need to
+limit a range, you can use the ``Math.clamp`` function before or after
+calling this function.
 
 ```sig
 pins.map(0, 0, 4, 0, 1023);
@@ -10,15 +16,16 @@ pins.map(0, 0, 4, 0, 1023);
 
 ### Parameters
 
-* ``value``: [Number](/reference/types/number) - the value to map
-* ``from low``: [Number](/reference/types/number)  - lower bound of the origin interval
-* ``from high``: [Number](/reference/types/number)  - upper bound of the origin interval
-* ``to low``: [Number](/reference/types/number)  - lower bound of the target interval
-* ``to high``: [Number](/reference/types/number)  - upper bound of the target interval
+* ``value``: a [number](/reference/types/number) that specifies the value to map
+* ``fromLow``: a [number](/reference/types/number)  that specifies the lower bound of the origin interval
+* ``fromHigh``: a [number](/reference/types/number)  that specifies the upper bound of the origin interval
+* ``toLow``: a [number](/reference/types/number)  that specifies the lower bound of the target interval
+* ``toHigh``: a [number](/reference/types/number)  that specifies the upper bound of the target interval
 
 ## Example
 
-Map the value read from the analog pin ``P0`` to an LED index between ``0`` and ``4``.
+This example maps the value read from the analog pin `P0` to an LED
+coordinate between `0` and `4`.
 
 ```blocks
 let value1 = pins.analogReadPin(AnalogPin.P0)

docs/reference/pins/on-pulsed.md

@@ -0,0 +1,31 @@
+# On Pulsed
+
+Configure the specified pin for digital input, and then
+execute the associated code block whenever the pin
+pulses **High** or **Low** (as specified).
+
+```sig
+pins.onPulsed(DigitalPin.P0, PulseValue.High, () => { });
+```
+
+### Parameters
+
+* ``name``: The micro:bit hardware pin to configure (``P0`` through ``P20``)
+* ``pulse``: Which state will cause the associated block to execute (**High** or **Low**)
+
+### Example
+
+The following example configures pin ``P2`` for digital input,
+and then displays the string `LOW` whenever ``P2`` pulses low.
+
+```blocks
+pins.onPulsed(DigitalPin.P2, PulseValue.Low, () => {
+    basic.showString("LOW");
+});
+```
+
+### See also
+
+[servo set pulse](/reference/pins/servo-set-pulse),
+[pulse duration](/reference/pins/pulse-duration),
+[digital read pin](/reference/pins/digital-read-pin)