0.2.190

fixing more help broken links

.travis.yml

@@ -14,4 +14,5 @@ cache:
   directories:
     - node_modules
     - built/cache
+    - libs/hello/built/cache
 

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(() => {

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

@@ -3,56 +3,56 @@
 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.  The `basic` namespace contains a number of very helpful
-functions:
+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 a namespace, simply type `basic`
-followed by `.`; a list of all the functions will appear. 
+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)
 
-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:
+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)
 
-# Function parameters
+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)
 
-You might have noticed that the call `showString` above takes one value, 
+## 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 the scroll. Try this:
+parameter that controls the speed of the scroll. Try this:
 
 ```typescript
 basic.showString("Hello!",50)
 ```
 
-You might have noticed that the function list above shows all
-the available parameters for each function. 
+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.showString("Hello!")
-basic.showLeds(`
-    . # . # .
-    . . . . .
-    . . # . .
-    # . . . #
-    . # # # .
-    `)
-basic.pause(1000)
 basic.clearScreen()
-basic.showString("Goodbye!")
-basic.showLeds(`
-    . # . # .
-    . . . . .
-    . . . . .
-    . # # # .
-    # . . . #
-    `)
-basic.pause(1000)
-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/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/uart-read.md

@@ -18,15 +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 = "";
+let uartData = "";
 let connected = 0;
 basic.showString("UART");
 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(() => {

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/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
 

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

@@ -5,12 +5,16 @@ Set up the part of the micro:bit that measures
 is speeding up or slowing down), in case you need to measure high
 or low acceleration.
 
+```sig
+input.setAccelerometerRange(AcceleratorRange.OneG);
+```
+
 ### Parameters
 
-* 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.
+* ``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
 

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) with 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
@@ -28,9 +28,7 @@ basic.forever(() => {
 
 #### ~hint
 
-If you are using **analog read pin** with another micro:bit
-running **analog write pin**, it is a good idea to check
-**analog read pin** many times and then take an average.
+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.
 
 #### ~
 

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

@@ -10,8 +10,8 @@ pins.analogSetPeriod(AnalogPin.P0, 20000)
 
 ### Parameters
 
-* `pin`: a [string](/reference/types/string) that specifies the pin to configure (`P0` through `P4`, or `P10`)
-* `μs`: a [number](/reference/types/number) that specifies the analog period in microseconds.
+* ``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 first sets `P0` to analog with **analog write
 pin**, and then sets the PWM period of `P0` to 20,000 microseconds.

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

@@ -9,8 +9,8 @@ pins.analogWritePin(AnalogPin.P0, 400)
 
 ### Parameters
 
-* a [string](/reference/types/string) that is the pin name you say (`P0` through `P4`, or `P10`)
-* a [number](/reference/types/number) from `0` through `1023`
+* ``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`
 
 ### Example
 

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

@@ -17,10 +17,10 @@ pins.map(0, 0, 4, 0, 1023);
 ### Parameters
 
 * ``value``: a [number](/reference/types/number) that specifies the value to map
-* ``from low``: a [number](/reference/types/number)  that specifies the lower bound of the origin interval
-* ``from high``: a [number](/reference/types/number)  that specifies the upper bound of the origin interval
-* ``to low``: a [number](/reference/types/number)  that specifies the lower bound of the target interval
-* ``to high``: a [number](/reference/types/number)  that specifies the upper bound of the target interval
+* ``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
 

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)

docs/reference/pins/pulse-duration.md

@@ -0,0 +1,30 @@
+# Pulse Duration
+
+Gets the duration of the last pulse in microseconds.
+
+This function should be called from an **on pulsed** handler.
+
+```sig
+pins.pulseDuration();
+```
+
+### Returns
+
+The duration of the last pulse, measured in microseconds.
+
+### Example
+
+The following example waits for pin ``P0`` to be pulsed high, and then
+displays the duration of the pulse in microseconds on the LED screen.
+
+```blocks
+pins.onPulsed(DigitalPin.P0, PulseValue.High, () => {
+    basic.showNumber(pins.pulseDuration());
+});
+```
+
+### See also
+
+[servo set pulse](/reference/pins/servo-set-pulse),
+[on pulsed](/reference/pins/on-pulsed),
+[digital read pin](/reference/pins/digital-read-pin)

docs/reference/pins/servo-set-pulse.md

@@ -9,8 +9,8 @@ pins.servoSetPulse(AnalogPin.P1, 1500)
 
 ### Parameters
 
-* `pin`: a [string](/reference/types/string) that specifies the pin to configure (`P0` through `P4`, or `P10`)
-* `μs`: a [number](/reference/types/number) that specifies the analog period in microseconds.
+* ``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.
 
 ### Example
 

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

@@ -1,9 +1,12 @@
 # Servo Write Pin
 
-Writes a value to the servo on to the specified [pin](/device/pins) (``P0``, ``P1``, ``P2``), controlling the shaft accordingly.
+Write a value to the servo on the specified [pin](/device/pins)
+and control the shaft.
 
-* on a standard servo, this will set the angle of the shaft (in degrees), moving the shaft to that orientation.
-* on a continuous rotation servo, this will set the speed of the servo (with 0 being full-speed in one direction, 180 being full speed in the other, and a value near 90 being no movement).
+This function will move the shaft of a standard servo to the specified
+angle, or set the speed of a continuous rotation servo. (`0` specifies
+full speed in one direction, `180` specifies full speed in the other,
+and approximately `90` specifies no movement.)
 
 ```sig
 pins.servoWritePin(AnalogPin.P0, 180)
@@ -11,18 +14,18 @@ pins.servoWritePin(AnalogPin.P0, 180)
 
 ### Parameters
 
-* `name` - [String](/reference/types/string); the pin name ("P0", "P1", or "P2")
-* `value` - a [Number](/reference/types/number) between 0 and 180 included
+* ``name``: a [string](/reference/types/string) that specifies the pin name (`P0` through `P4`, or `P10`)
+* ``value``: a [number](/reference/types/number) from `0` through `180`
 
 ### Examples
 
-* setting the shaft angle to mid point on a servo
+#### Setting the shaft angle to midpoint on a servo
 
 ```blocks
 pins.servoWritePin(AnalogPin.P0, 90)
 ```
 
-* control the shaft by using the tilt information of the accelerometer
+#### Controlling the shaft by using the tilt information of the accelerometer
 
 ```blocks
 basic.forever(() => {
@@ -33,7 +36,7 @@ basic.forever(() => {
 })
 ```
 
-* setting the full speed on a continuous servo
+#### Setting the full speed on a continuous servo
 
 ```blocks
 pins.servoWritePin(AnalogPin.P0, 0)

docs/reference/pins/set-pull.md

@@ -0,0 +1,32 @@
+# Set Pull
+
+Configure the electrical pull of the specified pin.
+
+Many micro:bit pins can be configured as _pull-ups_.  For example, a
+pull-up can set a pin's voltage to high (3.3 volts, or `1` when
+calling [digital read pin](/reference/pins/digital-read-pin)).  If one
+end of a button is connected to ``P0`` (set to high) and the other end
+is connected to ``GND`` (0 volts), then when you press the button,
+``P0`` is driven to 0 volts, and the micro:bit software can detect a
+button press.
+
+```sig
+pins.setPull(DigitalPin.P9, PinPullMode.PullDown);
+```
+
+### Parameters
+
+* ``name``: The micro:bit hardware pin to configure (``P0``-``P20``)
+* ``pull``: The pull to which to set the pin (**down**, **up**, or **none**)
+
+### Example
+
+The following example sets the pull of pin ``P0`` to **up** (high).
+
+```blocks
+pins.setPull(DigitalPin.P0, PinPullMode.PullUp);
+```
+
+### See also
+
+[BBC micro:bit | mbed](https://developer.mbed.org/platforms/Microbit/)

docs/reference/radio/on-data-received.md

@@ -3,9 +3,10 @@
 Run part of a program when the micro:bit receives a
 [number](/reference/types/number) or [string](/reference/types/string) over ``radio``.
 
-### Parameters
 
-* the part of the program to run when the micro:bit receives information over ``radio``.
+```sig
+radio.onDataReceived(() => { });
+```
 
 ### Simulator
 

docs/reference/radio/receive-number.md

@@ -2,6 +2,10 @@
 
 Receives the next number sent by a micro:bit in the same ``radio`` group.
 
+```sig
+radio.receiveNumber();
+```
+
 ### Returns
 
 * the first  [number](/reference/types/number) that the micro:bit received. If it did not receive any numbers, this function will return `0`.

docs/reference/radio/receive-string.md

@@ -8,7 +8,8 @@ radio.receiveString()
 
 ### Returns
 
-* the first [string](/reference/types/string) that was sent. If no string was sent, then this function returns an empty (blank) string.
+* the first [string](/reference/types/string) that was sent. If no
+  string was sent, then this function returns an empty (blank) string.
 
 ### Simulator
 

docs/reference/radio/received-signal-strength.md

@@ -8,6 +8,10 @@ the last time it ran the
 [receive number](/reference/radio/receive-number) function. That means
 it needs to run **receive number** first.
 
+```sig
+radio.receivedSignalStrength();
+```
+
 ### Returns
 
 * a [number](/reference/types/number) between `255` and `0` that means

docs/reference/radio/send-number.md

@@ -1,10 +1,14 @@
 # Send Number
 
-Broadcast a number to other micro:bits connected via ``radio``.
+Broadcast a [number](/reference/types/number) to other micro:bits connected via ``radio``.
+
+```sig
+radio.sendNumber(0);
+```
 
 ### Parameters
 
-* num - a number to send.
+* ``value`` - a [number](/reference/types/number) to send.
 
 ### Simulator
 
@@ -12,9 +16,9 @@ This function only works on the micro:bit, not in browsers.
 
 ### Example: Broadcasting acceleration
 
-This example broadcasts the value of your micro:bit's ``acceleration`` in the `x` direction 
-(left and right) to other micro:bits.
-This kind of program might be useful in a model car or model rocket.
+This example broadcasts the value of your micro:bit's ``acceleration``
+in the `x` direction (left and right) to other micro:bits.  This kind
+of program might be useful in a model car or model rocket.
 
 ```blocks
 input.onButtonPressed(Button.A, () => {
@@ -39,4 +43,3 @@ basic.forever(() => {
 ### See also
 
 [receive number](/reference/radio/receive-number), [on data received](/reference/radio/on-data-received)
-

docs/reference/radio/send-string.md

@@ -8,18 +8,17 @@ radio.sendString("Hello!")
 
 ### Parameters
 
-* `text` is a [String](/reference/types/string) to send by radio.
+* `msg` is a [string](/reference/types/string) to send by radio.
 
 ### Simulator
 
 This function only works on the micro:bit, not in browsers.
 
-
-
 ### Example: Two-way radio
 
-If you load this program onto two or more micro:bits, you can send a code word from one of them to the others by pressing button `A`.
-The other micro:bits will receive the code word and then show it.
+If you load this program onto two or more micro:bits, you can send a
+code word from one of them to the others by pressing button `A`.  The
+other micro:bits will receive the code word and then show it.
 
 ```blocks
 input.onButtonPressed(Button.A, () => {

docs/reference/radio/send-value.md

@@ -2,10 +2,14 @@
 
 Send a [string]() and [number]() together by ``radio`` to other micro:bits.
 
+```sig
+radio.sendValue("data", 0);
+```
+
 ### Parameters
 
-* a [string](/reference/types/string) to send by radio
-* a [number](/reference/types/number) to send by radio
+* ``name`` is a [string](/reference/types/string) to send by radio
+* ``value`` a [number](/reference/types/number) to send by radio
 
 ### Simulator
 

docs/reference/radio/set-group.md

@@ -10,6 +10,10 @@ function, it will figure out its own group ID by itself.  If you load
 the very same program onto two different micro:bits, they will be able
 to talk to each other because they will have the same group ID.
 
+```sig
+radio.setGroup(0);
+```
+
 ### Parameters
 
 * ``id`` is a [number](/reference/types/number) from ``0`` to ``255``.

docs/reference/radio/set-transmit-power.md

@@ -8,6 +8,10 @@ The scientific name for the strength of the ``radio`` signal is
 can be measured as -30 dBm, and a strength of `7` can be
 measured as +4 dBm.
 
+```sig
+radio.setTransmitPower(7);
+```
+
 ### Range
    
 If your micro:bit is sending with a strength of `7`, and you are in
@@ -16,7 +20,7 @@ can reach as far as 70 meters (about 230 feet).
 
 ### Parameters
 
-* a [number](/reference/types/number) between ``0`` and ``7`` that
+* ``power`` is a [number](/reference/types/number) between ``0`` and ``7`` that
 means how strong the signal is.
 
 ### Simulator

docs/reference/radio/write-value-to-serial.md

@@ -1,16 +1,19 @@
 # Write Value To Serial
 
 Writes the full data received data  via ``radio`` to serial in JSON format.   
+
 **Note** - This method only works for [send number](/reference/radio/send-number) and [send value](/reference/radio/send-value). It does not work for [send string](/reference/radio/send-string) (although a string can be sent with [send value](/reference/radio/send-value)).   
 
+```sig
+radio.writeValueToSerial();
+```
+
 ## Data received format
 The format for received data printed to serial is as follows    
 - [send number](/reference/radio/send-number) - ```{v:ValueSent,t:MicrobitTimeAlive,s:Unused}```
 - [send value](/reference/radio/send-number) - ```{v:Value,t:MicrobitTimeAlive,s:Unused,n:"Name"}```
 - [send string](/reference/radio/send-string) - ```{}``` (currently unavailable)
 
-
-
 ### Simulator
 
 This function only works on the micro:bit, not in browsers.

docs/reference/serial/read-line.md

@@ -0,0 +1,38 @@
+# Serial Read Line
+
+Read a line of text from the serial port.
+
+```sig
+serial.readLine();
+```
+
+#### ~hint
+
+This function expects the line it reads to be terminated with the `\r`
+character.  If your terminal software does not terminate lines with
+`\r`, this function will probably never return a value.
+
+#### ~
+
+### Returns
+
+* a [string](/reference/types/string) containing input from the serial port, such as a response typed by a user
+
+### Example
+
+The following example requests the user's name, then repeats it to greet the user.
+
+```blocks
+basic.forever(() => {
+    serial.writeLine("What is your name?");
+    let answer = serial.readLine();
+    serial.writeString("Hello,");
+    serial.writeLine(answer);
+});
+```
+
+### See also
+
+[serial](/device/serial),
+[serial write line](/reference/serial/write-line),
+[serial write value](/reference/serial/write-value)

docs/reference/serial/redirect-to.md

@@ -0,0 +1,31 @@
+# Serial Redirect To
+
+Dynamically configure the serial instance to use pins other than
+``USBTX`` and ``USBRX``.
+
+```sig
+serial.redirect(SerialPin.P0, SerialPin.P0, BaudRate.BaudRate115200);
+```
+
+### Parameters
+
+* ``tx``: the [serial pin](/device/pins) on which to transmit data 
+* ``rx``: the [serial pin](/device/pins) on which to receive data 
+* ``rate``: the baud rate at which to transmit and receive data (either `9600` or ``115200``)
+
+### Example
+
+When button ``A`` is pressed, the following example reconfigures the
+serial instance. The new configuration uses pin ``P1`` to transmit and
+``P2`` to receive, at a baud rate of `9600`.
+
+```blocks
+input.onButtonPressed(Button.A, () => {
+    serial.redirect(SerialPin.P1, SerialPin.P2, BaudRate.BaudRate9600);
+});
+```
+
+### See also
+
+[serial](/device/serial)
+

docs/reference/serial/write-line.md

@@ -1,14 +1,32 @@
-# Write Line
+# Serial Write Line
 
-Writes a string and a new line character (`\r\n`) to [serial](/device/serial).
+Write a string to the [serial](/device/serial) port and start a new line of text
+by writing `\r\n`.
 
 ```sig
 serial.writeLine("");
 ```
 
+### Parameters
+
+* `text` is the [string](/reference/types/string) to write to the serial port
+
+### Example: simple serial
+
+This program writes the word `BOFFO` to the serial port repeatedly.
+
+```blocks
+basic.forever(() => {
+    serial.writeLine("BOFFO");
+    basic.pause(5000);
+});
+```
+
 ### Example: streaming data
 
-The following example constantly checks the [compass heading](/reference/input/compass-heading) and sends the direction to serial.
+This program checks the
+[compass heading](/reference/input/compass-heading) and sends the
+direction to the serial port repeatedly.
 
 ```blocks
 basic.forever(() => {
@@ -26,8 +44,9 @@ basic.forever(() => {
     }
 })
 ```
-
 ### See also
 
-[serial](/device/serial), [write value](/reference/serial/write-value)
-
+[serial](/device/serial),
+[serial write number](/reference/serial/write-number),
+[serial write string](/reference/serial/write-string),
+[serial write value](/reference/serial/write-value)

docs/reference/serial/write-number.md

@@ -0,0 +1,41 @@
+# Serial Write Number
+
+Write a number to the [serial](/device/serial) port.
+
+```sig
+serial.writeNumber(0);
+```
+
+### Parameters
+
+* `value` is the [number](/reference/types/number) to write to the serial port
+
+### Example: one through ten
+
+This program repeatedly writes a 10-digit number to the serial port.
+
+```blocks
+basic.forever(() => {
+    serial.writeNumber(1234567890);
+    basic.pause(5000);
+});
+```
+
+### Example: plot bar graph does serial
+
+If you use the ``led.plotBarGraph`` function, it writes the number
+being plotted to the serial port too.
+
+```blocks
+basic.forever(() => {
+    led.plotBarGraph(input.lightLevel(), 255)
+    basic.pause(10000);
+})
+```
+
+### See also
+
+[serial](/device/serial),
+[serial write line](/reference/serial/write-line),
+[serial write value](/reference/serial/write-value)
+

docs/reference/serial/write-string.md

@@ -0,0 +1,31 @@
+# Serial Write String
+
+Write a string to the [serial](/device/serial) port,
+without starting a new line afterward.
+
+```sig
+serial.writeString("");
+```
+
+### Parameters
+
+* `text` is the [string](/reference/types/string) to write to the serial port
+
+### Example: simple serial
+
+This program writes the word `JUMBO` to the serial port repeatedly,
+without any new lines.
+
+```blocks
+basic.forever(() => {
+    serial.writeString("JUMBO");
+    basic.pause(1000);
+});
+```
+
+### See also
+
+[serial](/device/serial),
+[serial write line](/reference/serial/write-line),
+[serial write number](/reference/serial/write-number),
+[serial write value](/reference/serial/write-value)

docs/reference/serial/write-value.md

@@ -1,14 +1,23 @@
 # Write Value
 
-Writes name/value pair and a new line character (`\r\n`) to [serial](/device/serial).
+Write a name/value pair and a newline character (`\r\n`) to the [serial](/device/serial) port.
 
 ```sig
 serial.writeValue("x", 0);
 ```
 
+### Parameters
+
+* `name` is the [string](/reference/types/string) to write to the serial port
+* `value` is the [number](/reference/types/number) to write to the serial port
+
+
+
+
 ### Example: streaming data
 
-The sample below sends the temperature and light level every 10 seconds.
+Every 10 seconds, the example below sends the temperature and light level
+to the serial port.
 
 ```blocks
 basic.forever(() => {
@@ -18,19 +27,17 @@ basic.forever(() => {
 })
 ```
 
-### Plot bar graph does serial!
+#### ~hint
 
-If you use the `led.plotBarGraph` function, it automatically writes the value to the serial as well.
-
-```blocks
-basic.forever(() => {
-    led.plotBarGraph(input.lightLevel(), 255)
-    basic.pause(10000);
-})
-```
+The [send value](/reference/radio/send-value) function broadcasts
+string/number pairs.  You can use a second micro:bit to receive them,
+and then send them directly to the serial port with ``write value``.
 
+#### ~
 
 ### See also
 
-[serial](/device/serial), [write line](/reference/serial/write-line)
-
+[serial](/device/serial),
+[serial write line](/reference/serial/write-line),
+[serial write number](/reference/serial/write-number),
+[send value](/reference/radio/send-value)

docs/reference/types/string-functions.md

@@ -1,3 +1,3 @@
-## String functions
+# String functions
 
 TBD

docs/reference/types/string.md

@@ -9,12 +9,12 @@ A *String* is a sequence of characters. For the BBC micro:bit, ASCII character c
 ### Create a string variable
 
 ```block
-salutation = "Hello";
+let salutation = "Hello";
 ```
 
 To create a variable that holds a string:
 
-1. Click `Variables` (as the Block drawer).
+1. Click `Variables` (in the Block drawer).
 
 2. Type a name for your new string variable by clicking the down arrow, then click New Variable. Then type the variable name "salutation"
 
@@ -25,7 +25,7 @@ To create a variable that holds a string:
 Your code should look something like this:
 
 ```block
-salutation = "Hello";
+let salutation = "Hello";
 ```
 
 ### The function `show string`

libs/cpp-test/hello.ts

@@ -1,10 +1,10 @@
 basic.plotLeds(`
-# # . # #
-. . # . .
-. . # . .
-# . . . #
-. # # # .
-`);
+    # # . # #
+    . . # . .
+    . . # . .
+    # . . . #
+    . # # # .
+    `);
 basic.pause(300);
 basic.showString("Hello");
 // foo.bar();

libs/microbit-radio/radio.cpp

@@ -69,7 +69,7 @@ namespace radio {
         uint32_t sn = transmitSerialNumber ? microbit_serial_number() : 0;
         uint8_t buf[32];
         uint32_t* buf32 = (uint32_t*)buf;
-        memset(buf, 32, 0);
+        memset(buf, 0, 32);
         buf32[0] = value;                      // 4 bytes: value
         buf32[1] = t; // 4 bytes: running time
         buf32[2] = sn; // 4 bytes: serial number

libs/microbit/input.cpp

@@ -284,7 +284,7 @@ namespace input {
      * Sets the accelerometer sample range in gravities.
      * @param range a value describe the maximum strengh of acceleration measured
      */
-    //% help=input/set-accelerator-range
+    //% help=input/set-accelerometer-range
     //% blockId=device_set_accelerometer_range block="set accelerometer|range %range" icon="\uf135"
     //% weight=5
     void setAccelerometerRange(AcceleratorRange range) {

libs/microbit/pins.cpp

@@ -159,7 +159,7 @@ namespace pins {
     /**
     * Gets the duration of the last pulse in micro-seconds. This function should be called from a ``onPulsed`` handler.
     */
-    //% help=pins/pulse-micros
+    //% help=pins/pulse-duration
     //% blockId=pins_pulse_duration block="pulse duration (µs)"
     //% weight=21
     int pulseDuration() {
@@ -229,7 +229,7 @@ namespace pins {
     * @param name pin to set the pull mode on
     * @param pull one of the mbed pull configurations: PullUp, PullDown, PullNone 
     */
-    //% help=pins/digital-set-pull weight=3
+    //% help=pins/set-pull weight=3
     //% blockId=device_set_pull block="set pull|pin %pin|to %pull"
     void setPull(DigitalPin name, PinPullMode pull) {
         PinMode m = pull == PinPullMode::PullDown 

libs/microbit/pxt.json

@@ -26,16 +26,12 @@
         "pins.ts",
         "serial.cpp",
         "serial.ts",
-        "buffer.cpp",
-        "_locales/ar/microbit-strings.json",
-        "_locales/de/microbit-strings.json",
-        "_locales/es-ES/microbit-strings.json",
-        "_locales/fr/microbit-strings.json",
-        "_locales/ja/microbit-strings.json"
+        "buffer.cpp"
     ],
     "public": true,
     "dependencies": {},
     "yotta": {
+        "configIsJustDefaults": true,
         "config": {
             "microbit-dal": {
                 "bluetooth": {

libs/microbit/serial.cpp

@@ -61,11 +61,11 @@ namespace serial {
     * @param baud the new baud rate. eg: 115200
     */
     //% weight=10
-    //% help=serial/redirect
+    //% help=serial/redirect-to
     //% blockId=serial_redirect block="serial redirect to|TX %tx|RX %rx|at baud rate %rate"
     //% blockExternalInputs=1
     void redirect(SerialPin tx, SerialPin rx, BaudRate rate) {
       uBit.serial.redirect((PinName)tx, (PinName)rx);
       uBit.serial.baud((int)rate);
     }
-}
+}