added serial docs

docs/device.md

@@ -69,7 +69,11 @@ When your micro:bit isn’t connected to your computer, tablet or mobile, you wi
 The pins labelled 3V and GND are the power supply pins. 
 You can attach an external device such as a motor to these and power it using the battery or USB.
 
-### Bluetooth Low Energy Antenna
+### 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.
+
+### Bluetooth Low Energy (BLE) Antenna
 
 You will see the label BLE ANNTENA on the back of your micro:bit. It is for a messaging service, 
 so that devices can talk to each other. The micro:bit is a peripheral 

docs/device/serial.md

@@ -0,0 +1,64 @@
+# Serial
+
+The [serial](/reference/serial) supports [serial communication](https://en.wikipedia.org/wiki/Serial_port) between the BBC micro:bit and another computer. Basically, this allows you to send data from the micro:bit to your own computer. This is very useful for debugging purposes: you can add `write line` statements in your code and see them display on your computer as the program executes.
+
+The code below shows a simple script that sends a line when the BBC micro:bit starts and another line each time the button ``A`` is pressed.
+
+```blocks
+serial.writeLine("started...")
+input.onButtonPressed(Button.A, () => {
+    serial.writeLine("A pressed")
+})
+```
+
+## How to read the micro:bit's serial output from your computer
+
+Unfortunately, using the serial library requires quite a bit of a setup.
+
+### 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:
+
+* Follow instructions at https://developer.mbed.org/handbook/Windows-serial-configuration in order to install the device driver
+* Install a terminal emulator; we recommend [Tera Term](https://ttssh2.osdn.jp/index.html.en). At the time of this writing, the latest version is 4.88 and can be downloaded [from here](http://en.osdn.jp/frs/redir.php?m=jaist&f=%2Fttssh2%2F63767%2Fteraterm-4.88.exe). Follow the instructions from the installer.
+
+Once both the driver and the terminal emulator are installed, plug in the micro:bit and wait until the device is fully setup. Then, open TeraTerm.
+
+* Hit `File` > `New Connection`
+* Check "Serial"; in the dropdown menu, pick the COM port that says "mbed Serial Port". Hit `Ok`.
+* In the menus, hit `Setup` > `Serial Port` and set the baud rate to `115200`.
+
+You should be good. Feel free to hit `Setup` > `Save Setup` in the menus to erase the default configuration file with a new one so that you don't have to type in the settings again.
+
+Please note that Windows will assign you a different COM port if you plug in another micro:bit. If you're juggling between micro:bits, you'll have to change the COM port every time.
+
+### Alternative Windows setup with Putty
+
+If you prefer another terminal emulator (such as [PuTTY](http://www.putty.org/)), here are some instructions.
+
+* Open Windows's [Device Manager](https://windows.microsoft.com/en-us/windows/open-device-manager); expand the section called "Ports (COM & LPT)"; write down the com number for "mbed Serial Port" (e.g. COM14)
+* Open PuTTY; on the main screen, use the following settings: Serial / COM14 / 115200. Replace COM14 with the COM port number you wrote down previously. Feel free to type in a name and hit "Save" to remember this configuration.
+
+![](/static/mb/serial-library-0.png)
+
+* (optional): in the "Terminal" section, check "implicit cr in every lf"
+
+![](/static/mb/serial-library-1.png)
+
+### Linux
+
+(Untested).
+
+* 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.
+
+### Mac OS
+
+* Plug in the micro:bit
+* Open a terminal
+* `ls /dev/cu.*` will return to you a list of serial devices; one of them will look like `/dev/cu.usbmodem1422` (the exact number depends on your computer)
+* `screen /dev/cu.usbmodem1422 115200` will open up the micro:bit's serial output. To exit, hit `Ctrl-A` `Ctrl-D`.

docs/reference/serial.md

@@ -0,0 +1,8 @@
+# Serial
+
+[Serial communication](/device/serial) between the BBC micro:bit and another computer.
+
+```cards
+serial.writeLine("");
+serial.writeValue("x", 0);
+```

docs/reference/serial/write-line.md

@@ -0,0 +1,33 @@
+# Write Line
+
+Writes a string and a new line character (`\r\n`) to [serial](/device/serial).
+
+```sig
+serial.writeLine("");
+```
+
+### Example: streaming data
+
+The following example constantly checks the [compass heading](/reference/input/compass-heading) and sends the direction to serial.
+
+```blocks
+basic.forever(() => {
+    let heading = input.compassHeading()
+    if (heading < 45) {
+        serial.writeLine("N");
+    } else if (heading < 135) {
+        serial.writeLine("E");
+    }
+    else if (heading < 225) {
+        serial.writeLine("S");
+    }
+    else {
+        serial.writeLine("W");
+    }
+})
+```
+
+### See also
+
+[serial](/device/serial), [write value](/reference/serial/write-value)
+

docs/reference/serial/write-value.md

@@ -0,0 +1,36 @@
+# Write Value
+
+Writes name/value pair and a new line character (`\r\n`) to [serial](/device/serial).
+
+```sig
+serial.writeValue("x", 0);
+```
+
+### Example: streaming data
+
+The sample below sends the temperature and light level every 10 seconds.
+
+```blocks
+basic.forever(() => {
+    serial.writeValue("temp", input.temperature())
+    serial.writeValue("light", input.lightLevel())
+    basic.pause(10000);
+})
+```
+
+### Plot bar graph does serial!
+
+If you use the `led.plotBarGraph` function, it automatically writes the value to the serial as well.
+
+```blocks
+basic.forever(() => {
+    led.plotBarGraph(input.lightLevel(), 255)
+    basic.pause(10000);
+})
+```
+
+
+### See also
+
+[serial](/device/serial), [write value](/reference/serial/write-value)
+

libs/microbit/serial.ts

@@ -7,30 +7,24 @@ namespace serial {
      * Prints a line of text to the serial
      * @param value to send over serial
      */
+    //% help=/reference/serial/write-line
     //% blockId=serial_writeline block="serial|write %text"
     export function writeLine(text: string): void {
         writeString(text);
         writeString("\r\n");
     }
 
-    /**
-     * Prints a numeric value to the serial
-     */
-    export function writeNumber(value: number): void {
-        writeString(value.toString());
-    }
-
     /**
      * Writes a ``name: value`` pair line to the serial.
      * @param name name of the value stream, eg: x
      * @param value to write
      */
+    //% help=/reference/serial/write-value
     //% weight=80
     //% blockId=serial_writevalue block="serial|write %name|= %value"
     export function writeValue(name: string, value: number): void {
         writeString(name);
-        writeString(": ");
-        writeNumber(value);
-        writeLine("");
+        writeString(":");
+        writeLine(value.toString());
     }
 }