c_meyer/pxt-calliope
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs cleanup

Browse Source
This commit is contained in:
Peli de Halleux
2017-02-28 06:45:08 -08:00
parent 24c240c7de
commit ad2acb244a
246 changed files with 0 additions and 15424 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
docs/device/contents.md
View File

@ -1,19 +0,0 @@
# micro:bit - the device
The micro:bit is a very capable device with many components:
* [the USB connector](/device/usb)
* [the LED screen](/device/screen)
* [the buttons]
* [the accelerometer]
* [the compass]
* [the pins](/device/pins)
* [the battery plug]
The micro:bit embodies many fundamental concepts in computer science. To learn more, read:
* [the micro:bit - a reactive system](/device/reactive)
Sometimes, your micro:bit may display an error code. For more information, see:
* [the error codes](/device/error-codes)

47
docs/device/crocodile-clips.md
View File

@ -1,47 +0,0 @@
# crocodile clips
The large holes at the bottom of the board are designed to attach alligator/crocodile clips
to create electrical circuit with other components.
# ~hint
**No crocodile clips!?!?!** Use wires or Aluminium foil! [Read more...](/device/foil-circuits)
# ~
## Connecting Crocodile Clips
The hole for ``P0`` and ``GND`` allow to grab the board on the side which makes for a great grip.
![](/static/mb/device/croc-clips/crocclipsclamped.jpg)
Pass one jaw in the hole and grab the side of the board with the other jaw.
![](/static/mb/device/croc-clips/sideclamp.jpg)
For the center holes, ``P1`` and ``P2``, you can also grab the bottom of the board but they are a bit harder to grip.
You can also grip the board between the jaws. In which case, you will want to make sure to avoid overlapping the jaws
with the other pins as it will create short-circuit in the board.
![](/static/mb/device/croc-clips/badclamp.jpg)
Adding a little tape helps keeping the crocodile clips in place.
![](/static/mb/device/croc-clips/frontclamp.jpg)
## Example: on pin pressed with random numbers
This example displays a random number every time the crocodile clip holds `GND` then connects and disconnects the `P0` pin.
Each time the crocodile clip is firmly connected and disconnected from pin `P0`, the micro:bit will return a random Number between 0 and the parameter limit.
```blocks
input.onPinPressed(TouchPin.P0, () => {
basic.showNumber(Math.random(10))
})
```
## See also
[micro:bit pins](/device/pins)

23
docs/device/error-codes.md
View File

@ -1,23 +0,0 @@
# Error codes
Your micro:bit may encounter a situation that prevents it from running your code. When this happens, a frowny face will appear on your micro:bit screen (see picture) followed by an error number.
Below is a list of error numbers and what they mean:
* **10** (`MICROBIT_I2C_LOCKUP`): the micro:bit's I2C bus is not working
* **20** (`MICROBIT_OOM`): there is no free memory on the micro:bit
```sim
basic.showLeds(`
# . . . #
# # . # #
. . . . .
. # # # .
# . . . #
`)
```
### See also
[Run scripts on your micro:bit](/device/usb)

52
docs/device/foil-circuits.md
View File

@ -1,52 +0,0 @@
# foil circuits
The large holes at the bottom of the board are designed to attach alligator/crocodile clips
to create electrical circuit with other components.
If you do not have crocodile clips at hand, dyou can use wires or even Aluminium foil to acheive the same result.
We will show you how to connect the micro:bit to headphones using Alumunium foil and tape.
https://youtu.be/mhXYyPuvpz0
### Materials
* micro:bit and battery pack (you can also power it via USB)
* a small piece of cardboard
* Aluminium foil
* tape
### Assembly instructions
Tape the micro:bit and battery pack to the card board. Make sure to remove the batteries while you are building your circuit.
![](/static/mb/device/croc-clips/microbitattached.jpg)
Cut the thinest strip of foil possible and roll it into a cable. You can also try to fold, whatever works for you.
Build two of those wires.
![](/static/mb/device/croc-clips/foilcut.jpg)
Place the foil wire on the ``GND`` pin and attach with a piece of tape. Press hard to get the best connection between
the foil and the pin board. Make sure the foil is not overlapping with the other pins!
![](/static/mb/device/croc-clips/groundconnected.jpg)
Place the second wire on the ``P0`` pin the same way. Make sure the wire does not overlap with the other pins!
![](/static/mb/device/croc-clips/microbitconnect.jpg)
Tape the headphone jack connector to the cardboard and roll the wire coming from ``GND`` around the metal base.
Make sure the wire does not touch the other metal rings on the jack.
![](/static/mb/device/croc-clips/jackground.jpg)
Tape the second wire on the head of the jack connector.
![](/static/mb/device/croc-clips/jackconnect.jpg)
![](/static/mb/device/croc-clips/foilcircuit.jpg)
## See also
[micro:bit pins](/device/pins)

63
docs/device/pins.md
View File

