Bump V3.0.22 (#110)
* change simulator svg * change radio image * Remove google fonts cdn * change color of 'advanced' button * font fix * font fix 2 * display fix * change fullsceen simulator bg * Continuous servo * handle continuous state * adding shims * update rendering for continuous servos * fixing sim * fix sig * typo * fix sim * bump pxt * bump pxt * rerun travis * Input blocks revision - add Button and Pin event types - merge onPinPressed & onPinReleased in new onPinEvent function - create new onButtonEvent function * update input blocks in docs and tests * remove device_pin_release block * Hide DAL.x behind Enum * bring back deprecated blocks, but hide them * shims and locales files * fix input.input. typing * remove buildpr * bump V3 * update simulator aspect ratio * add Loudness Block * revoke loudness block * Adds soundLevel To be replaced by pxt-common-packages when DAL is updated. * Remove P0 & P3 from AnalogPin Co-authored-by: Juri <gitkraken@juriwolf.de>
This commit is contained in:
Amerlander
GitHub
19
docs/device/bluetooth/hf2.md
Normal file
19
docs/device/bluetooth/hf2.md
Normal file
@ -0,0 +1,19 @@
|
||||
# Bluetooth HF2
|
||||
|
||||
The Bluetooth HF2 service implements a subset of [HF2](https://github.com/Microsoft/uf2/blob/master/hf2.md), namely the serial message logging.
|
||||
|
||||
## Service
|
||||
|
||||
### HF2 service
|
||||
|
||||
* UUID: ``b112f5e6-2679-30da-a26e-0273b6043849``
|
||||
|
||||
### TX Characteristic
|
||||
|
||||
* Optional
|
||||
* UUDI: ``b112f5e6-2679-30da-a26e-0273b604384a``
|
||||
* NOTIFY only
|
||||
|
||||
This characteristic mostly emits HF2 serial messages. The first byte contains the type of message and length in the lower 6 bits. The message contains up to 19 bytes.
|
||||
|
||||
This service is supported by the MakeCode editor to receive messages.
|
||||
48
docs/device/crocodile-clips.md
Normal file
48
docs/device/crocodile-clips.md
Normal file
@ -0,0 +1,48 @@
|
||||
# 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](/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.
|
||||
|
||||
|
||||
|
||||
Pass one jaw in the hole and grab the side of the board with the other jaw.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
Adding a little tape helps keeping the crocodile clips in place.
|
||||
|
||||
|
||||
|
||||
## 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 @boardname@ will return a random Number between 0 and the parameter limit.
|
||||
|
||||
```blocks
|
||||
input.onPinPressed(TouchPin.P0, () => {
|
||||
basic.showNumber(randint(0, 10))
|
||||
})
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
[micro:bit pins](/device/pins)
|
||||
16
docs/device/data-analysis.md
Normal file
16
docs/device/data-analysis.md
Normal file
@ -0,0 +1,16 @@
|
||||
# Data Analysis
|
||||
|
||||
In addition to learning programming, the @boardname@ is a fantastic tool for observing and measuring things that happen in the natural world. The sciences rely on methods of observation, information gathering, and analysis. Using the @boardname@ with MakeCode, you can use the sensors and inputs to measure and capture physical events that occur. Measurement data can then be sent for recording by other devices like another @boardname@ or a personal computer.
|
||||
|
||||
|
||||
|
||||
The Data Viewer in the MakeCode editor allows you to stream and log data from your programs. It will do this when you write data values using the **[serial](/reference/serial)** write functions. When you try your code in the simulator or connect with USB, each value you write is saved and collected as a log for you to analyze later if you want.
|
||||
|
||||
These topics describe how to analyze your data using MakeCode with the @boardname@:
|
||||
|
||||
* [Plotting with LEDs](./data-analysis/led-plotting)
|
||||
* [Viewing your data](./data-analysis/viewing)
|
||||
* [Writing data](./data-analysis/writing)
|
||||
* [Generating data](./data-analysis/generating)
|
||||
* [Analyze](./data-analysis/analyze)
|
||||
* [Remote data collection](./data-analysis/remote)
|
||||
110
docs/device/data-analysis/analyze.md
Normal file
110
docs/device/data-analysis/analyze.md
Normal file
@ -0,0 +1,110 @@
|
||||
# Analyze
|
||||
|
||||
When it recognizes that data in the console has a format it can show in a chart, the Data Viewer will display it along with any new values that arrive. It also creates multiple charts if it notices more than one value stream in the incoming data.
|
||||
|
||||
If you want to keep the data and work with it later, you can download it and save it to your computer or mobile device.
|
||||
|
||||
## Charting value streams
|
||||
|
||||
As an example, let's generate some data for two values. The first value `x` makes a line on the chart. The second value is the square of the first value `x**2`shifted by `5`. This second value will show a chart of a parabola.
|
||||
|
||||
```blocks
|
||||
for (let x = 0; x <= 10; x++) {
|
||||
serial.writeValue("x", x)
|
||||
serial.writeValue("y", (x - 5)**2)
|
||||
basic.pause(1000)
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
Since we used ``||serial:serial write value||`` for each value, there are two charts, one for the `x` stream and the other for the `y` stream. Also, the values shown in the console window are formatted as name value pairs:
|
||||
|
||||
```
|
||||
x:0
|
||||
y:25
|
||||
x:1
|
||||
y:16
|
||||
...
|
||||
```
|
||||
|
||||
## Charting by data lines
|
||||
|
||||
Instead of writing multiple values separately, we can combine them in an array and write them together at once. Using the last example, let's combine each line and parabola value into an array.
|
||||
|
||||
```blocks
|
||||
for (let x = 0; x <= 10; x++) {
|
||||
serial.writeNumbers([x, (x - 5) ** 2])
|
||||
basic.pause(1000)
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
This time both values are shown on the same chart. We used ``||serial:serial write numbers||`` to send both values at the same time. Instead of being written as name value pairs, the values are combined into one line of comma separated values (CSV). The Data Viewer recognizes the values as one stream and puts multiple data lines on the same chart. The console shows the data in CSV format:
|
||||
|
||||
```
|
||||
0,25
|
||||
1,16
|
||||
2,9
|
||||
3,4
|
||||
...
|
||||
```
|
||||
|
||||
## Raw data
|
||||
|
||||
The data in the console window appears exactly like it's written by your program. The data your program writes is called "raw" data. The Data Viewer reads the data and "cooks" it by deciding how to display it in a way that's useful to you.
|
||||
|
||||
You can select and copy the raw data from the console and paste it into another program if you want to work with it outside of the MakeCode editor. Also, there is a copy button next to the console window that let's you easily copy the raw data with one click.
|
||||
|
||||
|
||||
|
||||
## Downloading your data
|
||||
|
||||
You can download your data to save it to view in another program. Click the **Download** button above the chart view.
|
||||
|
||||
|
||||
|
||||
The data is formatted again and saved in file with a name like:
|
||||
|
||||
``microbit-data-13-20-2018-14-18-15-0700.csv``
|
||||
|
||||
The filename contains the date and time when the data was downloaded. If you open the file in an editor you can see how the Data Viewer reformatted it from how it was in the console.
|
||||
|
||||
### Download format
|
||||
|
||||
The download file will contain your data as lines of CSV. The downloaded data from the first example will look something like this:
|
||||
|
||||
```
|
||||
sep=
|
||||
time (source1) x time (source1) y
|
||||
0 0 0 25
|
||||
1.018 1 1.026 16
|
||||
2.049 2 2.045 9
|
||||
3.062 3 3.059 4
|
||||
4.064 4 4.074 1
|
||||
5.078 5 5.078 0
|
||||
6.115 6 6.112 1
|
||||
7.097 7 7.112 4
|
||||
8.131 8 8.128 9
|
||||
9.145 9 9.145 16
|
||||
10.148 10 10.16 25
|
||||
```
|
||||
|
||||
The first line says what character is used as the value separator. Characters other than a comma can be used as separators. The Data Viewer choose to use a `TAB` character. The next line contains the headings for the values. These are the names of each value when name value pairs are written to the console. Also, a time value (timestamp) is included for each value. The timestamp is the amount of time since the start of the program when the value was written.
|
||||
|
||||
The remaining lines contain the data values and their timestamps. Each line has one occurrence of each value. So, for the example data above, each new `x` and `y` value is put together on the same line.
|
||||
|
||||
### Loading into a spreadsheet
|
||||
|
||||
Each line of data is placed into a row in the spreadsheet. The separators tell the spreadsheet which column the values go into.
|
||||
|
||||
|
||||
|
||||
### Analyze in the spreadsheet
|
||||
|
||||
Spreadsheets are powerful tools for analyzing and looking at relationships in your data. Most spreadsheet programs can do advanced charting too. Here's a chart of our example data. You'll notice that it looks similar to the chart displayed by the MakeCode editor.
|
||||
|
||||
|
||||
|
||||
The spreadsheet knows how to take the headings from the download file and use them as labels for the individual data lines.
|
||||
111
docs/device/data-analysis/generating.md
Normal file
111
docs/device/data-analysis/generating.md
Normal file
@ -0,0 +1,111 @@
|
||||
# Generating data
|
||||
|
||||
## Sensor values
|
||||
|
||||
Most of the data you want to record probably comes from values measured by the sensors. The sensor values are read using ``||input:Input||`` blocks. They return to your program the current value measured by the sensor.
|
||||
|
||||
```block
|
||||
serial.writeValue("accelX", input.acceleration(Dimension.X))
|
||||
```
|
||||
|
||||
```block
|
||||
serial.writeValue("heading", input.compassHeading())
|
||||
```
|
||||
|
||||
```block
|
||||
serial.writeValue("light", input.lightLevel())
|
||||
```
|
||||
|
||||
```block
|
||||
serial.writeValue("forceX", input.magneticForce(Dimension.X))
|
||||
```
|
||||
|
||||
## Pin data
|
||||
|
||||
External sensors and devices connected to the board are read using the ``||pins:Pins||`` blocks. Here are some examples of reading the pins and reporting measurements from devices:
|
||||
|
||||
### Soil moisture
|
||||
|
||||
```block
|
||||
let moisture = pins.analogReadPin(AnalogPin.P0)
|
||||
serial.writeValue("moisture", moisture)
|
||||
```
|
||||
|
||||
### Closed door detector
|
||||
|
||||
```block
|
||||
pins.onPulsed(DigitalPin.P0, PulseValue.Low, () => {
|
||||
serial.writeValue("DoorClosed", 1)
|
||||
})
|
||||
```
|
||||
|
||||
### I2C humidity sensor
|
||||
|
||||
```block
|
||||
let humidity = pins.i2cReadNumber(61, NumberFormat.Int8LE)
|
||||
serial.writeValue("humidity", humidity)
|
||||
```
|
||||
|
||||
## Human events
|
||||
|
||||
Sometimes we want to track human interactions with a device. These events might be button presses, gestures, or pin touches.
|
||||
|
||||
### Example: Button tracker
|
||||
|
||||
Run this example in the editor and switch to the Data Viewer. Watch it plot your button presses like pulse events in the chart.
|
||||
|
||||
```blocks
|
||||
let buttonValue = 0
|
||||
basic.forever(() => {
|
||||
if (input.buttonIsPressed(Button.A)) {
|
||||
buttonValue = 1
|
||||
} else {
|
||||
buttonValue = 0;
|
||||
}
|
||||
serial.writeValue("ButtonA", buttonValue)
|
||||
basic.pause(200)
|
||||
})
|
||||
```
|
||||
|
||||
Writing an additional value creates another stream that will appear in a separate chart. Adding and event for another button press, we can plot pulses on a second chart.
|
||||
|
||||
```blocks
|
||||
let buttonValue = 0
|
||||
basic.forever(() => {
|
||||
if (input.buttonIsPressed(Button.A)) {
|
||||
buttonValue = 1
|
||||
} else {
|
||||
buttonValue = 0;
|
||||
}
|
||||
serial.writeValue("ButtonA", buttonValue)
|
||||
if (input.buttonIsPressed(Button.B)) {
|
||||
buttonValue = 1
|
||||
} else {
|
||||
buttonValue = 0;
|
||||
}
|
||||
serial.writeValue("ButtonB", buttonValue)
|
||||
basic.pause(200)
|
||||
})
|
||||
```
|
||||
|
||||
## Time and timestamps
|
||||
|
||||
A timestamp marks when you read a value or detect that an event happens. These are commonly written along with other data values as an additional data item. The data viewer will create timestamps for values it sees when you write them. If you are downloading and saving data from the Data Viewer, it creates the timestamps for you and you don't need to add them.
|
||||
|
||||
If you need your own time values, you can make them from the **running time** of the board.
|
||||
|
||||
```block
|
||||
input.onGesture(Gesture.Shake, () => {
|
||||
serial.writeValue("shaken", input.runningTime())
|
||||
})
|
||||
```
|
||||
|
||||
Also, you can write your own custom CSV with your own timestamp:
|
||||
|
||||
```blocks
|
||||
serial.writeLine("timestamp,temp,light")
|
||||
basic.forever(() => {
|
||||
serial.writeNumbers([input.runningTime(), input.temperature(), input.lightLevel()])
|
||||
basic.pause(30000)
|
||||
})
|
||||
```
|
||||
97
docs/device/data-analysis/led-plotting.md
Normal file
97
docs/device/data-analysis/led-plotting.md
Normal file
@ -0,0 +1,97 @@
|
||||
# Plotting data with LEDs
|
||||
|
||||
To quickly see and record your data values, use the ``||led:plot bar graph||`` block. It will plot a value on the LED screen and write a number to console at the same time.
|
||||
|
||||
```blocks
|
||||
basic.forever(() => {
|
||||
let i = 0
|
||||
while (i < 25) {
|
||||
led.plotBarGraph(i, 25)
|
||||
i += 2
|
||||
basic.pause(1000)
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
Here's a plot of values from `1` to `25`:
|
||||
|
||||
```sim
|
||||
basic.forever(() => {
|
||||
let i = 0
|
||||
while (i < 25) {
|
||||
led.plotBarGraph(i, 25)
|
||||
i += 2
|
||||
basic.pause(1000)
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
## Plot range
|
||||
|
||||
A number of LEDs will light up to show how much the value is related to the _high_ number in the second argument. The high number sets the _range_ of values to show. If the high number is set to `16` and you want to plot the value of `8`, then that value is half of the range.
|
||||
|
||||
```block
|
||||
led.plotBarGraph(8, 16)
|
||||
```
|
||||
So, about half of the LEDs will light up to represent that number.
|
||||
|
||||
```sim
|
||||
basic.forever(() => {
|
||||
basic.clearScreen()
|
||||
basic.showString("8 up to 16")
|
||||
basic.clearScreen()
|
||||
basic.pause(500)
|
||||
led.plotBarGraph(8, 16)
|
||||
basic.pause(2000)
|
||||
})
|
||||
```
|
||||
|
||||
## Autoranging
|
||||
|
||||
If you don't know what the largest number to plot will be, then you can set the high number to `0`. This lets the largest value plotted be the range value. This is called _autoranging_. To see how it works, make an array of numbers and plot them. Put a large value in the middle of the array with smaller values before and after it. Watch as the same values are plotted with fewer lights after the largest number is plotted.
|
||||
|
||||
```blocks
|
||||
let values = [4,8,12,16,50,4,8,12,16]
|
||||
for (let i = 0; i < values.length; i++) {
|
||||
led.plotBarGraph(values[i], 0)
|
||||
basic.pause(1000)
|
||||
}
|
||||
```
|
||||
|
||||
## Recording plotted values
|
||||
|
||||
The ``||led:plot bar graph||`` also sends the number value it's plotting to the console. You can see the output in the Data Viewer. It charts the values and they appear as individual numbers in console.
|
||||
|
||||
```blocks
|
||||
input.onButtonPressed(Button.B, () => {
|
||||
for (let i = 0; i < 25; i++) {
|
||||
if (i % 2 > 0) {
|
||||
led.plotBarGraph(0, 0)
|
||||
} else {
|
||||
led.plotBarGraph(i, 24)
|
||||
}
|
||||
basic.pause(500)
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
The chart for the the plotted values from the example above:
|
||||
|
||||
|
||||
|
||||
The values appear in the console as just one number per line:
|
||||
|
||||
```
|
||||
0
|
||||
2
|
||||
0
|
||||
4
|
||||
0
|
||||
6
|
||||
...
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
[plot bar graph](/reference/led/plot-bar-graph)
|
||||
|
||||
161
docs/device/data-analysis/remote.md
Normal file
161
docs/device/data-analysis/remote.md
Normal file
@ -0,0 +1,161 @@
|
||||
# Remote data collection
|
||||
|
||||
If you have more than one @boardname@ you can setup one of them to receive data sent by radio from other @boardname@s. Remote @boardname@s can take measurements and send them to a board that's connected by USB to a computer. The @boardname@ connected to the computer is the data recorder and writes the received data to the serial port.
|
||||
|
||||
|
||||
|
||||
## Receiver @boardname@
|
||||
|
||||
Connect the @boardname@ to a computer with a USB cable. The data received over radio is sent to the computer with this connection using writes to the serial port. If you have the [Windows 10 MakeCode](https://www.microsoft.com/store/apps/9PJC7SV48LCX) app, you can view the received data with the [Data Viewer](./viewing) in the editor. Otherwise, you need a _serial terminal_ app or some other program that can read from the computer's serial port.
|
||||
|
||||
The receiving @boardname@ sets a radio group number on which to listen for incoming messages.
|
||||
|
||||
```block
|
||||
radio.setGroup(99)
|
||||
```
|
||||
|
||||
The receiver then waits to receive a packet (radio message) from the sender which contains the data to record. This happens inside an ``||radio:on received number||`` block. If the sending @boardname@ is measuring temperature at a remote location (somewhere else in the room maybe), the receiver will write the value received as a temperature measurement to the serial port.
|
||||
|
||||
```blocks
|
||||
radio.setGroup(99)
|
||||
radio.onReceivedNumber(function (receivedNumber) {
|
||||
basic.showNumber(receivedNumber)
|
||||
serial.writeValue("TempCelsius", receivedNumber)
|
||||
})
|
||||
```
|
||||
|
||||
## Remote sender @boardname@
|
||||
|
||||
A remote @boardname@ reads its measurement values and sends them to the same radio group as the receiver.
|
||||
|
||||
```block
|
||||
radio.setGroup(99)
|
||||
```
|
||||
A typical measurement program might read a sensor value continuously. Depending on how much the values change, the measurement program could contain the read operation in a loop with a delay interval. In the example here, the delay is one minute between each read of a temperature value. The value is sent on the current radio group with ``||radio:radio send number||``.
|
||||
|
||||
```blocks
|
||||
let temperature = 0
|
||||
radio.setGroup(99)
|
||||
basic.forever(() => {
|
||||
temperature = input.temperature()
|
||||
basic.showNumber(temperature)
|
||||
radio.sendNumber(temperature)
|
||||
basic.pause(60000)
|
||||
})
|
||||
```
|
||||
|
||||
## Sending multiple values
|
||||
|
||||
The remote @boardname@ in the previous example sent a single value which was temperature. The receiver understands that the incoming value is a temperature measurement. If you want the remote to also send the current amount of light measured, the receiver won't know that this other value isn't a temperature reading.
|
||||
|
||||
The sender code is modified to use a value packet instead of just a number message. Here's the sender program sending both temperature and light values with ``||radio:radio send value||``.
|
||||
|
||||
```blocks
|
||||
let temperature = 0
|
||||
let lightLevel = 0
|
||||
radio.setGroup(99)
|
||||
basic.forever(() => {
|
||||
temperature = input.temperature()
|
||||
radio.sendValue("temperature", temperature)
|
||||
lightLevel = input.lightLevel()
|
||||
radio.sendValue("light", lightLevel)
|
||||
basic.pause(60000)
|
||||
})
|
||||
```
|
||||
|
||||
Here's the program for the receiver to record both temperature and light:
|
||||
|
||||
```blocks
|
||||
radio.setGroup(99)
|
||||
radio.onReceivedValue(function (name: string, value: number) {
|
||||
basic.showString(name + ":")
|
||||
basic.showNumber(value)
|
||||
serial.writeValue(name, value)
|
||||
})
|
||||
```
|
||||
|
||||
The receiver program uses just one ``||radio:on received number||`` event to record the values. The ``name`` and the ``value`` are parameters for the event block so both temperature and light values are received here.
|
||||
|
||||
## Multiple remote stations
|
||||
|
||||
For more complex data recording situations, you might need to measure sensor values from multiple locations at the same time. This means that there is more than one remote @boardname@ (station) measuring data.
|
||||
|
||||
### Separate radio groups
|
||||
|
||||
You could add another receiver @boardname@ and set it to a different radio group. This way you can copy the same programs to each sender and receiver and just change the radio group number for the matched boards. This solution, though, means you need an extra receiver board and another computer to record the data from the second station.
|
||||
|
||||
### Station identifiers
|
||||
|
||||
A different solution from using more than one radio group is to still have just one receiver on one group but make the different stations send identifiers with their values.
|
||||
|
||||
This is done with ``||radio:radio set transmit serial number||`` which tells the radio to add the board's serial number to the packet it sends. The serial number is included with the ``name`` and ``value`` so the receiver can know what station it comes from.
|
||||
|
||||
```block
|
||||
radio.setTransmitSerialNumber(true)
|
||||
```
|
||||
|
||||
The sender's program with the identifier added:
|
||||
|
||||
```blocks
|
||||
let temperature = 0
|
||||
radio.setGroup(99)
|
||||
radio.setTransmitSerialNumber(true)
|
||||
basic.forever(() => {
|
||||
temperature = input.temperature()
|
||||
basic.showNumber(temperature)
|
||||
radio.sendValue("temperature", temperature)
|
||||
basic.pause(60000)
|
||||
})
|
||||
```
|
||||
|
||||
The program on the receiver board can use the serial number to make a name value pair that the [Data Viewer](./writing#name-value-pairs) can recognize:
|
||||
|
||||
```blocks
|
||||
let id = 0;
|
||||
radio.setGroup(99)
|
||||
radio.onReceivedValue(function (name: string, value: number) {
|
||||
id = radio.receivedPacket(RadioPacketProperty.SerialNumber)
|
||||
basic.showString(name + ":")
|
||||
basic.showNumber(value)
|
||||
serial.writeValue(id + "_" + name, value)
|
||||
})
|
||||
```
|
||||
|
||||
The serial number, ``id``, is used as a _prefix_ for the ``name`` to identify which station the ``value`` came from.
|
||||
|
||||
### Extended data recording
|
||||
|
||||
If you're recording data to save on a computer for analysis or other uses outside of the MakeCode editor, you can use the ``||radio:radio write received packet to serial||`` block to format it for you. This function will format the data from the received packet into a [JSON](https://en.wikipedia.org/wiki/JSON) string and write it to the serial port, all in one operation. It's used just like this:
|
||||
|
||||
```blocks
|
||||
radio.onReceivedNumber(function (receivedNumber) {
|
||||
radio.writeReceivedPacketToSerial();
|
||||
});
|
||||
```
|
||||
|
||||
The output to the serial port is a line of text with these name value pairs:
|
||||
|
||||
* **t** - time: the time when the packet was sent
|
||||
* **s** - serial: the serial number of the board that sent the packet (if enabled)
|
||||
* **n** - name: the name for the data value from the string part of the packet
|
||||
* **v** - value: the data from the number part of the packet
|
||||
|
||||
It's sent in this format to the serial port:
|
||||
|
||||
```json
|
||||
{"t":3504,"s":1951284846,"n":"temperature","v":19}
|
||||
{"t":3823,"s":1951284846,"n":"temperature","v":20}
|
||||
{"t":4143,"s":1951284846,"n":"temperature","v":20}
|
||||
{"t":4463,"s":1951284846,"n":"temperature","v":18}
|
||||
{"t":4781,"s":1951284846,"n":"temperature","v":21}
|
||||
{"t":5102,"s":1951284846,"n":"temperature","v":17}
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
[radio](/reference/radio), [serial write value](/reference/serial/write-value),
|
||||
[write received packet to serial](/reference/radio/write-received-packet-to-serial)
|
||||
|
||||
```package
|
||||
radio
|
||||
```
|
||||
50
docs/device/data-analysis/viewing.md
Normal file
50
docs/device/data-analysis/viewing.md
Normal file
@ -0,0 +1,50 @@
|
||||
# Viewing your data
|
||||
|
||||
## Recording data
|
||||
|
||||
When your code is writing data, and the editor is recording it, the **Show data** button is displayed in the simulator under the board and simulation controls.
|
||||
|
||||
|
||||
|
||||
## Data view window
|
||||
|
||||
If you press the **Show data** button, the editor will switch from the **Blocks** or **JavaScript** view to display a charting window and a text console.
|
||||
|
||||
|
||||
|
||||
The console window under the graph will show the data in the format it was written. The chart is the visual representation of the values appearing on the console.
|
||||
|
||||
## Time scroll
|
||||
|
||||
The chart will display new data as it arrives. The chart will scroll with time to continue to display new values.
|
||||
|
||||
|
||||
|
||||
## Data view controls
|
||||
|
||||
The chart window shows the data view controls on top of the chart.
|
||||
|
||||
|
||||
|
||||
Here's what the controls do:
|
||||
|
||||
**Return**: The return button switches the view back to previous code window (either Blocks or JavaScript).
|
||||
|
||||
|
||||
|
||||
|
||||
**Source**: Tells you where the data is coming from. If the code writing the data is running in the simulator, then the source is **Simulator**. If your code is running on the @boardname@ and connected by USB, the source is **@boardname@**.
|
||||
|
||||
|
||||
|
||||
**Pause**: The pause button will stop the display of new values and stop scrolling. When you resume, the chart starts again with the current value written.
|
||||
|
||||
|
||||
|
||||
**Resume**: The resume button will start displaying new values after the **Pause** button was pressed.
|
||||
|
||||
|
||||
|
||||
**Download**: The download button collects the data your code has written and downloads it to your computer as a file called something like _data-11-2018-23-00-0700.csv_. The numbers in the filename are the date and time when the file is created. The file may automatically open in an editor or spreadsheet if one of those programs is associated with _csv_ files.
|
||||
|
||||
|
||||
187
docs/device/data-analysis/writing.md
Normal file
187
docs/device/data-analysis/writing.md
Normal file
@ -0,0 +1,187 @@
|
||||
# Writing data
|
||||
|
||||
While you're using MakeCode, all data written by the [serial](/reference/serial) functions is recorded by the MakeCode editor. This happens when you try your code in the simulator and also when the @boardname@ is connected to a computer running the MakeCode app with USB.
|
||||
|
||||
## Data formats
|
||||
|
||||
The Data Viewer recognizes the format of your output and decides how to display it. If your data is a _stream_ of values it will plot them in the chart window and show them as text in the console. If your data is just text information, it appears only in the console window.
|
||||
|
||||
You can write data in these format types:
|
||||
|
||||
* Text ([string](/types/string)): `"Hello there!"`
|
||||
* [Numbers](/types/number): `"354"`
|
||||
* [Number arrays](/types/array): `"11,3,45,76"`
|
||||
* Name value pairs: `"accelY:956"`
|
||||
|
||||
## Text output
|
||||
|
||||
Text is formed by simply using string data. The text data is not recorded in the console until a complete "line" of text is written. A line is just a string with some special characters (ones you don't actually see printed) at the end. You can write several strings, say:
|
||||
|
||||
```block
|
||||
serial.writeString("Hello ");
|
||||
serial.writeString("from ")
|
||||
serial.writeString("micro:bit")
|
||||
```
|
||||
|
||||
This text, though, won't appear in the editor console until it becomes a complete line. If you follow the string writes with a line in your code, then the line will show up:
|
||||
|
||||
```block
|
||||
serial.writeString("Hello ")
|
||||
serial.writeString("from ")
|
||||
serial.writeString("micro:bit")
|
||||
serial.writeLine("")
|
||||
```
|
||||
|
||||
Text output is used mostly for messages since number formats have meaning when used for data analysis.
|
||||
|
||||
The blank ``||serial:serial write line||`` adds the special line ending characters and turns the previous strings into a complete line of text. The whole line could simply be written out with just one function:
|
||||
|
||||
```block
|
||||
serial.writeLine("Hello from micro:bit")
|
||||
```
|
||||
|
||||
When you're writing only text, it appears only in the console view and not in the chart window. This example writes four messages of text:
|
||||
|
||||
```block
|
||||
for (let i = 0; i < 4; i++) {
|
||||
serial.writeLine("Hello from micro:bit " + i)
|
||||
}
|
||||
```
|
||||
|
||||
The four messages appear in the console window:
|
||||
|
||||
|
||||
|
||||
## Writing numbers
|
||||
|
||||
In order for the Data Viewer to recognize a number as value and show in the chart, it has to be in a line by itself. So, numbers written individually won't be charted:
|
||||
|
||||
```block
|
||||
serial.writeNumber(1)
|
||||
serial.writeNumber(2)
|
||||
serial.writeNumber(3)
|
||||
```
|
||||
|
||||
The numbers don't show up as single values because they appear in the output as a string: `"123"`. Also, the string doesn't form a complete line so it doesn't show up in the console window either. You could add a blank line to the numbers already written. If you did this, you would have just one value charted which is `123`:
|
||||
|
||||
```block
|
||||
serial.writeNumber(1)
|
||||
serial.writeNumber(2)
|
||||
serial.writeNumber(3)
|
||||
serial.writeLine("")
|
||||
```
|
||||
|
||||
Here's a way to chart the numbers individually:
|
||||
|
||||
```block
|
||||
for (let i = 0; i < 4; i++) {
|
||||
serial.writeNumber(i)
|
||||
serial.writeLine("")
|
||||
}
|
||||
```
|
||||
|
||||
It's much better though to use a value stream by writing the numbers as [name value pairs](#name-value-pairs).
|
||||
|
||||
## Number arrays
|
||||
|
||||
Numbers in arrays are displayed on separate data lines on the same chart. You can use ``||serial:serial write numbers||`` to write several values at once. The numbers are written to the output as _comma separated values_ (CSV). The array of numbers:
|
||||
|
||||
```block
|
||||
let values = [0,1,2,3,4];
|
||||
```
|
||||
|
||||
is written to the output in the form of a CSV string as: `"0,1,2,3,4"`.
|
||||
|
||||
The Data Viewer recognizes this as an array of numbers and charts them on separate data lines:
|
||||
|
||||
```block
|
||||
let values = [0, 1, 2, 3, 4]
|
||||
basic.forever(() => {
|
||||
serial.writeNumbers(values)
|
||||
})
|
||||
```
|
||||
|
||||
Data lines are shown for each value in the array:
|
||||
|
||||
|
||||
|
||||
Give this example a try and watch the chart make a diamond pattern from two triangle waves:
|
||||
|
||||
```blocks
|
||||
let diamond: number[] = []
|
||||
basic.forever(() => {
|
||||
for (let i = 0; i <= 10 - 1; i++) {
|
||||
if (i < 5) {
|
||||
diamond[0] = i
|
||||
diamond[1] = 5 - i
|
||||
} else {
|
||||
diamond[0] = 10 - i
|
||||
diamond[1] = i - 5
|
||||
}
|
||||
serial.writeNumbers(diamond)
|
||||
basic.pause(500)
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
It will look like this:
|
||||
|
||||
|
||||
|
||||
## Name value pairs
|
||||
|
||||
A very common way to report and record data is to use a _name value pair_ (NVP). A value is given a name so you know what it's for or where it came from. The name value pair is written with the format of _name:value_. There is a name, a colon character, and the value all together on one line. The line is written to the output and the Data Viewer recognizes it as a value and charts it as part of a value stream. The value stream is based on the name so any new values received with the same name are displayed on the chart that's showing values for that name. If more than one type of name value pair is found, the Data Viewer makes another value stream and shows those values on a different chart.
|
||||
|
||||
If you want to report the values for both temperature and light, you can make separate name value pairs for them. The name value pairs are written using ``||serial:serial write value||``. This function writes the values to the output as lines in a format like this:
|
||||
|
||||
```
|
||||
temp:17
|
||||
light:118
|
||||
temp:18
|
||||
light:117
|
||||
```
|
||||
|
||||
```blocks
|
||||
basic.forever(() => {
|
||||
serial.writeValue("temp", input.temperature())
|
||||
serial.writeValue("light", input.lightLevel())
|
||||
basic.pause(5000)
|
||||
})
|
||||
```
|
||||
|
||||
Two charts display each value stream:
|
||||
|
||||
|
||||
|
||||
The console output shows the different name value pairs too:
|
||||
|
||||
|
||||
|
||||
### Writing subvalues
|
||||
|
||||
Similar to number arrays, different name value pairs are shown on one chart by using _subvalues_. You make a subvalue by combining a first-level name and a second-level name with a `'.'`:
|
||||
|
||||
``"firstLevel.secondLevel"``
|
||||
|
||||
The first-level name is value name for the chart. The second-level name is the name for the actual value displayed.
|
||||
|
||||
If you want to show all three values of acceleration on a single chart, then use each axis as a second-level (subvalue) name, ``"acceleration.x"``.
|
||||
|
||||
```block
|
||||
serial.writeValue("acceleration.x", input.acceleration(Dimension.X))
|
||||
```
|
||||
|
||||
To show the values for each axis together:
|
||||
|
||||
```blocks
|
||||
basic.forever(() => {
|
||||
serial.writeValue("acceleration.x", input.acceleration(Dimension.X))
|
||||
serial.writeValue("acceleration.y", input.acceleration(Dimension.Y))
|
||||
serial.writeValue("acceleration.z", input.acceleration(Dimension.Z))
|
||||
basic.pause(500)
|
||||
})
|
||||
```
|
||||
|
||||
Each subvalue ``'x'``, ``'y'``, and ``'z'`` is displayed on the chart named ``"acceleration"`` in the Data Viewer.
|
||||
|
||||
|
||||
86
docs/device/error-codes.md
Normal file
86
docs/device/error-codes.md
Normal file
@ -0,0 +1,86 @@
|
||||
# Error codes
|
||||
|
||||
Your @boardname@ may encounter a situation that prevents it from running your code. When this happens, a frowny face will appear on your @boardname@ screen (see picture) followed by an error number. These are called _panic_ codes.
|
||||
|
||||
```sim
|
||||
basic.forever(function() {
|
||||
basic.showLeds(`
|
||||
# . . . #
|
||||
# # . # #
|
||||
. . . . .
|
||||
. # # # .
|
||||
# . . . #
|
||||
`)
|
||||
basic.pause(1000)
|
||||
basic.clearScreen()
|
||||
basic.showString("020")
|
||||
})
|
||||
```
|
||||
|
||||
## Board system errors
|
||||
|
||||
The @boardname@ system errors range between **01** - **99**. For a full list of these codes, what they mean and what you can do to resolve them, visit the [micro:bit guide to error codes](https://support.microbit.org/en/support/solutions/articles/19000016969).
|
||||
|
||||
* **10** (`MICROBIT_I2C_LOCKUP`): the @boardname@'s I2C bus is not working
|
||||
* **20** (`MICROBIT_OOM`): there is no free memory on the @boardname@
|
||||
* **30** (`MICROBIT_HEAP_ERROR`): a problem in the heap space
|
||||
* **40** (`MICROBIT_NULL_DEREFERENCE `): there was a NULL dereference, the @boardname@ tried to manage a invalid object pointer
|
||||
* **42** (`MICROBIT_SYSTEM_ERROR`): there's an error condition in the @boardname@ system software
|
||||
* **43** (`MICROBIT_NO_RADIO`): the @boardname@ can't enable the radio
|
||||
* **50** (`MICROBIT_HARDWARE_UNAVAILABLE_ACC`): an error occurred with the micro:bit's accelerometer component
|
||||
* **51** (`MICROBIT_HARDWARE_UNAVAILABLE_MAG`): an error occurred with the micro:bit's magnetometer component
|
||||
* **90** (`MICROBIT_HARDWARE_CONFIGURATION_ERROR`): actual board hardware doesn't match the configuration description
|
||||
* **98** (`MICROBIT_ASSERTION_FAILED`): assertion failed, the condition in an [assert](/reference/control/assert) was false
|
||||
|
||||
## Memory errors
|
||||
|
||||
Memory error codes range from **800** - **909**.
|
||||
|
||||
### ~alert
|
||||
|
||||
#### Report errors!
|
||||
|
||||
If you ever see an error within the range of **800** - **909**, please report an issue at [GitHub](https://github.com/microsoft/pxt-microbit/issues) or on the [support](https://support.microbit.org/) page.
|
||||
|
||||
### ~
|
||||
|
||||
### Garbage collector errors
|
||||
|
||||
Error codes generated from the garbage collector.
|
||||
|
||||
* **840**: Allocation pointer is null or invalid
|
||||
* **841**: Garbage collection work queue error
|
||||
* **843**: VTable entry is not free
|
||||
* **844**: GC allocation failed for requested number of bytes
|
||||
* **846**: Invalid allocation thread
|
||||
* **848**: Allocation pointer beyond allocation header
|
||||
* **849**: Allocation pointer is null
|
||||
|
||||
### Program access errors
|
||||
|
||||
* **901** (`PANIC_INVALID_BINARY_HEADER`): the type header for the object is not valid
|
||||
* **902** (`PANIC_OUT_OF_BOUNDS`): the object data portion is greater than the length defined for it
|
||||
* **903** (`PANIC_REF_DELETED`): an object reference was deleted and the object is no longer valid
|
||||
* **904** (`PANIC_SIZE`): the object size doesn't match the size defined for the type
|
||||
* **905** (`PANIC_INVALID_VTABLE`): an object vtable is invalid or not initialized
|
||||
* **906** (`PANIC_INTERNAL_ERROR`): an internal resource error
|
||||
* **907** (`PANIC_NO_SUCH_CONFIG`): the specified device resource is not present
|
||||
* **909** (`PANIC_INVALID_ARGUMENT`): the argument value is out of range or the type or format is invalid
|
||||
|
||||
## JavaScript runtime codes
|
||||
|
||||
### Invalid cast codes
|
||||
|
||||
When the static type of ``x`` is a class ``C``, the dynamic type of ``x`` isn’t ``C``, and you try to access a field on ``x`` or call a method on ``x``, you will get one of the following codes, depending on dynamic type of ``x``.
|
||||
|
||||
* **980** (`PANIC_CAST_FROM_UNDEFINED`): when value of ``x`` is ``undefined``
|
||||
* **981** (`PANIC_CAST_FROM_BOOLEAN`): when value of ``x`` is ``true`` or ``false``
|
||||
* **982** (`PANIC_CAST_FROM_NUMBER`): when ``x`` is a ``number``
|
||||
* **983** (`PANIC_CAST_FROM_STRING`): when ``x`` is a ``string``
|
||||
* **984** (`PANIC_CAST_FROM_OBJECT`): when ``x`` is object of some type
|
||||
* **985** (`PANIC_CAST_FROM_FUNCTION`): when ``x`` is a function
|
||||
* **989** (`PANIC_CAST_FROM_NULL`): when ``x`` is ``null``
|
||||
|
||||
## See also
|
||||
|
||||
[panic](/reference/control/panic), [assert](/reference/control/assert)
|
||||
11
docs/device/firmware.md
Normal file
11
docs/device/firmware.md
Normal file
@ -0,0 +1,11 @@
|
||||
# Firmware
|
||||
|
||||
Occasionally, changes and improvements to the system software (firmware) on the @boardname@ are needed. Updates to the firmware are made by the [micro:bit Education Foundation](http://microbit.org/about).
|
||||
|
||||
## Do I need an update?
|
||||
|
||||
Changes to the firmware don't happen very often. You probably don't need to update it for your @boardname@ if everything is working alright. Sometimes there's a problem with a certain part of the board not working right or it has trouble connecting to your computer or other device. In those cases, a firmware update may include a fix for the problem.
|
||||
|
||||
## Getting a firmware update
|
||||
|
||||
Instructions for updating the firmware are shown on the **[firmware upgrade](https://microbit.org/guide/firmware/)** support page at microbit.org.
|
||||
52
docs/device/foil-circuits.md
Normal file
52
docs/device/foil-circuits.md
Normal file
@ -0,0 +1,52 @@
|
||||
# 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, you can use wires or even Aluminium foil to achieve the same result.
|
||||
We will show you how to connect the @boardname@ to headphones using Aluminium foil and tape.
|
||||
|
||||
https://youtu.be/mhXYyPuvpz0
|
||||
|
||||
## Materials
|
||||
|
||||
* @boardname@ and battery pack (you can also power it via USB)
|
||||
* a small piece of cardboard
|
||||
* Aluminium foil
|
||||
* tape
|
||||
|
||||
## Assembly instructions
|
||||
|
||||
Tape the @boardname@ and battery pack to the card board. Make sure to remove the batteries while you are building your circuit.
|
||||
|
||||
|
||||
|
||||
Cut the thinnest 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.
|
||||
|
||||
|
||||
|
||||
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!
|
||||
|
||||
|
||||
|
||||
Place the second wire on the ``P0`` pin the same way. Make sure the wire does not overlap with the other pins!
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
Tape the second wire on the head of the jack connector.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## See also
|
||||
|
||||
[@boardname@ pins](/device/pins)
|
||||
145
docs/device/mes-events.md
Normal file
145
docs/device/mes-events.md
Normal file
@ -0,0 +1,145 @@
|
||||
# MES events
|
||||
|
||||
Events and event values are generated in the Message Event Service (MES). Using MES events allows orderly interactions between the @boardname@ and external devices. These events are sent to and received from other wireless devices paired with the @boardname@ (phone, game pad, etc.).
|
||||
|
||||
The event source IDs represent a device feature category. The event values are actions for, or notifications about a device feature.
|
||||
|
||||
### ~hint
|
||||
|
||||
**MES system sources**
|
||||
|
||||
The MES events are defined in this source file of the **[microbit-dal](https://github.com/lancaster-university/microbit-dal)**:
|
||||
|
||||
* [MESEvents.h](https://github.com/lancaster-university/microbit-dal/blob/master/inc/bluetooth/MESEvents.h)
|
||||
|
||||
Also, you can see how the message bus works in the DAL core files:
|
||||
|
||||
* [MemberFunctionCallback.cpp](https://github.com/lancaster-university/microbit-dal/blob/master/source/core/MemberFunctionCallback.cpp)
|
||||
* [MicroBitListener.cpp](https://github.com/lancaster-university/microbit-dal/blob/master/source/core/MicroBitListener.cpp)
|
||||
|
||||
### ~
|
||||
|
||||
## Raised events
|
||||
|
||||
Events are generated, or _raised_, for by the @boardname@ for a paired device. These are raised using the [raise event](/reference/control/raise-event) function.
|
||||
|
||||
```typescript-ignore
|
||||
control.raiseEvent(
|
||||
control.eventSourceId(EventBusSource.MES_REMOTE_CONTROL_ID),
|
||||
control.eventValueId(EventBusValue.MES_REMOTE_CONTROL_EVT_VOLUMEUP)
|
||||
);
|
||||
```
|
||||
|
||||
### Remote control
|
||||
|
||||
Events for using the @boardname@ as a remote control for audio play.
|
||||
|
||||
#### MES_REMOTE_CONTROL_ID
|
||||
|
||||
* `MES_REMOTE_CONTROL_EVT_PLAY`: Play the current track
|
||||
* `MES_REMOTE_CONTROL_EVT_PAUSE`: Pause the current play in progress
|
||||
* `MES_REMOTE_CONTROL_EVT_STOP`: Stop playing and reset to the beginning of the current track
|
||||
* `MES_REMOTE_CONTROL_EVT_NEXTTRACK`: Skip to the next track
|
||||
* `MES_REMOTE_CONTROL_EVT_PREVTRACK`: Skip to the previous track
|
||||
* `MES_REMOTE_CONTROL_EVT_FORWARD`: Move forward in the current track
|
||||
* `MES_REMOTE_CONTROL_EVT_REWIND`: Move backward in the current track
|
||||
* `MES_REMOTE_CONTROL_EVT_VOLUMEUP`: Increase the play volume (audio)
|
||||
* `MES_REMOTE_CONTROL_EVT_VOLUMEDOWN`: Decrease the play volume (audio)
|
||||
|
||||
### Camera
|
||||
|
||||
Control camera actions on a paired device.
|
||||
|
||||
#### MES_CAMERA_ID
|
||||
|
||||
* `MES_CAMERA_EVT_LAUNCH_PHOTO_MODE`: Turn on or set the camera to _photo_ mode.
|
||||
* `MES_CAMERA_EVT_LAUNCH_VIDEO_MODE`: Turn on or set the camera to _video_ mode.
|
||||
* `MES_CAMERA_EVT_TAKE_PHOTO`: Capture the picture in the camera view.
|
||||
* `MES_CAMERA_EVT_START_VIDEO_CAPTURE`: Begin capturing video (start record)
|
||||
* `MES_CAMERA_EVT_STOP_VIDEO_CAPTURE`: End capturing video (stop record)
|
||||
* `MES_CAMERA_EVT_STOP_PHOTO_MODE`: Stop photo mode and return to the default mode
|
||||
* `MES_CAMERA_EVT_STOP_VIDEO_MODE`: Stop video mode and return to the default mode
|
||||
* `MES_CAMERA_EVT_TOGGLE_FRONT_REAR`: Switch from the front camera to rear camera or rear to front
|
||||
|
||||
### Alerts
|
||||
|
||||
Trigger standard alert notifications on a device.
|
||||
|
||||
#### MES_ALERTS_ID
|
||||
|
||||
* `MES_ALERT_EVT_DISPLAY_TOAST`
|
||||
* `MES_ALERT_EVT_VIBRATE`
|
||||
* `MES_ALERT_EVT_PLAY_SOUND`
|
||||
* `MES_ALERT_EVT_PLAY_RINGTONE`
|
||||
* `MES_ALERT_EVT_FIND_MY_PHONE`
|
||||
* `MES_ALERT_EVT_ALARM1`
|
||||
* `MES_ALERT_EVT_ALARM2`
|
||||
* `MES_ALERT_EVT_ALARM3`
|
||||
* `MES_ALERT_EVT_ALARM4`
|
||||
* `MES_ALERT_EVT_ALARM5`
|
||||
* `MES_ALERT_EVT_ALARM6`
|
||||
|
||||
## Received events
|
||||
|
||||
Events are received by the @boardname@ from a paired device. You capture these in an [on event](/reference/control/on-event) function.
|
||||
|
||||
```typescript-ignore
|
||||
control.onEvent(EventBusSource.MES_DEVICE_INFO_ID, EventBusValue.MES_DEVICE_INCOMING_CALL, () => {
|
||||
|
||||
})
|
||||
```
|
||||
|
||||
### Carrier signal strength
|
||||
|
||||
Signal strength to the subscribed carrier service.
|
||||
|
||||
#### MES_SIGNAL_STRENGTH_ID
|
||||
|
||||
* `MES_SIGNAL_STRENGTH_EVT_NO_BAR`: No service available or very low signal strength
|
||||
* `MES_SIGNAL_STRENGTH_EVT_ONE_BAR`: Low signal strength
|
||||
* `MES_SIGNAL_STRENGTH_EVT_TWO_BAR`: Medium signal strength
|
||||
* `MES_SIGNAL_STRENGTH_EVT_THREE_BAR`: High signal strength
|
||||
* `MES_SIGNAL_STRENGTH_EVT_FOUR_BAR`: Full signal strength
|
||||
|
||||
### Device information
|
||||
|
||||
Information about the current status of the device
|
||||
|
||||
#### MES_DEVICE_INFO_ID
|
||||
|
||||
* `MES_DEVICE_ORIENTATION_LANDSCAPE`: Display orientation is now in landscape
|
||||
* `MES_DEVICE_ORIENTATION_PORTRAIT`: Display orientation is now in portrait
|
||||
* `MES_DEVICE_GESTURE_NONE`: No gesture detected for device activation
|
||||
* `MES_DEVICE_GESTURE_DEVICE_SHAKEN`: The device was shaken
|
||||
* `MES_DEVICE_DISPLAY_OFF`: Device display is now turned off
|
||||
* `MES_DEVICE_DISPLAY_ON`: Device display is now turned on
|
||||
* `MES_DEVICE_INCOMING_CALL`: Currently receiving an incoming call
|
||||
* `MES_DEVICE_INCOMING_MESSAGE`: A message was received (SMS or other messaging app)
|
||||
|
||||
### Game pad controller
|
||||
|
||||
Button events from a paired game pad.
|
||||
|
||||
#### MES_DPAD_CONTROLLER_ID
|
||||
|
||||
* `MES_DPAD_BUTTON_A_DOWN`: Button **A** pressed
|
||||
* `MES_DPAD_BUTTON_A_UP`: Button **A** released
|
||||
* `MES_DPAD_BUTTON_B_DOWN`: Button **B** pressed
|
||||
* `MES_DPAD_BUTTON_B_UP`: Button **B** released
|
||||
* `MES_DPAD_BUTTON_C_DOWN`: Button **C** pressed
|
||||
* `MES_DPAD_BUTTON_C_UP`: Button **C** released
|
||||
* `MES_DPAD_BUTTON_D_DOWN`: Button **D** pressed
|
||||
* `MES_DPAD_BUTTON_D_UP`: Button **D** released
|
||||
* `MES_DPAD_BUTTON_1_DOWN`: Button **1** pressed
|
||||
* `MES_DPAD_BUTTON_1_UP`: Button **1** released
|
||||
* `MES_DPAD_BUTTON_2_DOWN`: Button **2** pressed
|
||||
* `MES_DPAD_BUTTON_2_UP`: Button **2** released
|
||||
* `MES_DPAD_BUTTON_3_DOWN`: Button **3** pressed
|
||||
* `MES_DPAD_BUTTON_3_UP`: Button **3** released
|
||||
* `MES_DPAD_BUTTON_4_DOWN`: Button **4** pressed
|
||||
* `MES_DPAD_BUTTON_4_UP`: Button **4** released
|
||||
|
||||
## See also
|
||||
|
||||
[raise event](/reference/control/raise-event), [on event](/reference/control/on-event),
|
||||
[event value](/reference/control/event-value)
|
||||
64
docs/device/pins.md
Normal file
64
docs/device/pins.md
Normal file
@ -0,0 +1,64 @@
|
||||
# micro:bit pins
|
||||
|
||||
The micro:bit pins
|
||||
|
||||
|
||||
|
||||
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!
|
||||
|
||||
## ~hint
|
||||
|
||||
Watch out! The pins labelled 3V and GND relate to the power supply of the board, and they should NEVER be connected together.
|
||||
For details on the power, current and voltage limitations of the board, see [Power Supply](https://tech.microbit.org/hardware/powersupply/)
|
||||
|
||||
## ~
|
||||
|
||||
*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 5 and the other end to GND. When the button is pressed, the voltage on pin 5 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.
|
||||
|
||||
172
docs/device/reactive.md
Normal file
172
docs/device/reactive.md
Normal file
@ -0,0 +1,172 @@
|
||||
# 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. It can, however, 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:
|
||||
|
||||
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
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 program below for counting button presses.
|
||||
|
||||
```typescript
|
||||
let count = 0
|
||||
|
||||
input.onButtonPressed(Button.A, () => {
|
||||
count++;
|
||||
})
|
||||
|
||||
basic.forever(() => {
|
||||
basic.showNumber(count)
|
||||
})
|
||||
```
|
||||
|
||||
The program above contains three statements that execute in order from top to bottom.
|
||||
The first statement initializes the global variable `count` to zero.
|
||||
|
||||
```typescript
|
||||
// statement 1
|
||||
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 code is contained within the braces `{...}`; it increments the global variable `count` by one.
|
||||
|
||||
```typescript
|
||||
// statement 1
|
||||
let count = 0
|
||||
// statement 2
|
||||
input.onButtonPressed(Button.A, () => {
|
||||
count++;
|
||||
})
|
||||
```
|
||||
|
||||
The third statement queues a `forever` loop for later execution by the scheduler; the body of this loop (also inside the braces `{...}`) displays the current value of global variable `count` on the LED screen.
|
||||
|
||||
```typescript
|
||||
// statement 1
|
||||
let count = 0
|
||||
// statement 2
|
||||
input.onButtonPressed(Button.A, () => {
|
||||
count++;
|
||||
})
|
||||
// statement 3
|
||||
basic.forever(() => {
|
||||
basic.showNumber(count)
|
||||
})
|
||||
```
|
||||
|
||||
There are no more statements after the execution of these three statements, but this is not the end of program execution! That’s because the program queued the `forever` loop for execution by the scheduler (and registered an event handler for presses of button A).
|
||||
|
||||
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 (another function) as a parameter. The function uses the `control.inBackground` 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` program and revisit its execution based on what we have learned about the micro:bit scheduler. As detailed before, the program executes three steps to:
|
||||
|
||||
1. Initialize the global variable `count` to zero
|
||||
2. Set up the event handler for each press of button **A**
|
||||
3. Queue the forever loop to the run queue
|
||||
|
||||
The program 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.showNumber(0)`. In the diagram below, we use “Show 0” to refer to the execution of this function:
|
||||
|
||||
|
||||
|
||||
|
||||
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.showNumber(1)`.
|
||||
|
||||
## 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
|
||||
let count = 0
|
||||
|
||||
input.onButtonPressed(Button.A, () => {
|
||||
count = count + 1
|
||||
})
|
||||
|
||||
basic.forever(() => {
|
||||
basic.showNumber(count)
|
||||
})
|
||||
|
||||
input.onButtonPressed(Button.B, () => {
|
||||
count = 0
|
||||
})
|
||||
```
|
||||
|
||||
97
docs/device/screen.md
Normal file
97
docs/device/screen.md
Normal file
@ -0,0 +1,97 @@
|
||||
# LED screen
|
||||
|
||||
```sim
|
||||
basic.showLeds(`
|
||||
# . # . #
|
||||
. # . # .
|
||||
# . # . #
|
||||
. # . # .
|
||||
# . # . #
|
||||
`);
|
||||
```
|
||||
|
||||
The micro:bit LED screen has 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 center 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 and numbers on screen using the [show number](/reference/basic/show-number) and [show string](/reference/basic/show-string) functions.
|
||||
|
||||
## The display buffer
|
||||
|
||||
The micro:bit runtime keeps a representation of the state of all 25 LEDS in memory. This state is known as the "display buffer" and controls which LEDs are on and which are off. The plot, unplot, and 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 this, 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")
|
||||
```
|
||||
|
||||
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 to the display'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/ .
|
||||
81
docs/device/serial.md
Normal file
81
docs/device/serial.md
Normal file
@ -0,0 +1,81 @@
|
||||
# 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.
|
||||
|
||||
### ~ hint
|
||||
|
||||
**Windows earlier than 10**
|
||||
|
||||
If you are running a Windows version earlier than 10, you must [install a device driver](https://os.mbed.com/docs/latest/tutorials/windows-serial-driver.html) (for the computer to recognize the serial interface of the micro:bit).
|
||||
|
||||
## ~
|
||||
Also, if you don't see the serial port as one of your computer's devices, you might need to [update the firmware](/device/firmware) on the @boardname@. Find the device name for the attached serial port in the following instructions for your operating system.
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
|
||||
* (optional): in the "Terminal" section, check "implicit cr in every lf"
|
||||
|
||||
|
||||
|
||||
## 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`.
|
||||
144
docs/device/servo.md
Normal file
144
docs/device/servo.md
Normal file
@ -0,0 +1,144 @@
|
||||
# Equipping a microservo with Crocodile clips
|
||||
|
||||
## ~ hint
|
||||
|
||||
If you are conducting a class or group activity, you should consider preparing all servos ahead of time.
|
||||
|
||||
## ~
|
||||
|
||||
## Using a microservo with the @boardname@
|
||||
|
||||
The @boardname@ provides just enough current to operate the SG90 microservo. This servo requires 3 connections: **GND**, **3V** and a logic **pin**. In this tutorial, we will equip the servo with crocodile clips to make it easier to use. However, you could also use a shield or crocodile clips with a male connector on one end to achieve the same result.
|
||||
|
||||
### ~ hint
|
||||
|
||||
To better understand how servos work and how they are controlled, take a few minutes to read this [Brief Guide to Servos](https://www.kitronik.co.uk/pdf/a-brief-guide-to-servos.pdf).
|
||||
|
||||
### ~
|
||||
|
||||
## The easy way: Alligator/Crocodile Clip to Male Jumpers #hintconnection
|
||||
|
||||
The easiest way to connect a servo to the @boardname@ is to use cables with an **Alligator/Crocodile clip** on one end
|
||||
and a **Male jumper (pig tail)** on the other end. You can purchase bundles these cables from various electronic resellers or easily build some as shown here.
|
||||
|
||||
https://youtu.be/XtzsydSTXEg
|
||||
|
||||
### Materials
|
||||
|
||||
* 1 Crocodile clip cable
|
||||
* 1 male (pig tail) cable
|
||||
* Cutting pliers or wire cutter
|
||||
* 1 piece of heat shrink tubing and a lighter
|
||||
|
||||
Simply cut the cables, strip them, twist the bare wires together, and cover the connection with some heat shrink tubing.
|
||||
|
||||
### ~ hint
|
||||
|
||||
It is very **important** to ensure a good connection between the 2 cables. If the connection is weak, the microservo will not receive enough current and it will not work. **If you have access to a soldering iron, we strongly recommend that you solder this connection.**
|
||||
|
||||
### ~
|
||||
|
||||
## Direct connection
|
||||
|
||||
You can also connect your crocodile clips directly to the servo.
|
||||
|
||||
### Materials
|
||||
|
||||
* Cutting pliers or wire cutter
|
||||
* Tape (masking, duct tape, and/or packing tape)
|
||||
* 3 crocodile clips, yellow, red and black.
|
||||
* 1 micro servo 9g (SG90)
|
||||
|
||||
### Step 1: Cut off the connector
|
||||
|
||||
With the cutting pliers, cut off the dark plastic connector.
|
||||
|
||||
|
||||
|
||||
### Step 2: Strip the ends of the cables
|
||||
|
||||
Using the pliers or a wire stripper, strip the plastic insulation from the cables.
|
||||
|
||||
|
||||
|
||||
### Step 3: Twist the wire strands together
|
||||
|
||||
Twist the strands of bare wire at the ends of the servo cables together.
|
||||
|
||||
|
||||
|
||||
### Step 4: Crocodile clip
|
||||
|
||||
Cut a crocodile cable in two and strip off the insulation. If it's possible, try to use cables with colors that match the cables on the servo!
|
||||
|
||||
|
||||
|
||||
### Step 5: Thread the cable ends together
|
||||
|
||||
Place the cables next to each other...
|
||||
|
||||
|
||||
|
||||
... and thread them together.
|
||||
|
||||
|
||||
|
||||
### ~ hint
|
||||
|
||||
It is very **important** to ensure that there is a good connection between the 2 cables. If the connection is weak, the microservo will not receive enough current and it will not work. **If you have access to a soldering iron, we strongly recommend soldering this connection.**
|
||||
|
||||
### ~
|
||||
|
||||
### Step 6: Protect the connection
|
||||
|
||||
Protect the connection with heat shrink tubing, electrical tape, or duct tape.
|
||||
|
||||
|
||||
|
||||
### Step 7: Repeat for all cables
|
||||
|
||||
Repeat the same process until all cables are connected.
|
||||
|
||||
|
||||
|
||||
### Step 8: Testing!
|
||||
|
||||
It's time to test and find out if your connections are all secure and that the servo will function **when the @boardname@ is powered by battery**.
|
||||
|
||||
* Connect the microservo cables to these pins on the @boardname@: black to **GND**, red to **3V**, and the remaining cable to pin **0**.
|
||||
|
||||
|
||||
|
||||
## ~ hint
|
||||
|
||||
When attaching the crocodile clips to the pins, don't be afraid to clamp on to the edge of the board with the clips.
|
||||
|
||||
|
||||
|
||||
## ~
|
||||
|
||||
* Download the following code to your @boardname@.
|
||||
|
||||
```blocks
|
||||
basic.forever(() => {
|
||||
pins.servoWritePin(AnalogPin.P0, pins.map(
|
||||
input.acceleration(Dimension.X),
|
||||
-512,
|
||||
512,
|
||||
0,
|
||||
180
|
||||
))
|
||||
})
|
||||
```
|
||||
|
||||
* Test with both power sources and make sure that the servo moves when you tilt the board:
|
||||
>* Connected with USB.
|
||||
>* Powered by batteries **only** and not connected with USB.
|
||||
|
||||
## Calibrating
|
||||
|
||||
Use the [servo calibrator](/projects/servo-calibrator) program to determine the best angles to use for your make.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If your servo seems to stutter and remain stuck at a particular position, it means that it's not receiving enough power. This is probably due to a weak connection or low battery level. Make sure that each connection is good and check your batteries.
|
||||
25
docs/device/simulator.md
Normal file
25
docs/device/simulator.md
Normal file
@ -0,0 +1,25 @@
|
||||
# Simulator
|
||||
|
||||
The JavaScript simulator allows you to test and execute most BBC micro:bit programs in the browser.
|
||||
It allows you 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()
|
||||
```
|
||||
36
docs/device/usb.md
Normal file
36
docs/device/usb.md
Normal file
@ -0,0 +1,36 @@
|
||||
# Uploading programs to your @boardname@
|
||||
|
||||
Most of the time you'll be writing and testing your programs in the [simulator](/device/simulator). Once you've finished your program though, you can **compile** it and run it on your @boardname@. Transferring your program to the @boardname@ is as simple as saving a file to a drive on your computer.
|
||||
|
||||
When you plug your @boardname@ into USB, a new drive is created with the **@drivename@** label. This is where you'll save your program.
|
||||
|
||||
|
||||
|
||||
The basic steps are:
|
||||
|
||||
1. Connect your @boardname@ to your computer with a USB cable.
|
||||
2. Click **Download** to download the `.hex` file.
|
||||
3. Move the `.hex` file from your computer onto the **@drivename@** drive. The next section has instructions for the browser that you're using.
|
||||
|
||||
## How to transfer the program with your browser
|
||||
|
||||
Here are instructions for different browsers on Windows and Mac computers. Choose the one you're using:
|
||||
|
||||
### Windows browsers
|
||||
|
||||
* [Microsoft Edge](/device/usb/windows-edge)
|
||||
* [Internet Explorer](/device/usb/windows-ie)
|
||||
* [Chrome](/device/usb/windows-chrome)
|
||||
* [Firefox](/device/usb/windows-firefox)
|
||||
|
||||
### Mac browsers
|
||||
|
||||
* [Safari](/device/usb/mac-safari)
|
||||
* [Chrome](/device/usb/mac-chrome)
|
||||
* [Firefox](/device/usb/mac-firefox)
|
||||
|
||||
## ~hint
|
||||
|
||||
Transfer not working? See some [troubleshooting tips](/device/usb/troubleshoot).
|
||||
|
||||
## ~
|
||||
69
docs/device/usb/mac-chrome.md
Normal file
69
docs/device/usb/mac-chrome.md
Normal file
@ -0,0 +1,69 @@
|
||||
# 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.
|
||||
|
||||
|
||||
|
||||
## Step 2: Download your program
|
||||
|
||||
1. Open your project on @homeurl@
|
||||
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.
|
||||
|
||||
|
||||
|
||||
## 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/troubleshoot).
|
||||
|
||||
## ~
|
||||
71
docs/device/usb/mac-firefox.md
Normal file
71
docs/device/usb/mac-firefox.md
Normal file
@ -0,0 +1,71 @@
|
||||
# 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.
|
||||
|
||||
|
||||
|
||||
## Step 2: Download your program
|
||||
|
||||
1. Open your project on @homeurl@
|
||||
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.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 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/troubleshoot).
|
||||
|
||||
## ~
|
||||
68
docs/device/usb/mac-safari.md
Normal file
68
docs/device/usb/mac-safari.md
Normal file
@ -0,0 +1,68 @@
|
||||
# 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.
|
||||
|
||||
|
||||
|
||||
## Step 2: Download your program
|
||||
|
||||
1. Open your project on @homeurl@
|
||||
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:
|
||||
|
||||
|
||||
|
||||
## 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/troubleshoot).
|
||||
|
||||
## ~
|
||||
24
docs/device/usb/troubleshoot.md
Normal file
24
docs/device/usb/troubleshoot.md
Normal file
@ -0,0 +1,24 @@
|
||||
# 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**
|
||||
|
||||
|
||||
|
||||
**Mac**
|
||||
|
||||
|
||||
|
||||
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`.
|
||||
44
docs/device/usb/webusb.md
Normal file
44
docs/device/usb/webusb.md
Normal file
@ -0,0 +1,44 @@
|
||||
# WebUSB
|
||||
|
||||
[WebUSB](https://wicg.github.io/webusb/) is an emerging web standard that allows to access @boardname@ from web pages.
|
||||
It allows for a **one-click download** without installing any additional app or software! It also allows to receive data from the @boardname@.
|
||||
|
||||
## Support
|
||||
|
||||
* Chrome 79+ browser for Android, Chrome OS, Linux, macOS and Windows 10.
|
||||
* Microsoft Edge 79+ browser for Android, Chrome OS, Linux, macOS and Windows 10.
|
||||
|
||||
## Prepare your @boardname@
|
||||
|
||||
Make sure that your @boardname@ is running version **0249** or above of the firmware. Upgrading is as easy as dragging a file and it takes a few seconds to get it done.
|
||||
|
||||
* [Check out the instructions to check and upgrade your @boardname@.](/device/usb/webusb/troubleshoot)
|
||||
|
||||
## Pair your @boardname@
|
||||
|
||||
Here are the steps on the supported browsers:
|
||||
|
||||
* connect your @boardname@ to your computer with the microUSB cable
|
||||
* open a project
|
||||
* click the triple dot icon on the **Download** button and click **Pair device**
|
||||
* click on the **Pair device** button and select **Calliope mini** or **DAPLink CMSIS-DAP** from the list.
|
||||
|
||||
If you don't see any devices in the list and @boardname@ has the right firmware (**0249** or above), you can create a [support ticket](https://support.microbit.org/support/tickets/new) to notify the Micro:bit Foundation of the problem. Skip the rest of these steps.
|
||||
|
||||
## Unpair your @boardname@ #unpair
|
||||
|
||||
You will need to unpair your device from the editor to disable WebUSB.
|
||||
|
||||
* Click on the **lock** icon in the address bar
|
||||
* Uncheck each **Calliope mini** or **DAPLink CMSIS-DAP** device
|
||||
* Reload the page
|
||||
|
||||
|
||||
|
||||
## One-click Download
|
||||
|
||||
Once your @boardname@ is paired, MakeCode will use WebUSB to transfer the code without having to drag and drop. Happy coding!
|
||||
|
||||
## Console output
|
||||
|
||||
MakeCode will be able to "listen" to your @boardname@ and display the console output.
|
||||
69
docs/device/usb/webusb/troubleshoot.md
Normal file
69
docs/device/usb/webusb/troubleshoot.md
Normal file
@ -0,0 +1,69 @@
|
||||
# Troubleshooting downloads with WebUSB
|
||||
|
||||
### ~ avatar
|
||||
|
||||
Having issues pairing your @boardname@ with [WebUSB](/device/usb/webusb)? Let's try to figure out why!
|
||||
|
||||
### ~
|
||||
|
||||
## Step 1: Check your cable
|
||||
|
||||
Make sure that your @boardname@ is connected to your computer with a micro USB cable. You should see a **MICROBIT** drive appear in Windows Explorer when it's connected.
|
||||
|
||||
|
||||
|
||||
**If you can see the MICROBIT drive go to step 2**.
|
||||
|
||||
If you can't see the drive:
|
||||
* Make sure that the USB cable is working.
|
||||
>Does the cable work on another computer? If not, find a different cable to use. Some cables may only provide a power connection and don't actually transfer data.
|
||||
* Try another USB port on your computer.
|
||||
|
||||
Is the cable good but you still can't see the **MICROBIT** drive? Hmm, you might have a problem with your @boardname@. Try the additional steps described in the [fault finding](https://support.microbit.org/support/solutions/articles/19000024000-fault-finding-with-a-micro-bit) page at microbit.org. If this doesn't help, you can create a [support ticket](https://support.microbit.org/support/tickets/new) to notify the Micro:bit Foundation of the problem. **Skip the rest of these steps**.
|
||||
|
||||
## Step 2: Check your firmware version
|
||||
|
||||
It's possible that the firmware version on the @boardname@ needs an update. Let's check:
|
||||
|
||||
1. Go to the **MICROBIT** drive.
|
||||
2. Open the **DETAILS.TXT** file.<br/>
|
||||
<br/>
|
||||
3. Look for a line in the file that says the version number. It should say **Version: \.\.\.**
|
||||
|
||||
or **Interface Version: \.\.\.**
|
||||
|
||||
<br/>
|
||||
|
||||
If the version is **0234**, **0241**, **0243** you **NEED** to update the [firmware](/device/firmware) on your @boardname@. Go to **Step 3** and follow the upgrade instructions.
|
||||
|
||||
If the version is **0249**, **0250** or higher, **you have the right firmware** go to step **4**.
|
||||
|
||||
## Step 3: Upgrade the firmware
|
||||
|
||||
1. Put your @boardname@ into **MAINTENANCE Mode**. To do this, unplug the USB cable from the @boardname@ and then re-connect the USB cable while you hold down the reset button. Once you insert the cable, you can release the reset button. You should now see a **MAINTENANCE** drive instead of the **MICROBIT** drive like before. Also, a yellow LED light will stay on next to the reset button.
|
||||
|
||||
2. **[Download the firmware .hex file](https://microbit.org/guide/firmware/)**
|
||||
3. Drag and drop that file onto the **MAINTENANCE** drive.
|
||||
4. The yellow LED will flash while the `HEX` file is copying. When the copy finishes, the LED will go off and the @boardname@ resets. The **MAINTENANCE** drive now changes back to **MICROBIT**.
|
||||
5. The upgrade is complete! You can open the **DETAILS.TXT** file to check and see that the firmware version changed to the match the version of the `HEX` file you copied.
|
||||
|
||||
### ~hint
|
||||
|
||||
If you want to know more about connecting the board, MAINTENANCE Mode, and upgrading the firmware, read about it in the [Firmware guide](https://microbit.org/guide/firmware/).
|
||||
|
||||
### ~
|
||||
|
||||
## Step 4: Check your browser version
|
||||
|
||||
WebUSB is a fairly new feature and may require you to update your browser. Check that your browser version matches one of these:
|
||||
|
||||
* Chrome 65+ for Android, Chrome OS, Linux, macOS and Windows 10.
|
||||
|
||||
|
||||
## Step 5: Pair device
|
||||
|
||||
Once you've updated the firmware, open the **Chrome Browser**, go to the editor and click on **Pair Device** in the gearwheel menu.
|
||||
See [WebUSB](/device/usb/webusb) for pairing instructions.
|
||||
|
||||
Enjoy fast downloads!
|
||||
|
||||
92
docs/device/usb/windows-chrome.md
Normal file
92
docs/device/usb/windows-chrome.md
Normal file
@ -0,0 +1,92 @@
|
||||
# Uploading from Chrome for Windows
|
||||
|
||||
## ~ hint
|
||||
|
||||
Starting with Chrome 65 on Windows 10,
|
||||
you can use **WebUSB** to download with one-click.
|
||||
[Learn more about WebUSB...](/device/usb/webusb).
|
||||
|
||||
## ~
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
## Step 2 (optional): Configure Chrome to ask where to save the file
|
||||
|
||||
You only need to do this once.
|
||||
|
||||
1. Open the **Settings** for Chrome.
|
||||
2. Click **Advanced** at the bottom of the page.
|
||||
3. Find the **Downloads** settings.
|
||||
4. Enable the setting **Ask where to save each file before downloading**.
|
||||
|
||||
## Step 3: Download your program
|
||||
|
||||
1. Open your project on @homeurl@
|
||||
2. Click **Download**
|
||||
3. If you did Step 2 above, Chrome will ask where to save the `.hex` file,
|
||||
so save it into the `MICROBIT` drive.
|
||||
Otherwise, continue with one of the options in Step 4 below.
|
||||
|
||||
## Step 4: Transfer the file to your micro:bit
|
||||
|
||||
If the file was saved onto your computer, you will need to transfer it to the micro:bit.
|
||||
|
||||
## Manual transfer
|
||||
|
||||
Your `.hex` file (created in Step 3 above) 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**.
|
||||
|
||||
|
||||
|
||||
In File Explorer, drag and drop the `.hex` file from the download folder onto the `MICROBIT` drive.
|
||||
|
||||
Alternatively, right-click on the hex file, choose **Send to**, and then **MICROBIT**.
|
||||
|
||||
|
||||
|
||||
## Step 5: After transferring the file
|
||||
|
||||
* 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/troubleshoot).
|
||||
|
||||
## ~
|
||||
72
docs/device/usb/windows-edge.md
Normal file
72
docs/device/usb/windows-edge.md
Normal file
@ -0,0 +1,72 @@
|
||||
# Uploading from Microsoft 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 @boardname@ to your computer via USB
|
||||
2. Click **Download** to download the `.hex` file
|
||||
3. Click the **Save As** button in the bottom bar and save the `.hex` file into the MICROBIT 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.
|
||||
|
||||
|
||||
|
||||
## Step 2: Download your program
|
||||
|
||||
1. Open your project on @homeurl@
|
||||
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.
|
||||
|
||||
4. Click **Save As**
|
||||
|
||||
|
||||
|
||||
5. Save the ``.hex`` file into the **MICROBIT** drive
|
||||
|
||||
|
||||
|
||||
## Step 3: Transfer the file to your micro:bit
|
||||
|
||||
* 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 @boardname@. To rerun
|
||||
your program, press the reset button on the back of your @boardname@. 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/troubleshoot).
|
||||
|
||||
## ~
|
||||
71
docs/device/usb/windows-firefox.md
Normal file
71
docs/device/usb/windows-firefox.md
Normal file
@ -0,0 +1,71 @@
|
||||
# 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. Click the **Save As** button and save the `.hex` file into the MICROBIT 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.
|
||||
|
||||
|
||||
|
||||
## Step 2: Download your program
|
||||
|
||||
1. Open your project on @homeurl@.
|
||||
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 may appear asking whether you want to save or open the `.hex` file. If it doesn't, go click on the downloads icon at the top of the browser.
|
||||
|
||||
|
||||
|
||||
Click the folder icon and copy the file from the list of downloads to the **MICROBIT** drive.
|
||||
|
||||
|
||||
|
||||
## Step 3: Transfer the file to your micro:bit
|
||||
|
||||
* 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 @boardname@. To rerun
|
||||
your program, press the reset button on the back of your @boardname@. 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/troubleshoot).
|
||||
|
||||
## ~
|
||||
70
docs/device/usb/windows-ie.md
Normal file
70
docs/device/usb/windows-ie.md
Normal file
@ -0,0 +1,70 @@
|
||||
# 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. **Click the down arrow next to Save** in the bottom bar and select **Save As**.
|
||||
4. In the save dialog, save the `.hex` file into the MICROBIT 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.
|
||||
|
||||
|
||||
|
||||
## Step 2: Download your program
|
||||
|
||||
1. Open your project on @homeurl@
|
||||
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 **on the arrow next to Save** and click **Save As**
|
||||
|
||||
|
||||
|
||||
In the save dialog, save as the ``.hex`` file to the MICROBIT drive.
|
||||
|
||||
|
||||
|
||||
## Step 3: Transfer the file to your micro:bit
|
||||
|
||||
* 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 @boardname@. To rerun
|
||||
your program, press the reset button on the back of your @boardname@. 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/troubleshoot).
|
||||
|
||||
## ~
|
||||
65
docs/device/windows-app/troubleshoot.md
Normal file
65
docs/device/windows-app/troubleshoot.md
Normal file
@ -0,0 +1,65 @@
|
||||
# Troubleshooting downloads from the Windows 10 App
|
||||
|
||||
### ~ avatar
|
||||
|
||||
Is the [Windows App](https://www.microsoft.com/store/apps/9pjc7sv48lcx) not downloading your program properly? Let's try to figure out why!
|
||||
|
||||
### ~
|
||||
|
||||
## Step 1: Check your cable
|
||||
|
||||
Make sure that your @boardname@ is connected to your computer with a micro USB cable. You should see a **MICROBIT** drive appear in Windows Explorer when it's connected.
|
||||
|
||||
|
||||
|
||||
**If you can see the MICROBIT drive go to step 2**.
|
||||
|
||||
If you can't see the drive:
|
||||
* Make sure that the USB cable is working.
|
||||
>Does the cable work on another computer? If not, find a different cable to use. Some cables may only provide a power connection and don't actually transfer data.
|
||||
* Try another USB port on your computer.
|
||||
|
||||
Is the cable good but you still can't see the **MICROBIT** drive? Hmm, you might have a problem with your @boardname@. Try the additional steps described in the [fault finding](https://support.microbit.org/support/solutions/articles/19000024000-fault-finding-with-a-micro-bit) page at microbit.org. If this doesn't help, you can create a [support ticket](https://support.microbit.org/support/tickets/new) to notify the Micro:bit Foundation of the problem. **Skip the rest of these steps**.
|
||||
|
||||
## Step 2: Check your firmware version
|
||||
|
||||
It's possible that the firmware version on the @boardname@ needs an update. Let's check:
|
||||
|
||||
1. Go to the **MICROBIT** drive.
|
||||
2. Open the **DETAILS.TXT** file.<br/>
|
||||
<br/>
|
||||
3. Look for a line in the file that says the version number. It should say **Version: \.\.\.**
|
||||
<br/>
|
||||
|
||||
If the version is **0234**, you **NEED** to update the [firmware](/device/firmware) on your @boardname@. Go to **Step 3** and follow the upgrade instructions.
|
||||
|
||||
If the version is **0241**, **0243** or higher, **you have the right firmware**. You can create a [support ticket](https://support.microbit.org/support/tickets/new) to notify the Micro:bit Foundation of the problem. **Skip the rest of these steps**.
|
||||
|
||||
## Step 3: Upgrade the firmware
|
||||
|
||||
1. Put your @boardname@ into **MAINTENANCE Mode**. To do this, unplug the USB cable from the @boardname@ and then re-connect the USB cable while you hold down the reset button. Once you insert the cable, you can release the reset button. You should now see a **MAINTENANCE** drive instead of the **MICROBIT** drive like before. Also, a yellow LED light will stay on next to the reset button.
|
||||
|
||||
2. **[Download the firmware .hex file](https://microbit.org/guide/firmware/#update-firmware)**
|
||||
3. Drag and drop that file onto the **MAINTENANCE** drive.
|
||||
4. The yellow LED will flash while the `HEX` file is copying. When the copy finishes, the LED will go off and the @boardname@ resets. The **MAINTENANCE** drive now changes back to **MICROBIT**.
|
||||
5. The upgrade is complete! You can open the **DETAILS.TXT** file to check and see that the firmware version changed to the match the version of the `HEX` file you copied.
|
||||
|
||||
### ~hint
|
||||
|
||||
If you want to know more about connecting the board, MAINTENANCE Mode, and upgrading the firmware, read about it in the [micro:bit firmware guide](https://microbit.org/guide/firmware).
|
||||
|
||||
### ~
|
||||
|
||||
## Step 4: Wait for the driver updates
|
||||
|
||||
Once you've updated the firmware, Windows will detect the updated device and install the drivers necessary to enable communication with the @boardname@. This step happens in the background and may take a minute or two.
|
||||
|
||||
## Step 5: Drag and drop a fresh .hex file
|
||||
|
||||
If different editors were used with this board, it may need a reset to bring it back to a known-good state. Do this by dragging a ``.hex`` file containing a simple program onto the drive. You can use the one here. Click on the **Download** icon below the blocks, then drag and drop the file onto the @drivename@ drive.
|
||||
|
||||
```blocks
|
||||
basic.forever(function() {
|
||||
basic.showString("OK")
|
||||
})
|
||||
```
|
||||
Reference in New Issue
Block a user