Writing micro:bit content
Note: most of this applies to writing Arduino content also, the main difference being to change the workspace language from "microbit_micropython" to "arduino".
Overview
The Grok micro:bit simulator can run MicroPython code for the micro:bit. It does this by running a modified version of the micro:bit MicroPython firmware inside the sandbox. Although it runs (Micro) Python, there's a custom language "microbit_micropython" that makes it use the micro:bit simulator. For the most part, it works just like any other language on Grok, e.g. to embed a micro:bit code snippet that can be run inside a slide:
```lang:microbit_micropython; from microbit import * display.show(Image.HEART) ```
Inline examples
As above, runnable code snippets are written just like any other language. When run, they will automatically create the "view" that shows the running micro:bit, and an I/O view to show any console output (or errors).
To pre-create the micro:bit or terminal views:
```device-output;eg:last; ```
```terminal;eg:last;<br>```
You can optionally disable the ability to see the terminal output using device-output:toolbar-disable-show-output; instead of just device-output;.
There may be cases where you want to show a running program without providing access to the code (e.g. in a problem slide). You can do this using an encrypted file.
```lang:microbit_micropython;encrypted;hidden; from microbit import * display.show(Image.HEART) ``` ```device-output;eg:last; ```
Custom micro:bit tags
You can use the grok-microbit-leds tag to show an expected state, as in https://groklearning.com/learn/aca-dt-mini-78-py-microbit-radio/images/1/
<grok-microbit-leds values=" 0,5,0,5,0, 0,5,0,5,0, 0,5,0,5,0, 9,9,9,9,9, 9,9,9,9,9 "></grok-microbit-leds>
Problems
This works just like any other problem on Grok, except the language for the problem must be set to "micro:bit MicroPython". The problem will automatically get the simulator tab in the bottom half of the learning interface.
Yellowboxes (device animations)
In the micro:bit crash course, we needed a way to show example output for a program without providing the actual code for that program. We do this by providing a "device animation" which is a playback of a recording of an interaction with a micro:bit. The learning interface renders this inside a yellow box, hence why they're called yellowboxes. This is similar to the logo animations we provide on logo questions. If you're writing new content, you might want to use an inline micro:bit example with hidden encrypted code, but if you're updating the crash course or want to show a complete walkthrough of the functionality of a program then you need a yellowbox.
First write the program in the main Grok editor (on any problem or in the playground). Then run the program and interact with it. After stopping the program, Ctrl-click on the "Save" button and it will prompt you for a filename. Enter "___device_animation" which will copy the contents of the log that was sent from the simulator to the client to show all the things happening on the simulated micro:bit.
To embed this in a slide:
```device-animation; <paste the contents of ___device_animation here> ```
You can optionally use device-animation:loop; to make it a looped animation.
Test cases
See this page for more information.
Additional components
Both the inline slide examples and the main problem micro:bit can have additional "components" plugged into them. These have three purposes:
- To provide additional UI for built-in features that aren't used by most problems (e.g. temperature, accelerometer).
- To connect additional electronic components to the micro:bit (e.g. servo, LED, button, rover)
- To simulate other micro:bits talking via radio.
To add components to the workspace, you can use a hidden file called components.json. For a problem workspace, create the file as an undeletable, unrenamable, readonly, hidden, & exportable file.
For inline slide workspaces, use:
```lang:json;hidden;path:components.json; [ ... ] ```
This file should be a JSON list of component objects, each of which has a "type" (identifying the type of component), plus other optional arguments for that type. The following components are currently supported:
- Accelerometer
- Button
- Compass
- Gesture
- Light Dependent Resistor (Light Sensor)
- LED
- Moisture Sensor
- Orientation (compass and rotation)
- Potentiometer
- Rover
- Servo
- Shake (specific gesture, see also the Gesture component)
- Speaker
- Temperature
- Radio (these components are more complicated and are described in detail in the radio components FAQ page, in addition to a brief overview below.
Accelerometer component
Add controls for using the accelerometer on the micro:bit. This component displays as three sliders, one for each axis (X, Y, Z). This allows more fine control than the orientation control. Has the following parameters:
type(required) - "accelerometer".name(optional) - string - Configure a name to be displayed to the user on hovering over the button.
Example:
[
{"type": "accelerometer"}
]
Button component
Attach a button to the micro:bit. Has the following parameters:
type(required) - "button".pin(required) - integer - The pin the button is attached to.name(optional) - string - Configure a name to be displayed to the user on hovering over the button.pull(optional) - one of ['up', 'down'] - Configure wether the button is pull up or pull down. Defaults to 'down'.key(optional) - single character - A keyboard shortcut for the button.icon(optional) - string - Adds an icon to the button. Good options include lamp8, play4, pause2, stop2, arrow-up, arrow-down, arrow-left, and arrow-right. For a full list, contact Grok.
Example:
[
{"type": "button", "pin": 8, "key": "1"}
]
Compass component
Attach a compass to the micro:bit. Allows rotation around a single axis to change the compass facing. Has the following parameters:
type(required) - "compass".
Example:
[
{"type": "compass"}
]
Gesture component
Attach a gesture generator to the micro:bit. This displays a dropdown box that allows you to choose what gesture the micro:bit should experience. Has the following parameters:
type(required) - "gesture".
Example:
[
{"type": "gesture"}
]
Light Dependent Resistor (LDR) component
Attach an LDR to the micro:bit. Has the following parameters:
type(required) - "ldr".name(optional) - string - Configure a name to be displayed to the user on hovering over the LDR.value(optional) - integer - Sets what value the LDR should have at the start of the program (ranges between 0 and 1, defaults to 0.92). This is displayed as a percentage to the user.
Example:
[
{"type": "ldr"}
]
Light Emitting Diode (LED) component
Attach an LED to the micro:bit. Can be either single colour (first example) or RGB (second example).
A single colour LED has the following parameters:
type(required) - "led".pin- integer - The pin that the LED is attached to.name(optional) - string - Configure a name to be displayed to the user on hovering over the LDR.color(optional) - one of ['red', 'green', 'blue'] - sets the colour of the LED. Defaults to 'red'
Example:
[
{"type": "led", "pin": 13}
]
An RGB LED has the following parameters:
type(required) - "led".pins- 3 integer array - The pins that the LED is attached to, in RGB order.color- 'rgb' - sets the LED to RGB mode.common(optional) - one of ['anode', 'cathode'] - sets whether the LED is common anode, or common cathode. Defaults to 'anode'name(optional) - string - Configure a name to be displayed to the user on hovering over the LDR.
Example:
[
{"type": "led", "color": "rgb", "pins": [10,11,12]}
]
Moisture sensor component
Attach a moisture sensor to the micro:bit. Has the following parameters:
type(required) - "moisture".pin- integer - The pin that the sensor is attached to.value(optional) - integer from 0 to 1023, inclusive - shows what the initial moisture level is. Defaults to 511, which maps to 511 on read_analog.
Example:
[
{"type": "moisture", "pin": 2}
]
Orientation component
Attach an orientation component to the micro:bit. Allows full 3-axis rotation. Has the following parameters:
type(required) - "orientation".
Example:
[ {"type": "orientation"} ]
Potentiometer component
Attach a potentiometer to the micro:bit. Has the following parameters:
type(required) - "pot".pin- integer - The pin that the sensor is attached to.name(optional) - string - Configure a name to be displayed to the user on hovering over the pot.style(optional) - one of ['rotary', 'vertical', 'horizontal'] - sets the visual style of the pot.value(optional) - float from 0 to 1, inclusive - sets the value of the pot, as a fraction of the input voltage (3v)
Example:
[
{"type": "pot", "pin": 3}
]
Rover component
Attach the micro:bit to a rover. Note that the rover currently cannot be tested. Has the following pin attachments:
- pin 16 - left motor forwards
- pin 0 - left motor backwards
- pin 12 - right motor forwards
- pin 8 - right motor backwards
Has the following parameters:
type(required) - "rover".blip(optional) - boolean - sets whether the rover should leave a trail behind it on the canvas. Default false.line_following(optional) - boolean - sets whether the rover should have the line following sensors attached. Default false. The left sensor attaches to pin 1, and the right to pin 2.
Example:
[
{"type": "rover"}
]
Servo component
Attach a servo to the micro:bit. Has the following parameters:
type(required) - "servo".pin- integer - The pin that the servo is attached to.name(optional) - string - Configure a name to be displayed to the user on hovering over the servo.
Example:
[
{"type": "servo", "pin": 1}
]
Shake component
Attach a component to trigger the shake gesture. Has the following parameters:
type(required) - "servo".
Example:
[
{"type": "shake"}
]
Speaker component
Attach a speaker to the micro:bit. Has the following parameters:
type(required) - "speaker".pin- integer - The pin that the speaker is attached to.name(optional) - string - Configure a name to be displayed to the user on hovering over the servo.
Example:
[
{"type": "speaker", "pin": 0}
]
Temperature component
Attach a component to control the temperature, which is read by the micro:bit's internal sensor. Has the following parameters:
type(required) - "temperature".
Example:
[
{"type": "temperature"}
]
Radio components
This is a bit of a misnomer as they do not actually represents components plugged into the micro:bit, but rather other micro:bits that can communicate with the main one via radio. At this stage these are implemented in the JS frontend for the simulator, but long term it would be great to make them run as separate instances of the simulator with the logic implemented in MicroPython. These currently work in two ways:
- Remote sensors. This simulates a remote micro:bit that just sends the data from one of its sensors over the radio at some predefined interval and channel. This is currently implemented for the temperature sensor, and is configured by adding a "radio" option to the "type": "temperature" component (see the "Temperature Display" problem in the micro:bit crash course for an example).
- Emulated programs. The entire problem-specific logic is implemented in JS, and a mini-micro:bit is displayed next to the main micro:bit. These JS-simulated mini micro:bits can send/receive radio, show/scroll text and images on the screen, and handle button presses. These are added using the "type": "radio-microbit" component, with problem specific configuration options.
- For the crash course problems (e.g. game show host, morse code, etc) these are built into the learning interface.
- Problem authors can also define their own simulated micro:bits by defining a simple state machine in components.json.
To read more about adding both types of simulated radio micro:bits, see this page.