@ -1,63 +0,0 @@
# micro:bit pins
The micro:bit pins
![](/static/mb/device/pins-0.png)
The micro:bit has 25 external connections on the edge connector of the board, which we refer to as ‘pins’. The edge connector is the grey area on the right side of the figure above.
There are five large pins, that are also connected to holes in the board labelled: 0, 1, 2, 3V, and GND. And along the same edge, there are 20 small pins that you can use when plugging the micro:bit into an edge connector.
### Large pins
You can easily attach crocodile clips or 4mm banana plugs to the five large pins.
The first three, labelled 0, 1 and 2 are flexible and can be used for many different things - which means they are often called ‘general purpose input and output’ (shortened to GPIO). These three pins also have the ability to read analogue voltages using something called an analogue-to-digital converter (ADC). They all have the same function:
* **0**: GPIO (general purpose digital input and output) with analogue to digital convertor (ADC).
* **1**: GPIO with ADC
* **2**: GPIO with ADC
The other two large pins (3V and GND) are very different!/td/td
### ~hint
Watch out! The pins labelled 3V and GND relate to the power supply of the board, and they should NEVER be connected together.
### ~
*power input*: If the micro:bit is powered by USB or a battery, then you can use the 3V pin as a *power output* to power peripherals with.
* **3V**: *3 volt power output* or *power input*. (1) *power output*: If the micro:bit is powered by USB or a battery, then you can use the 3V pin as a power output to power peripherals with; (2) *power input*: If the micro:bit is not being powered by USB or battery, you can use the 3V pin as a power input to power the micro:bit
* **GND**: attaches to ground in order to complete a circuit (required when using the 3V pin)
If you hold the ‘GND’ pin with one hand, you can program the microbit to detect yourself touching the 0,1 or 2 pins with your other hand, giving you three more buttons to experiment with (you just used your body to complete an electrical circuit).
### Small pins
There are 20 small pins numbered sequentially from 3-22 (these pins are not labeled on the micro:bit, however, they are labelled in the picture above).
Unlike the three large pins that are dedicated to being used for external connections, some of the small pins are shared with other components on the micro:bit board. For example, pin 3 is shared with some of the LEDs on the screen of the micro:bit, so if you are using the screen to scroll messages, you can’t use this pin as well.
* **pin 3**: GPIO shared with LED Col 1 of the LED screen; can be used for ADC and digital I/O when the LED screen is turned off.
* **pin 4**: GPIO shared with LED Col 2 of the LED screen; can be used for ADC and digital I/O when the LED screen is turned off.
* **pin 5**: GPIO shared with Button A. This lets you trigger or detect a button "A" click externally. This pin has a pull-up resistor, which means that by default it is at voltage of 3V. To replace button A on the micro:bit with an external button, connect one end of the external button to pin 4 and the other end to GND. When the button is pressed, the voltage on pin 4 is pulled down to 0, which generates a button click event.
* **pin 6**: GPIO shared with LED Col 9 of the LED screen; can be used for digital I/O when the LED screen is turned off.
* **pin 7**: GPIO shared with LED Col 8 of the LED screen; can be used for digital I/O when the LED screen is turned off.
* **pin 8**: Dedicated GPIO, for sending and sensing digital signals.
* **pin 9**: GPIO shared with LED Col 7 of the LED screen; can be used for digital I/O when the LED screen is turned off.
* **pin 10**: GPIO shared with LED Col 3 of the LED screen; can be used for ADC and digital I/O when the LED screen is turned off.
* **pin 11**: GPIO shared with Button B. This lets you trigger or detect a button “B” click externally.
* **pin 12**: this GPIO pin has been reserved to provide support for accessibility.
* **pin 13**: GPIO that is conventionally used for the serial clock (SCK) signal of the 3-wire Serial Peripheral Interface (SPI) bus.
* **pin 14**: GPIO that is conventionally used for the Master In Slave Out (MISO) signal of the SPI bus.
* **pin 15**: GPIO that is conventionally used for the Master Out Slave In (MOSI) signal of the SPI bus.
* **pin 16**: Dedicated GPIO (conventionally also used for SPI ‘Chip Select’ function).
* **pins 17 and 18**: these pins are wired to the 3V supply, like the large ‘3V’ pad.
* **pins 19 and 20**: implement the clock signal (SCL) and data line (SDA) of the I2C bus communication protocol. With I2C, several devices can be connected on the same bus and send/read messages to and from the CPU. Internally, the accelerometer and the compass are connected to i2c.
* **pins 21 and 22**: these pins are wired to the GND pin and serve no other function
### Connecting to the small pins
It is recommended that an edge connector be acquired to connect to the small pins. More information on compatible edge connectors will be available later.

158
docs/device/reactive.md
View File

