From 67c5f0612afaf9e5f57224f109a2718e8188b649 Mon Sep 17 00:00:00 2001 From: Peli de Halleux Date: Fri, 15 Apr 2016 16:36:31 -0700 Subject: [PATCH] added serial docs --- docs/device.md | 6 ++- docs/device/serial.md | 64 ++++++++++++++++++++++++++++ docs/reference/serial.md | 8 ++++ docs/reference/serial/write-line.md | 33 ++++++++++++++ docs/reference/serial/write-value.md | 36 ++++++++++++++++ libs/microbit/serial.ts | 14 ++---- 6 files changed, 150 insertions(+), 11 deletions(-) create mode 100644 docs/device/serial.md create mode 100644 docs/reference/serial.md create mode 100644 docs/reference/serial/write-line.md create mode 100644 docs/reference/serial/write-value.md diff --git a/docs/device.md b/docs/device.md index 48f52856..e765af73 100644 --- a/docs/device.md +++ b/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 diff --git a/docs/device/serial.md b/docs/device/serial.md new file mode 100644 index 00000000..117cdd73 --- /dev/null +++ b/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`. diff --git a/docs/reference/serial.md b/docs/reference/serial.md new file mode 100644 index 00000000..24c47b69 --- /dev/null +++ b/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); +``` diff --git a/docs/reference/serial/write-line.md b/docs/reference/serial/write-line.md new file mode 100644 index 00000000..b0aca910 --- /dev/null +++ b/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) + diff --git a/docs/reference/serial/write-value.md b/docs/reference/serial/write-value.md new file mode 100644 index 00000000..8ee9d6e2 --- /dev/null +++ b/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) + diff --git a/libs/microbit/serial.ts b/libs/microbit/serial.ts index 0418818e..b3ee8909 100644 --- a/libs/microbit/serial.ts +++ b/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()); } }