0.3.13

see 65594842fc

.gitignore

@@ -1,11 +1,15 @@
 node_modules
 yotta_modules
 yotta_targets
+pxt_modules
 built
 typings
 tmp
 temp
 projects/**
+clients/win10/app/AppPackages
+clients/win10/app/BundlePackages
+clients/win10/app/BundleArtifacts
 clients/win10/app/bin
 clients/win10/app/bld
 clients/win10/*.opendb
@@ -18,4 +22,4 @@ clients/**/obj/**
 *.tgz
 *.db
 *.suo
-*.log
+*.log

.travis.yml

@@ -4,8 +4,12 @@ node_js:
 script:
   - "node node_modules/pxt-core/built/pxt.js travis"  
   - "(cd libs/lang-test0; node ../../node_modules/pxt-core/built/pxt.js run)"
+  - "(cd libs/lang-test1; node ../../node_modules/pxt-core/built/pxt.js run)"
+  - "(cd libs/lang-test0; node ../../node_modules/pxt-core/built/pxt.js test)"
+  - "(cd libs/lang-test1; node ../../node_modules/pxt-core/built/pxt.js test)"
+  - "node node_modules/pxt-core/built/pxt.js testdir tests"
   - "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 +18,5 @@ cache:
   directories:
     - node_modules
     - built/cache
+    - libs/hello/built/cache
 

README.md

@@ -9,12 +9,19 @@ PXT ([Microsoft Programming Experience Toolkit](https://github.com/Microsoft/pxt
 
 ## Local server
 
+The local server allows to run the editor and the documentation from your computer.
+
 ### Setup
 
 The following commands are a 1-time setup after synching the repo on your machine.
 
-* clone this repo to your computer
-* install the PXT command line
+* if not yet installed, install [Node.js 4.4.5 or higher](https://nodejs.org/en/download/)
+* [clone this repo](https://help.github.com/articles/cloning-a-repository/) to your computer and go in the project folder
+```
+git clone https://github.com/microsoft/pxt-microbit
+cd pxt-microbit
+```
+* install the PXT command line (add ``sudo`` for Mac/Linux shells).
 ```
 npm install -g pxt
 ```
@@ -37,7 +44,9 @@ If you need modify the `.cpp` files, turn on yotta compilation with the ``-yt``
 pxt serve -yt
 ```
 
-To make sure you're running the latest tools, run (add ``sudo`` for Mac/Linux shells)
+## Updates
+
+To update your PXT version and make sure you're running the latest tools, run (add ``sudo`` for Mac/Linux shells)
 ```
 pxt update
 ```
@@ -54,6 +63,23 @@ that wraps ``codethemicrobit.com`` and provides additional features.
 * Install Visual Studio 2015 Update 2 or higher. Make sure the Windows 10 templates are installed.
 * open the ``win10/app.sln`` solution and launch the ``codethemicrobit`` project.
 
+## Testing
+
+The build automatically runs the following:
+
+* make sure the built-in packages compile
+* `pxt run` in `libs/lang-test*` - this will run the test in command line runner; 
+  there is a number of asserts in both of these
+* `pxt testdir` in `tests` - this makes sure all the files compile and generates .hex files
+* run the TD->TS converter on a number of test scripts from `microbit.co.uk` and make sure the results compile
+
+To test something on the device:
+
+* do a `pxt deploy` in `libs/lang-test*` - they should show `1` or `2` on the screen (and not unhappy face)
+* run `pxt testdir` in `tests` and deploy some of the hex files from `tests/built`
+
+The `lang-test0` source comes from the `pxt-core` package. It's also tested with `pxt run` there. 
+
 ## Code of Conduct
 
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.

clients/win10/app/codethemicrobitapp.jsproj

@@ -20,22 +20,18 @@
     <ProjectConfiguration Include="Release|AnyCPU">
       <Configuration>Release</Configuration>
       <Platform>AnyCPU</Platform>
-      <UseDotNetNativeToolchain>true</UseDotNetNativeToolchain>
     </ProjectConfiguration>
     <ProjectConfiguration Include="Release|ARM">
       <Configuration>Release</Configuration>
       <Platform>ARM</Platform>
-      <UseDotNetNativeToolchain>true</UseDotNetNativeToolchain>
     </ProjectConfiguration>
     <ProjectConfiguration Include="Release|x64">
       <Configuration>Release</Configuration>
       <Platform>x64</Platform>
-      <UseDotNetNativeToolchain>true</UseDotNetNativeToolchain>
     </ProjectConfiguration>
     <ProjectConfiguration Include="Release|x86">
       <Configuration>Release</Configuration>
       <Platform>x86</Platform>
-      <UseDotNetNativeToolchain>true</UseDotNetNativeToolchain>
     </ProjectConfiguration>
   </ItemGroup>
   <PropertyGroup Label="Globals">

cmds/cmds.ts

@@ -28,11 +28,12 @@ export function deployCoreAsync(res: ts.pxt.CompileResult) {
 
 function getBitDrivesAsync(): Promise<string[]> {
     if (process.platform == "win32") {
+        let rx = new RegExp("^([A-Z]:).* " + pxt.appTarget.compile.deployDrives)
         return execAsync("wmic PATH Win32_LogicalDisk get DeviceID, VolumeName, FileSystem")
             .then(buf => {
                 let res: string[] = []
                 buf.toString("utf8").split(/\n/).forEach(ln => {
-                    let m = /^([A-Z]:).* MICROBIT/.exec(ln)
+                    let m = rx.exec(ln)
                     if (m) {
                         res.push(m[1] + "/")
                     }
@@ -41,8 +42,9 @@ function getBitDrivesAsync(): Promise<string[]> {
             })
     }
     else if (process.platform == "darwin") {
+        let rx = new RegExp(pxt.appTarget.compile.deployDrives)
         return readDirAsync("/Volumes")
-            .then(lst => lst.filter(s => /MICROBIT/.test(s)).map(s => "/Volumes/" + s + "/"))
+            .then(lst => lst.filter(s => rx.test(s)).map(s => "/Volumes/" + s + "/"))
     } else {
         return Promise.resolve([])
     }

docs/about.md

@@ -31,33 +31,33 @@ 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!");
+input.onButtonPressed(Button.A, () => {
+    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 +65,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/logic/boolean.md

@@ -86,7 +86,7 @@ if (led.point(1,1) && led.point(2,2)) {
 When you compare two Numbers, you get a Boolean value, such as the comparison `x < 5` in the code below:
 
 ```blocks
-let x = math.random(5)
+let x = Math.random(5)
 if(x < 5) {
    basic.showString("low");
 } else { 

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,15 +1,36 @@
-# JavaScript
+# JavaScript and TypeScript
 
-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:
+Visit the cards below to starting programming JavaScript and TypeScript with the micro:bit:
 
 ```codecard
 [{
-  "name": "Calling Functions",
-  "url":"/js/call"
+  "name": "Calling",
+  "url":  "/js/call"
 },{
-  "name": "Sequencing Commands",
-  "url":"/js/sequence"
+  "name": "Sequencing",
+  "url":  "/js/sequence"
+},{
+  "name": "Variables",
+  "url":  "/js/variables"
+},{
+  "name": "Operators",
+  "url": "/js/operators"
+},{
+  "name": "Statements",
+  "url": "/js/statements"
+},{
+  "name": "Functions",
+  "url": "/js/functions"
+},{
+  "name": "Types",
+  "url": "/js/types"
+},{
+  "name": "Classes",
+  "url": "/js/classes"
+},{
+  "name": "FAQ",
+  "url": "/js/faq"
 }
 ]
-```
+
+```

docs/js/call.md

@@ -3,23 +3,27 @@
 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 helpful functions, such as:
 
 ```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)
 
-We call this feature "Intellisense". Continue typing to select one of the functions, 
+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, 

docs/js/classes.md

@@ -0,0 +1,268 @@
+# Classes
+
+Traditional JavaScript focuses on functions and prototype-based inheritance as the basic means of building up reusable components, 
+but this may feel a bit awkward to programmers more comfortable with an object-oriented approach, where classes inherit functionality 
+and objects are built from these classes.
+
+Starting with ECMAScript 2015, also known as ECMAScript 6, JavaScript programmers will be able to build their applications using 
+this object-oriented class-based approach. TypeScript, allows you to use these techniques now, compiling them 
+down to JavaScript that works across all major browsers and platforms, without having to wait for the next version of JavaScript.
+
+Let's take a look at a simple class-based example:
+
+```ts
+class Greeter {
+    greeting: string;
+    constructor(message: string) {
+        this.greeting = message;
+    }
+    greet() {
+        return "Hello, " + this.greeting;
+    }
+}
+
+let greeter = new Greeter("world");
+```
+
+We declare a new class `Greeter`. This class has three members: a property called `greeting`, a constructor, and a method `greet`.
+
+You'll notice that in the class when we refer to one of the members of the class we prepend `this.`.
+This denotes that it's a member access.
+
+In the last line we construct an instance of the `Greeter` class using `new`.
+This calls into the constructor we defined earlier, creating a new object with the `Greeter` shape, and running the constructor to initialize it.
+
+# Inheritance
+
+### ~hint
+### Inheritance is not supported yet for the micro:bit. Coming soon...
+### ~
+
+In TypeScript, we can use common object-oriented patterns.
+Of course, one of the most fundamental patterns in class-based programming is being able to extend existing classes to create new ones using inheritance.
+
+Let's take a look at an example:
+
+```ts
+class Animal {
+    name: string;
+    constructor(theName: string) { this.name = theName; }
+    move(distanceInMeters: number = 0) {
+        console.log(`${this.name} moved ${distanceInMeters}m.`);
+    }
+}
+
+class Snake extends Animal {
+    constructor(name: string) { super(name); }
+    move(distanceInMeters = 5) {
+        console.log("Slithering...");
+        super.move(distanceInMeters);
+    }
+}
+
+class Horse extends Animal {
+    constructor(name: string) { super(name); }
+    move(distanceInMeters = 45) {
+        console.log("Galloping...");
+        super.move(distanceInMeters);
+    }
+}
+
+let sam = new Snake("Sammy the Python");
+let tom: Animal = new Horse("Tommy the Palomino");
+
+sam.move();
+tom.move(34);
+```
+
+This example covers quite a few of the inheritance features in TypeScript that are common to other languages.
+Here we see the `extends` keywords used to create a subclass. 
+You can see this where `Horse` and `Snake` subclass the base class `Animal` and gain access to its features.
+
+Derived classes that contain constructor functions must call `super()` which will execute the constructor function on the base class.
+
+The example also shows how to override methods in the base class with methods that are specialized for the subclass.
+Here both `Snake` and `Horse` create a `move` method that overrides the `move` from `Animal`, giving it functionality specific to each class.
+Note that even though `tom` is declared as an `Animal`, since its value is a `Horse`, when `tom.move(34)` calls the overriding method in `Horse`:
+
+```Text
+Slithering...
+Sammy the Python moved 5m.
+Galloping...
+Tommy the Palomino moved 34m.
+```
+
+# Public, private, and protected modifiers
+
+## Public by default
+
+In our examples, we've been able to freely access the members that we declared throughout our programs.
+If you're familiar with classes in other languages, you may have noticed in the above examples 
+we haven't had to use the word `public` to accomplish this; for instance, 
+C# requires that each member be explicitly labeled `public` to be visible.
+In TypeScript, each member is `public` by default.
+
+You may still mark a member `public` explicitly.
+We could have written the `Animal` class from the previous section in the following way:
+
+```ts
+class Animal {
+    public name: string;
+    public constructor(theName: string) { this.name = theName; }
+    public move(distanceInMeters: number) {
+        console.log(`${this.name} moved ${distanceInMeters}m.`);
+    }
+}
+```
+
+## Understanding `private`
+
+When a member is marked `private`, it cannot be accessed from outside of its containing class. For example:
+
+```ts
+class Animal {
+    private name: string;
+    constructor(theName: string) { this.name = theName; }
+}
+
+new Animal("Cat").name; // Error: 'name' is private;
+```
+
+TypeScript is a structural type system.
+When we compare two different types, regardless of where they came from, if the types of all members are compatible, then we say the types themselves are compatible.
+
+However, when comparing types that have `private` and `protected` members, we treat these types differently.
+For two types to be considered compatible, if one of them has a `private` member, 
+then the other must have a `private` member that originated in the same declaration.
+The same applies to `protected` members.
+
+Let's look at an example to better see how this plays out in practice:
+
+```ts
+class Animal {
+    private name: string;
+    constructor(theName: string) { this.name = theName; }
+}
+
+class Rhino extends Animal {
+    constructor() { super("Rhino"); }
+}
+
+class Employee {
+    private name: string;
+    constructor(theName: string) { this.name = theName; }
+}
+
+let animal = new Animal("Goat");
+let rhino = new Rhino();
+let employee = new Employee("Bob");
+
+animal = rhino;
+animal = employee; // Error: 'Animal' and 'Employee' are not compatible
+```
+
+In this example, we have an `Animal` and a `Rhino`, with `Rhino` being a subclass of `Animal`.
+We also have a new class `Employee` that looks identical to `Animal` in terms of shape.
+We create some instances of these classes and then try to assign them to each other to see what will happen.
+Because `Animal` and `Rhino` share the `private` side of their shape from the same declaration of 
+`private name: string` in `Animal`, they are compatible. However, this is not the case for `Employee`.
+When we try to assign from an `Employee` to `Animal` we get an error that these types are not compatible.
+Even though `Employee` also has a `private` member called `name`, it's not the one we declared in `Animal`.
+
+## Understanding `protected`
+
+The `protected` modifier acts much like the `private` modifier with the exception that members 
+declared `protected` can also be accessed by instances of deriving classes. For example,
+
+```ts
+class Person {
+    protected name: string;
+    constructor(name: string) { this.name = name; }
+}
+
+class Employee extends Person {
+    private department: string;
+
+    constructor(name: string, department: string) {
+        super(name);
+        this.department = department;
+    }
+
+    public getElevatorPitch() {
+        return `Hello, my name is ${this.name} and I work in ${this.department}.`;
+    }
+}
+
+let howard = new Employee("Howard", "Sales");
+console.log(howard.getElevatorPitch());
+console.log(howard.name); // error
+```
+
+Notice that while we can't use `name` from outside of `Person`, 
+we can still use it from within an instance method of `Employee` because `Employee` derives from `Person`.
+
+A constructor may also be marked `protected`.
+This means that the class cannot be instantiated outside of its containing class, but can be extended. For example,
+
+```ts
+class Person {
+    protected name: string;
+    protected constructor(theName: string) { this.name = theName; }
+}
+
+// Employee can extend Person
+class Employee extends Person {
+    private department: string;
+
+    constructor(name: string, department: string) {
+        super(name);
+        this.department = department;
+    }
+
+    public getElevatorPitch() {
+        return `Hello, my name is ${this.name} and I work in ${this.department}.`;
+    }
+}
+
+let howard = new Employee("Howard", "Sales");
+let john = new Person("John"); // Error: The 'Person' constructor is protected
+```
+
+# Readonly modifier
+
+You can make properties readonly by using the `readonly` keyword.
+Readonly properties must be initialized at their declaration or in the constructor.
+
+```ts
+class Octopus {
+    readonly name: string;
+    readonly numberOfLegs: number = 8;
+    constructor (theName: string) {
+        this.name = theName;
+    }
+}
+let dad = new Octopus("Man with the 8 strong legs");
+dad.name = "Man with the 3-piece suit"; // error! name is readonly.
+```
+
+## Parameter properties
+
+In our last example, we had to declare a readonly member `name` and a constructor parameter `theName` in the `Octopus` class, and we then immediately set `name` to `theName`.
+This turns out to be a very common practice.
+*Parameter properties* let you create and initialize a member in one place.
+Here's a further revision of the previous `Octopus` class using a parameter property:
+
+```ts
+class Octopus {
+    readonly numberOfLegs: number = 8;
+    constructor(readonly name: string) {
+    }
+}
+```
+
+Notice how we dropped `theName` altogether and just use the shortened `readonly name: string` parameter on the constructor to create and initialize the `name` member.
+We've consolidated the declarations and assignment into one location.
+
+Parameter properties are declared by prefixing a constructor parameter with an accessibility modifier or `readonly`, or both.
+Using `private` for a parameter property declares and initializes a private member; likewise, the same is done for `public`, `protected`, and `readonly`.
+

docs/js/faq.md

@@ -0,0 +1,58 @@
+# Frequently asked questions
+
+# What is the language supported for the micro:bit?
+
+For the micro:bit, we support a "static" subset of TypeScript (itself a superset of JavaScript):
+
+## Supported language features
+
+* variables with `let`, `const`, and `var`
+* functions with lexical scoping and recursion
+* top-level code in the file; hello world really is `console.log("Hello world")`
+* `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
+* conditional operator `? :`; lazy boolean operators
+* namespaces (a form of modules) 
+* 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 `() => ...`
+* classes with fields, methods and constructors; `new` keyword
+* array literals `[1, 2, 3]`
+* enums
+
+## 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
+
+For JS-only targets we may implement the following:
+
+* regular expressions
+* classes implementing interfaces
+
+Things that we are not very likely to implement:
+
+* file-based modules (`import * from ...`, `module.exports` etc); we do support namespaces
+* spread operator
+* `yield` expression and ``function*``
+* `await` expression and `async function`
+* `typeof` expression
+* tagged templates ``tag `text ${expression} more text` ``; regular templates are supported
+* binding with arrays or objects: `let [a, b] = ...; let { x, y } = ...`
+* `with` statement
+* `eval`
+* `delete` statement
+* `for ... in` statements
+* JSX (HTML as part of JavaScript)

docs/js/functions.md

@@ -0,0 +1,161 @@
+# Functions
+
+Functions are the fundamental building block of programs. Here is the simplest
+way to make a function that adds two numbers:
+
+```ts
+// Named function
+function add(x : number, y : number) {
+    return x + y;
+}
+
+basic.showNumber(add(1, 2))
+```
+
+### ~ hint
+For the micro:bit, you must specify a [type](/js/types) for each function parameter. 
+### ~ 
+
+Functions can refer to variables outside of the function body.
+When they do so, they're said to `capture` these variables.
+
+```ts
+let z = 100;
+
+function addToZ(x: number, y: number) {
+    return x + y + z;
+}
+
+basic.showNumber(addToZ(1, 2))
+```
+
+## Typing the function
+
+Let's add a return type to our add function:
+
+```ts
+function add(x: number, y: number): number {
+    return x + y;
+}
+```
+
+TypeScript can figure the return type out by looking at the return statements, so you can optionally leave this off in many cases.
+
+# Optional and Default Parameters
+
+In TypeScript, the number of arguments given to a function has to match the number of parameters the function expects.
+
+```ts
+function buildName(firstName: string, lastName: string) {
+    return firstName + " " + lastName;
+}
+
+let result1 = buildName("Bob");                  // error, too few parameters
+let result2 = buildName("Bob", "Adams", "Sr.");  // error, too many parameters
+let result3 = buildName("Bob", "Adams");         // ah, just right
+```
+
+In JavaScript, every parameter is optional, and users may leave them off as they see fit.
+When they do, their value is `undefined`.
+We can get this functionality in TypeScript by adding a `?` to the end of parameters we want to be optional.
+For example, let's say we want the last name parameter from above to be optional:
+
+```ts
+function buildName(firstName: string, lastName?: string) {
+    if (lastName)
+        return firstName + " " + lastName;
+    else
+        return firstName;
+}
+
+let result1 = buildName("Bob");                  // works correctly now
+let result2 = buildName("Bob", "Adams", "Sr.");  // error, too many parameters
+let result3 = buildName("Bob", "Adams");         // ah, just right
+```
+
+Any optional parameters must follow required parameters.
+Had we wanted to make the first name optional rather than the last name, we would need to change the order of parameters in the function, putting the first name last in the list.
+
+In TypeScript, we can also set a value that a parameter will be assigned if the user does not provide one, or if the user passes `undefined` in its place.
+These are called default-initialized parameters.
+Let's take the previous example and default the last name to `"Smith"`.
+
+```ts
+function buildName(firstName: string, lastName = "Smith") {
+    return firstName + " " + lastName;
+}
+
+let result1 = buildName("Bob");                  // works correctly now, returns "Bob Smith"
+let result2 = buildName("Bob", undefined);       // still works, also returns "Bob Smith"
+let result3 = buildName("Bob", "Adams", "Sr.");  // error, too many parameters
+let result4 = buildName("Bob", "Adams");         // ah, just right
+```
+
+Default-initialized parameters that come after all required parameters are treated as optional, and just like optional parameters, can be omitted when calling their respective function.
+This means optional parameters and trailing default parameters will share commonality in their types, so both
+
+```ts
+function buildName(firstName: string, lastName?: string) {
+    // ...
+}
+```
+
+and
+
+```ts
+function buildName(firstName: string, lastName = "Smith") {
+    // ...
+}
+```
+
+share the same type `(firstName: string, lastName?: string) => string`.
+The default value of `lastName` disappears in the type, only leaving behind the fact that the parameter is optional.
+
+Unlike plain optional parameters, default-initialized parameters don't *need* to occur after required parameters.
+If a default-initialized parameter comes before a required parameter, users need to explicitly pass `undefined` to get the default initialized value.
+For example, we could write our last example with only a default initializer on `firstName`:
+
+```ts
+function buildName(firstName = "Will", lastName: string) {
+    return firstName + " " + lastName;
+}
+
+let result1 = buildName("Bob");                  // error, too few parameters
+let result2 = buildName("Bob", "Adams", "Sr.");  // error, too many parameters
+let result3 = buildName("Bob", "Adams");         // okay and returns "Bob Adams"
+let result4 = buildName(undefined, "Adams");     // okay and returns "Will Adams"
+```
+
+# Rest Parameters
+
+Required, optional, and default parameters all have one thing in common: they talk about one parameter at a time.
+Sometimes, you want to work with multiple parameters as a group, or you may not know how many parameters a function will ultimately take.
+In JavaScript, you can work with the arguments directly using the `arguments` variable that is visible inside every function body.
+
+In TypeScript, you can gather these arguments together into a variable:
+
+```ts
+function buildName(firstName: string, ...restOfName: string[]) {
+    return firstName + " " + restOfName.join(" ");
+}
+
+let employeeName = buildName("Joseph", "Samuel", "Lucas", "MacKinzie");
+```
+
+*Rest parameters* are treated as a boundless number of optional parameters.
+When passing arguments for a rest parameter, you can use as many as you want; you can even pass none.
+The compiler will build an array of the arguments passed in with the name given after the ellipsis (`...`), allowing you to use it in your function.
+
+The ellipsis is also used in the type of the function with rest parameters:
+
+```ts
+function buildName(firstName: string, ...restOfName: string[]) {
+    return firstName + " " + restOfName.join(" ");
+}
+
+let buildNameFun: (fname: string, ...rest: string[]) => string = buildName;
+```
+
+### ~button /js/types
+NEXT: Types
+### ~

docs/js/lang.md

@@ -1,75 +0,0 @@
-# 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/operators.md

@@ -0,0 +1,30 @@
+## Operators
+
+The following JavaScript operators are supported for the micro:bit.
+
+### ~hint
+Note that for the micro:bit all arithmetic is performed on integers, rather than floating point.
+This also is true when simulating in the browser.
+### ~
+
+# Assignment, arithmetic and bitwise
+
+* assignment operators - [read more](http://devdocs.io/javascript/operators/assignment_operators)
+* arithmetic operators - [read more](http://devdocs.io/javascript/operators/arithmetic_operators) 
+* bitwise operators - [read more](http://devdocs.io/javascript/operators/bitwise_operators)
+
+# Comparision and conditional
+
+* comparison operators - [read more](http://devdocs.io/javascript/operators/comparison_operators)
+* conditional operator - [read more](http://devdocs.io/javascript/operators/conditional_operator)
+
+## More
+
+* lambda functions `() => { ... }`
+* array literals `[1, 2, 3]`
+* strings, with a few common methods
+* [string templates](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) (`` `x is ${x}` ``)
+
+### ~button /js/statements
+NEXT: Statements
+### ~

docs/js/sequence.md

@@ -1,6 +1,6 @@
-## Sequencing commands
+# Sequencing
 
-By calling one function after another, you can create an animation:
+By calling one function after another, in sequence, you can create an animation:
 
 ```typescript
 basic.showLeds(`
@@ -9,17 +9,55 @@ basic.showLeds(`
     . . # . .
     # . . . #
     . # # # .
-    `)
+    `);
 basic.showLeds(`
     . # . # .
     . . . . .
     . . . . .
     . # # # .
     # . . . #
-    `)
+    `);
 ```
 
-## The Semicolon
+### The semicolon 
 
-Coming soon...
+In JavaScript, the semicolon (;) is used to terminate (or end) a statement. However, in most
+cases, the semicolon is optional and can be omitted. So both code sequences below are 
+legal:
 
+```typescript
+basic.showNumber(1)
+basic.showNumber(2)
+```
+
+```typescript
+basic.showNumber(1); 
+basic.showNumber(2);
+```
+
+### The empty statement
+
+In JavaScript, there is the concept of an *empty statement*, which is whitespace followed by
+a semicolon in the context where a statement is expected.
+So, the following code is an infinite loop
+followed by a call to `showNumber` that will never execute:
+```typescript
+while(true) ;  
+basic.showNumber(1);
+```
+
+
+### ~hint
+For the micro:bit, we don't allow a program to contain an empty statement, such as shown above. 
+If you really want an empty statement, you need to use curly braces to delimit an empty statement block:
+```typescript
+while(true) { } 
+basic.showNumber(1);
+```
+### ~
+
+[Read more](http://inimino.org/~inimino/blog/javascript_semicolons) about semicolons in JavaScript.
+
+### ~button /js/variables
+NEXT: Variable Declarations
+### ~

docs/js/statements.md

@@ -0,0 +1,33 @@
+# Statements
+
+The following JavaScript statements are supported for the micro:bit:
+
+## Variable declarations
+* `const` statement - [read more](http://devdocs.io/javascript/statements/const)
+* `let` statement - [read more](http://devdocs.io/javascript/statements/let)
+* `var` statement - [read more](http://devdocs.io/javascript/statements/var)
+
+## Block-structured statements
+
+* `{ }` block statement - [read more](http://devdocs.io/javascript/statements/block)
+* `if-else` conditional statement - [read more](http://devdocs.io/javascript/statements/if...else)
+* `while` loop - [read more](http://devdocs.io/javascript/statements/do...while)
+* `do-while` loop - [read more](http://devdocs.io/javascript/statements/do...while)
+* `for(;;)` loop - [read more](http://devdocs.io/javascript/statements/for)
+* `switch` statement (on numbers only) - [read more](http://devdocs.io/javascript/statements/switch)
+
+## Control-flow commands
+
+* `break` statement - [read more](http://devdocs.io/javascript/statements/break)
+* `continue` statement - [read more](http://devdocs.io/javascript/statements/continue)
+* `return` statement - [read more](http://devdocs.io/javascript/statements/return)
+* `debugger` statement for breakpoints - [read more](http://devdocs.io/javascript/statements/debugger)
+
+## Labelling statements
+
+* labelled statement - [read more](http://devdocs.io/javascript/statements/label)
+* `default` statement - [read more](http://devdocs.io/javascript/statements/default)
+
+### ~button /js/functions
+NEXT: Functions
+### ~

docs/js/types.md

@@ -0,0 +1,140 @@
+# Types
+
+For programs to be useful, we need to be able to work with some of the simplest units of data: 
+numbers, strings, structures, boolean values, and the like.
+
+# Boolean
+
+The most basic datatype is the simple true/false value, which is called a `boolean` value.
+
+```ts
+let isDone: boolean = false;
+```
+
+# Number
+
+### ~ hint 
+In JavaScript, `numbers` are floating point values.
+However, for the micro:bit, `numbers` are integer values.
+### ~
+
+Integer values can be specified via decimal, hexadecimal and octal notation:
+
+```ts
+let decimal: number = 42;
+let hex: number = 0xf00d;
+let binary: number = 0b1010;
+let octal: number = 0o744;
+```
+
+# String
+
+As in other languages, we use the type `string` to refer to textual data.
+Use double quotes (`"`) or single quotes (`'`) to surround string data.
+
+```ts
+let color: string = "blue";
+color = 'red';
+```
+
+You can also use *template strings*, which can span multiple lines and have embedded expressions.
+These strings are surrounded by the backtick/backquote (`` ` ``) character, and embedded expressions are of the form `${ expr }`.
+
+```ts
+let fullName: string = `Bob Bobbington`;
+let age: number = 37;
+let sentence: string = `Hello, my name is ${ fullName }.
+
+I'll be ${ age + 1 } years old next month.`
+```
+
+This is equivalent to declaring `sentence` like so:
+
+```ts
+let sentence: string = "Hello, my name is " + fullName + ".\n\n" +
+    "I'll be " + (age + 1) + " years old next month."
+```
+
+# Array
+
+Arrays allow you to work with an expandable sequence of values, addressed by an integer-valued index.
+Array types can be written in one of two ways.
+In the first, you use the type of the elements followed by `[]` to denote an array of that element type:
+
+```ts
+let list: number[] = [1, 2, 3];
+```
+
+The second way uses a generic array type, `Array<elemType>`:
+
+```ts
+let list: Array<number> = [1, 2, 3];
+```
+
+### ~hint
+For the micro:bit, all elements of an array must have the same type.
+### ~
+
+
+# Enum
+
+A helpful addition to the standard set of datatypes from JavaScript is the `enum`.
+As in languages like C#, an enum is a way of giving more friendly names to sets of numeric values.
+
+```ts
+enum Color {Red, Green, Blue};
+let c: Color = Color.Green;
+```
+
+By default, enums begin numbering their members starting at `0`.
+You can change this by manually setting the value of one of its members.
+For example, we can start the previous example at `1` instead of `0`:
+
+```ts
+enum Color {Red = 1, Green, Blue};
+let c: Color = Color.Green;
+```
+
+Or, even manually set all the values in the enum:
+
+```ts
+enum Color {Red = 1, Green = 2, Blue = 4};
+let c: Color = Color.Green;
+```
+
+# Any
+
+The TypeScript type `any` is not supported in the micro:bit.
+
+
+# Void
+
+`void` is the absence of having any type at all.
+You may commonly see this as the return type of functions that do not return a value:
+
+```ts
+function warnUser(): void {
+    basic.showString("This is my warning message");
+}
+```
+
+Declaring variables of type `void` is not useful.
+
+# Type Inference
+
+In TypeScript, there are several places where type inference is used to provide type information when there is
+no explicit type annotation. For example, in this code
+
+```ts
+let x = 3;
+let y = x + 3
+```
+
+The type of the `x` variable is inferred to be `number`. Similarly, the type of `y` variable also is inferred to be `number`.
+This kind of inference takes place when initializing variables and members, 
+setting parameter default values, and determining function return types.
+
+
+### ~button /js/classes
+NEXT: Classes
+### ~

docs/js/variables.md

@@ -0,0 +1,121 @@
+# Variable Declarations
+
+Declaring a variable in JavaScript has always traditionally been done with the `var` keyword.
+
+```typescript
+var a = 10;
+```
+
+The `var` construct has some [problems](http://www.typescriptlang.org/docs/handbook/variable-declarations.html), 
+which is why `let` statements were introduced. Apart from the keyword used, `let` statements are written 
+the same way `var` statements are.
+
+```typescript
+let a = 10;
+```
+
+The key difference is not in the syntax, but in the semantics, which we'll now dive into.
+
+## Block-scoping
+
+When a variable is declared using `let`, it uses what some call *lexical-scoping* or *block-scoping*.
+Unlike variables declared with `var` whose scopes leak out to their containing function, 
+block-scoped variables are not visible outside of their nearest containing block or `for`-loop.
+
+```typescript
+function f(input: boolean) {
+    let a = 100;
+
+    if (input) {
+        // Still okay to reference 'a'
+        let b = a + 1;
+        return b;
+    }
+
+    // Error: 'b' doesn't exist here
+    return b;
+}
+```
+
+Here, we have two local variables `a` and `b`.
+`a`'s scope is limited to the body of `f` while `b`'s scope is limited to the containing `if` statement's block.
+
+Another property of block-scoped variables is that they can't be read or written to before they're actually declared.
+While these variables are "present" throughout their scope, all points up until their declaration are part of their *temporal dead zone*.
+This is just a sophisticated way of saying you can't access them before the `let` statement, and luckily TypeScript will let you know that.
+
+```typescript
+a++; // illegal to use 'a' before it's declared;
+let a;
+```
+
+## Re-declarations
+
+With `var` declarations, it doesn't matter how many times you declare your variables, you just get one:
+
+```typescript
+var x = 10;
+var x = 20; 
+```
+
+In the above example, all declarations of `x` actually refer to the *same* `x`, and this is perfectly valid.
+This often ends up being a source of bugs. Thankfully, `let` declarations are not as forgiving.
+
+```typescript
+let x = 10;
+let x = 20; // error: can't re-declare 'x' in the same scope
+```
+
+## Shadowing
+
+The act of introducing a new name in a more deeply nested scope is called *shadowing*.
+It is a bit of a double-edged sword in that it can introduce certain bugs on its own in the 
+event of accidental shadowing, while also preventing certain bugs.
+For instance, imagine a `sumMatrix` function using `let` variables.
+
+```typescript
+function sumMatrix(matrix: number[][]) {
+    let sum = 0;
+    for (let i = 0; i < matrix.length; i++) {
+        var currentRow = matrix[i];
+        for (let i = 0; i < currentRow.length; i++) {
+            sum += currentRow[i];
+        }
+    }
+
+    return sum;
+}
+```
+
+This version of the loop will actually perform the summation correctly because the inner loop's `i` shadows `i` from the outer loop.
+Shadowing should *usually* be avoided in the interest of write clearer code, such as
+
+```typescript
+function sumMatrix(matrix: number[][]) {
+    let sum = 0;
+    for (let i = 0; i < matrix.length; i++) {
+        var currentRow = matrix[i];
+        for (let j = 0; j < currentRow.length; j++) {
+            sum += currentRow[j];
+        }
+    }
+
+    return sum;
+}
+```
+While there are some scenarios where it may be fitting to take advantage of it, you should use your best judgement.
+
+# `const` declarations
+
+`const` declarations are another way of declaring variables.
+
+```typescript
+const numLivesForCat = 9;
+```
+
+They are like `let` declarations but, as their name implies, their value cannot be changed once they are bound.
+In other words, they have the same scoping rules as `let`, but you can't re-assign to them.
+
+### ~button /js/operators
+NEXT: Operators
+### ~

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/headbands/activity.md

@@ -5,7 +5,7 @@
 Your beginning code should look like this:
 
 ```blocks 
-let coll = (<string[]>[])
+let coll: string[] = []
 coll.push("puppy")
 coll.push("clock")
 coll.push("night")
@@ -27,7 +27,7 @@ game.startCountdown(30000)
 Let's add more words for the player to act out! But first, we need to increase the time in one round to give the player more time get through all the words. Let's change the `game->start countdown` statement.
 
 ```blocks
-let coll = (<string[]>[])
+let coll: string[] = []
 coll.push("puppy")
 coll.push("clock")
 coll.push("night")
@@ -52,7 +52,8 @@ game.startCountdown(60000)
 Now let's add 5 more words to our list of charade words. Right above the the line `word:=coll->at(index)` add 5 lines that say `coll->add("")`. In this example, we will add the words **bicycle, telephone, sun, car, and ant** but you can add whatever words you like.
 
 ```blocks
-let coll.push("puppy")
+let coll: string[] = []
+coll.push("puppy")
 coll.push("clock")
 coll.push("night")
 coll.push("cat")

docs/lessons/headbands/quiz-answers.md

@@ -19,7 +19,7 @@ A 'collection' is a group of variables of the same type stored together. A 'coll
 ## 2. Consider the following lines of code.
 
 ```blocks
-let coll = (<string[]>[])
+let coll: string[] = []
 coll.push("puppy")
 coll.push("clock")
 ```
@@ -35,7 +35,7 @@ basic.showString(coll[0], 150)
 ## 3. Consider the following lines of code.
 
 ```blocks
-let coll = (<string[]>[])
+let coll: string[] = []
 coll.push("puppy")
 coll.push("clock")
 coll.push("cat")
@@ -52,7 +52,7 @@ basic.showString(coll[2], 150)
 ## 4. Consider the following line of code.
 
 ```blocks
-let coll = (<string[]>[])
+let coll: string[] = []
 ```
 
 Write the five (5) lines of code that will add the following five words to `data->coll`: puppy, clock, night, cat, cow.
@@ -60,7 +60,8 @@ Write the five (5) lines of code that will add the following five words to `data
 <br/>
 
 ```blocks
-let coll.push("puppy")
+let coll: string[] = []
+coll.push("puppy")
 coll.push("clock")
 coll.push("night")
 coll.push("cat")

docs/lessons/hero/activity.md

@@ -211,7 +211,7 @@ Let's setup the logic for the food and the ghost to be in different quadrants. F
 let hero = game.createSprite(2, 2);
 let food = game.createSprite(4, 4);
 let ghost = game.createSprite(0, 0);
-let ghost.change(LedSpriteProperty.Blink, 100);
+ghost.change(LedSpriteProperty.Blink, 100);
 food = led.brightness() == 8;
 while (true) {
     basic.pause(400);
@@ -265,7 +265,7 @@ while (true) {
     }
 
 }
-0.set(LedSpriteProperty.X, 4);
+ghost.set(LedSpriteProperty.X, 4);
 
 
 ```

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.md

@@ -14,7 +14,7 @@ Here are some cool projects that you can build with your micro:bit!
   "imageUrl": "/static/mb/projects/a2-buttons.png"
 },{
   "name": "Love Meter",
-  "url":"/projects/lover-meter",
+  "url":"/projects/love-meter",
   "imageUrl":"/static/mb/projects/a3-pins.png"
 },{
   "name": "Rock Paper Scissors",

docs/projects/the-watch.md

@@ -148,12 +148,6 @@ Trim any leftover fabric, threads or tape.
 
 Your watch is ready!
 
-### ~avatar avatar
-
-Excellent, you're ready to continue with the [challenges](/projects/rock-paper-scissors)!
-
-### ~
-
 ### Acknowledgements
 
 Artistic design by Melinda Hoeneisen.

docs/reference.md

@@ -22,14 +22,13 @@ control.inBackground(() => {
     
 });
 ```
-
 ## Advanced
-
+  
 ```namespaces
 devices.tellCameraTo(MesCameraEvent.TakePhoto);
 bluetooth.onBluetoothConnected(() => {});
 ```
-
+  
 ```package
 microbit-devices
 microbit-bluetooth

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.md

@@ -21,4 +21,4 @@ bluetooth.onBluetoothDisconnected(() => {
 
 ```package
 microbit-bluetooth
-```
+```

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

@@ -1,148 +0,0 @@
-# Game Library
-
-The game library supports simple single-player time-based games. The player has a **sprite**, number of **lives** and a **score**. The game has a sprite, number of **levels** and a **countdown clock**.  The general goal of a game will be to move the sprite and achieve a top score before time runs out or the number of lives goes to zero.
-
-The code below shows a simple game where the user gets to press the button ``A`` as much times as possible in 10 seconds.
-
-```blocks
-input.onButtonPressed(Button.A, () => {
-    game.addScore(1)
-})
-game.startCountdown(10000)
-```
-
-### [Create sprite](/reference/game/create-sprite)
-
-Create sprite with x, y coordinates and returns a LED Sprite. Create a new LED sprite.
-
-![](/static/mb/create-sprite-0.png)
-
-```
-export function createSprite(x: number, y: number) : micro_bitSprites.LedSprite
-```
-
-### [Move](/reference/game/move)
-
-Sprite move by a certain number
-
-![](/static/mb/game-library/move-0.png)
-
-```
-export function move(_this: micro_bitSprites.LedSprite, leds: number)
-```
-
-### [Turn](/reference/game/turn)
-
-Rotates a sprite to the right by a certain number of degrees
-
-![](/static/mb/game-library/turn-0.png)
-
-```
-export function turnRight(_this: micro_bitSprites.LedSprite, degrees: number)
-```
-
-Rotates a sprite to the left by a certain number of degrees
-
-```
-export function turnLeft(_this: micro_bitSprites.LedSprite, degrees: number)
-```
-
-### [Change](/reference/game/change)
-
-Sprite will change the x position by this number
-
-![](/static/mb/change-0.png)
-
-```
-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)
-```
-
-### [Set](/reference/game/set)
-
-Sprite will change the x position by this number
-
-```
-export function setX(_this: micro_bitSprites.LedSprite, x: number)
-```
-
-Sprite will change the y position by this number
-
-![](/static/mb/change-0.png)
-
-```
-export function changeYBy(_this: micro_bitSprites.LedSprite, y: number)
-```
-
-### [If on edge, bounce](/reference/game/if-on-edge-bounce)
-
-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)
-```
-
-### [Change score by](/reference/game/change-score-by)
-
-When a player achieves a goal, you can increase the game score
-
-* add score points to the current score
-
-![](/static/mb/game-library/pic1.png)
-
-```
-export function addScore(points: number)
-```
-
-### [Score](/reference/game/score)
-
-* set the current score to a particular value.
-
-```
-export function setScore(value: number)
-```
-
-* get the current score value
-
-![](/static/mb/game-library/pic2.png)
-
-```
-export function score() : number
-```
-
-### [Countdown](/reference/game/start-countdown)
-
-If your game has a time limit, you can start a countdown in which case `game->current time` returns the remaining time.
-
-* start a countdown with the maximum duration of the game in milliseconds.
-
-![](/static/mb/game-library/pic3.png)
-
-```
-export function startCountdown(ms: number)
-```
-
-### [Game over](/reference/game/game-over)
-
-If the `life` reaches zero or the time expires (see countdown), the game enters the **game over** mode. When the game is over, `game->is running` returns false
-
-* check if the game still running.
-
-```
-let running = game.isRunning()
-```
-
-You can also end the game by calling the `game -> game over` function:
-
-![](/static/mb/game-library/pic0.png)
-
-```
-game.gameOver()
-```

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-frame.md

@@ -16,7 +16,7 @@ export function showFrame(img: micro_bit.Image, frame: number)
 
 ### Difference from `plot frame`
 
-The `show frame` function is the same as [plot frame](/reference/image/plot-frame), but contains a built-in delay after the LED screen has been updated (whereas `plot frame` has no built-in delay)
+The `show frame` function is the same as [plot frame](/reference/images/plot-frame), but contains a built-in delay after the LED screen has been updated (whereas `plot frame` has no built-in delay)
 
 ### Example
 

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.md

@@ -14,6 +14,7 @@ input.onPinPressed(TouchPin.P0, () => {
 });
 input.buttonIsPressed(Button.A);
 input.compassHeading();
+input.pinIsPressed(TouchPin.P0);
 input.temperature();
 input.acceleration(Dimension.X);
 input.lightLevel();
@@ -21,7 +22,6 @@ input.rotation(Rotation.Pitch);
 input.magneticForce(Dimension.X);
 input.runningTime();
 input.setAccelerometerRange(AcceleratorRange.OneG);
-input.pinIsPressed(TouchPin.P0);
 input.calibrate();
 input.onLogoDown(() => {
     

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-leds.md

@@ -3,11 +3,11 @@
 Display an [Image](/reference/images/image) on the BBC micro:bit's [LED screen](/device/screen). NOTE: `basic -> plot image` has been replaced by `basic -> show leds`.
 
 ```sig
-basic.plotLeds(`
+basic.showLeds(`
 . . . . .
 . # . # .
 . . # . .
-# ; . . #
+# . . . #
 . # # # .
 `)
 ```
@@ -16,14 +16,14 @@ basic.plotLeds(`
 
 * leds - a series of LED on/off states that form an image (see steps below)
 
-### Example: simley
+### Example: smiley
 
 ```blocks
-basic.plotLeds(`
+basic.showLeds(`
 . . . . .
 . # . # .
 . . # . .
-# ; . . #
+# . . . #
 . # # # .
 `)
 ```

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,32 @@
 # 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 sets up the ``stop animation`` part of the program,
+and then shows a string that you can stop with button ``B``.
+
+```blocks
+input.onButtonPressed(Button.B, () => {
+    led.stopAnimation();
+});
+basic.showString("STOP ME! STOP ME! PLEASE, WON'T SOMEBODY STOP ME?");
+```
+
+### ~hint
+
+It's important to set up ``stop animation`` before showing the
+animation, so the ``stop animation`` part of the program will be ready
+to go.
+
+### ~
+
+### See Also
+
+[show animation](/reference/basic/show-animation)

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

@@ -14,8 +14,8 @@ pins.servoWritePin(AnalogPin.P0, 180)
 
 ### Parameters
 
-* a [string](/reference/types/string) that specifies the pin name (`P0` through `P4`, or `P10`)
-* a [number](/reference/types/number) from `0` through `180`
+* ``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