@ -1,158 +0,0 @@
# The micro:bit - a reactive system
### Computing systems
What sort of a *computing system* is the micro:bit?
### ~hint
There are different types of computing systems, to address different kinds of problems that arise in practice: *transaction processing systems* are used by banks to handle huge numbers of financial transactions by their customers; *distributed systems* make a set of networked computers appear as one big computer (like Google’s search engine); there are also *parallel systems*, such as graphic cards, which perform a huge number of primitive operations simultaneously, using a great number of small processing cores.
### ~
The micro:bit is a *reactive system* – it reacts continuously to external events, such as a person pressing the A button of the micro:bit or shaking the device. The reaction to an event may be to perform a computation, update variables, and change the display. After the device reacts to an event, it is ready to react to the next one. If this sounds like a computer game, that’s because most computer games are reactive systems too!
### Responsiveness
We want reactive systems to be responsive, which means to react in a timely manner to events. For example, when you play a computer game, it’s frustrating if you press a button to make a character jump, but it doesn’t immediately jump. A delay in reacting, or lack of responsiveness , can be the difference between life and death, both in the real and virtual worlds.
Let’s consider a simple example: you want to program your micro:bit to accurately count the number of times the A button has been pressed and continuously display the current count on the 5x5 [LED screen](/device/screen). Because the LED screen is small, we can only display one digit of a number at a time on it. The [show number](/reference/basic/show-number) function will scroll the digits of a number across the screen so you can read it.
Let’s say that the current count is 42 and the number 42 is scrolling across the LED screen. This means there is some code executing to perform the scroll. So, what should happen if you press the A button during the scroll? It would be a bad idea to ignore the button press, so some code should record the occurrence of the button press. But we just said there already is code running in order to scroll the number 42! If we wait until the code scrolling the 42 has finished to look for a button press, we will miss the button press. We want to avoid this sort of unresponsiveness.
### Concurrency
To be responsive, a reactive system needs to be able to do several things at the same time (concurrently), just like you can. But the micro:bit only has one CPU for executing your program, which means it can only execute one program instruction at a time. On the other hand, it can execute millions of instructions in a single second. This points the way to a solution.
Think about how a motion picture projector works - it projects only 24 frames per second, yet this is good enough to provide the illusion of fluid motion on the screen. The micro:bit can execute millions of instructions per second, so it seems quite possible for the device to both to smoothly scroll the number 42 across the LED screen while looking for button presses and counting them.
Let’s think about three sequences of instructions:
* Sequence S1 contains the instructions (let’s say several hundred thousand or so) that scroll the number 42 across the LED screen;
* Sequence S2 contains a few instructions to check if button A is pressed;
* Sequence S3 contains a few instructions to increment a counter.
In order to be responsive, we would like to *interrupt* the execution of sequence S1 *periodically* to execute the sequence S2, which will check if button A is pressed, which looks like:
TODO Diagram
The result is that it takes sequence S1 a little longer to complete, due to the interruptions to execute sequence S2, but we are checking often enough to detect a press of button A . When S2 detects a press of button A, then the sequence S3 can be executed before S1 resumes:
TODO Diagram
As we’ll soon see, there are other choices for how the sequences can be ordered to achieve the desired result.
### The micro:bit scheduler and queuing up subprograms
The micro:bit’s *scheduler* provides the capability to concurrently execute different code sequences, relieving us of a lot of low-level programming. In fact, scheduling is so useful that it is a part of every *operating system*!
The first job of the scheduler is to allow multiple *subprograms* to be queued up for later execution . For our purposes, a subprogram is just a statement or sequence of statements in the context of a larger program. Consider the Touch Develop program below for counting button presses.
```blocks
let count = 0
input.onButtonPressed(Button.A, () => {
count++;
})
basic.forever(() => {
basic.showNumber(count, 150)
})
```
The program above contains three statements that execute in order from top to bottom.
The first statement initializes the global variable `count` to zero.
```blocks
let count = 0
```
The second statement informs the scheduler that on each and every event of the A button being pressed, a subprogram (called the event handler) should be queued for execution. The event handler is demarcated by the do/end keywords; it increments the global variable `count` by one.
```blocks
let count = 0
// ...
input.onButtonPressed(Button.A, () => {
count++;
})
```
The third statement queues a `forever` loop for later execution by the scheduler; the body of this loop (between the do/end keywords) displays the current value of global variable `count` on the LED screen. The third statement
```blocks
let count = 0
// ...
basic.forever(() => {
basic.showNumber(count, 150)
})
```
The function ends after the execution of these three statements, but this is not the end of program execution! That’s because the function queued the `forever` loop for execution by the scheduler.
The second job of the scheduler is to periodically interrupt execution to read (poll) the various inputs to the micro:bit (the buttons, pins, etc.) and fire off events (such as “button A pressed”). Recall that the firing of an event causes the event handler subprogram associated with that event to be queued for later execution. The scheduler uses a timer built into the micro:bit hardware to interrupt execution every 6 milliseconds and poll the inputs, which is more than fast enough to catch the quickest press of a button.
### Cooperative passing of control
How does the forever loop get to start execution? Furthermore, once the forever loop is running, how does any other subprogram (like the event handler that increments the count) ever get a chance to execute?
The answer is “cooperation” and “passing”. Think of a football team doing a drill – there is one ball and each footballer gets to dribble the ball for a certain number of touches, after which they pass to another footballer. A footballer who never passes prevents all other footballers from dribbling. A cooperative footballer always passes to some other footballer after taking a few touches.
If you hadn’t guessed already, a footballer represents subprogram and dribbling the ball corresponds to that subprogram executing. Only one subprogram gets to execute at a time, as there is only one ball (processor). Footballer Alice passing the ball to footballer Bob corresponds to stopping execution of Alice’s subprogram (and remembering where it stopped) and starting/resuming execution of Bob’s subprogram.
We will call this “passing control of execution” rather than “passing the ball”. However, in the world of the micro:bit, the concurrently executing subprograms are not aware of each other, so they don’t actually pass control directly to one another. Rather they pass control of execution back to the scheduler and the scheduler determines the subprogram to pass control to next. The programmer inserts a call to the `pause` function to indicate a point in the subprogram where control of execution passes to the scheduler. Also, when a subprogram ends execution, control passes to the scheduler.
Let’s take a look at the implementation of the `basic.forever` function to see an example of cooperative scheduling:
```typescript
function forever(body: () => void) {
control.inBackground(() => {
while(true) {
body()
basic.pause(20)
}
})
}
```
The `forever` loop actually is a function that takes a subprogram (an *Action* in Touch Develop) as a parameter. The function uses the `control -> in background` function of the micro:bit runtime to queue a `while true` loop for execution by the scheduler. The while loop has two statements. The first statement runs the subprogram represented by the `body` parameter. The second statement passes control to the scheduler (requesting to “sleep” for 20 milliseconds).
Though the `while true` loop will repeatedly execute the body subprogram, between each execution of the body it will permit the scheduler to execute other subprograms. If the while loop did not contain the call to `pause`, then once control passed into the while loop, it would never pass back to the scheduler and no other subprogram would be able to execute (unless the body subprogram contained a call to `pause` itself).
### Round-robin scheduling
Now, we come to the third and final job of the scheduler, which is to determine which subprogram to pass control to next. The scheduler uses two queues to perform this task, the sleep queue and the run queue. The sleep queue contains the subprograms that have called the pause function and still have time left to sleep. The run queue contains all the non-sleeping subprograms, such as the event handlers queued by the firing of an event.
The scheduler moves the subprogram that has just paused into the sleep queue and then removes the subprogram at the head of the run queue and resumes its execution. Once a subprogram’s sleep period is over, the scheduler moves it from the sleep queue to the back of the run queue.
The property of such round-robin scheduling is that under the assumption that every subprogram periodically enters the sleep queue, then every subprogram will periodically get a chance to execute.
### Putting it all together
Let’s go back to the `count button presses` function and revisit its execution based on what we have learned about the micro:bit scheduler. As detailed before, the function executes three steps to: (1) set up the event handler for each press of button A; (2) queue the forever loop to the run queue; (3) initialize the global variable `count` to zero.
The function then ends execution and control passes back to the scheduler. Let’s assume the user has not pressed any buttons . The scheduler finds the `forever` loop in the run queue and passes control to it. The loop first calls `basic -> show number(0,150)`. In the diagram below, we use “Show 0” to refer to the execution of this function:
![](/static/mb/device/reactive-3.png)
While "Show 0" (the blue sequence) is running, periodic interrupts by the scheduler (every 6 milliseconds) poll for button presses and queue an event handler for each press of button A. Let’s say that one button press takes place during this time, as shown above. This will cause an event handler (labelled “inc”) to be queued for later execution by the scheduler. Once the "Show 0" has completed, the loop then calls `basic -> pause(20)` to put the forever loop to sleep for 20 milliseconds and give the scheduler an opportunity to run any newly queued event handler. Control passes to the “inc” event handler which will increment the global variable `count` from 0 to 1 and then complete, returning control to the scheduler. At some point, the `forever` loop moves from the sleep queue to the run queue; the `forever` loop then will resume and call `basic -> show number(1,150)`.
### Final thoughts
Through this example, we have seen that the micro:bit scheduler enables you to create a program that is composed of concurrent subprograms. In essence, the programmer needs to only think about the concurrent subprograms cooperatively passing control back to the scheduler, making sure no subprogram hogs control (or “dribbles the ball without passing”) for too long. While a subprogram runs, the scheduler polls the buttons and other IO peripherals at a high frequency in order to fire off events and queue event handlers for later execution, but this is invisible to the programmer.
As a result, you can easily add a new capability to the micro:bit by just adding a new subprogram. For example, if you want to add a reset feature to the counter program, all you need to do is add a new event handler for a press of button B that sets the global variable "count" to zero, as shown below:
```typescript
export function countButtonPressesWithReset() {
let count = 0
input.onButtonPressed(Button.A, () => {
count = count + 1
})
basic.forever(() => {
basic.showNumber(count, 150)
})
input.onButtonPressed(Button.B, () => {
count = 0
})
}
```

