pxt-calliope/docs/reference/js/serial-library.md

Serial Library

The serial library #docs

The serial library supports serial communication 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.

serial.writeLine("started...")
input.onButtonPressed("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. At the time of this writing, the latest version is 4.88 and can be downloaded from here. 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), here are some instructions.

• Open Windows's 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.

• (optional): in the "Terminal" section, check "implicit cr in every lf"

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.

Using the serial library in your programs

If the serial button is not available, you will need first to add the micro:bit serial library to your script:

• tap on add new
• tap on library
• select micro:bit serial

Writing data

This is basically what you will use the serial library for: debugging purposes.

• write a number

serial.writeNumber(42)

• write a string

serial.writeString("hello")

• write a line of text

serial.writeLine("this is a line")

Theoretically, you can dump more sophisticated data and then read it back in the event that two micro:bits should be connected to each other over serial. We have not tested this scenario yet as we have yet to expose functionality that allows re-routing the serial ports to the edge connector.

• write an image

let img = images.createImage(`
. . . . .
. # . # .
. . . . .
. . . . .
# # # # #
`)
serial.writeImage(img)

• write the current screen LED status

serial.writeScreen()

Reading data

This is useful if you have something connected at the other end. As explained above, this is not yet a scenario.

• reads a line of text

let msg = serial.readString()

• reads an image

img = serial.readImage()

• reads the state of the screen from serial

serial.readScreen()