100
docs/device/screen.md
View File

@ -1,100 +0,0 @@
# LED screen
The micro:bit LED screen
```sim
basic.showLeds(`
# . # . #
. # . # .
# . # . #
. # . # .
# . # . #
`);
```
The micro:bit LED screen consists of 25 red LED lights arranged in a 5X5 grid (5 LEDs across by 5 LEDs down).
In the screen above, we created a checkerboard pattern using the LEDs.
### Which LED?
You use `(x ,y)` coordinates to specify a particular LED in the grid;
where `x` is the horizontal position (0,1,2,3,4) and `y` is the vertical position
(0, 1, 2, 3, 4).
To figure out the ``x``, ``y`` coordinates, position your micro:bit horizontally, like a credit card (see picture above).
Here are the x, y coordinates for the LEDs in the 5X5 grid:
`(0,0)` `(1,0)` `(2,0)` `(3,0)` `(4,0)`
`(0,1)` `(1,1)` `(2,1)` `(3,1)` `(4,1)`
`(0,2)` `(1,2)` `(2,2)` `(3,2)` `(4,2)`
`(0,3)` `(1,3)` `(2,3)` `(3,3)` `(4,3)`
`(0,4)` `(1,4)` `(2,4)` `(3,4)` `(4,4)`
The x, y coordinates for the LED in the centre of the grid are `(2,2)`. Starting from `(0,0)` count over 2 columns and then down 2 rows.
### Check your understanding
Which LEDs are turned on in the checkboard pattern above?
### Row, column - 1
Since the row and column numbers start at 0, an easy way to figure out the (x,y) coordinates
is to subtract 1 from the row and column number (when counting from 1).
In other words, to specify the LED in the 4th column 5th row, subtract 1 from each number to get coordinates `(3,4)`.
### Turn a LED on/off
Use [plot](/reference/led/plot) and [unplot](/reference/led/unplot) to turn a LED on or off
```blocks
led.plot(0,0);
led.plot(1,1);
basic.pause(1000);
led.unplot(0,0);
basic.pause(1000);
led.unplot(1,1);
```
### Is a LED on/off?
Use the [point](/reference/led/point) function to find out if a LED is on or off.
```blocks
if(led.point(0,0)) {
}
```
### Display images, strings and numbers
Instead of turning individual LEDs on or off, as above, you can display an [image](/reference/images/image) directly to the screen or show text/numbers on screen using the [show number](/reference/basic/show-number)/[show string](/reference/basic/show-string) function.
### The display buffer
The micro:bit runtime keeps an in-memory representation of the state of all 25 LEDS. This state is known as the "display buffer" and controls which LEDS are on and which are off. The plot/unplot/point functions access the display buffer directly. On the other hand, the functions that show an image, number or string overwrite the buffer completely. To illustrate, first try running this code sequence
```blocks
basic.showString("d")
led.plot(0, 0)
```
You will see the letter "d" displayed as well as the LED in position `0,0` lit up. Now try reversing the order of the two statements above:
```blocks
led.plot(0, 0)
basic.showString("d", 150)
```
You will not see the LED at position `0,0` lit up because the `show string` function overwrites the whole display buffer.
### Pins: P3, P4, P6, P7, P9, P10
These pins are coupled to the LED matrix display, and also it’s associated ambient light sensing mode.
To disable the display driver feature (which will automatically disable the light sensing feature) use the function [led.enable](/reference/led/enable).
More information at http://tech.microbit.org/hardware/edgeconnector_ds/ .

93
docs/device/serial.md
View File

@ -1,93 +0,0 @@
# 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")
})
```
Data is also automatically streamed to serial by the ** bar graph** block
and picked up by the editor. This data can be streamed to the cloud as well.
```blocks
basic.forever(() => {
led.plotBarGraph(input.acceleration(Dimension.X), 0);
});
```
## How to read the micro:bit's serial output from your computer
Unfortunately, using the serial library requires quite a bit of a setup.
### BBC micro:bit Chrome Extension
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](https://pxt.microbit.org)
* 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).
* 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
* Install the terminal emulator [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.
#### Windows > 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
* 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`.
Alternative programs include `minicom` and so on.
### 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`.

25
docs/device/simulator.md
View File

@ -1,25 +0,0 @@
# Simulator
The JavaScript simulator allows to test and execute most BBC micro:bit programs in the browser.
It allows to emulate sensor data or user interactions.
```sim
input.onButtonPressed(Button.A, () => {
basic.showString("A");
});
input.onButtonPressed(Button.B, () => {
basic.showString("B");
});
input.onPinPressed(TouchPin.P0, () => {
basic.showString("0");
});
input.onPinPressed(TouchPin.P1, () => {
basic.showString("1");
});
input.onPinPressed(TouchPin.P2, () => {
basic.showString("2");
});
input.temperature()
input.compassHeading()
input.lightLevel()
```

31
docs/device/usb.md
View File

@ -1,31 +0,0 @@
# Uploading programs on your micro:bit
While you're writing and testing your programs, you'll mostly be [running them
in the simulator](/device/simulator), but once you've finished your program you
can **compile** it and run it on your micro:bit.
The basic steps are:
1. Connect your micro:bit to your computer via USB
2. Click **Download** and download the `.hex` file
3. Copy the `.hex` file from your computer onto the micro:bit drive
![](/static/mb/device/usb-thin.jpg)
## Instructions
Pick the instructions for your operating system and browser:
* [Windows - Microsoft Edge](/device/usb/windows-edge)
* [Windows - Internet Explorer](/device/usb/windows-ie)
* [Windows - Chrome](/device/usb/windows-chrome)
* [Windows - Firefox](/device/usb/windows-firefox)
* [Mac - Safari](/device/usb/mac-safari)
* [Mac - Chrome](/device/usb/mac-chrome)
* [Mac - Firefox](/device/usb/mac-firefox)
### ~hint
Transfer not working? See some [troubleshooting tips](/device/usb/troubleshooting).
### ~

69
docs/device/usb/mac-chrome.md
View File

@ -1,69 +0,0 @@
# Uploading from Chrome for Mac
While you're writing and testing your programs, you'll mostly be [running them
in the simulator](/device/simulator), but once you've finished your program you
can **compile** it and run it on your micro:bit.
The basic steps are:
1. Connect your micro:bit to your computer via USB
2. Click **Download** and download the `.hex` file
3. Copy the `.hex` file from your computer onto the micro:bit drive
## Requirements
You need the following things to transfer and run a script on your micro:bit:
* A-Male to Micro USB cable to connect your computer to your micro:bit. This is
the same cable that is commonly used to connect a smart phone to a computer.
* A PC running Windows 7 or later, or a Mac running OS X 10.6 or later
## Step 1: Connect your micro:bit to your computer
First, connect the micro:bit:
1. Connect the small end of the USB cable to the micro USB port on your micro:bit.
2. Connect the other end of the USB cable to a USB port on your computer.
Your computer should recognise your micro:bit as a new drive. On computers
running Windows, `MICROBIT` appears as a drive under Devices and drives. On a Mac
it appears as a new drive under Devices.
![](/static/mb/device/usb-osx-device.png)
## Step 2: Download your program
1. Open your project on [pxt.microbit.org](https://pxt.microbit.org)
2. Click **Download**
3. When prompted, choose to **save** the compiled file onto your computer. The
prompt will be different depending on which browser you are using, or
whether you are using a Windows computer or a Mac
When you select **Download** in Chrome, the file will appear at the bottom of
the browser. Click on the small arrow and select **Show in Finder**. This will
show the file in your download folder. Drag and drop the file onto your
`MICROBIT` drive.
![](/static/mb/device/usb-osx-chrome.png)
## Step 3: Transfer the file to your micro:bit
* Once you've found the folder containing your `.hex` file, drag and drop it
onto your `MICROBIT` drive
* The LED on the back of your micro:bit flashes during the transfer (which
should only take a few seconds).
* Once transferred, the code will run automatically on your micro:bit. To rerun
your program, press the reset button on the back of your micro:bit. The reset
button automatically runs the newest file on the micro:bit.
By copying the script onto the `MICROBIT` drive, you have programmed it into the
flash memory on the micro:bit, which means even after you unplug the micro:bit,
your program will still run if the micro:bit is powered by battery.
### ~hint
Transfer not working? See some [troubleshooting tips](/device/usb/troubleshooting).
### ~

71
docs/device/usb/mac-firefox.md
View File

@ -1,71 +0,0 @@
# Uploading from Firefox for Mac
While you're writing and testing your programs, you'll mostly be [running them
in the simulator](/device/simulator), but once you've finished your program you
can **compile** it and run it on your micro:bit.
The basic steps are:
1. Connect your micro:bit to your computer via USB
2. Click **Download** and download the `.hex` file
3. Copy the `.hex` file from your computer onto the micro:bit drive
## Requirements
You need the following things to transfer and run a script on your micro:bit:
* A-Male to Micro USB cable to connect your computer to your micro:bit. This is
the same cable that is commonly used to connect a smart phone to a computer.
* A PC running Windows 7 or later, or a Mac running OS X 10.6 or later
## Step 1: Connect your micro:bit to your computer
First, connect the micro:bit:
1. Connect the small end of the USB cable to the micro USB port on your micro:bit.
2. Connect the other end of the USB cable to a USB port on your computer.
Your computer should recognise your micro:bit as a new drive. On computers
running Windows, `MICROBIT` appears as a drive under Devices and drives. On a Mac
it appears as a new drive under Devices.
![](/static/mb/device/usb-osx-device.png)
## Step 2: Download your program
1. Open your project on [pxt.microbit.org](https://pxt.microbit.org)
2. Click **Download**
3. When prompted, choose to **save** the compiled file onto your computer. The
prompt will be different depending on which browser you are using, or
whether you are using a Windows computer or a Mac
A dialogue box will appear, asking whether you would like to open or save your
hex file. Select **Save file** and click **OK** and the file will then appear in
your downloads in the top right of your browser. Right click on the file and
click on **Show in Finder** and the file will appear in your downloads folder.
Select the file and drag and drop it onto your `MICROBIT` drive.
![](/static/mb/device/usb-osx-firefox-1.jpg)
![](/static/mb/device/usb-osx-firefox-2.png)
## Step 3: Transfer the file to your micro:bit
* Once you've found the folder containing your `.hex` file, drag and drop it
onto your `MICROBIT` drive
* The LED on the back of your micro:bit flashes during the transfer (which
should only take a few seconds).
* Once transferred, the code will run automatically on your micro:bit. To rerun
your program, press the reset button on the back of your micro:bit. The reset
button automatically runs the newest file on the micro:bit.
By copying the script onto the `MICROBIT` drive, you have programmed it into the
flash memory on the micro:bit, which means even after you unplug the micro:bit,
your program will still run if the micro:bit is powered by battery.
### ~hint
Transfer not working? See some [troubleshooting tips](/device/usb/troubleshooting).
### ~

68
docs/device/usb/mac-safari.md
View File

@ -1,68 +0,0 @@
# Uploading from Safari for Mac
While you're writing and testing your programs, you'll mostly be [running them
in the simulator](/device/simulator), but once you've finished your program you
can **compile** it and run it on your micro:bit.
The basic steps are:
1. Connect your micro:bit to your computer via USB
2. Click **Download** and download the `.hex` file
3. Copy the `.hex` file from your computer onto the micro:bit drive
## Requirements
You need the following things to transfer and run a script on your micro:bit:
* A-Male to Micro USB cable to connect your computer to your micro:bit. This is
the same cable that is commonly used to connect a smart phone to a computer.
* A PC running Windows 7 or later, or a Mac running OS X 10.6 or later
## Step 1: Connect your micro:bit to your computer
First, connect the micro:bit:
1. Connect the small end of the USB cable to the micro USB port on your micro:bit.
2. Connect the other end of the USB cable to a USB port on your computer.
Your computer should recognise your micro:bit as a new drive. On computers
running Windows, `MICROBIT` appears as a drive under Devices and drives. On a Mac
it appears as a new drive under Devices.
![](/static/mb/device/usb-osx-device.png)
## Step 2: Download your program
1. Open your project on [pxt.microbit.org](https://pxt.microbit.org)
2. Click **Download**
3. When prompted, choose to **save** the compiled file onto your computer. The
prompt will be different depending on which browser you are using, or
whether you are using a Windows computer or a Mac
When you select **Download** in Safari a file called `Unknown` will be
downloaded into your Downloads folder. Open your Downloads folder and drag and
drop the file onto your `MICROBIT` drive, under Devices:
![](/static/mb/device/usb-osx-dnd.png)
## Step 3: Transfer the file to your micro:bit
* Once you've found the folder containing your `.hex` file, drag and drop it
onto your `MICROBIT` drive
* The LED on the back of your micro:bit flashes during the transfer (which
should only take a few seconds).
* Once transferred, the code will run automatically on your micro:bit. To rerun
your program, press the reset button on the back of your micro:bit. The reset
button automatically runs the newest file on the micro:bit.
By copying the script onto the `MICROBIT` drive, you have programmed it into the
flash memory on the micro:bit, which means even after you unplug the micro:bit,
your program will still run if the micro:bit is powered by battery.
### ~hint
Transfer not working? See some [troubleshooting tips](/device/usb/troubleshooting).
### ~

24
docs/device/usb/troubleshooting.md
View File

@ -1,24 +0,0 @@
# Troubleshooting Transfer
You can’t drag and drop more than one hex file at once onto your micro:bit. If
you try to drag and drop a second hex file onto your micro:bit before the first
file has finished downloading, then the second file may fail in different ways.
When the first program has been written to the micro:bit, the drive will
disengage. If you drag and drop a second file at this point it may not find the
drive and the second write will fail.
The errors may look like this:
**Windows**
![](/static/mb/device/usb-windows-copy-file-error.jpg)
**Mac**
![](/static/mb/device/usb-osx-copy-file-error.png)
Or it may appear that there are two hex files on your micro:bit so the micro:bit
won’t be able to run multiple files. To rectify this, unplug your micro:bit and
plug it in again. Make sure that your micro:bit appears as `MICROBIT` and not
`MAINTENANCE`.

79
docs/device/usb/windows-chrome.md
View File

@ -1,79 +0,0 @@
# Uploading from Chrome for Windows
While you're writing and testing your programs, you'll mostly be [running them
in the simulator](/device/simulator), but once you've finished your program you
can **compile** it and run it on your micro:bit.
The basic steps are:
1. Connect your micro:bit to your computer via USB
2. Click **Download** and download the `.hex` file
3. Copy the `.hex` file from your computer onto the micro:bit drive
### ~hint
You can use the [micro:bit uploader](/uploader) to automatically deploy ``.hex`` files to your micro:bit!
![](/static/uploader/tooltip.png)
### ~
## Requirements
You need the following things to transfer and run a script on your micro:bit:
* A-Male to Micro USB cable to connect your computer to your micro:bit. This is
the same cable that is commonly used to connect a smart phone to a computer.
* A PC running Windows 7 or later, or a Mac running OS X 10.6 or later
## Step 1: Connect your micro:bit to your computer
First, connect the micro:bit:
1. Connect the small end of the USB cable to the micro USB port on your micro:bit.
2. Connect the other end of the USB cable to a USB port on your computer.
Your computer should recognise your micro:bit as a new drive. On computers
running Windows, `MICROBIT` appears as a drive under Devices and drives. On a Mac
it appears as a new drive under Devices.
![](/static/mb/device/usb-windows-device.jpg)
## Step 2: Download your program
1. Open your project on [pxt.microbit.org](https://pxt.microbit.org)
2. Click **Download**
3. When prompted, choose to **save** the compiled file onto your computer. The
prompt will be different depending on which browser you are using, or
whether you are using a Windows computer or a Mac
Your `.hex` file appears as a download at the bottom of the browser. Click on
the arrow next to the name of the file and then click **Show in folder**.
![](/static/mb/device/usb-windows-chrome.png)
Drag and drop the `.hex` file from the download folder onto the `MICROBIT` drive.
## Step 3: Transfer the file to your micro:bit
* Once you've found the folder containing your `.hex` file, drag and drop it
onto your `MICROBIT` drive
* The LED on the back of your micro:bit flashes during the transfer (which
should only take a few seconds).
* Once transferred, the code will run automatically on your micro:bit. To rerun
your program, press the reset button on the back of your micro:bit. The reset
button automatically runs the newest file on the micro:bit.
In File Explorer, right-click on the hex file (created in Step 2 above), choose **Send to**, and then **MICROBIT**.
![](/static/mb/device/usb-windows-sendto.jpg)
By copying the script onto the `MICROBIT` drive, you have programmed it into the
flash memory on the micro:bit, which means even after you unplug the micro:bit,
your program will still run if the micro:bit is powered by battery.
### ~hint
Transfer not working? See some [troubleshooting tips](/device/usb/troubleshooting).
### ~

89
docs/device/usb/windows-edge.md
View File

@ -1,89 +0,0 @@
# Uploading from Edge on Windows
How to compile, transfer, and run a program on your micro:bit on **Microsoft Edge**.
While you're writing and testing your programs, you'll mostly be [running them
in the simulator](/device/simulator), but once you've finished your program you
can **compile** it and run it on your micro:bit.
The basic steps are:
1. Connect your micro:bit to your computer via USB
2. Click **Download** and download the `.hex` file
3. Copy the `.hex` file from your computer onto the micro:bit drive
### ~hint
You can use the [micro:bit uploader](/uploader) to automatically deploy ``.hex`` files to your micro:bit!
![](/static/uploader/tooltip.png)
### ~
## Requirements
You need the following things to transfer and run a script on your micro:bit:
* A-Male to Micro USB cable to connect your computer to your micro:bit. This is
the same cable that is commonly used to connect a smart phone to a computer.
* A PC running Windows 7 or later, or a Mac running OS X 10.6 or later
## Step 1: Connect your micro:bit to your computer
First, connect the micro:bit:
1. Connect the small end of the USB cable to the micro USB port on your micro:bit.
2. Connect the other end of the USB cable to a USB port on your computer.
Your computer should recognise your micro:bit as a new drive. On computers
running Windows, `MICROBIT` appears as a drive under Devices and drives. On a Mac
it appears as a new drive under Devices.
![](/static/mb/device/usb-windows-device.jpg)
## Step 2: Download your program
1. Open your project on [pxt.microbit.org](https://pxt.microbit.org)
2. Click **Download**
3. When prompted, choose to **save** the compiled file onto your computer. The
prompt will be different depending on which browser you are using, or
whether you are using a Windows computer or a Mac
A message will appear at the bottom of the browser asking what you want to do
with the file. Click **Save**:
![](/static/mb/device/usb-windows-edge-1.png)
Then click **Open folder** and drag and drop the file from your Downloads to
your `MICROBIT` drive.
![](/static/mb/device/usb-windows-edge-2.png)
## Step 3: Transfer the file to your micro:bit
* Once you've found the folder containing your `.hex` file, drag and drop it
onto your `MICROBIT` drive
* If you're using Windows, you can use **Send to** as described below
* The LED on the back of your micro:bit flashes during the transfer (which
should only take a few seconds).
* Once transferred, the code will run automatically on your micro:bit. To rerun
your program, press the reset button on the back of your micro:bit. The reset
button automatically runs the newest file on the micro:bit.
In File Explorer, right-click on the hex file (created in Step 2 above), choose **Send to**, and then **MICROBIT**.
![](/static/mb/device/usb-windows-sendto.jpg)
By copying the script onto the `MICROBIT` drive, you have programmed it into the
flash memory on the micro:bit, which means even after you unplug the micro:bit,
your program will still run if the micro:bit is powered by battery.
If you want to save time, you can use the [micro:bit uploader](/uploader) to
automatically deploy hex files to your micro:bit. It works on Windows and is
compatible with any browser.
### ~hint
Transfer not working? See some [troubleshooting tips](/device/usb/troubleshooting).
### ~

86
docs/device/usb/windows-firefox.md
View File

@ -1,86 +0,0 @@
# Uploading from Firefox on Windows
How to compile, transfer, and run a program on your micro:bit on **Firefox for Windows**.
While you're writing and testing your programs, you'll mostly be [running them
in the simulator](/device/simulator), but once you've finished your program you
can **compile** it and run it on your micro:bit.
The basic steps are:
1. Connect your micro:bit to your computer via USB
2. Click **Download** and download the `.hex` file
3. Copy the `.hex` file from your computer onto the micro:bit drive
### ~hint
You can use the [micro:bit uploader](/uploader) to automatically deploy ``.hex`` files to your micro:bit!
![](/static/uploader/tooltip.png)
### ~
## Requirements
You need the following things to transfer and run a script on your micro:bit:
* A-Male to Micro USB cable to connect your computer to your micro:bit. This is
the same cable that is commonly used to connect a smart phone to a computer.
* A PC running Windows 7 or later, or a Mac running OS X 10.6 or later
## Step 1: Connect your micro:bit to your computer
First, connect the micro:bit:
1. Connect the small end of the USB cable to the micro USB port on your micro:bit.
2. Connect the other end of the USB cable to a USB port on your computer.
Your computer should recognise your micro:bit as a new drive. On computers
running Windows, `MICROBIT` appears as a drive under Devices and drives. On a Mac
it appears as a new drive under Devices.
![](/static/mb/device/usb-windows-device.jpg)
## Step 2: Download your program
1. Open your project on [pxt.microbit.org](https://pxt.microbit.org)
2. Click **Download**
3. When prompted, choose to **save** the compiled file onto your computer. The
prompt will be different depending on which browser you are using, or
whether you are using a Windows computer or a Mac
A window will appear asking whether you want to save or open the `.hex` file.
Select **Save File** and then select **OK**.
![](/static/mb/device/usb-windows-firefox-1.png)
The file will then appear in your downloads in the top right of your browser.
Click the **folder icon** next to the filename to open it in Windows Explorer.
![](/static/mb/device/usb-windows-firefox-2.jpg)
Drag and drop the `.hex` file from the download folder onto the `MICROBIT` drive.
## Step 3: Transfer the file to your micro:bit
* Once you've found the folder containing your `.hex` file, drag and drop it
onto your `MICROBIT` drive
* If you're using Windows, you can use **Send to** as described below
* The LED on the back of your micro:bit flashes during the transfer (which
should only take a few seconds).
* Once transferred, the code will run automatically on your micro:bit. To rerun
your program, press the reset button on the back of your micro:bit. The reset
button automatically runs the newest file on the micro:bit.
In File Explorer, right-click on the hex file (created in Step 2 above), choose **Send to**, and then **MICROBIT**.
![](/static/mb/device/usb-windows-sendto.jpg)
By copying the script onto the `MICROBIT` drive, you have programmed it into the
flash memory on the micro:bit, which means even after you unplug the micro:bit,
your program will still run if the micro:bit is powered by battery.
### ~hint
Transfer not working? See some [troubleshooting tips](/device/usb/troubleshooting).
### ~

86
docs/device/usb/windows-ie.md
View File

@ -1,86 +0,0 @@
# Uploading from Internet Explorer on Windows
While you're writing and testing your programs, you'll mostly be [running them
in the simulator](/device/simulator), but once you've finished your program you
can **compile** it and run it on your micro:bit.
The basic steps are:
1. Connect your micro:bit to your computer via USB
2. Click **Download** and download the `.hex` file
3. Copy the `.hex` file from your computer onto the micro:bit drive
### ~hint
You can use the [micro:bit uploader](/uploader) to automatically deploy ``.hex`` files to your micro:bit!
![](/static/uploader/tooltip.png)
### ~
## Requirements
You need the following things to transfer and run a script on your micro:bit:
* A-Male to Micro USB cable to connect your computer to your micro:bit. This is
the same cable that is commonly used to connect a smart phone to a computer.
* A PC running Windows 7 or later, or a Mac running OS X 10.6 or later
## Step 1: Connect your micro:bit to your computer
First, connect the micro:bit:
1. Connect the small end of the USB cable to the micro USB port on your micro:bit.
2. Connect the other end of the USB cable to a USB port on your computer.
Your computer should recognise your micro:bit as a new drive. On computers
running Windows, `MICROBIT` appears as a drive under Devices and drives. On a Mac
it appears as a new drive under Devices.
![](/static/mb/device/usb-windows-device.jpg)
## Step 2: Download your program
1. Open your project on [pxt.microbit.org](https://pxt.microbit.org)
2. Click **Download**
3. When prompted, choose to **save** the compiled file onto your computer. The
prompt will be different depending on which browser you are using, or
whether you are using a Windows computer or a Mac
A message will appear at the bottom of the browser asking what you want to do
with the file. Click **Save**:
![](/static/mb/device/usb-windows-ie11-1.png)
Then click **Open folder** and drag and drop the file from your Downloads to
your `MICROBIT` drive.
![](/static/mb/device/usb-windows-ie11-2.png)
## Step 3: Transfer the file to your micro:bit
* Once you've found the folder containing your `.hex` file, drag and drop it
onto your `MICROBIT` drive
* If you're using Windows, you can use **Send to** as described below
* The LED on the back of your micro:bit flashes during the transfer (which
should only take a few seconds).
* Once transferred, the code will run automatically on your micro:bit. To rerun
your program, press the reset button on the back of your micro:bit. The reset
button automatically runs the newest file on the micro:bit.
**Send to**: If you're using Windows you use *Send to* in File Explorer:
In File Explorer, right-click on the hex file (created in Step 2 above), choose **Send to**, and then **MICROBIT**.
![](/static/mb/device/usb-windows-sendto.jpg)
By copying the script onto the `MICROBIT` drive, you have programmed it into the
flash memory on the micro:bit, which means even after you unplug the micro:bit,
your program will still run if the micro:bit is powered by battery.
### ~hint
Transfer not working? See some [troubleshooting tips](/device/usb/troubleshooting).
### ~