From 074087b0b7baa3762dfd2ca77cd40d411d2c77ae Mon Sep 17 00:00:00 2001 From: Phil Howard Date: Wed, 14 Oct 2020 21:40:50 +0100 Subject: [PATCH] Remove hard linebreaks and trailing whitespace This changeset removes - hopefully all - hard linebreaks in a single pass to make future corrections clearer and concise. --- accessories/making-accessories.md | 8 +- bluetooth/apps-and-examples.md | 8 +- bluetooth/index.md | 25 ++- bluetooth/profile.md | 26 +--- community/slack.md | 16 +- hardware/1-3-revision.md | 95 +++--------- hardware/1-5-revision.md | 93 +++--------- hardware/edgeconnector.md | 142 +++++------------- hardware/i2c-shared.md | 2 +- hardware/i2c.md | 4 +- hardware/index.md | 87 +++-------- hardware/power-consumption.md | 8 +- hardware/powersupply.md | 95 +++--------- hardware/reference-design.md | 76 +++------- hardware/schematic.md | 66 +++----- index.md | 30 ++-- latest-revision/README.MD | 3 +- .../latest-revision-accessories.md | 4 +- latest-revision/latest-revision-content.md | 4 +- latest-revision/latest-revision-editors.md | 11 +- latest-revision/latest-revision-main.md | 14 +- projects.md | 4 +- software/hex-format.md | 2 +- software/in_browser_compiler.md | 51 ++----- software/index.md | 46 ++---- software/interface.md | 10 +- software/makecode.md | 2 +- software/micropython.md | 132 ++++------------ software/other-languages.md | 7 +- software/python-editor.md | 2 +- software/readout_hex.md | 2 +- software/runtime.md | 5 +- software/testing.md | 2 +- 33 files changed, 302 insertions(+), 780 deletions(-) diff --git a/accessories/making-accessories.md b/accessories/making-accessories.md index ee8e254..1cdaf5d 100644 --- a/accessories/making-accessories.md +++ b/accessories/making-accessories.md @@ -14,10 +14,9 @@ A [list of available accessories](https://microbit.org/buy/accessories/) is main ## Using the Edge Connector -The micro:bit card edge connector, commonly referred to as the 'edge connector' or the 'pins' makes accessory design easy. +The micro:bit card edge connector, commonly referred to as the 'edge connector' or the 'pins' makes accessory design easy. -Many micro:bit accessories are designed to use an edge connector socket, so it is simple -to plug in and remove the board. +Many micro:bit accessories are designed to use an edge connector socket, so it is simple to plug in and remove the board. There are limitations to the current that can be drawn from the micro:bit, and accessories must be designed carefully to ensure they do not damage the micro:bit, or that the micro:bit cannot damage them. @@ -37,8 +36,7 @@ There are two lozenge shaped pads on the back of the micro:bit. These allow you ### V2 revision In the V2 board revision, the 3V lozenge is connected to the 3V ring on the edge connector. -- If you make an accessory that uses the lozenges, it must be protected from reverse charging -when the board is powered by USB, battery or edge connector. +- If you make an accessory that uses the lozenges, it must be protected from reverse charging when the board is powered by USB, battery or edge connector. - You can now source power from the lozenges if you are making an accessory, as they are consistent with the power architecture of the edge connector. Due to the addition of a speaker, current accessories that use the lozenges to power the micro:bit will no longer fit. diff --git a/bluetooth/apps-and-examples.md b/bluetooth/apps-and-examples.md index 7bdde6a..e902df8 100644 --- a/bluetooth/apps-and-examples.md +++ b/bluetooth/apps-and-examples.md @@ -9,13 +9,9 @@ ref: bluetooth lang: en --- -Bluetooth applications can run on a variety of devices, including but not limited -to smart phones and tablets. You can also run Bluetooth enabled applications -on devices such as a Raspberry Pi. +Bluetooth applications can run on a variety of devices, including but not limited to smart phones and tablets. You can also run Bluetooth enabled applications on devices such as a Raspberry Pi. -Below is a curated list of some Bluetooth applications you might like to read -about and try for yourself with your micro:bit. Please contribute to this list -if you know of any more. Many listed here are take from the [micro:bit Awesome list](https://github.com/carlosperate/awesome-microbit) +Below is a curated list of some Bluetooth applications you might like to read about and try for yourself with your micro:bit. Please contribute to this list if you know of any more. Many listed here are take from the [micro:bit Awesome list](https://github.com/carlosperate/awesome-microbit) ## Applications, tools and examples diff --git a/bluetooth/index.md b/bluetooth/index.md index 903109d..8e39b09 100644 --- a/bluetooth/index.md +++ b/bluetooth/index.md @@ -9,33 +9,26 @@ ref: bluetooth lang: en --- # Overview -The micro:bit processor has an on board -[Bluetooth](http://blog.bluetooth.com/a-developers-guide-to-bluetooth/) transceiver. This is combined with a PCB trace aerial and other minor components alongside a software stack that gives -the micro:bit a certified and credible Bluetooth capability. +The micro:bit processor has an on board [Bluetooth](http://blog.bluetooth.com/a-developers-guide-to-bluetooth/) transceiver. This is combined with a PCB trace aerial and other minor components alongside a software stack that gives the micro:bit a certified and credible Bluetooth capability. ## Bluetooth software stack -v1 Nordic Semiconductor [Soft Device S110](https://www.nordicsemi.com/Software-and-Tools/Software/S110) -V2 Nordic Semiconductor [Soft Device S140](https://www.nordicsemi.com/Software-and-tools/Software/S140) . We may switch to [S113](https://www.nordicsemi.com/Software-and-tools/Software/S113) and [S122](https://www.nordicsemi.com/Software-and-tools/Software/S122) at compile time to save flash memory (if this affects anything you are working on please [contact micro:bit support](https://support.microbit.org/en/support/tickets/new)). +v1 Nordic Semiconductor [Soft Device S110](https://www.nordicsemi.com/Software-and-Tools/Software/S110) +V2 Nordic Semiconductor [Soft Device S140](https://www.nordicsemi.com/Software-and-tools/Software/S140) +We may switch to [S113](https://www.nordicsemi.com/Software-and-tools/Software/S113) and [S122](https://www.nordicsemi.com/Software-and-tools/Software/S122) at compile time to save flash memory (if this affects anything you are working on please [contact micro:bit support](https://support.microbit.org/en/support/tickets/new)). -Using Bluetooth, you can connect to other devices and send and receive -data from and to the micro:bit. + +Using Bluetooth, you can connect to other devices and send and receive data from and to the micro:bit. ## micro:bit Bluetooth Features -Bluetooth features available on the micro:bit are defined in a -[Bluetooth profile](/bluetooth/profile). The micro:bit supports one, custom developed profile. +Bluetooth features available on the micro:bit are defined in a [Bluetooth profile](/bluetooth/profile). The micro:bit supports one, custom developed profile. ## Bluetooth and the micro:bit software -The [DAL/C++](https://lancaster-university.github.io/microbit-docs/ble/profile/#reference-documentation) lists the adopted and custom features available within the profile. -[MakeCode](https://makecode.microbit.org/reference/bluetooth) contains a set of blocks to make use -of the various micro:bit services. +The [DAL/C++](https://lancaster-university.github.io/microbit-docs/ble/profile/#reference-documentation) lists the adopted and custom features available within the profile. [MakeCode](https://makecode.microbit.org/reference/bluetooth) contains a set of blocks to make use of the various micro:bit services. -The processor also has a number of non-bluetooth proprietary -modes of operation, on which we build the micro:bit radio -protocol. This only works between micro:bits and is what is defined as 'Micro:bit Radio' in the DAL -and 'radio' in MakeCode and MicroPython, as well as Mbed C++. +The processor also has a number of non-bluetooth proprietary modes of operation, on which we build the micro:bit radio protocol. This only works between micro:bits and is what is defined as 'Micro:bit Radio' in the DAL and 'radio' in MakeCode and MicroPython, as well as Mbed C++. ## Apps diff --git a/bluetooth/profile.md b/bluetooth/profile.md index 026a68d..e3dffba 100644 --- a/bluetooth/profile.md +++ b/bluetooth/profile.md @@ -11,12 +11,9 @@ lang: en ## Overview -The micro:bit supports Bluetooth via a single BBC micro:bit profile -which was custom developed for the device. This profile -allows it to communicate with other BLE capable devices. +The micro:bit supports Bluetooth via a single BBC micro:bit profile which was custom developed for the device. This profile allows it to communicate with other BLE capable devices. -If you are looking for information about the 'radio' feature, it is a [proprietary protocol from Nordic -and Lancaster University](https://lancaster-university.github.io/microbit-docs/ubit/radio/). This is not Bluetooth and the difference is described further in [this article on using the micro:bit wirelessly](https://support.microbit.org/support/solutions/articles/19000083637-using-the-micro-bit-wirelessly-) +If you are looking for information about the 'radio' feature, it is a [proprietary protocol from Nordic and Lancaster University](https://lancaster-university.github.io/microbit-docs/ubit/radio/). This is not Bluetooth and the difference is described further in [this article on using the micro:bit wirelessly](https://support.microbit.org/support/solutions/articles/19000083637-using-the-micro-bit-wirelessly-) ## BBC micro:bit Bluetooth Profile @@ -36,32 +33,23 @@ There are also some example programs in the [microbit-samples](https://github.co [bluetooth-eddystone-url]https://github.com/lancaster-university/microbit-samples/tree/master/source/examples/bluetooth-eddystone-url [bluetooth-uart]https://github.com/lancaster-university/microbit-samples/tree/master/source/examples/bluetooth-uart -The micro:bit has a Bluetooth 4.1 stack with Bluetooth Low Energy (BLE) and supports -the [GAP Perhipheral Role](https://bluetooth-developer.blogspot.com/2016/07/microbit-and-bluetooth-roles.html). +The micro:bit has a Bluetooth 4.1 stack with Bluetooth Low Energy (BLE) and supports the [GAP Perhipheral Role](https://bluetooth-developer.blogspot.com/2016/07/microbit-and-bluetooth-roles.html). -As per all Bluetooth, it operates in the ISM (Industrial Scientific Medical) band -and this starts at **2.4GHz and ends at 2.41GHz**. BLE divides the frequency -band into 50 x 2MHz bands of which 40 are used. +As per all Bluetooth, it operates in the ISM (Industrial Scientific Medical) band and this starts at **2.4GHz and ends at 2.41GHz**. BLE divides the frequency band into 50 x 2MHz bands of which 40 are used. These are called **channels** and numbered **0 to 39**. Channels 37, 38 and 39 are used for “advertising”. -When devices are connected, they use the other channels in a particular sequence -controlled by a feature called **adaptive frequency hopping**. +When devices are connected, they use the other channels in a particular sequence controlled by a feature called **adaptive frequency hopping**. This helps reduce the impact of congestion from other radio users. -Data transfer rates will only be a few 100K per second at best and it very much depends on -how your application uses the Bluetooth features; lots of small temperature containing packets -would have a lower data transfer rate than using the UART service, as it depends on the -proportion of system protocol information vs. application data. +Data transfer rates will only be a few 100K per second at best and it very much depends on how your application uses the Bluetooth features; lots of small temperature containing packets would have a lower data transfer rate than using the UART service, as it depends on the proportion of system protocol information vs. application data. There are some useful [advanced configuration options in the micro:bit runtime code](https://lancaster-university.github.io/microbit-docs/advanced/#compile-time-options-with-yotta) ## Challenge -It would be possible for anyone with the appropriate knowledge to define and -implement other Bluetooth profiles. You would need to use the Mbed C/C++ environment -to do this. +It would be possible for anyone with the appropriate knowledge to define and implement other Bluetooth profiles. You would need to use the Mbed C/C++ environment to do this. We are seeking collaborators to help us define the new profile elements that expose some of the V2 features. diff --git a/community/slack.md b/community/slack.md index cd0b35a..775038b 100644 --- a/community/slack.md +++ b/community/slack.md @@ -9,9 +9,7 @@ ref: community lang: en --- -The micro:bit community is already spread across the world, building cool things -with micro:bits and building the software that runs on them. Many micro:bit hardware and software resources are openly licensed, and we want to encourage and support -contributions from anyone interested. +The micro:bit community is already spread across the world, building cool things with micro:bits and building the software that runs on them. Many micro:bit hardware and software resources are openly licensed, and we want to encourage and support contributions from anyone interested. If you'd like to be part of the world-wide micro:bit developer community, then there are a couple of ways you can do this. @@ -25,7 +23,7 @@ In addition to our regular [Micro:bit Educational Foundation newsletter](https:/ ## Join us on the microbit-community slack channel! -[Slack](https://slack) is a messaging service that allows teams and communities to connect online. It's a brilliant tool for live collaboration and the place to be for current micro:bit chatter! +[Slack](https://slack) is a messaging service that allows teams and communities to connect online. It's a brilliant tool for live collaboration and the place to be for current micro:bit chatter! Please note that Slack complements, but does not replace [micro:bit help & support](http://support.microbit.org, where you can search for help and ask the team questions. @@ -43,10 +41,6 @@ If you'd like to join the slack channel, please fill in the form below. This for ## Other channels and communities In addition to the Foundation's own channels of communication, there are many other online communities of support. -- [MakeCode micro:bit forum](https://forum.makecode.com/c/microbit/11) -Connect with the MakeCode team for more technical details regarding developing micro:bit extensions -or working on the MakeCode editor. -- [Mu Gitter](https://gitter.im/mu-editor) -Gitter chat is similar to Slack and aimed at developers using [Mu](https://codewith.mu/) -- [/r/microbit](https://www.reddit.com/r/microbit) -A reddit discussion on micro:bit +- [MakeCode micro:bit forum](https://forum.makecode.com/c/microbit/11) Connect with the MakeCode team for more technical details regarding developing micro:bit extensions or working on the MakeCode editor. +- [Mu Gitter](https://gitter.im/mu-editor) Gitter chat is similar to Slack and aimed at developers using [Mu](https://codewith.mu/) +- [/r/microbit](https://www.reddit.com/r/microbit) A reddit discussion on micro:bit diff --git a/hardware/1-3-revision.md b/hardware/1-3-revision.md index 896805e..a2efb86 100644 --- a/hardware/1-3-revision.md +++ b/hardware/1-3-revision.md @@ -23,12 +23,8 @@ lang: en ## Getting Started With the micro:bit Hardware -The micro:bit hardware is based on the Arm-Mbed platform. -It has an application processor with lots of on-chip perhipherals. -Some off-chip peripherals are connected to this chip. -There is an interface processor connected to the application processor, -and it is the interface processors job to manage communications over the USB -and to support the drag-and-drop code-flashing process. +The micro:bit hardware is based on the Arm-Mbed platform. It has an application processor with lots of on-chip perhipherals. Some off-chip peripherals are connected to this chip. +There is an interface processor connected to the application processor, and it is the interface processors job to manage communications over the USB and to support the drag-and-drop code-flashing process. The interface processor does not connect to any of the micro:bit peripherals. Two key pieces of information to help understand the internals of the micro:bit are: @@ -44,12 +40,8 @@ Two key pieces of information to help understand the internals of the micro:bit ### nRF51 Application Processor -The nRF51 application processor is where user programs run. -A single, complete application including user code, runtime code and bluetooth stack -is loaded and run directly from on chip flash memory. -All user accessible GPIO pins are provided by this processor. -There is an onboard 2.4GHz radio engine used to provide Bluetooth capabilities -via an off-chip aerial. +The nRF51 application processor is where user programs run. A single, complete application including user code, runtime code and bluetooth stack is loaded and run directly from on chip flash memory. All user accessible GPIO pins are provided by this processor. +There is an onboard 2.4GHz radio engine used to provide Bluetooth capabilities via an off-chip aerial. | item | details | --- | --- @@ -64,10 +56,8 @@ via an off-chip aerial. ### Bluetooth Wireless Communication -The on board 2.4GHz transciever supports Bluetooth communications via the Nordic S110 SoftDevice, -which provides a fully qualified Bluetooth low energy stack. -This allows the micro:bit to communicate with a wide range of Bluetooth devices, -including smartphones and tablets. +The on board 2.4GHz transciever supports Bluetooth communications via the Nordic S110 SoftDevice, which provides a fully qualified Bluetooth low energy stack. +This allows the micro:bit to communicate with a wide range of Bluetooth devices, including smartphones and tablets. | item | details | --- | --- @@ -85,12 +75,9 @@ including smartphones and tablets. ### Low Level Radio Communications The on board 2.4GHz transciever supports a number of other radio communications standards, on which we build the microbit-radio protocol -This protocol provides a very simple small-packet broadcast radio interface between other devices -that support it, such as other micro:bit devices. -The 'radio' interface that appears in a number of the languages on the micro:bit -is built on top of this protocol. -Additionally, the micro:bit runtime software adds a 'group code' to each data payload, -allowing for simple user managed device addressing and filtering to take place. +This protocol provides a very simple small-packet broadcast radio interface between other devices that support it, such as other micro:bit devices. +The 'radio' interface that appears in a number of the languages on the micro:bit is built on top of this protocol. +Additionally, the micro:bit runtime software adds a 'group code' to each data payload, allowing for simple user managed device addressing and filtering to take place. | item | details | --- | --- @@ -107,17 +94,10 @@ allowing for simple user managed device addressing and filtering to take place. ### Buttons -The two buttons on the front of the micro:bit, and the 1 button on the back, -are tact momentary push to make buttons. The back button is connected to the KL26 -interface processor and to the nRF51 processor for system reset purposes. This -means that the application will reset regardless of if it is powered from USB -or from battery. +The two buttons on the front of the micro:bit, and the 1 button on the back, are tact momentary push to make buttons. The back button is connected to the KL26 interface processor and to the nRF51 processor for system reset purposes. This means that the application will reset regardless of if it is powered from USB or from battery. Front buttons A and B can be programmed in the user application for any purpose. -A and B are debounced by software, which also includes short press, long press, -and 'both A+B' press detection. Buttons operate in a typical inverted electrical mode, -where a pullup resistor ensures a logical '1' when the button is released, -and a logical '0' when the button is pressed. +A and B are debounced by software, which also includes short press, long press, and 'both A+B' press detection. Buttons operate in a typical inverted electrical mode, where a pullup resistor ensures a logical '1' when the button is released, and a logical '0' when the button is pressed. Both A and B buttons are connected to GPIO pins that are also accessible on the micro:bit edge connector. | item | details @@ -131,11 +111,8 @@ Both A and B buttons are connected to GPIO pins that are also accessible on the The display is a 5x5 array of LEDs. It is connected to the micro:bit as a 3x9 matrix. -Runtime software repeatedly refreshes this matrix at a high speed, -such that it is within the user persistence of vision range, and no flicker is detected. -This LED matrix is also used to sense ambient light, -by repeatedly switching some of the LED drive pins into inputs and sampling the voltage decay time, -which is roughly proportional to ambient light levels. +Runtime software repeatedly refreshes this matrix at a high speed, such that it is within the user persistence of vision range, and no flicker is detected. +This LED matrix is also used to sense ambient light, by repeatedly switching some of the LED drive pins into inputs and sampling the voltage decay time, which is roughly proportional to ambient light levels. | item | details | --- | --- @@ -151,8 +128,7 @@ which is roughly proportional to ambient light levels. ### Accelerometer The accelerometer is a separate chip that provides 3-axis sensing. -It also includes some on board gesture detection (such as fall detection) in hardware, -and additional gesture sensing (e.g. logo-up, logo-down, shake) via software algorithms. +It also includes some on board gesture detection (such as fall detection) in hardware, and additional gesture sensing (e.g. logo-up, logo-down, shake) via software algorithms. It is connected to the application processor via the I2C bus. | item | details @@ -168,10 +144,8 @@ It is connected to the application processor via the I2C bus. ### Magnetometer The magnetometer is a separate chip that provides magnetic field strength sensing. -A software algorithm in the standard runtime uses the on board accelerometer -to turn these readings into a board orientation independent compass reading. -The compass must be calibrated before use, and the calibration process is automatically -initiated by the runtime software. +A software algorithm in the standard runtime uses the on board accelerometer to turn these readings into a board orientation independent compass reading. +The compass must be calibrated before use, and the calibration process is automatically initiated by the runtime software. This device is connected to the application processor via the I2C bus. | item | details @@ -185,8 +159,7 @@ This device is connected to the application processor via the I2C bus. ### Temperature Sensing The nRF51 application processor has an on board core temperature sensor. -This is exposed via the standard runtime software, and provides an estimate of ambient -temperature. +This is exposed via the standard runtime software, and provides an estimate of ambient temperature. | item | details | --- | --- @@ -198,12 +171,7 @@ temperature. ### General Purpose Input/Output Pins -The edge connector brings out many of the GPIO circuits of the application -processor. Some of these circuits are shared with other functions of the micro:bit, but -many of these extra circuits can be re-allocated to general purpose use if some software -features are turned off. Note: the nRF51 data sheet states that GPIO pins may be -in std-drive (0.5mA) and high-drive (5mA) mode, with a maximum of 3 pins in high-drive -mode at any one time. +The edge connector brings out many of the GPIO circuits of the application processor. Some of these circuits are shared with other functions of the micro:bit, but many of these extra circuits can be re-allocated to general purpose use if some software features are turned off. Note: the nRF51 data sheet states that GPIO pins may be in std-drive (0.5mA) and high-drive (5mA) mode, with a maximum of 3 pins in high-drive mode at any one time. | item | details | --- | --- @@ -228,10 +196,7 @@ mode at any one time. ### Power Supply -Power to the micro:bit may be provided via the USB connection, via the -interface chip (which has an on-board regulator), or via a battery plugged into the top -connector. It is also possible (with care) to power the micro:bit from the 3V pad at the -bottom. The 3V pad at the bottom can be used to supply a small amount of power external circuits. +Power to the micro:bit may be provided via the USB connection, via the interface chip (which has an on-board regulator), or via a battery plugged into the top connector. It is also possible (with care) to power the micro:bit from the 3V pad at the bottom. The 3V pad at the bottom can be used to supply a small amount of power external circuits. | item | details | --- | --- @@ -246,9 +211,7 @@ bottom. The 3V pad at the bottom can be used to supply a small amount of power e ### Interface -The interface chip handles the USB connection, and is used for flashing -new code to the micro:bit, sending and receiving serial data back and forth to your -main computer. +The interface chip handles the USB connection, and is used for flashing new code to the micro:bit, sending and receiving serial data back and forth to your main computer. | item | details | --- | --- @@ -263,12 +226,7 @@ main computer. ### USB Communications -The micro:bit has an on board USB communications stack, that is built into the firmware -of the interface chip. This stack provides the ability to drag and drop files onto the -MICROBIT drive in order to load code into the application processor. It also allows -serial data to be streamed to and from the micro:bit application processor over USB to -an external host computer, and supports the CMSIS-DAP protocol for host debugging -of application programs. +The micro:bit has an on board USB communications stack, that is built into the firmware of the interface chip. This stack provides the ability to drag and drop files onto the MICROBIT drive in order to load code into the application processor. It also allows serial data to be streamed to and from the micro:bit application processor over USB to an external host computer, and supports the CMSIS-DAP protocol for host debugging of application programs. | item | details | --- | --- @@ -282,12 +240,7 @@ of application programs. ### Debugging -The interface processor can be used with special host tools to debug -code that is running on the application processor. It connects to the application -processor via 4 signal wires. The KL26 interface processor code can also -be debuged via it's integral SWD software debug interface, for example to -load initial bootloader code into this processor at manufacturing time, or to -recover a lost bootloader. +The interface processor can be used with special host tools to debug code that is running on the application processor. It connects to the application processor via 4 signal wires. The KL26 interface processor code can also be debuged via it's integral SWD software debug interface, for example to load initial bootloader code into this processor at manufacturing time, or to recover a lost bootloader. | item | details | --- | --- @@ -297,9 +250,7 @@ recover a lost bootloader. ### Mechanical -We have some [nice 2D and 3D CAD drawings and models of the micro:bit](https://github.com/microbit-foundation/microbit-reference-design) including all the important dimensions. These models can be used as a basis for generating -really nice marketing and project images of the micro:bit, but also as a basis for accurate -manufacture of attachments e.g. via 3D printing. +We have some [nice 2D and 3D CAD drawings and models of the micro:bit](https://github.com/microbit-foundation/microbit-reference-design) including all the important dimensions. These models can be used as a basis for generating really nice marketing and project images of the micro:bit, but also as a basis for accurate manufacture of attachments e.g. via 3D printing. | item | details | --- | --- diff --git a/hardware/1-5-revision.md b/hardware/1-5-revision.md index 6802346..47b28cd 100644 --- a/hardware/1-5-revision.md +++ b/hardware/1-5-revision.md @@ -23,18 +23,14 @@ lang: en The micro:bit hardware is based on the Arm-Mbed platform. It has an application processor with lots of on-chip perhipherals. Some off-chip peripherals are connected to this chip. -There is an interface processor connected to the application processor, -and it is the interface processors job to manage communications over the USB -and to support the drag-and-drop code-flashing process. +There is an interface processor connected to the application processor, and it is the interface processors job to manage communications over the USB and to support the drag-and-drop code-flashing process. The interface processor does not connect to any of the micro:bit peripherals. Two key pieces of information to help understand the internals of the micro:bit are: * The [schematics](../schematic), which shows the detailed component data and connectivity of the device. -* The [reference design](../reference-design), which is a complete module design of a compatible micro:bit, - and is designed to be a starting point for anyone interested in understanding the micro:bit - or designing their own variant. +* The [reference design](../reference-design), which is a complete module design of a compatible micro:bit, and is designed to be a starting point for anyone interested in understanding the micro:bit or designing their own variant. # Hardware Description @@ -42,11 +38,9 @@ Two key pieces of information to help understand the internals of the micro:bit ## nRF51 Application Processor The nRF51 application processor is where user programs run. -A single, complete application including user code, runtime code and bluetooth stack -is loaded and run directly from on chip flash memory. +A single, complete application including user code, runtime code and bluetooth stack is loaded and run directly from on chip flash memory. All user accessible GPIO pins are provided by this processor. -There is an onboard 2.4GHz radio engine used to provide Bluetooth capabilities -via an off-chip aerial. +There is an onboard 2.4GHz radio engine used to provide Bluetooth capabilities via an off-chip aerial. | item | details | --- | --- @@ -61,10 +55,8 @@ via an off-chip aerial. ## Bluetooth Wireless Communication -The on board 2.4GHz transciever supports Bluetooth communications via the Nordic S110 SoftDevice, -which provides a fully qualified Bluetooth low energy stack. -This allows the micro:bit to communicate with a wide range of Bluetooth devices, -including smartphones and tablets. +The on board 2.4GHz transciever supports Bluetooth communications via the Nordic S110 SoftDevice, which provides a fully qualified Bluetooth low energy stack. +This allows the micro:bit to communicate with a wide range of Bluetooth devices, including smartphones and tablets. | item | details | --- | --- @@ -81,14 +73,10 @@ including smartphones and tablets. ## Low Level Radio Communications -The on board 2.4GHz transciever supports a number of other radio communications standards, -including the proprietary Nordic Gazell protocol. -This protocol provides a very simple small-packet broadcast radio interface between other devices -that support this proprietary protocol, such as other micro:bit devices. -The 'radio' interface that appears in a number of the languages on the micro:bit -is built on top of this Gazell protocol. -Additionally, the micro:bit runtime software adds a 'group code' to each data payload, -allowing for simple user managed device addressing and filtering to take place. +The on board 2.4GHz transciever supports a number of other radio communications standards, including the proprietary Nordic Gazell protocol. +This protocol provides a very simple small-packet broadcast radio interface between other devices that support this proprietary protocol, such as other micro:bit devices. +The 'radio' interface that appears in a number of the languages on the micro:bit is built on top of this Gazell protocol. +Additionally, the micro:bit runtime software adds a 'group code' to each data payload, allowing for simple user managed device addressing and filtering to take place. | item | details | --- | --- @@ -105,17 +93,10 @@ allowing for simple user managed device addressing and filtering to take place. ## Buttons -The two buttons on the front of the micro:bit, and the 1 button on the back, -are tact momentary push to make buttons. The back button is connected to the KL26 -interface processor and to the nRF51 processor for system reset purposes. This -means that the application will reset regardless of if it is powered from USB -or from battery. +The two buttons on the front of the micro:bit, and the 1 button on the back, are tact momentary push to make buttons. The back button is connected to the KL26 interface processor and to the nRF51 processor for system reset purposes. This means that the application will reset regardless of if it is powered from USB or from battery. Front buttons A and B can be programmed in the user application for any purpose. -A and B are debounced by software, which also includes short press, long press, -and 'both A+B' press detection. Buttons operate in a typical inverted electrical mode, -where a pullup resistor ensures a logical '1' when the button is released, -and a logical '0' when the button is pressed. +A and B are debounced by software, which also includes short press, long press, and 'both A+B' press detection. Buttons operate in a typical inverted electrical mode, where a pullup resistor ensures a logical '1' when the button is released, and a logical '0' when the button is pressed. Both A and B buttons are connected to GPIO pins that are also accessible on the micro:bit edge connector. | item | details @@ -129,11 +110,8 @@ Both A and B buttons are connected to GPIO pins that are also accessible on the The display is a 5x5 array of LEDs. It is connected to the micro:bit as a 3x9 matrix. -Runtime software repeatedly refreshes this matrix at a high speed, -such that it is within the user persistence of vision range, and no flicker is detected. -This LED matrix is also used to sense ambient light, -by repeatedly switching some of the LED drive pins into inputs and sampling the voltage decay time, -which is roughly proportional to ambient light levels. +Runtime software repeatedly refreshes this matrix at a high speed, such that it is within the user persistence of vision range, and no flicker is detected. +This LED matrix is also used to sense ambient light, by repeatedly switching some of the LED drive pins into inputs and sampling the voltage decay time, which is roughly proportional to ambient light levels. | item | details | --- | --- @@ -149,10 +127,8 @@ which is roughly proportional to ambient light levels. ## Motion sensor The 1.5 micro:bit variant has a combined accelerometer and magnetometer chip that provides 3-axis sensing and magnetic field strength sensing. -It also includes some on board gesture detection (such as fall detection) in hardware, -and additional gesture sensing (e.g. logo-up, logo-down, shake) via software algorithms. -A software algorithm in the standard runtime uses the on board accelerometer -to turn readings into a board orientation independent compass reading. +It also includes some on board gesture detection (such as fall detection) in hardware, and additional gesture sensing (e.g. logo-up, logo-down, shake) via software algorithms. +A software algorithm in the standard runtime uses the on board accelerometer to turn readings into a board orientation independent compass reading. The compass must be calibrated before use, and the calibration process is automatically initiated by the runtime software. This device is connected to the application processor via the I2C bus. @@ -169,8 +145,7 @@ The v1.5 micro:bit has a footprint for two different motion sensors: one made by ## Temperature Sensing The nRF51 application processor has an on board core temperature sensor. -This is exposed via the standard runtime software, and provides an estimate of ambient -temperature. +This is exposed via the standard runtime software, and provides an estimate of ambient temperature. | item | details | --- | --- @@ -182,12 +157,7 @@ temperature. ## General Purpose Input/Output Pins -The edge connector brings out many of the GPIO circuits of the application -processor. Some of these circuits are shared with other functions of the micro:bit, but -many of these extra circuits can be re-allocated to general purpose use if some software -features are turned off. Note: the nRF51 data sheet states that GPIO pins may be -in std-drive (0.5mA) and high-drive (5mA) mode, with a maximum of 3 pins in high-drive -mode at any one time. +The edge connector brings out many of the GPIO circuits of the application processor. Some of these circuits are shared with other functions of the micro:bit, but many of these extra circuits can be re-allocated to general purpose use if some software features are turned off. Note: the nRF51 data sheet states that GPIO pins may be in std-drive (0.5mA) and high-drive (5mA) mode, with a maximum of 3 pins in high-drive mode at any one time. | item | details | --- | --- @@ -211,10 +181,7 @@ mode at any one time. ## Power Supply -Power to the micro:bit may be provided via the USB connection, via the -interface chip (which has an on-board regulator), or via a battery plugged into the top -connector. It is also possible (with care) to power the micro:bit from the 3V pad at the -bottom. The 3V pad at the bottom can be used to supply a small amount of power external circuits. +Power to the micro:bit may be provided via the USB connection, via the interface chip (which has an on-board regulator), or via a battery plugged into the top connector. It is also possible (with care) to power the micro:bit from the 3V pad at the bottom. The 3V pad at the bottom can be used to supply a small amount of power external circuits. | item | details | --- | --- @@ -229,9 +196,7 @@ bottom. The 3V pad at the bottom can be used to supply a small amount of power e ## Interface -The interface chip handles the USB connection, and is used for flashing -new code to the micro:bit, sending and receiving serial data back and forth to your -main computer. +The interface chip handles the USB connection, and is used for flashing new code to the micro:bit, sending and receiving serial data back and forth to your main computer. | item | details | --- | --- @@ -246,12 +211,7 @@ main computer. ## USB Communications -The micro:bit has an on board USB communications stack, that is built into the firmware -of the interface chip. This stack provides the ability to drag and drop files onto the -MICROBIT drive in order to load code into the application processor. It also allows -serial data to be streamed to and from the micro:bit application processor over USB to -an external host computer, and supports the CMSIS-DAP protocol for host debugging -of application programs. +The micro:bit has an on board USB communications stack, that is built into the firmware of the interface chip. This stack provides the ability to drag and drop files onto the MICROBIT drive in order to load code into the application processor. It also allows serial data to be streamed to and from the micro:bit application processor over USB to an external host computer, and supports the CMSIS-DAP protocol for host debugging of application programs. | item | details | --- | --- @@ -265,12 +225,7 @@ of application programs. ## Debugging -The interface processor can be used with special host tools to debug -code that is running on the application processor. It connects to the application -processor via 4 signal wires. The KL26 interface processor code can also -be debuged via it's integral SWD software debug interface, for example to -load initial bootloader code into this processor at manufacturing time, or to -recover a lost bootloader. +The interface processor can be used with special host tools to debug code that is running on the application processor. It connects to the application processor via 4 signal wires. The KL26 interface processor code can also be debuged via it's integral SWD software debug interface, for example to load initial bootloader code into this processor at manufacturing time, or to recover a lost bootloader. | item | details | --- | --- @@ -280,9 +235,7 @@ recover a lost bootloader. ## Mechanical -We have some [nice 2D and 3D CAD drawings and models of the micro:bit](https://github.com/microbit-foundation/microbit-reference-design) including all the important dimensions. These models can be used as a basis for generating -really nice marketing and project images of the micro:bit, but also as a basis for accurate -manufacture of attachments e.g. via 3D printing. +We have some [nice 2D and 3D CAD drawings and models of the micro:bit](https://github.com/microbit-foundation/microbit-reference-design) including all the important dimensions. These models can be used as a basis for generating really nice marketing and project images of the micro:bit, but also as a basis for accurate manufacture of attachments e.g. via 3D printing. | item | details | --- | --- diff --git a/hardware/edgeconnector.md b/hardware/edgeconnector.md index 251fa29..838b021 100644 --- a/hardware/edgeconnector.md +++ b/hardware/edgeconnector.md @@ -18,16 +18,12 @@ lang: en The edge connector on the micro:bit is used to connect to external circuits and components. -There are 25 strips/pins including 5 rings for using with 4mm banana plugs or crocodile clips. 3 of these rings are for general purpose input and output (GPIO) and are -also capable of analog, PWM and touch sensing, and two are connected to the micro:bit power supply. +There are 25 strips/pins including 5 rings for using with 4mm banana plugs or crocodile clips. 3 of these rings are for general purpose input and output (GPIO) and are also capable of analog, PWM and touch sensing, and two are connected to the micro:bit power supply. -The smaller strips spaced at 1.27mm on the edge connector have additional signals, -some of which are used by the micro:bit, and others that are free for you to use. -There are a number of external PCB connectors for purchase with an 80w 1.27mm pitch -that can be used to easily access these extra pins. +The smaller strips spaced at 1.27mm on the edge connector have additional signals, some of which are used by the micro:bit, and others that are free for you to use. +There are a number of external PCB connectors for purchase with an 80w 1.27mm pitch that can be used to easily access these extra pins. -Only the pins on the front are connected to signals. The back rings are connected to the -front rings, but the back small strips are unconnected. +Only the pins on the front are connected to signals. The back rings are connected to the front rings, but the back small strips are unconnected. ## Edge Connector Pins @@ -152,107 +148,58 @@ This table shows various data about each of the pins on the micro:bit edge conne Notes -1. RINGs for 0, 1, 2, 3V and GND are also connected to the respective reverse -side rings on the edge connector. +1. RINGs for 0, 1, 2, 3V and GND are also connected to the respective reverse side rings on the edge connector. -2. The 3V and GND rings have guard strips either side of the big rings, -to avoid any degradation of device performance due to slipping crocodile -clip connections. Care should be taken on rings 0, 1 and 2 to avoid -shorting crocodile clips against adjacent pins, which could cause -some slight interference with the pattern currently displayed on -the LED matrix, or introduce some innaccuracies in the light sensing -readings. +2. The 3V and GND rings have guard strips either side of the big rings, to avoid any degradation of device performance due to slipping crocodile clip connections. Care should be taken on rings 0, 1 and 2 to avoid shorting crocodile clips against adjacent pins, which could cause some slight interference with the pattern currently displayed on the LED matrix, or introduce some innaccuracies in the light sensing readings. -3. The DAL DynamicPWM driver (and the underlying Nordic timer peripherals) -dictate that PWM can only be active on 3 pins simultaneously. -Any attempt to allocate a 4th pin for PWM use, will disable one of the -existing PWM pins. +3. The DAL DynamicPWM driver (and the underlying Nordic timer peripherals) dictate that PWM can only be active on 3 pins simultaneously. Any attempt to allocate a 4th pin for PWM use, will disable one of the existing PWM pins. -4. Digital input pins are by default configured with internal -pull down resistors when the pins are configured by the DAL. +4. Digital input pins are by default configured with internal pull down resistors when the pins are configured by the DAL. -5. Functions in brackets should be used with caution, as other features -of the device may become unstable, degraded or non operational, if their -normal use is not disabled in the software first. +5. Functions in brackets should be used with caution, as other features of the device may become unstable, degraded or non operational, if their normal use is not disabled in the software first. -6. The source file for [the pinout table](/docs/hardware/pinmap.csv) is held in CSV format. -You can load this into a spreadsheet and sort and filter it in any way that -makes sense to you. There is also a [zipped Python script](/docs/hardware/csv2md.zip) in this folder -that you can download to re-generate the markdown table version of the pinmap -used on this page, from the .csv file. +6. The source file for [the pinout table](/docs/hardware/pinmap.csv) is held in CSV format. You can load this into a spreadsheet and sort and filter it in any way that makes sense to you. There is also a [zipped Python script](/docs/hardware/csv2md.zip) in this folder that you can download to re-generate the markdown table version of the pinmap used on this page, from the .csv file. -7. The pin marked 'ACCESSIBILITY' is used to enable/disable an on-board -accessibility mode, and should not be used for anything else (even though it -can be used as a GPIO for testing). Future versions of the official micro:bit -editors may remove the ability to write to this pin. +7. The pin marked 'ACCESSIBILITY' is used to enable/disable an on-board accessibility mode, and should not be used for anything else (even though it can be used as a GPIO for testing). Future versions of the official micro:bit editors may remove the ability to write to this pin. ## Uncoupling Default Functionality -Pins that are marked with brackets around functions, require the default -functionality for that pin to be disabled, before other functions can -be used. +Pins that are marked with brackets around functions, require the default functionality for that pin to be disabled, before other functions can be used. **pins: P3, P4, P6, P7, P9, P10** -These pins are coupled to the LED matrix display, and also it's associated -ambient light sensing mode. To disable the display driver feature (which -will automatically disable the light sensing feature) call the DAL -function `display.enable(false)`. To turn the display driver back on again -later, call the DAL function `display.enable(true)`. +These pins are coupled to the LED matrix display, and also it's associated ambient light sensing mode. To disable the display driver feature (which will automatically disable the light sensing feature) call the DAL function `display.enable(false)`. To turn the display driver back on again later, call the DAL function `display.enable(true)`. -Note also that the LED 3x9 matrix connects LEDs with associated resistors across -these pins, so you should take that into account when designing circuits to use these -pins for other purposes. +Note also that the LED 3x9 matrix connects LEDs with associated resistors across these pins, so you should take that into account when designing circuits to use these pins for other purposes. **pins: P5, P11** -These pins are assigned to the two on-board buttons. In their default -setup with all the standard high level languages, there is a global -uBit instance containing: `uBit.buttonA`, `uBit.buttonB` and `uBit.buttonAB`. +These pins are assigned to the two on-board buttons. In their default setup with all the standard high level languages, there is a global uBit instance containing: `uBit.buttonA`, `uBit.buttonB` and `uBit.buttonAB`. -Buttons are hooked into the system timer in their constructor for -regular debouncing. However, if you want to completely remove -this feature and use the physical pins for other purposes, -you can `delete uBit.buttonA`, it will call the C++ destructor -and de-register the button instance from the system timer, effectively -disabling all DAL activity with that pin. It is then possible -to use a `MicroBitPin` instance around the physical pin name to -control it directly without interference from the DAL. +Buttons are hooked into the system timer in their constructor for regular debouncing. However, if you want to completely remove this feature and use the physical pins for other purposes, you can `delete uBit.buttonA`, it will call the C++ destructor and de-register the button instance from the system timer, effectively disabling all DAL activity with that pin. It is then possible to use a `MicroBitPin` instance around the physical pin name to control it directly without interference from the DAL. -Be aware though, that there are 10K external pullup resistors -fitted to the micro:bit board. +Be aware though, that there are 10K external pullup resistors fitted to the micro:bit board. **pins: P19, P20** -These pins are allocated to the I2C bus, which is used by both the -onboard motion sensor. It is strongly suggested -that you avoid using these pins for any function other than I2C. +These pins are allocated to the I2C bus, which is used by both the onboard motion sensor. It is strongly suggested that you avoid using these pins for any function other than I2C. -It is possible to disable the DAL services that use these pins as the I2C bus, -but the motion sensor device will still be connected -to the bus, and may try to interpret the signals as data payloads, -which could create some undesirable side effects on the SDA and interrupt -pins. There are 4K7 pullups fitted to both pins on the board, so the -best use for these two signals is to add other I2C devices. +It is possible to disable the DAL services that use these pins as the I2C bus, but the motion sensor device will still be connected to the bus, and may try to interpret the signals as data payloads, which could create some undesirable side effects on the SDA and interrupt pins. There are 4K7 pullups fitted to both pins on the board, so the best use for these two signals is to add other I2C devices. -The main reason you might choose to use these pins for other purposes would -be if you were designing your own micro:bit variant without any -I2C devices, and then it would free up two more pins for other -purposes. +The main reason you might choose to use these pins for other purposes would be if you were designing your own micro:bit variant without any I2C devices, and then it would free up two more pins for other purposes. ## Power Supply Capabilities -There is a dedicated page on [power supply capabilities and parameters](/hardware/powersupply), which better defines how you can use the GND and 3V rings +There is a dedicated page on [power supply capabilities and parameters](/hardware/powersupply), which better defines how you can use the GND and 3V rings ## GPIO Capabilities ### NRF51 -These key GPIO parameters are transcribed directly from Section 6, 7 and 8 of the [nRF51822 Datasheet](https://infocenter.nordicsemi.com/pdf/nRF51822_PS_v3.1.pdf), -and provided here as a handy reference. +These key GPIO parameters are transcribed directly from Section 6, 7 and 8 of the [nRF51822 Datasheet](https://infocenter.nordicsemi.com/pdf/nRF51822_PS_v3.1.pdf), and provided here as a handy reference. | KEY | Description | section | Min | Max | | --- | -------------------------------------------------- | ------- | ---- | ---- | @@ -271,29 +218,16 @@ and provided here as a handy reference. | RPD | Pull down resistance | 8.23 | 11K | 16K | -NOTE 1: The maximum number of pins configured as high-drive (5mA) -at any one time is 3 pins. +NOTE 1: The maximum number of pins configured as high-drive (5mA) at any one time is 3 pins. -NOTE 2: A common way that the maximum pin voltages can be exceeded, is -to attach an inductive load such as a speaker, motor, or piezo sounder -directly to the pin. These devices often have significant back-EMF -when energised, and will generate voltages that exceed the maximum -specifications of the GPIO pins, and may cause premature device failure. +NOTE 2: A common way that the maximum pin voltages can be exceeded, is to attach an inductive load such as a speaker, motor, or piezo sounder directly to the pin. These devices often have significant back-EMF when energised, and will generate voltages that exceed the maximum specifications of the GPIO pins, and may cause premature device failure. -NOTE 3: The pin marked 'ACCESSIBILITY' is used to enable/disable an on-board -accessibility mode, and should not be used for anything else (even though it -can be used as a GPIO for testing). Future versions of the official micro:bit -editors may remove the ability to write to this pin. +NOTE 3: The pin marked 'ACCESSIBILITY' is used to enable/disable an on-board accessibility mode, and should not be used for anything else (even though it can be used as a GPIO for testing). Future versions of the official micro:bit editors may remove the ability to write to this pin. -NOTE 4: The BBC suggest in the safety guide, that the maximum current -you can draw from the whole edge connector at any one time is -v190mA. This is set based on the 30mA budget for on board peripherals, -and the fact that the on board regulator of the KL26 when powered -from USB is rated at a maximum of 120mA. On the latest board revision the maximum current is V2270mA, though it is possible that the on-board mic and speaker can draw more current, so this value is TBC. +NOTE 4: The BBC suggest in the safety guide, that the maximum current you can draw from the whole edge connector at any one time is v190mA. This is set based on the 30mA budget for on board peripherals, and the fact that the on board regulator of the KL26 when powered from USB is rated at a maximum of 120mA. On the latest board revision the maximum current is V2270mA, though it is possible that the on-board mic and speaker can draw more current, so this value is TBC. ### NRF52 -These key GPIO parameters are transcribed directly from Section 6, 7 and 8 of the [nRF52833 Datasheet](https://infocenter.nordicsemi.com/pdf/nRF52833_PS_v1.2.pdf), -and provided here as a handy reference. +These key GPIO parameters are transcribed directly from Section 6, 7 and 8 of the [nRF52833 Datasheet](https://infocenter.nordicsemi.com/pdf/nRF52833_PS_v1.2.pdf), and provided here as a handy reference. | KEY | Description | section | Min | Max | | --- | ----------------------------------------------------- | ------- | ---- | ---- | @@ -318,25 +252,20 @@ and provided here as a handy reference. ## Connectors and Breakouts -There are a number of suppliers of edge connector for the BBC micro:bit, in various forms, -such as a right angle through-hole, a stand-up through-hole and a stand-up surface -mount. +There are a number of suppliers of edge connector for the BBC micro:bit, in various forms, such as a right angle through-hole, a stand-up through-hole and a stand-up surface mount. There is an 80 way * 1.27mm pitch double sided PCB connector, which you can buy from a number of sources. -At a pinch, it is also possible to use an old PCI edge connector from a PC motherboard, -as the pitch is the same (but it is slightly wider). +At a pinch, it is also possible to use an old PCI edge connector from a PC motherboard, as the pitch is the same (but it is slightly wider). -There are also some nice ideas that have surfaced in the community such as using just -the right size of countersunk or cheese-head bolt, or even 3D printed inserts. +There are also some nice ideas that have surfaced in the community such as using just the right size of countersunk or cheese-head bolt, or even 3D printed inserts. -Can you help to find or design a better connection solution to the micro:bit -edge connector? Share your designs and discoveries with us! +Can you help to find or design a better connection solution to the micro:bit edge connector? Share your designs and discoveries with us! ## Edge Connnectors for the BBC micro:bit [Add your connector to our list](http://github.com/microbit-foundation/dev-docs/edit/master/hardware/edgeconnector.md){: .btn.sm-btn} -| Supplier | Product +| Supplier | Product | -------- | ------- |[4UCon](http://www.4uconnector.com/online/index.asp)| [4UCon connector](https://cdn.shopify.com/s/files/1/2311/3697/files/1944_Drawing.pdf?3325) |[Cyclonn](http://www.dgyuliang.net)| [Cylconn 90 degree connector](http://www.dgyuliang.net/d/file/Produtcs/Customized%20Connector/MICRO%20BIT%20Connector/84a0fe06b4296135d64139b5b4297ef3.pdf), [Cylconn 180 degree connector](http://www.dgyuliang.net/d/file/Produtcs/Customized%20Connector/MICRO%20BIT%20Connector/0d43030af84ade6fc3f00e242079c055.pdf) @@ -352,9 +281,6 @@ edge connector? Share your designs and discoveries with us! [KiCad component and footprint library](https://github.com/anthonykirby/kicad_microbit_connector) -[2D CAD drawing](https://www.kitronik.co.uk/pdf/bbc_microbit_mechanical_datasheet_V2.pdf) -This drawing has all the key micro:bit dimensions, including the pin spacing of the -various pins of the edge connector on the micro:bit board. +[2D CAD drawing](https://www.kitronik.co.uk/pdf/bbc_microbit_mechanical_datasheet_V2.pdf) This drawing has all the key micro:bit dimensions, including the pin spacing of the various pins of the edge connector on the micro:bit board. -[Kitronik BBC micro:bit CAD Resources](https://kitronik.co.uk/blogs/resources/bbc-microbit-cad-resources) -This page contains a range of resources that can be used to create online reources or 3D printed designs +[Kitronik BBC micro:bit CAD Resources](https://kitronik.co.uk/blogs/resources/bbc-microbit-cad-resources) This page contains a range of resources that can be used to create online reources or 3D printed designs diff --git a/hardware/i2c-shared.md b/hardware/i2c-shared.md index a788f03..196229b 100644 --- a/hardware/i2c-shared.md +++ b/hardware/i2c-shared.md @@ -32,7 +32,7 @@ Overall, this means 0x1D, 0x0E (from v1.3), 0x1F and 0x19 (for the revision) are ### Table of address used by micro:bit accessories (please edit) If you make an accessory for the micro:bit, please help us by editing the table below and sharing the details of the i2c addresses you use. -| accessory name | organisation | i2c address(es) used | +| accessory name | organisation | i2c address(es) used | |----------------|--------------|-----------------------| | eg [banana-bit]()|eg Banana enterprises | eg 0x76, 0x29 | diff --git a/hardware/i2c.md b/hardware/i2c.md index 0f691f7..642b198 100644 --- a/hardware/i2c.md +++ b/hardware/i2c.md @@ -24,7 +24,7 @@ The external lines run to the edge connector and can be used for accessories. | | accelerometer | magnetometer (compass) | KL27 | |---------------------|------------------|------------------------| -| motion sensor variant 1 (LSM303AGR) | 0x19 (0x32/0x33) | 0x1E (0x3C/0x3D) | TBC +| motion sensor variant 1 (LSM303AGR) | 0x19 (0x32/0x33) | 0x1E (0x3C/0x3D) | TBC | motion sensor variant 2 (FXOS8700CQ) | 0x1F (0x3E/0x3F) | 0x1F (0x3E/0x3F) | TBC This means 0x1E, 0x1F and 0x19 are reserved for onboard use. @@ -32,7 +32,7 @@ This means 0x1E, 0x1F and 0x19 are reserved for onboard use. ### Table of address used by micro:bit accessories (please edit) If you make an accessory for the micro:bit, please help us by editing the table below and sharing the details of the i2c addresses you use. -| accessory name | organisation | i2c address(es) used | +| accessory name | organisation | i2c address(es) used | |----------------|--------------|-----------------------| | [EDU:BIT](https://www.cytron.io/p-edubit)| Cytron Technologies | 0x08 (0x10/0x11) | diff --git a/hardware/index.md b/hardware/index.md index 258dc83..e2ec62a 100644 --- a/hardware/index.md +++ b/hardware/index.md @@ -39,11 +39,9 @@ Two key pieces of information to help understand the internals of the micro:bit ### nRF52 Application Processor The nRF52 application processor is where user programs run. -A single, complete application including user code, runtime code and Bluetooth stack -is loaded and run directly from on chip flash memory. +A single, complete application including user code, runtime code and Bluetooth stack is loaded and run directly from on chip flash memory. All user accessible GPIO pins are provided by this processor. -There is an onboard 2.4GHz radio peripheral used to provide Bluetooth and custom radio capabilities -via an off-chip aerial. +There is an onboard 2.4GHz radio peripheral used to provide Bluetooth and custom radio capabilities via an off-chip aerial. | item | details | --- | --- @@ -58,10 +56,8 @@ via an off-chip aerial. ### Bluetooth Wireless Communication -The on board 2.4GHz supports Bluetooth communications via the [Nordic S140 SoftDevice](https://www.nordicsemi.com/Software-and-Tools/Software/S140), -which provides a fully qualified Bluetooth low energy stack. -This allows the micro:bit to communicate with a wide range of Bluetooth devices, -including smartphones and tablets. +The on board 2.4GHz supports Bluetooth communications via the [Nordic S140 SoftDevice](https://www.nordicsemi.com/Software-and-Tools/Software/S140), which provides a fully qualified Bluetooth low energy stack. +This allows the micro:bit to communicate with a wide range of Bluetooth devices, including smartphones and tablets. | item | details | --- | --- @@ -79,12 +75,9 @@ including smartphones and tablets. ### Low level radio communications The on board 2.4GHz transciever supports a number of other radio communications standards, on which we build the microbit-radio protocol -This protocol provides a very simple small-packet broadcast radio interface between other devices -that support it, such as other micro:bit devices. -The 'radio' interface that appears in a number of the languages on the micro:bit -is built on top of this protocol. -Additionally, the micro:bit runtime software adds a 'group code' to each data payload, -allowing for simple user managed device addressing and filtering to take place. +This protocol provides a very simple small-packet broadcast radio interface between other devices that support it, such as other micro:bit devices. +The 'radio' interface that appears in a number of the languages on the micro:bit is built on top of this protocol. +Additionally, the micro:bit runtime software adds a 'group code' to each data payload, allowing for simple user managed device addressing and filtering to take place. | item | details | --- | --- @@ -101,17 +94,10 @@ allowing for simple user managed device addressing and filtering to take place. ### Buttons -The two buttons on the front of the micro:bit, and the one button on the back, -are tact momentary push-to-make buttons. The back button is connected to the KL27 -interface processor and to the NRF52 processor for system reset purposes. This -means that the application will reset regardless of if it is powered from USB -or from battery. +The two buttons on the front of the micro:bit, and the one button on the back, are tact momentary push-to-make buttons. The back button is connected to the KL27 interface processor and to the NRF52 processor for system reset purposes. This means that the application will reset regardless of if it is powered from USB or from battery. Front buttons A and B can be programmed in the user application for any purpose. -A and B are debounced by software, which also includes short press, long press, -and 'both A+B' press detection. Buttons operate in a typical inverted electrical mode, -where a pullup resistor ensures a logical '1' when the button is released, -and a logical '0' when the button is pressed. +A and B are debounced by software, which also includes short press, long press, and 'both A+B' press detection. Buttons operate in a typical inverted electrical mode, where a pullup resistor ensures a logical '1' when the button is released, and a logical '0' when the button is pressed. Both A and B buttons are connected to GPIO pins that are also accessible on the micro:bit edge connector. | item | details @@ -125,11 +111,8 @@ Both A and B buttons are connected to GPIO pins that are also accessible on the The display is a 5x5 array of LEDs. It is connected to the micro:bit as a 5x5 matrix. -Runtime software repeatedly refreshes this matrix at a high speed, -such that it is within the user persistence of vision range, and no flicker is detected. -This LED matrix is also used to sense ambient light, -by repeatedly switching some of the LED drive pins into inputs and sampling the voltage decay time, -which is roughly proportional to ambient light levels. +Runtime software repeatedly refreshes this matrix at a high speed, such that it is within the user persistence of vision range, and no flicker is detected. +This LED matrix is also used to sense ambient light, by repeatedly switching some of the LED drive pins into inputs and sampling the voltage decay time, which is roughly proportional to ambient light levels. | item | details | --- | --- @@ -144,10 +127,8 @@ which is roughly proportional to ambient light levels. ### Motion sensor The micro:bit has a combined accelerometer and magnetometer chip that provides 3-axis sensing and magnetic field strength sensing. -It also includes some on board gesture detection (such as fall detection) in hardware, -and additional gesture sensing (e.g. logo-up, logo-down, shake) via software algorithms. -A software algorithm in the standard runtime uses the on board accelerometer -to turn readings into a board orientation independent compass reading. +It also includes some on board gesture detection (such as fall detection) in hardware, and additional gesture sensing (e.g. logo-up, logo-down, shake) via software algorithms. +A software algorithm in the standard runtime uses the on board accelerometer to turn readings into a board orientation independent compass reading. The compass must be calibrated before use, and the calibration process is automatically initiated by the runtime software. This device is connected to the application processor via the I2C bus. @@ -177,20 +158,18 @@ temperature. ### Speaker -In addition to outputing sound via PWM on the pins, the micro:bit has a PCB mounted magnetic speaker -to which sound output is mirrored. +In addition to outputing sound via PWM on the pins, the micro:bit has a PCB mounted magnetic speaker to which sound output is mirrored. | item | details | --- | --- | Type | JIANGSU HUANENG MLT-8530 -| SPL | 80dB @ 5V, 10cm -| Self-resonant frequency | 2700Hz +| SPL | 80dB @ 5V, 10cm +| Self-resonant frequency | 2700Hz | More Info | [Datasheet](https://datasheet.lcsc.com/szlcsc/1811151451_Jiangsu-Huaneng-Elec-MLT-8530_C94599.pdf) ### Microphone -An on board MEMs microphone provides a sound input to the micro:bit and a built in LED -indicator on the front of the board shows the user when this is powered. +An on board MEMs microphone provides a sound input to the micro:bit and a built in LED indicator on the front of the board shows the user when this is powered. The microphone has an external bias circuit of 33K:1K (power to ground) and is AC-coupled to the microphone input pin. @@ -200,16 +179,13 @@ The microphone has an external bias circuit of 33K:1K (power to ground) and is A | Sensitvity | -38dB ±3dB @ 94dB SPL | SNR | 63dB | AOP | 118db SPL -| Frequency range | 100Hz ~ 80kHz +| Frequency range | 100Hz ~ 80kHz | Polar pattern | Omnidirectional | More Info | [Datsheet](https://www.knowles.com/docs/default-source/model-downloads/spu0410lr5h-qb-revh32421a731dff6ddbb37cff0000940c19.pdf?Status=Master&sfvrsn=cebd77b1_4) ### General Purpose Input/Output Pins -The edge connector brings out many of the GPIO circuits of the application -processor. Some of these circuits are shared with other functions of the micro:bit, but -many of these extra circuits can be re-allocated to general purpose use if some software -features are turned off. +The edge connector brings out many of the GPIO circuits of the application processor. Some of these circuits are shared with other functions of the micro:bit, but many of these extra circuits can be re-allocated to general purpose use if some software features are turned off. | item | details | --- | --- @@ -233,7 +209,7 @@ features are turned off. ### Power supply -Power to the micro:bit may be provided via 5V on the USB connector, or via a 3V battery plugged into the JST connector. It is also possible (with care) to power the micro:bit from the 3V /GND rings on the edge connector. The 3V /GND rings at the bottom can be used to supply power to external circuits. The board uses an LDO specified up to 300mA, with thermal cut-out for short circuit protection. +Power to the micro:bit may be provided via 5V on the USB connector, or via a 3V battery plugged into the JST connector. It is also possible (with care) to power the micro:bit from the 3V /GND rings on the edge connector. The 3V /GND rings at the bottom can be used to supply power to external circuits. The board uses an LDO specified up to 300mA, with thermal cut-out for short circuit protection. | item | details | --- | --- @@ -247,9 +223,7 @@ Power to the micro:bit may be provided via 5V on the USB connector, or via a 3V ### Interface -The interface chip handles the USB connection, and is used for flashing -new code to the micro:bit, sending and receiving serial data back and forth to your -main computer. +The interface chip handles the USB connection, and is used for flashing new code to the micro:bit, sending and receiving serial data back and forth to your main computer. | item | details | --- | --- @@ -264,12 +238,8 @@ main computer. ### USB communications -The micro:bit has an on board USB communications stack, that is built into the firmware -of the interface chip. This stack provides the ability to drag and drop files onto the -MICROBIT drive in order to load code into the application processor. It also allows -serial data to be streamed to and from the micro:bit application processor over USB to -an external host computer, and supports the CMSIS-DAP protocol for host debugging -of application programs. +The micro:bit has an on board USB communications stack, that is built into the firmware of the interface chip. This stack provides the ability to drag and drop files onto the +MICROBIT drive in order to load code into the application processor. It also allows serial data to be streamed to and from the micro:bit application processor over USB to an external host computer, and supports the CMSIS-DAP protocol for host debugging of application programs. | item | details | --- | --- @@ -283,12 +253,7 @@ of application programs. ### Debugging -The interface processor can be used with special host tools to debug -code that is running on the application processor. It connects to the application -processor via 4 signal wires. The KL27 interface processor code can also -be debuged via it's integral SWD software debug interface, for example to -load initial bootloader code into this processor at manufacturing time, or to -recover a lost bootloader. +The interface processor can be used with special host tools to debug code that is running on the application processor. It connects to the application processor via 4 signal wires. The KL27 interface processor code can also be debuged via it's integral SWD software debug interface, for example to load initial bootloader code into this processor at manufacturing time, or to recover a lost bootloader. | item | details | --- | --- @@ -298,9 +263,7 @@ recover a lost bootloader. ### Mechanical -We have some [nice 2D and 3D CAD drawings and models of the micro:bit](https://github.com/microbit-foundation/microbit-reference-design) including all the important dimensions. These models can be used as a basis for generating -really nice marketing and project images of the micro:bit, but also as a basis for accurate -manufacture of attachments e.g. via 3D printing. +We have some [nice 2D and 3D CAD drawings and models of the micro:bit](https://github.com/microbit-foundation/microbit-reference-design) including all the important dimensions. These models can be used as a basis for generating really nice marketing and project images of the micro:bit, but also as a basis for accurate manufacture of attachments e.g. via 3D printing. | item | details | --- | --- diff --git a/hardware/power-consumption.md b/hardware/power-consumption.md index 6d8a351..37802c0 100644 --- a/hardware/power-consumption.md +++ b/hardware/power-consumption.md @@ -14,19 +14,19 @@ The micro:bit v2 V2 board revision has a range of modes **Awake** Board is fully operational. The nRF52 and KL27 will try and conserve power if they can. Power LED is lit. -**Sleep** Put the nRF52 to sleep when instructed by CODAL. Wake when USB is connected, reset is pressed or instructed to by CODAL. +**Sleep** Put the nRF52 to sleep when instructed by CODAL. Wake when USB is connected, reset is pressed or instructed to by CODAL. -On USB - Press and hold power/reset for 5 seconds to enter sleep. The micro:bit power LED will dim from bright red to off. It will then flash on/off, showing you that it is still connnected to the power source. Press power/reset to wake up. +On USB - Press and hold power/reset for 5 seconds to enter sleep. The micro:bit power LED will dim from bright red to off. It will then flash on/off, showing you that it is still connnected to the power source. Press power/reset to wake up. Removing the USB power cable and re-adding it will also wake the micro:bit **Power off** Power off the device. Triggered by pressing and holding the reset button. -On battery - Press and hold power/reset for 5 seconds to power off the micro:bit. The micro:bit power LED will dim from bright red to off. It will then remain off until you press the power/reset to wake up. +On battery - Press and hold power/reset for 5 seconds to power off the micro:bit. The micro:bit power LED will dim from bright red to off. It will then remain off until you press the power/reset to wake up. Inserting a USB power lead will also wake the device. ## LED display -The LED display on the V2 board revision is also brighter than previous revisions, so when using at full brightness you will notice faster battery rundown than an equivalent program on a v1 board. +The LED display on the V2 board revision is also brighter than previous revisions, so when using at full brightness you will notice faster battery rundown than an equivalent program on a v1 board. See our tips on [prolonging battery life](https://support.microbit.org/en/support/solutions/articles/19000087231-prolonging-battery-life) \ No newline at end of file diff --git a/hardware/powersupply.md b/hardware/powersupply.md index 8435263..523d5cb 100644 --- a/hardware/powersupply.md +++ b/hardware/powersupply.md @@ -15,7 +15,7 @@ lang: en Power to the micro:bit may be provided via: - USB connection via the interface chip (which has an on-board regulator) -- A battery plugged into the JST connector. +- A battery plugged into the JST connector. - The 3V and GND pins on the Edge Connector - The two losenge shaped pads on the rear right of the board @@ -23,13 +23,9 @@ Power from the micro:bit can be provided by the 3V and GND pins to small externa It's is important to stay within the design parameters of the board: -* When powered from USB, the on board interface chip (KL26v1/KL27V2) uses it's on chip -regulator to provide power, and this chip is rated at a maximum of 120mA. +* When powered from USB, the on board interface chip (KL26v1/KL27V2) uses it's on chip regulator to provide power, and this chip is rated at a maximum of 120mA. -* The on-board current budget will vary depending on the use of the display, -the Bluetooth, microphone, speaker and other peripherals. You should allow a worst case budget -of 30mA for when all on board peripherals are in use, leaving v190mA/V2270mA for circuits -plugged into the edge connector. +* The on-board current budget will vary depending on the use of the display, the Bluetooth, microphone, speaker and other peripherals. You should allow a worst case budget of 30mA for when all on board peripherals are in use, leaving v190mA/V2270mA for circuits plugged into the edge connector. * When powered from a battery, the KL chip is not powered up and the USB Indicator LED will not light up. @@ -37,11 +33,7 @@ plugged into the edge connector. ### Key Voltages -As taken from each of the chip data sheets, it can be seen that different -devices have slightly different operating voltage ranges and absolute -maximum voltages. Manufacturers state the operating voltage range as well -as the absolute maximum tolerable by the device. You should never exceed -the operating voltage range of any of the devices. +As taken from each of the chip data sheets, it can be seen that different devices have slightly different operating voltage ranges and absolute maximum voltages. Manufacturers state the operating voltage range as well as the absolute maximum tolerable by the device. You should never exceed the operating voltage range of any of the devices. ### v1 revision @@ -53,9 +45,7 @@ the operating voltage range of any of the devices. | MMA8653FC | 1.95V | 3.6V | 3.6Vabs | MAG3110 | 1.95V | 3.6V | 3.6Vabs -This table implies an operating voltage range of the micro:bit device as a whole -as being 1.8V min (for 1.5 variants) or 1.95V min (for 1.3* variants dictated by the motion sensor) and -3.6V max (dictated by all devices). +This table implies an operating voltage range of the micro:bit device as a whole as being 1.8V min (for 1.5 variants) or 1.95V min (for 1.3* variants dictated by the motion sensor) and 3.6V max (dictated by all devices). ### V2 revision @@ -65,8 +55,7 @@ as being 1.8V min (for 1.5 variants) or 1.95V min (for 1.3* variants dictated by | KL27 | 1.71V | 3.6V | 3.8Vabs | LSM303 | 1.71V | 3.6V | 3.6Vabs -This table implies an operating voltage range of the micro:bit device as a whole -as being 1.7V min and 3.6V max. +This table implies an operating voltage range of the micro:bit device as a whole as being 1.7V min and 3.6V max. ## Practicalities @@ -74,77 +63,43 @@ as being 1.7V min and 3.6V max. -When powered from USB, the KL26 v1 interface chip's on-board regulator is used -to provide 3.3V to the rest of the board. The latest revision V2 has a seperate regulator on the board. - -The [KL26 data sheet](http://www.nxp.com/docs/pcn_attachments/16440_KL26P64M48SF5_Rev.4.pdf)v1 -section 3.8.2, Table 30. "USB VREG electrical specifications" indicates the maximum -current from the regulated supply is 120mA. Some of this current is required to -run on-board devices, such as the KL26 itself, the nRF application processor, the motion sensor, and the LED display. When Bluetooth is enabled, the current -consumption of the nRF increases slightly. You should budget your current -requirements for anything you attach to the micro:bit v1 to not exceed about -90mA to give enough safe headroom for worst case with all on board peripherals -in use. - -This means that if you require more than 90mA from the edge connector, -(e.g. driving lots of NeoPixels or a small motor) these should have power supplied -to them externally. You can back-power the micro:bit via it's 3V pad, but please -be sure to use a properly regulated supply and a protection diode, as explained -below, so that your micro:bit always has a supply within the operating range of -all the on board peripherals and the supplies are not able to power each other. - -It is advised that you do not power the micro:bit from USB battery packs. This is -because some makes and models of USB battery packs can generate out of range -voltages when they are not suitably loaded that could damage your micro:bit -(i.e. when a small current is drawn). -Also, some USB battery packs will switch off automatically when the current -drawn from them is too low. +When powered from USB, the KL26 v1 interface chip's on-board regulator is used to provide 3.3V to the rest of the board. The latest revision V2 has a seperate regulator on the board. + +The [KL26 data sheet](http://www.nxp.com/docs/pcn_attachments/16440_KL26P64M48SF5_Rev.4.pdf)v1 section 3.8.2, Table 30. "USB VREG electrical specifications" indicates the maximum current from the regulated supply is 120mA. Some of this current is required to run on-board devices, such as the KL26 itself, the nRF application processor, the motion sensor, and the LED display. When Bluetooth is enabled, the current consumption of the nRF increases slightly. You should budget your current requirements for anything you attach to the micro:bit v1 to not exceed about +90mA to give enough safe headroom for worst case with all on board peripherals in use. + +This means that if you require more than 90mA from the edge connector, (e.g. driving lots of NeoPixels or a small motor) these should have power supplied to them externally. You can back-power the micro:bit via it's 3V pad, but please be sure to use a properly regulated supply and a protection diode, as explained below, so that your micro:bit always has a supply within the operating range of all the on board peripherals and the supplies are not able to power each other. + +It is advised that you do not power the micro:bit from USB battery packs. This is because some makes and models of USB battery packs can generate out of range voltages when they are not suitably loaded that could damage your micro:bit (i.e. when a small current is drawn). +Also, some USB battery packs will switch off automatically when the current drawn from them is too low. ### Battery Powering -When powered from a battery plugged into the top battery connector, the -KL26 interface chip is not powered up, and the System LED will not be -turned on. If your code does not display anything on the display, -this might look like the micro:bit is not working, but it is. +When powered from a battery plugged into the top battery connector, the KL26 interface chip is not powered up, and the System LED will not be turned on. If your code does not display anything on the display, this might look like the micro:bit is not working, but it is. -Because the nRF51 chip is powered almost directly (there is only one BAT60 diode -between the supply and the nRF51 power rails), a fully charged **LiPoly battery** -that is specced to reach 4.2V **will be give greater than the [3.6V maximum that -the nRF51 can withstand**](#key-voltages) +Because the nRF51 chip is powered almost directly (there is only one BAT60 diode between the supply and the nRF51 power rails), a fully charged **LiPoly battery** that is specced to reach 4.2V **will be give greater than the [3.6V maximum that the nRF51 can withstand**](#key-voltages) There is further information about the [battery connection and use](https://support.microbit.org/solution/articles/19000013982-how-do-i-power-my-micro-bit-/en) in our knowledgebase ### 3V Ring Powering The micro:bit may be powered from the 3V/GND rings on the edge connector. -There are also two losenge shaped pads on the far right of the back of the PCB -that can be used to supply power (e.g. solderable pads for a 2xAAA holder that -has wires or pins at one edge). [The topmost losenge is 0V and the bottom most -losenge is 3V](../../accessories/making-accessories/#battery-pads). +There are also two losenge shaped pads on the far right of the back of the PCB that can be used to supply power (e.g. solderable pads for a 2xAAA holder that has wires or pins at one edge). [The topmost losenge is 0V and the bottom most losenge is 3V](../../accessories/making-accessories/#battery-pads). -When powering from the 3V ring or the losenge on the PCB, you should take -appropriate best practice precautions: +When powering from the 3V ring or the losenge on the PCB, you should take appropriate best practice precautions: -1. Fit an external protection diode (preferably with a low Vf rating) -to prevent damage due to the power supply being connected the wrong way -round. +1. Fit an external protection diode (preferably with a low Vf rating) to prevent damage due to the power supply being connected the wrong way round. -2. If powered from a voltage source that could generate a voltage higher -than the maximum operating voltage of the micro:bit, fit some form -of over voltage protection, or proper regulation. +2. If powered from a voltage source that could generate a voltage higher than the maximum operating voltage of the micro:bit, fit some form of over voltage protection, or proper regulation. ### Power Supply Architecture v1 The [schematic](/hardware/schematic/) shows the architecture of the power supply. -Key points to note are that there are two BAT60A diodes, one from the 3.3V -supply from the KL26/27 interface chip, and one from the external battery connector. -Note that the 3V ring on the edge connector is V_TGT, which is the raw -supply provided to all on board chips, so this is why extra care -should be taken when connecting directly to the 3V ring or the 3V losenge. - -The BAT60A devices have a low Vf rating, you can read about this in the -[BAT60A datasheet](http://www.infineon.com/dgdl/Infineon-BAT60ASERIES-DS-v01_01-en.pdf?fileId=db3a304313d846880113def70c9304a9) +Key points to note are that there are two BAT60A diodes, one from the 3.3V supply from the KL26/27 interface chip, and one from the external battery connector. +Note that the 3V ring on the edge connector is V_TGT, which is the raw supply provided to all on board chips, so this is why extra care should be taken when connecting directly to the 3V ring or the 3V losenge. + +The BAT60A devices have a low Vf rating, you can read about this in the [BAT60A datasheet](http://www.infineon.com/dgdl/Infineon-BAT60ASERIES-DS-v01_01-en.pdf?fileId=db3a304313d846880113def70c9304a9) ### Power Supply Architecture V2 TBC \ No newline at end of file diff --git a/hardware/reference-design.md b/hardware/reference-design.md index 778d7ff..a4c876d 100644 --- a/hardware/reference-design.md +++ b/hardware/reference-design.md @@ -13,37 +13,22 @@ review-with: jonnya ## Reference Design -As well as learning about how the micro:bit is designed from the [schematic](../../hardware/schematic/), -we want to enable people to build their own hardware products and projects based -on the micro:bit. This means taking all the hardware that you've connected -to your micro:bit and putting down on one circuit board. +As well as learning about how the micro:bit is designed from the [schematic](../../hardware/schematic/), we want to enable people to build their own hardware products and projects based on the micro:bit. This means taking all the hardware that you've connected to your micro:bit and putting down on one circuit board. ![micro:bit plant monitor](/docs/hardware/assets/referencedesign-57055.png){:width="40%"} *Turn all these cables into a single board!* -Because the micro:bit has a Bluetooth radio, building your own boards just like -the micro:bit is complicated - you need to tune the antenna, add the right -resonance circuit and then certify the board, if you'd like to build more than -just a few of them. Therefore, in order to make it easier to build things based -on the micro:bit, we've made this version of the board that uses a pre-certified nRF51-based -module (details in [Module Choice](#module-choice) below). This way you can take your mind off the gritty RF details and just concentrate on adding your own components to the board. +Because the micro:bit has a Bluetooth radio, building your own boards just like the micro:bit is complicated - you need to tune the antenna, add the right resonance circuit and then certify the board, if you'd like to build more than just a few of them. Therefore, in order to make it easier to build things based on the micro:bit, we've made this version of the board that uses a pre-certified nRF51-based module (details in [Module Choice](#module-choice) below). This way you can take your mind off the gritty RF details and just concentrate on adding your own components to the board. -Furthermore, the micro:bit has a built in programmer and debugger, which is -important for a development board, but might not be worth the cost if you're -just building fixed-function product. The programmer on the reference design -can be easily extracted and used to program other boards - so you can make one -programmer to program all your micro:bit based designs! +Furthermore, the micro:bit has a built in programmer and debugger, which is important for a development board, but might not be worth the cost if you're just building fixed-function product. The programmer on the reference design can be easily extracted and used to program other boards - so you can make one programmer to program all your micro:bit based designs! ## Reference Design Features -* **100% binary compatible with the micro:bit, including all the same hardware -features: 3xbuttons, 5x5 display, motion sensor)** -* Released under the [SolderPad License 0.51](http://solderpad.org/licenses/SHL-0.51/) (based on Apache-2.0, but tailored - towards Open Hardware) +* **100% binary compatible with the micro:bit, including all the same hardware features: 3xbuttons, 5x5 display, motion sensor)** +* Released under the [SolderPad License 0.51](http://solderpad.org/licenses/SHL-0.51/) (based on Apache-2.0, but tailored towards Open Hardware) * Based on pre-certified [nRF51822 module](#module-choice) for ease of use -* Separate programmer and debugger circuits so that you can strip back -things that you don't need +* Separate programmer and debugger circuits so that you can strip back things that you don't need * Standard 2.54mm pitch connector for * all the micro:bit edge connector pins * programming the KL26 and the nRF51822 @@ -54,61 +39,45 @@ things that you don't need * Design available in Eagle, Altium and KiCad formats * Coin cell connection and holder option ([but beware the dangers of coin cells to children](http://www.bbc.co.uk/news/health-37410343)) -Any code that you write for your micro:bit can be run on the reference design -without modification. +Any code that you write for your micro:bit can be run on the reference design without modification. ![micro:bit reference design back](/docs/hardware/assets/referencedesign-76a11.png){:width="40%"} ![micro:bit reference design front](/docs/hardware/assets/referencedesign-2988d.png){:width="37%"} ## Modularity -The reference design is laid out in a very modular way, so that someone working -with it can easily customise the board to include only the parts they need. +The reference design is laid out in a very modular way, so that someone working with it can easily customise the board to include only the parts they need. ![the reference design is modular](/docs/hardware/assets/referencedesign-9cfb5.png). -For example, if you want to make something really tiny that doesn't make use -of all the expansion or the LEDs, you could make use of the 'bare minimum subset' -section of the board, and have a separate programmer. +For example, if you want to make something really tiny that doesn't make use of all the expansion or the LEDs, you could make use of the 'bare minimum subset' section of the board, and have a separate programmer. ## Module Choice There are multiple vendors of Bluetooth pre-certified modules based on the nRF51822. But because the micro:bit uses every pin on the nRF51822, only modules that exposes all of the GPIO of the chip can be used. We have initially chosen the [Raytac MDBT40-256V3](http://www.raytac.com/product/ins.php?index_id=63), which is available from outlets like Seedstudio, and commonly used on things like Adafruit BLE boards. -This design is fully open source, and we're happy to accept pull requests for -variants that use other modules, or improvements. +This design is fully open source, and we're happy to accept pull requests for variants that use other modules, or improvements. -For your own projects, using a different module is as simple as wiring the right -pins. The [hardware](../../hardware/) page has a detailed pinmap. Likewise, -contributions to this pinmap document for other popular modules are welcome. +For your own projects, using a different module is as simple as wiring the right pins. The [hardware](../../hardware/) page has a detailed pinmap. Likewise, contributions to this pinmap document for other popular modules are welcome. -There is a [list of nRF51822 modules maintained by Nordic Semiconductor](https://www.nordicsemi.com/eng/Products/3rd-Party-Bluetooth-low-energy-Modules), -from which you could choose any module that has all 31 GPIOs broken out. If your -design doesn't use all of the pins on the edge connector and you are able to -recompile your software for your custom design ([for example using Mbed](/software/runtime/)) -then you could choose a range of other modules. +There is a [list of nRF51822 modules maintained by Nordic Semiconductor](https://www.nordicsemi.com/eng/Products/3rd-Party-Bluetooth-low-energy-Modules), from which you could choose any module that has all 31 GPIOs broken out. If your design doesn't use all of the pins on the edge connector and you are able to recompile your software for your custom design ([for example using Mbed](/software/runtime/)) then you could choose a range of other modules. ## Software Bringup -Unlike a micro:bit, your device won't come pre-flashed! Neither of the MCUs will -have any software, so you'll need a debugger, or to ask the people manufacturing -your board to flash it for you. +Unlike a micro:bit, your device won't come pre-flashed! Neither of the MCUs will have any software, so you'll need a debugger, or to ask the people manufacturing your board to flash it for you. ### KL26 Software -As described on the [interface firmware](/software/daplink-interface) page, there is -a bootloader and a main interface program that needs to be flashed to the KL26. +As described on the [interface firmware](/software/daplink-interface) page, there is a bootloader and a main interface program that needs to be flashed to the KL26. -The hex file/image that contains both of these together can be found -here: [hex file](/docs/hardware/assets/kl26z_bl_if_BL0233_IF0234.hex.zip) +The hex file/image that contains both of these together can be found here: [hex file](/docs/hardware/assets/kl26z_bl_if_BL0233_IF0234.hex.zip) You should flash this onto your KL26 using the header labelled MKL26 prog: ![KL26 program header](/docs/hardware/assets/referencedesign-7eaaa.png) -If you don't have a debugger, the nRF51-DK board can be used as a J-link -debugger with the following configuration. +If you don't have a debugger, the nRF51-DK board can be used as a J-link debugger with the following configuration. ![Using an nRF51-DK as a debugger](/docs/hardware/assets/referencedesign-609b1.png){:width="40%"} @@ -116,12 +85,9 @@ Please see [this page](https://developer.mbed.org/users/MarceloSalazar/notebook/ ### nRF51 Software -Once you have flashed the KL26 then you can use the USB interface on the -reference design itself in order to program any micro:bit hex file onto the -device. +Once you have flashed the KL26 then you can use the USB interface on the reference design itself in order to program any micro:bit hex file onto the device. -If you have chosen not to include a KL26 circuit then you can use an external -programmer and the nRF51prog header: +If you have chosen not to include a KL26 circuit then you can use an external programmer and the nRF51prog header: ![nRF51 prog header](/docs/hardware/assets/referencedesign-d1599.png) @@ -131,8 +97,7 @@ The documentation of the reference design is hosted at GitHub where schematics, [micro:bit reference design GitHub page](https://github.com/microbit-foundation/microbit-reference-design) -The reference design uses the same ICs as the micro:bit itself, so to avoid -duplication of documentation, please refer to the [micro:bit hardware page](../../hardware/) for further details. +The reference design uses the same ICs as the micro:bit itself, so to avoid duplication of documentation, please refer to the [micro:bit hardware page](../../hardware/) for further details. ## Design Software @@ -142,7 +107,6 @@ The reference design is provided in formats that can be loaded and used in: * [Eagle Express/Maker/Educational](http://cadsoft.io/pricing/) * [KiCad EDA](http://kicad-pcb.org/) -Currently, the design is 'Altium First' and we would appreciate any support or -expertise around improving the conversion to KiCad and Eagle formats. +Currently, the design is 'Altium First' and we would appreciate any support or expertise around improving the conversion to KiCad and Eagle formats. If anyone has experience with Eagle import, and needs any Altium / Protel export versions and libraries, they can be supplied, please see [this GitHub issue](https://github.com/microbit-foundation/microbit-reference-design/issues/1). diff --git a/hardware/schematic.md b/hardware/schematic.md index 0c24fc5..60ad469 100644 --- a/hardware/schematic.md +++ b/hardware/schematic.md @@ -13,14 +13,11 @@ review-with: jonnya ## Overview -This page discusses the micro:bit schematic and Bill of Materials (BOM), -which shows the electrical connections of the micro:bit and the components used in it. +This page discusses the micro:bit schematic and Bill of Materials (BOM), which shows the electrical connections of the micro:bit and the components used in it. The schematic is available from the BBC's [micro:bit hardware repository](https://github.com/bbcmicrobit/hardware) -If you're looking to make something of your own based on the micro:bit, you might prefer to -use our ['Reference Design'](/hardware/reference-design/) which is based on a radio module and has space on the layout -for you to add your own components. +If you're looking to make something of your own based on the micro:bit, you might prefer to use our ['Reference Design'](/hardware/reference-design/) which is based on a radio module and has space on the layout for you to add your own components. ## Schematics @@ -65,72 +62,53 @@ Whilst we work on the publication of the schematic for the latest revision, here | P0.28 | COL1 | N | P4 | | P0.31 | COL3 | N | P3 | | P0.30 | COL5 | N | P10 | - + ## Key Features -Below, we've extracted some useful details about the hardware that anyone implementing -software for the micro:bit, interfacing to it, or designing an add-on board for it -should find useful. +Below, we've extracted some useful details about the hardware that anyone implementing software for the micro:bit, interfacing to it, or designing an add-on board for it should find useful. ### LEDS -The LED matrix is physically layed out as a 5x5. On the V2 board this is implemeted as a 5x5 matrix, but in the v1, this is implemented as a -scanned matrix of 9x3 (i.e. 9 colums by 3 rows). Row 2 Col 8, and Row 2 Col 9 are not used. +The LED matrix is physically layed out as a 5x5. On the V2 board this is implemeted as a 5x5 matrix, but in the v1, this is implemented as a scanned matrix of 9x3 (i.e. 9 colums by 3 rows). Row 2 Col 8, and Row 2 Col 9 are not used. The LED matrix is driven via a high-speed multiplex generated by application processor software. This software also uses the LED Row and Col pins to implement the light sensing feature, as such you may see a difference in sensitivity between borad revisions. -Some of the Columns appear on the edge connector, so if you want to use extra GPIO pins, -you have to disable the display in software. +Some of the Columns appear on the edge connector, so if you want to use extra GPIO pins, you have to disable the display in software. ### Interface -The Interface sheet shows the KL26/v1KL27v2 processor, which is an NXP microcontroller with an Arm processor, that implements -the USB protocol for the USB connector. This provides a method for loading code onto the application -processor, using a drag and drop interface. +The Interface sheet shows the KL26/v1KL27v2 processor, which is an NXP microcontroller with an Arm processor, that implements the USB protocol for the USB connector. This provides a method for loading code onto the application processor, using a drag and drop interface. -The USB protocol handler on this processor implements a Mass Storage Class device in order to offer -the drag and drop code load interface. It also provides a Connected Device Class that allows -a serial port interface to be used across the USB. +The USB protocol handler on this processor implements a Mass Storage Class device in order to offer the drag and drop code load interface. It also provides a Connected Device Class that allows a serial port interface to be used across the USB. -The interface processor also contains an on-board regulator that steps down the USB voltage -to 3.3V suitable for powering the rest of the micro:bit, and you can draw 120mAv1/300mAV2 from this -processor regulator. A TVS device is fitted to suppress ESD spikes and out of range voltages -that could be present on the USB connector. +The interface processor also contains an on-board regulator that steps down the USB voltage to 3.3V suitable for powering the rest of the micro:bit, and you can draw 120mAv1/300mAV2 from this processor regulator. A TVS device is fitted to suppress ESD spikes and out of range voltages that could be present on the USB connector. This processor does not have any connection to the GPIO pins on the micro:bit. ### Sensors -There is one combined motion sensor IC on the micro:bit, that contains an accelerometer and a magnetometer. The accelerometer -measures acceleration in 3 axies, and the magnetometer can be used as a compass, as well as a magnetic field detector. +There is one combined motion sensor IC on the micro:bit, that contains an accelerometer and a magnetometer. The accelerometer measures acceleration in 3 axies, and the magnetometer can be used as a compass, as well as a magnetic field detector. The device is connected to the application processor [I2c bus](../i2c/), and for the v1 revision this [I2c bus is also shared](../i2c-shared/) to two pins on the edge connector. I2C pullup resistors are pre-fitted on the board. -The magnetometer can generate one processor interrupt for the application processor, and the -accelerometer can generate two different processor interrupts for the application processor. +The magnetometer can generate one processor interrupt for the application processor, and the accelerometer can generate two different processor interrupts for the application processor. -Note, the physical orientation of this IC is important for binary compatibility with the driver -code in the application processor, which assumes a particular physical orientation in it's calculations. +Note, the physical orientation of this IC is important for binary compatibility with the driver code in the application processor, which assumes a particular physical orientation in it's calculations. ### Power Supply -Power to the micro:bit can be provided by 3 sources: The USB, the battery connector, and the 3V pad -on the edge connector. +Power to the micro:bit can be provided by 3 sources: The USB, the battery connector, and the 3V pad on the edge connector. -For USB powering, the KL26 interface processor has an on-board regulator that brings the external -USB voltage into the correct range for the micro:bit board. +For USB powering, the KL26 interface processor has an on-board regulator that brings the external USB voltage into the correct range for the micro:bit board. -A low-Vf diode (in this case about 0.23V max) is used to switch between sources. The diode prevents back-powering -of any source from any other source. +A low-Vf diode (in this case about 0.23V max) is used to switch between sources. The diode prevents back-powering of any source from any other source. -Care should be taken if powering the micro:bit from the 3V pad on the edge connector, as the trace -from that pad is connected directly to the IC's on the board. Please check the datasheets for the -appropriate IC's for their maximum tolerable voltages. +Care should be taken if powering the micro:bit from the 3V pad on the edge connector, as the trace from that pad is connected directly to the IC's on the board. Please check the datasheets for the appropriate IC's for their maximum tolerable voltages. @@ -156,19 +134,13 @@ The edge connector is the main interface to external components attached to the This interface has a range of digital, analog, touch, pwm, and serial communications interfaces. -10Mohm weak pull-up resistors are fitted on P0 P1 and P2 for use in touch sensing mode, where they -provide a weak pull-up to the supply providing a default high input and the user touching the GND -pad pulls the pin down towards 0V, providing a low input. When in non touch modes, these -pads have stronger internal pull-downs enabled in the software, so that the default input state -when not connected is 'low'. +10Mohm weak pull-up resistors are fitted on P0 P1 and P2 for use in touch sensing mode, where they provide a weak pull-up to the supply providing a default high input and the user touching the GND pad pulls the pin down towards 0V, providing a low input. When in non touch modes, these pads have stronger internal pull-downs enabled in the software, so that the default input state when not connected is 'low'. -Guard pins are provided both sides of the 3V and GND pads, so that shorting by crocodile clips -does not degrade the features of the device by causing spurious inputs. +Guard pins are provided both sides of the 3V and GND pads, so that shorting by crocodile clips does not degrade the features of the device by causing spurious inputs. Both the front and the back of each of the 5 round ring pads are electrically connected. -A number of pins have alternate assigned functions for use by the micro:bit, many of these -can be disabled in software to gain more general purpose IO pins. +A number of pins have alternate assigned functions for use by the micro:bit, many of these can be disabled in software to gain more general purpose IO pins. The V2 board revision has a notched edge connector to make it easier to connect crocodile clips and wire etc. This does not affect compatibility with peripherals with edge connector sockets. diff --git a/index.md b/index.md index 9710793..c72583a 100644 --- a/index.md +++ b/index.md @@ -11,26 +11,17 @@ post_filter: featured ## The micro:bit developer community site This site aims to sit between a community wiki and a technical data sheet for the micro:bit. -The content is available to [edit on Github](http://github.com/microbit-foundation/dev-docs) and is [openly licensed through Creative Commons](https://github.com/microbit-foundation/dev-docs/blob/master/LICENSE.MD). +The content is available to [edit on Github](http://github.com/microbit-foundation/dev-docs) and is [openly licensed through Creative Commons](https://github.com/microbit-foundation/dev-docs/blob/master/LICENSE.MD). -The site is maintained by the Micro:bit Educational Foundation in order to document the -hardware and software that make the micro:bit work the way it does. +The site is maintained by the Micro:bit Educational Foundation in order to document the hardware and software that make the micro:bit work the way it does. -We hope to encourage contributions into these projects in order -to broaden our ecosystem and the range of things people can invent -with a micro:bit. +We hope to encourage contributions into these projects in order to broaden our ecosystem and the range of things people can invent with a micro:bit. -The Micro:bit Educational Foundation aims to be a 'responsible downstream' to the -many open source [software](https://tech.microbit.org/software/) projects that are used to build the micro:bit: much like -a good Linux distribution collates, tests, stabilises and releases combinations of -many diverse open source packages, the micro:bit Educational Foundation and the -micro:bit community present micro:bit users with a stable, tested release of all -the things you need to make the magical 'end-to-end' micro:bit experience. +The Micro:bit Educational Foundation aims to be a 'responsible downstream' to the many open source [software](https://tech.microbit.org/software/) projects that are used to build the micro:bit: much like a good Linux distribution collates, tests, stabilises and releases combinations of many diverse open source packages, the micro:bit Educational Foundation and the micro:bit community present micro:bit users with a stable, tested release of all the things you need to make the magical 'end-to-end' micro:bit experience. ## Help us build it -If you'd like to help us make the micro:bit better, then there are a number of -ways that you can get involved. +If you'd like to help us make the micro:bit better, then there are a number of ways that you can get involved. ### Code Contribute features and fixes to one of the upstream projects that the micro:bit relies upon: @@ -38,15 +29,12 @@ Contribute features and fixes to one of the upstream projects that the micro:bit * The [MakeCode Editor](https://github.com/microsoft/pxt-microbit) * The [Python Editor](https://github.com/bbcmicrobit/PythonEditor) * [DAPlink](https://github.com/ARMmbed/DAPLink) - + ### Build -Help us build a brilliant hardware ecosystem around micro:bit - derivative boards, -cool accessories and add ons, or even suggestions for future versions of the micro:bit. +Help us build a brilliant hardware ecosystem around micro:bit - derivative boards, cool accessories and add ons, or even suggestions for future versions of the micro:bit. * The [micro:bit schematic](/hardware/schematic/) and [reference design](/hardware/reference-design) are good places to start for making your own projects * The [accessories guide](https://microbit.org/buy/accessories/) gives you an idea of what's currently available. ### Write - * [Improve the documentation and this site](https://github.com/microbit-foundation/dev-docs), either reporting issues -or adding documentation will be extremely helpful. - * Help build a community around micro:bit - join the [slack channel and Email list](/community/), -share the things you've created on twitter, blog about them! + * [Improve the documentation and this site](https://github.com/microbit-foundation/dev-docs), either reporting issues or adding documentation will be extremely helpful. + * Help build a community around micro:bit - join the [slack channel and Email list](/community/), share the things you've created on twitter, blog about them! diff --git a/latest-revision/README.MD b/latest-revision/README.MD index 55a459f..cc225fc 100644 --- a/latest-revision/README.MD +++ b/latest-revision/README.MD @@ -1,4 +1,3 @@ ## Latest revision (Temp) -This folder will exist until general announcement at which point -the guidance articles within will migrate to support.microbit.org. \ No newline at end of file +This folder will exist until general announcement at which point the guidance articles within will migrate to support.microbit.org. \ No newline at end of file diff --git a/latest-revision/latest-revision-accessories.md b/latest-revision/latest-revision-accessories.md index dd95a6d..01e0d94 100644 --- a/latest-revision/latest-revision-accessories.md +++ b/latest-revision/latest-revision-accessories.md @@ -78,7 +78,7 @@ Whereas on previous revisions, the I2C bus was shared between the motion sensor ### Power -The micro:bit can now be powered from the two losenge shaped pads on the rear of the board and the 3V/GND pins. +The micro:bit can now be powered from the two losenge shaped pads on the rear of the board and the 3V/GND pins. If you use the losenge pads, you must diode (or otherwise) protect themselves from the micro:bit having power via another source. This was still necessary on the previous revision when the board was powered from battery, but is now true for USB and edge-connector power also. @@ -106,7 +106,7 @@ The additional memory available to the latest revision means that you have more The latest board revision introduces a superset of the Intel-Hex format that enables compatibility across processor variants. A Universal Hex is a file that contains the binary data for both micro:bit v1 and micro:bit V2, in a format that the DAPLink can process to only write to memory the data relevant to its micro:bit board. -A **Universal Hex** hex file will work on a v1 or V2 board. +A **Universal Hex** hex file will work on a v1 or V2 board. A clear indication that you are working with this format is that a compiled .hex file will be ~1.8Mb as opposed to ~700Kb in size. A [Universal Hex JavaScript Library](https://github.com/microbit-foundation/microbit-universal-hex) has been written to implement the format and associated detailed [specification of the Universal Hex format](https://github.com/microbit-foundation/universal-hex/). Please [get in contact](mailto:support@microbit.org?subject=Request%20for%20access%20to%20Universal%20hex&20spec&body=Name%3A%0D%0A%0D%0AGitHub%20ID%3A) if you require access to the specification. diff --git a/latest-revision/latest-revision-content.md b/latest-revision/latest-revision-content.md index bfdfe0b..769c634 100644 --- a/latest-revision/latest-revision-content.md +++ b/latest-revision/latest-revision-content.md @@ -13,11 +13,11 @@ lang: en * TOC {:toc} -## Overview +## Overview Thank you, content producers for your support of the micro:bit - without people writing amazing resources and showing the world creative ways to use technology, micro:bit wouldn’t be nearly as exciting for people all around the world to use. -If you’d like to keep up to date with technical information about the device, please sign up to our [DAL, Devices and Editors mailing list](http://eepurl.com/dyRx-v) which provides information on hardware revisions, or key low-level software changes as early as possible. +If you’d like to keep up to date with technical information about the device, please sign up to our [DAL, Devices and Editors mailing list](http://eepurl.com/dyRx-v) which provides information on hardware revisions, or key low-level software changes as early as possible. ---------- diff --git a/latest-revision/latest-revision-editors.md b/latest-revision/latest-revision-editors.md index 2806238..d53e990 100644 --- a/latest-revision/latest-revision-editors.md +++ b/latest-revision/latest-revision-editors.md @@ -15,7 +15,7 @@ lang: en Thanks for your continuing support of the micro:bit. There is a wonderful breadth of [third party editors](https://microbit.org/code/#other-editors) available for the micro:bit that support different coding languages and learning scenarios. This article provides information to help you continue to support the 5 million existing micro:bits in the world and the latest board revision with the exciting new features of a speaker and microphone. -If you’d like to keep up to date with technical information about the device, please sign up to our [DAL, Devices and Editors mailing list](http://eepurl.com/dyRx-v) which provides information on hardware revisions, or key low-level software changes as early as possible. +If you’d like to keep up to date with technical information about the device, please sign up to our [DAL, Devices and Editors mailing list](http://eepurl.com/dyRx-v) which provides information on hardware revisions, or key low-level software changes as early as possible. ---------- @@ -23,7 +23,7 @@ Please note that we do as much development as possible in the open, so if you’ - [Micro:bit Educational Foundation on GitHub](https://github.com/microbit-foundation) -- [microbit-dal](https://github.com/lancaster-university/microbit-dal) +- [microbit-dal](https://github.com/lancaster-university/microbit-dal) - [CODAL](https://github.com/microbit-foundation/codal/) - [microbit](https://github.com/lancaster-university/microbit) - [MicroPython](https://github.com/bbcmicrobit/micropython) @@ -34,8 +34,7 @@ Your tools are some of the most direct ways that users experience the micro:bit. ## If you’re using the microbit DAL/Runtime -The most important change here is that the latest board revision runtime is based on [CODAL](https://lancaster-university.github.io/codal/) -and no longer makes use of Arm Mbed. +The most important change here is that the latest board revision runtime is based on [CODAL](https://lancaster-university.github.io/codal/) and no longer makes use of Arm Mbed. | V2 | v1 @@ -51,7 +50,7 @@ The [instructions for building CODAL](https://github.com/microbit-foundation/cod ## If you’re using MicroPython -Based on the current work in CODAL we've also worked with Damien George, the author of MicroPython, to build the changes into an updated release of MicroPython for the micro:bit. +Based on the current work in CODAL we've also worked with Damien George, the author of MicroPython, to build the changes into an updated release of MicroPython for the micro:bit. The exisiting API has not changed. Scripts that use features that are common to all revisions will not be affected. @@ -96,7 +95,7 @@ This gives a teacher or facilitator who is unable to update their editors (for e The latest board revision introduces a superset of the Intel-Hex format that enables compatibility across processor variants. A Universal Hex is a file that contains the binary data for both micro:bit v1 and micro:bit V2, in a format that the DAPLink can process to only write to memory the data relevant to its micro:bit board. -A **Universal Hex** hex file will work on a v1 or V2 board. +A **Universal Hex** hex file will work on a v1 or V2 board. A clear indication that you are working with this format is that a compiled .hex file will be ~1.8Mb as opposed to ~700Kb in size. A [Universal Hex JavaScript Library](https://github.com/microbit-foundation/microbit-universal-hex) has been written to implement the format and associated detailed [specification of the Universal Hex format](https://github.com/microbit-foundation/universal-hex/). Please [get in contact](mailto:support@microbit.org?subject=Request%20for%20access%20to%20Universal%20hex&20spec&body=Name%3A%0D%0A%0D%0AGitHub%20ID%3A) if you require access to the specification. diff --git a/latest-revision/latest-revision-main.md b/latest-revision/latest-revision-main.md index 9be024d..e75d8ba 100644 --- a/latest-revision/latest-revision-main.md +++ b/latest-revision/latest-revision-main.md @@ -12,7 +12,7 @@ lang: en * TOC {:toc} -The [**latest revision**](./announcement/) of the BBC micro:bit is designed to be completely familiar to anyone who has used the original device. It’s the same size, shape, looks very similar, and works in the same way. Every programme that could run on a micro:bit version 1 can be re-built to run on the latest revision. +The [**latest revision**](./announcement/) of the BBC micro:bit is designed to be completely familiar to anyone who has used the original device. It’s the same size, shape, looks very similar, and works in the same way. Every programme that could run on a micro:bit version 1 can be re-built to run on the latest revision. The editors will support both versions simultaneously for features common to both boards,for example the motion sensor, LEDs, buttons etc. @@ -25,7 +25,7 @@ Amongst the micro:bit features, ‘sound’ is in a unique position of being alr - On board speaker - MEMs Microphone with LED indicator -- Touch sensitive logo +- Touch sensitive logo - Built-in sleep/off mode that means the board can be powered-down with batteries connected - Discrete regulator that can supply up to 190mA of current to external accessories @@ -131,8 +131,8 @@ When they are finalised, we will notify people via the [DAL, Editors and Devices ## How do I use the new features? -The **speaker** works in the same way you would expect when you connect up your headphones or an external speaker to the micro:bit. By default, the sound output will be on both the speaker and Edge connector. -The **microphone** will have an additional set of blocks in MakeCode and objects in MicroPython to use, so that you can monitor and respond to sound. +The **speaker** works in the same way you would expect when you connect up your headphones or an external speaker to the micro:bit. By default, the sound output will be on both the speaker and Edge connector. +The **microphone** will have an additional set of blocks in MakeCode and objects in MicroPython to use, so that you can monitor and respond to sound. The **logo touch** is implemented in the same way as touching a pin on the edge connector and will have equivalent blocks in MakeCode and objects in MicroPython to use. Note that Logo touch is capacitive touch by default and the edge pins are resistive. To access the features of the latest revision only (eg. to output sound only on the speaker and not the edge connector), you will need to add additional code to your programs. This ensures that the default editor experience continues to work for everyone, regardless of the board revision. @@ -149,7 +149,7 @@ An extension has been developed to include the microphone and logo touch feature 1. Open [https://makecode.microbit.org/beta](https://makecode.microbit.org/beta) -2. Select Advanced > Add Extension and paste [https://github.com/microbit-foundation/pxt-microbit-v2-extension](https://github.com/microbit-foundation/pxt-microbit-v2-extension) into the search box. +2. Select Advanced > Add Extension and paste [https://github.com/microbit-foundation/pxt-microbit-v2-extension](https://github.com/microbit-foundation/pxt-microbit-v2-extension) into the search box. 3. Click on the extension to add it to the toolbox. **V2 MakeCode APIs** @@ -179,7 +179,7 @@ More information about this is available on our [hex format](../software/hex-for The Foundation has written a javascript library to generate these files - you do not need to re-implement any file generation. -### Bluetooth BLE +### Bluetooth BLE A hex file that enables all micro:bit Bluetooth services is available to use for testing BLE. [Download the updated version of the BLE all services hex](/docs/latest-revision/assets/bluetooth-services.hex) @@ -199,7 +199,7 @@ If you haven’t already received a device, but would like one in order to test/ ## How do I find out more about the hardware and software updates? -Our [DAL, Devices and Editors mailing list](http://eepurl.com/dyRx-v) provides up to date information about the any technical changes regarding the micro:bit. +Our [DAL, Devices and Editors mailing list](http://eepurl.com/dyRx-v) provides up to date information about the any technical changes regarding the micro:bit. ## How do I feed back or raise issues? diff --git a/projects.md b/projects.md index cfc080d..dae6d92 100644 --- a/projects.md +++ b/projects.md @@ -11,9 +11,9 @@ lang: en This page collates technical projects, research and development that have been done on/with the BBC micro:bit in universities, labs, clubs and schools around the world. It has been created by the micro:bit community, and you are welcome to submit any of your own work to it by [submitting a project template](https://github.com/microbit-foundation/dev-docs/issues/new?template=labs.md) -If you’d like to see [research about the impact of micro:bit, head over to our main site](https://microbit.org/research/). +If you’d like to see [research about the impact of micro:bit, head over to our main site](https://microbit.org/research/). ---- +--- [Add your research/project to the lab](https://github.com/microbit-foundation/dev-docs/issues/new?template=labs.md){: .btn.sm-btn} diff --git a/software/hex-format.md b/software/hex-format.md index 99b10cc..4035479 100644 --- a/software/hex-format.md +++ b/software/hex-format.md @@ -21,7 +21,7 @@ A micro:bit .hex file usually starts writing data to the same fixed location in The latest board revision introduces a superset of the Intel-Hex format that enables compatibility across processor variants. A Universal Hex is a file that contains the binary data for both micro:bit v1 and micro:bit V2, in a format that DAPLink can process to only write to memory the data relevant to its micro:bit board. -A **Universal Hex** hex file will work on a v1 or V2 board. +A **Universal Hex** hex file will work on a v1 or V2 board. A clear indication that you are working with this format is that a compiled .hex file will be ~1.8Mb as opposed to ~700Kb in size. A [Universal Hex JavaScript Library](https://github.com/microbit-foundation/microbit-universal-hex) has been written to implement the format and associated detailed [specification of the Universal Hex format](https://github.com/microbit-foundation/universal-hex/). diff --git a/software/in_browser_compiler.md b/software/in_browser_compiler.md index 086d796..db267b2 100644 --- a/software/in_browser_compiler.md +++ b/software/in_browser_compiler.md @@ -13,66 +13,41 @@ lang: en ## Overview There are a number of different code editors for the micro:bit. -Of the available editors; [MakeCode](https://makecode.microbit.org) and [Python](https://python.microbit.org) have an -in-browser compiler. This means that when you hit the **Download** button -to translate your code into a language supported by the micro:bit, all of the -hard work takes place inside your web browser. +Of the available editors; [MakeCode](https://makecode.microbit.org) and [Python](https://python.microbit.org) have an in-browser compiler. This means that when you hit the **Download** button to translate your code into a language supported by the micro:bit, all of the hard work takes place inside your web browser. You can also use MicroPython offline by installing the [Mu editor](https://codewith.mu) on your computer. -The in-browser build process is useful, because you are not dependent -on an internet connection in order to code and innovate with your -micro:bit - once you have the web page open and the editor is cached -on your computer, you can work independently of internet access. +The in-browser build process is useful, because you are not dependent on an internet connection in order to code and innovate with your micro:bit - once you have the web page open and the editor is cached on your computer, you can work independently of internet access. -By being web based, these editors allow you to write code for the -micro:bit without needing to install any special software on your -computer, which is especially important if working in a previously -unused classroom, or on a public computer. +By being web based, these editors allow you to write code for the micro:bit without needing to install any special software on your computer, which is especially important if working in a previously unused classroom, or on a public computer. ## How it Works ![img](/docs/software/assets/browser-build-pipeline.png) -The above diagram shows an example of how blocks code is converted into a -.hex file that can be loaded onto your micro:bit +The above diagram shows an example of how blocks code is converted into a .hex file that can be loaded onto your micro:bit -1a. Edit your script; this is automatically saved inside the web browser cache on your -computer. +1a. Edit your script; this is automatically saved inside the web browser cache on your computer. -1b. Press the **Download** button, and the script is first -converted into javascript. The in-browser-compiler then converts it into Arm machine code instructions. +1b. Press the **Download** button, and the script is first converted into javascript. The in-browser-compiler then converts it into Arm machine code instructions. -1c. The Arm machine code instructions are 'linked' with the Lancaster University -runtime code, [the DAL](/software/runtime) and converted into an [Intel-HEX file -format](/software/hex-format). This is done by ensuring that the in-browser-compiler knows the entry points -of key functions that it needs to be able to call out into. +1c. The Arm machine code instructions are 'linked' with the Lancaster University runtime code, [the DAL](/software/runtime) and converted into an [Intel-HEX file format](/software/hex-format). This is done by ensuring that the in-browser-compiler knows the entry points of key functions that it needs to be able to call out into. -2. You accept the download of the .hex file, which is stored in the filing system -on your computer. +2. You accept the download of the .hex file, which is stored in the filing system on your computer. -3. Download/Flash the .hex file onto the MICROBIT drive, and the interface -processor on the micro:bit copies it into the flash memory inside the application -processor. Your code now runs. +3. Download/Flash the .hex file onto the MICROBIT drive, and the interface processor on the micro:bit copies it into the flash memory inside the application processor. Your code now runs. -Because code is compiled in-browser, the compiler needs to have a copy of -the runtime/DAL code in order to create a complete distributable package. -There is a pre-compiled copy of the runtime (DAL+Mbed) that gets loaded -when you first load the editor. +Because code is compiled in-browser, the compiler needs to have a copy of the runtime/DAL code in order to create a complete distributable package. +There is a pre-compiled copy of the runtime (DAL+Mbed) that gets loaded when you first load the editor. ## Other Features -MakeCode supports two-way conversion of code, so you can write code as blocks and -see what the generated code looks like in Javascript/MakeCode Python. You can also write Javascript/MakeCode Python code, and if -possible, MakeCode will convert this back into blocks automatically. +MakeCode supports two-way conversion of code, so you can write code as blocks and see what the generated code looks like in Javascript/MakeCode Python. You can also write Javascript/MakeCode Python code, and if possible, MakeCode will convert this back into blocks automatically. Makecode also allows you to [write your own block types](https://makecode.com/extensions) and [publish them as Extensions](https://makecode.microbit.org/extensions). -The Python web editor does not use the in-browser compiler. It only -sits inside the frame of the website, but it gains access to the -save and import functionality for saving and loading scripts -to local files, and to and from a cloud store. +The Python web editor does not use the in-browser compiler. It only sits inside the frame of the website, but it gains access to the save and import functionality for saving and loading scripts to local files, and to and from a cloud store. Read more about how MicroPython works: [MicroPython on micro:bit](/software/micropython) diff --git a/software/index.md b/software/index.md index f345f74..36ada57 100644 --- a/software/index.md +++ b/software/index.md @@ -20,19 +20,16 @@ Software for the micro:bit consists of two main groups: 2. software that runs on the micro:bit (target) -Typically, a program is written on the host computer and then transferred to -the micro:bit over USB. +Typically, a program is written on the host computer and then transferred to the micro:bit over USB. -There are actually two chips on the -micro:bit, one that is running the **DAPlink** software entirely to facilitate the flashing (KL26v1/KL27V2) and one that actually runs the user's code (nRF51v1/nRF52V2). +There are actually two chips on the micro:bit, one that is running the **DAPlink** software entirely to facilitate the flashing (KL26v1/KL27V2) and one that actually runs the user's code (nRF51v1/nRF52V2). ![Software flow](/docs/software/assets/software-program.svg) ## High level programming languages -The 'high level' programming languages for the micro:bit break down into -two broad categories +The 'high level' programming languages for the micro:bit break down into two broad categories * Compiled languages: your program is compiled to Arm assembler or some other kind of bytecode before being copied onto the micro:bit. @@ -46,11 +43,7 @@ In order to ensure that the micro:bit online code editors could scale to support This process is explained in full in the [In browser compiler](/software/in_browser_compiler) page, and in fantastic detail at [TouchDevelop in 208 bits](https://www.touchdevelop.com/docs/touch-develop-in-208-bits). -These in-browser-compilers do not compile the whole of the software stack, -but just the user's script. Function calls and low level functions are -handled by the micro:bit runtime and Mbed. A pre-compiled runtime image is -included in the browser and concatenated with the compiled script before -being presented for download. +These in-browser-compilers do not compile the whole of the software stack, but just the user's script. Function calls and low level functions are handled by the micro:bit runtime and Mbed. A pre-compiled runtime image is included in the browser and concatenated with the compiled script before being presented for download. ### Interpreted languages @@ -62,8 +55,7 @@ There is also a [port of the Javascript interpreter Espruino](http://www.espruin ## Coding environments and IDEs -There are a huge number of possible coding environments that you can use -to program the micro:bit. +There are a huge number of possible coding environments that you can use to program the micro:bit. Among the most popular are the official ones listed at http://microbit.org/code as well as the offline Mu editor. @@ -93,34 +85,22 @@ Here's a non-exhaustive list of possible code editors for use with the micro:bit ## From coding environment to micro:bit -Each of the coding environments generates a special file called a .hex file, which -contains code for your micro:bit, written in a format it can understand. +Each of the coding environments generates a special file called a .hex file, which contains code for your micro:bit, written in a format it can understand. -The micro:bit code is updated by dragging a .hex file onto the MICROBIT drive -that appears on your computer, when you plug in the micro:bit. It looks just like a -USB memory stick to your computer (the flash drive is actually emulated - by the [DAPLink](/software/daplink-interface) software) +The micro:bit code is updated by dragging a .hex file onto the MICROBIT drive that appears on your computer, when you plug in the micro:bit. It looks just like a USB memory stick to your computer (the flash drive is actually emulated by the [DAPLink](/software/daplink-interface) software) -It is also possible to 'flash' code to your micro:bit by using a mobile app, -and using the Bluetooth communications interface from your mobile phone. +It is also possible to 'flash' code to your micro:bit by using a mobile app, and using the Bluetooth communications interface from your mobile phone. -You can read more about [bluetooth flashing](/bluetooth/profile) or -[bluetooth apps](/bluetooth/apps-and-examples) by following these links. +You can read more about [bluetooth flashing](/bluetooth/profile) or [bluetooth apps](/bluetooth/apps-and-examples) by following these links. ### micro:bit Low Level (C/C++) Software Stack -When you write an application for your micro:bit, other pieces of software are -joined together with your application to make up the final .hex file that is -flashed. This code consists of various lower level software components, such as: +When you write an application for your micro:bit, other pieces of software are joined together with your application to make up the final .hex file that is flashed. This code consists of various lower level software components, such as: -* [DAL/CODAL](./runtime/) (sometimes called the runtime), written in C++ by Lancaster University. The DAL abstracts the -facilities of the micro:bit into a common set of functions that can be used -by all coding languages. The high level block functions in MakeCode map almost directly onto equivalent C/C++ calls in the runtime. MicroPython requires less use of the DAL. +* [DAL/CODAL](./runtime/) (sometimes called the runtime), written in C++ by Lancaster University. The DAL abstracts the facilities of the micro:bit into a common set of functions that can be used by all coding languages. The high level block functions in MakeCode map almost directly onto equivalent C/C++ calls in the runtime. MicroPython requires less use of the DAL. -* [Arm Mbed](./runtime/) The Arm mbed SDK provides standardised drivers for MCU peripherals and abstracts most of the low level hardware details of different MCUs, meaning that micro:bit software can be easily run on other hardware. This -includes an abstraction for BLE, the Mbed BLE api. +* [Arm Mbed](./runtime/) The Arm mbed SDK provides standardised drivers for MCU peripherals and abstracts most of the low level hardware details of different MCUs, meaning that micro:bit software can be easily run on other hardware. This includes an abstraction for BLE, the Mbed BLE api. -* [Nordic nRF5 SDK](./runtime/#nordic-nrf5-sdk) mbed itself builds on top of the -Nordic nRF5 SDK, the component provided by Nordic to assist programmers in using their hardware. +* [Nordic nRF5 SDK](./runtime/#nordic-nrf5-sdk) mbed itself builds on top of the Nordic nRF5 SDK, the component provided by Nordic to assist programmers in using their hardware. * [MicroPython interpreter](./micropython) If you are using Python, then the whole MicroPython language interpreter is joined to your application to make up the .hex file. MicroPython on the micro:bit uses Mbed underneath, though MicroPython also runs on a wide range of other hardware platforms. diff --git a/software/interface.md b/software/interface.md index d40ff5c..598f662 100644 --- a/software/interface.md +++ b/software/interface.md @@ -13,11 +13,11 @@ lang: en The micro:bit presents itself as a USB disk when it is connected over USB, and can be programmed through this interface without the need to install any drivers. This makes it easier to use as a beginner. Furthermore, no matter what code you run on your micro:bit, or how you manage to crash the device, you can always still put a new program on using the USB connection.This is made possible by having a separate 'interface chip' or 'interface MCU' on the micro:bit dedicated to USB connections, programming and debugging. -The **Interface MCU** is a **Freescale KL27** v2 or **Freescale KL26** v1. +The **Interface MCU** is a **Freescale KL27** v2 or **Freescale KL26** v1. The chip that developers' code runs on, and that all the peripherals are connected to is called the 'target MCU'. See the [Hardware](/hardware) page and the schematic for more details about how these two devices are connected. -The **Target MCU** is a **Nordic Semiconductor nRF52833** V2 or **Nordic Semiconductor nRF51822** v1. +The **Target MCU** is a **Nordic Semiconductor nRF52833** V2 or **Nordic Semiconductor nRF51822** v1. DAPlink interface @@ -50,8 +50,7 @@ This software provides four USB endpoints that have specific purposes: * WebUSB - faciliates communicating witht the device via a WebUSB capable browser. -The DAPLink software and interface chip are part of the [Arm Mbed HDK](https://developer.mbed.org/handbook/mbed-HDK) -and the [Mbed Enabled program](https://www.mbed.com/en/about-mbed/mbed-enabled/) +The DAPLink software and interface chip are part of the [Arm Mbed HDK](https://developer.mbed.org/handbook/mbed-HDK) and the [Mbed Enabled program](https://www.mbed.com/en/about-mbed/mbed-enabled/) The micro:bit currently ships with DAPLink bootloader at version 0255 and interface at version 0255. @@ -70,8 +69,7 @@ The following versions of the device have previously been shipped with the follo It is possible to update the version of DAPLink running on your micro:bit. This is done using the DAPLink bootloader. This means that in fact, DAPLink is built twice for the micro:bit. -1. `bootloader mode` is used to for updating the main interface firmware. In this mode, the drive name is `MAINTENANCE` and hex files dropped onto the disk are written into the -KL27 V2 or KL26 v1 flash. These files MUST contain an image of DAPLink or equivalent. +1. `bootloader mode` is used to for updating the main interface firmware. In this mode, the drive name is `MAINTENANCE` and hex files dropped onto the disk are written into the KL27 V2 or KL26 v1 flash. These files MUST contain an image of DAPLink or equivalent. 2. `interface mode` is used to target the nRF52833 V2 or nRF51822 v1. In this mode, the drive name is `MICROBIT` and the hex files dropped onto the micro:bit are written to the flash of the target MCU. There are detailed instructions for how to [update the firmware version on the micro:bit website](https://microbit.org/get-started/user-guide/firmware/). diff --git a/software/makecode.md b/software/makecode.md index 76af02f..c591446 100644 --- a/software/makecode.md +++ b/software/makecode.md @@ -40,7 +40,7 @@ The editor has built in support for [Github authoring](https://makecode.com/blog Users can [publish their own tutorials](https://makecode.com/writing-docs/user-tutorials) for simple, guided steps on using MakeCode. Tutorials also support third party extensions. ### Community -There are a variety of ways to get involved and interact +There are a variety of ways to get involved and interact - Join the [micro:bit developer community on Slack](../../community/) - Raise a [MakeCode issue or feature request](https://github.com/Microsoft/pxt-microbit/issues) - Ask the MakeCode development team on [MakeCode forum for micro:bit](https://forum.makecode.com/c/microbit/11) diff --git a/software/micropython.md b/software/micropython.md index 4b4be09..49c07f2 100644 --- a/software/micropython.md +++ b/software/micropython.md @@ -12,17 +12,13 @@ lang: en ## Overview -MicroPython is a version of the popular Python programming language for -devices like the micro:bit. It's free software: creating, maintaining and -documenting MicroPython is the work of an international team of -volunteers. +MicroPython is a version of the popular Python programming language for devices like the micro:bit. It's free software: creating, maintaining and documenting MicroPython is the work of an international team of volunteers. There are many ways to use MicroPython on the micro:bit. You can use: 1. The browser based [Python Editor](https://python.microbit.org). 2. The offline [Mu editor](https://codewith.mu) -3. Your regular editor to create Python files and a suite of command line -tools to interact with the device (for advanced users only). +3. Your regular editor to create Python files and a suite of command line tools to interact with the device (for advanced users only). 5. One of the [third party editors](https://microbit.org/code/#other-editors) listed on the website. @@ -43,11 +39,9 @@ Finally, there are great [tutorials for MicroPython on the micro:bit](https://mi ## What is MicroPython? -MicroPython is just as easy to learn as the other programming languages but -differs from them in several important respects: +MicroPython is just as easy to learn as the other programming languages but differs from them in several important respects: -1. MicroPython is a complete reimplementation of Python 3. This includes advanced features not found in any of the other languages: basic data types (strings, -integers, floating point numbers, booleans), data structures (lists, dictionaries, sets), classes, exception handling, generators and list comprehensions. +1. MicroPython is a complete reimplementation of Python 3. This includes advanced features not found in any of the other languages: basic data types (strings, integers, floating point numbers, booleans), data structures (lists, dictionaries, sets), classes, exception handling, generators and list comprehensions. 2. MicroPython runs entirely on the micro:bit itself - no need for a compiler. @@ -55,125 +49,69 @@ integers, floating point numbers, booleans), data structures (lists, dictionarie 4. MicroPython comes with lots of exclusive features: a powerful music programming language, a speech synthesiser, built-in images and music, a local file system and a large range of ways to connect to attached devices: I2C, NeoPixel, SPI and UART. -v1 The Bluetooth stack is not enabled inside MicroPython because of memory -constraints. However MicroPython uses the Bluetooth radio hardware with its own -simple yet powerful `radio` module. The protocol for the `radio` module is a -lot more beginner friendly than Bluetooth yet allows users to create efficient -yet effective wireless networks of micro:bit devices. Conceptually it works in -the same way as walkie-talkies: anyone broadcasting on a certain channel can be -heard by anyone listening on the same channel (and there are a large selection -of channels to tune into). That's it! - -Finally, and perhaps most importantly, by learning MicroPython you're learning -how to use Python - one of the world's most popular professional programming -languages. You inadvertantly use Python *every day* when you use YouTube, -Google, Facebook, Instagram, DropBox and a plethora of other online services. +v1 The Bluetooth stack is not enabled inside MicroPython because of memory constraints. However MicroPython uses the Bluetooth radio hardware with its own simple yet powerful `radio` module. The protocol for the `radio` module is a lot more beginner friendly than Bluetooth yet allows users to create efficient yet effective wireless networks of micro:bit devices. Conceptually it works in the same way as walkie-talkies: anyone broadcasting on a certain channel can be heard by anyone listening on the same channel (and there are a large selection of channels to tune into). That's it! + +Finally, and perhaps most importantly, by learning MicroPython you're learning how to use Python - one of the world's most popular professional programming languages. You inadvertantly use Python *every day* when you use YouTube, Google, Facebook, Instagram, DropBox and a plethora of other online services. These skills are valuable: Python programmers are in demand. ### The MicroPython Software -MicroPython is itself written in C++. The MicroPython "runtime" is built using -a set of offline tools. The output from this build process is a `.hex` file -containing the complete MicroPython language. The editors described above -combine this file with your code to generate the file you copy onto the device. +MicroPython is itself written in C++. The MicroPython "runtime" is built using a set of offline tools. The output from this build process is a `.hex` file containing the complete MicroPython language. The editors described above combine this file with your code to generate the file you copy onto the device. -You can flash just the runtime .hex file onto any micro:bit by simply making -sure the editor based code is empty. +You can flash just the runtime .hex file onto any micro:bit by simply making sure the editor based code is empty. -When MicroPython is loaded to the micro:bit in this way, it obviously doesn't -have a user program associated with it. But, you can connect to your micro:bit -over the USB Serial port using a terminal program (or inside the Mu editor -press the REPL button to do the same). You can then have a live conversation -with MicroPython; for example if you type `display.show("Hello")`, the moment -that you press `RETURN` the message `"hello"` will scroll on the screen. +When MicroPython is loaded to the micro:bit in this way, it obviously doesn't have a user program associated with it. But, you can connect to your micro:bit over the USB Serial port using a terminal program (or inside the Mu editor press the REPL button to do the same). You can then have a live conversation with MicroPython; for example if you type `display.show("Hello")`, the moment that you press `RETURN` the message `"hello"` will scroll on the screen. -More interesting still, if the .hex file you copied onto the device *does* -contain some of your code, it's still possible to connect with the REPL and -interact with your program. This is very useful for debugging purposes. +More interesting still, if the .hex file you copied onto the device *does* contain some of your code, it's still possible to connect with the REPL and interact with your program. This is very useful for debugging purposes. ### Adding a User Application to MicroPython -Both the web hosted and the offline editor (Mu) have a copy of this MicroPython -.hex file inside them, as a plain text file. +Both the web hosted and the offline editor (Mu) have a copy of this MicroPython .hex file inside them, as a plain text file. -When you write your Python application, both the web hosted editor and the -offline editor Mu create a modified .hex file for you to copy to the micro:bit. +When you write your Python application, both the web hosted editor and the offline editor Mu create a modified .hex file for you to copy to the micro:bit. This modified file contains 3 things 1. An identical copy of the base MicroPython .hex code file; -2. A small header which marks a region as a MicroPython script (followed by the -length of the script in bytes); -3. A verbatim copy of your Python program, complete with comments and any -spaces. +2. A small header which marks a region as a MicroPython script (followed by the length of the script in bytes); +3. A verbatim copy of your Python program, complete with comments and any spaces. -As a result, Mu and the `uflash` command are able to retrieve your Python code -from .hex files (even if you forgot to save your source code). +As a result, Mu and the `uflash` command are able to retrieve your Python code from .hex files (even if you forgot to save your source code). When you flash (i.e. copy) a .hex file into the micro:bit it reboots. -MicroPython looks for your script in a special memory address. If it finds a -script it'll attempt to run it. Your program will run all the while there is -something to do, so it will keep going all the while your program loops around, -or until an error occurs (at which time the program will stop and scroll a -helpful error message on the device). +MicroPython looks for your script in a special memory address. If it finds a script it'll attempt to run it. Your program will run all the while there is something to do, so it will keep going all the while your program loops around, or until an error occurs (at which time the program will stop and scroll a helpful error message on the device). ### Is MicroPython Compiled or Interpreted? It's Both! Compilation is when code is turned into instructions the computer understands. -As a result, these instructions are evaluated very quickly. Interpretation is -when code is run by another (interpreting) program instead of directly on the -computer. Interpretation has the advantage of flexibility: it's possible to -interact with the interpreter while your program is running and change things. -This is, in fact, what you're doing when you live-code using the REPL. However, -due to the interpretation process interpreted code is slower than compiled -code. +As a result, these instructions are evaluated very quickly. Interpretation is when code is run by another (interpreting) program instead of directly on the computer. Interpretation has the advantage of flexibility: it's possible to interact with the interpreter while your program is running and change things. +This is, in fact, what you're doing when you live-code using the REPL. However, due to the interpretation process interpreted code is slower than compiled code. -MicroPython uses a combination of compilation and interpretation techniques -to run your program. Here's how: +MicroPython uses a combination of compilation and interpretation techniques to run your program. Here's how: -When MicroPython sees a script it parses each line of the script. The end -result is a set of in-memory tokens grouped in such a way that they represent -how your program works. This is called the *parse tree*. +When MicroPython sees a script it parses each line of the script. The end result is a set of in-memory tokens grouped in such a way that they represent how your program works. This is called the *parse tree*. -The parse tree is compiled into a terse set of instructions called Python -*bytecode*. Bytecode instructions are like CPU assembly language instructions, -but they are targeted for a *virtual machine*, not for a real piece of computer -hardware. +The parse tree is compiled into a terse set of instructions called Python *bytecode*. Bytecode instructions are like CPU assembly language instructions, but they are targeted for a *virtual machine*, not for a real piece of computer hardware. -The Python bytecode is given to the Python virtual machine to run and so your -program is executed. +The Python bytecode is given to the Python virtual machine to run and so your program is executed. All of the above happens in the blink of an eye. -The Python virtual machine built into MicroPython is itself compiled from C++ -code. It reads Python bytecodes and interprets them one at a time, -calling into lower level C++ functions to make each one perform -it's unique purpose. By using a bytecode interpreter, MicroPython -implements a virtual machine with it's own virtual instruction set. -It is virtual, because these instructions are not "baked in" to the -hardware, but they are implemented in software. This is what allows -MicroPython to be easily 'ported' onto different computer systems -with different processors. +The Python virtual machine built into MicroPython is itself compiled from C++ code. It reads Python bytecodes and interprets them one at a time, calling into lower level C++ functions to make each one perform it's unique purpose. By using a bytecode interpreter, MicroPython implements a virtual machine with it's own virtual instruction set. +It is virtual, because these instructions are not "baked in" to the hardware, but they are implemented in software. This is what allows MicroPython to be easily 'ported' onto different computer systems with different processors. ### Code Editors and Tools -The [Python in Education](http://pyedu.io/) website contains lots of -[micro:bit related resources](http://pythonineducation.org/en/microbit/) and -an online editor as well as general Python in education related resources. +The [Python in Education](http://pyedu.io/) website contains lots of [micro:bit related resources](http://pythonineducation.org/en/microbit/) and an online editor as well as general Python in education related resources. -You can [download Mu](http://codewith.mu/) from its website and also get -involved with [its development](https://github.com/mu-editor/). In addition, -the browser based editor is [open source and community maintained](https://github.com/bbcmicrobit/PythonEditor). +You can [download Mu](http://codewith.mu/) from its website and also get involved with [its development](https://github.com/mu-editor/). In addition, the browser based editor is [open source and community maintained](https://github.com/bbcmicrobit/PythonEditor). -A couple of Python modules provide code and command line commands for -[flashing your micro:bit](https://uflash.readthedocs.io/en/latest/) and -[interacting with the filesystem](https://microfs.readthedocs.io/en/latest/). +A couple of Python modules provide code and command line commands for [flashing your micro:bit](https://uflash.readthedocs.io/en/latest/) and [interacting with the filesystem](https://microfs.readthedocs.io/en/latest/). ### Community Contributions -Many people in the international Python community have contributed free-to-use -resources via the [MicroPython / BBC micro:bit World Tour](https://microworldtour.github.io/). +Many people in the international Python community have contributed free-to-use resources via the [MicroPython / BBC micro:bit World Tour](https://microworldtour.github.io/). [Online python simulator](https://create.withcode.uk/) @@ -187,8 +125,7 @@ resources via the [MicroPython / BBC micro:bit World Tour](https://microworldtou ### Documentation -Tutorials and API documentation for developers can be -[found here](https://microbit-micropython.readthedocs.io/en/latest/). +Tutorials and API documentation for developers can be [found here](https://microbit-micropython.readthedocs.io/en/latest/). ### Logging an Issue with the Development Team @@ -217,14 +154,11 @@ Tutorials and API documentation for developers can be ### Other Links -All development is covered by the Python Software Foundation's -[code of conduct](https://www.python.org/psf/codeofconduct/). +All development is covered by the Python Software Foundation's [code of conduct](https://www.python.org/psf/codeofconduct/). -The [Python Software Foundation](https://www.python.org/psf-landing/) -represents, supports and coordinates the wider Python community. +The [Python Software Foundation](https://www.python.org/psf-landing/) represents, supports and coordinates the wider Python community. -Learn how to [embed assembly language](http://docs.micropython.org/en/latest/pyboard/pyboard/tutorial/assembler.html) in -your Python scripts (this feature is enabled for MicroPython on the micro:bit). +Learn how to [embed assembly language](http://docs.micropython.org/en/latest/pyboard/pyboard/tutorial/assembler.html) in your Python scripts (this feature is enabled for MicroPython on the micro:bit). Pycomic's [micro:bit image maker](https://pycomic.github.io/microbit.html) allows you to create images to use in documentation. diff --git a/software/other-languages.md b/software/other-languages.md index 4c49ef1..8c21085 100644 --- a/software/other-languages.md +++ b/software/other-languages.md @@ -12,12 +12,9 @@ lang: en ## Overview -Aside from the officially supported editors: [Makecode](https://makecode.microbit.org) -and [Python](https://python.microbit.org) there are a number of different -languages that include support for the micro:bit. +Aside from the officially supported editors: [Makecode](https://makecode.microbit.org) and [Python](https://python.microbit.org) there are a number of different languages that include support for the micro:bit. -This resource aims to compile a list of these programming languages with a link -to the documentation, plus an example program. +This resource aims to compile a list of these programming languages with a link to the documentation, plus an example program. ## Submissions To add a new language to the page, [edit the page on Github](http://github.com/microbit-foundation/dev-docs/edit/master/software/other-languages.md). For a language to be accepted it's implementation must be complete enough to display a heart on the display! diff --git a/software/python-editor.md b/software/python-editor.md index e778434..878ef43 100644 --- a/software/python-editor.md +++ b/software/python-editor.md @@ -35,7 +35,7 @@ It is possible to use the Python Editor offline to generate, upload and download - [MakeCode Technical Docs](https://makecode.com/docs) for general development ### Community -There are a variety of ways to get involved and interact +There are a variety of ways to get involved and interact - Join the [micro:bit developer community on Slack](../../community/) - Raise a [Python Editor issue or feature request](https://github.com/bbcmicrobit/PythonEditor/issues) - Ask a question on the [MicroPython forum for micro:bit](https://forum.micropython.org/viewforum.php?f=17&sid=de047c3e944921889becbc00f02a918f) diff --git a/software/readout_hex.md b/software/readout_hex.md index 5826436..287a455 100644 --- a/software/readout_hex.md +++ b/software/readout_hex.md @@ -14,7 +14,7 @@ review-with: jonnya ## Overview -There may be occasions when you want to take a look at the programming that is running on the micro:bit or if you have misplaced the original program. +There may be occasions when you want to take a look at the programming that is running on the micro:bit or if you have misplaced the original program. ## uBitTool diff --git a/software/runtime.md b/software/runtime.md index e4e6b09..60ee720 100644 --- a/software/runtime.md +++ b/software/runtime.md @@ -66,7 +66,7 @@ Firstly, you should get yourself into a situation where you can build the micro: ### Asking for features and reporting bugs -If you would have a feature request, or would like to get involved in the micro:bit runtime development, visit the [list of open issues](https://github.com/lancaster-university/microbit-dal/issues) and raise a new issue if it isn't already in there. +If you would have a feature request, or would like to get involved in the micro:bit runtime development, visit the [list of open issues](https://github.com/lancaster-university/microbit-dal/issues) and raise a new issue if it isn't already in there. You can also join the [microbit developer community on Slack](/community) if you'd like to discuss the micro:bit runtime and its components. @@ -102,8 +102,7 @@ micro:bit was based on the well-established Mbed 2.0 SDK, with which mbed 5 is c ## Nordic nRF5 SDK -The Mbed abstraction for the Nordic chip is built on top of the Nordic nRF5 SDK -https://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF5-SDK +The Mbed abstraction for the Nordic chip is built on top of the Nordic nRF5 SDK https://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF5-SDK Crucially, this includes Nordic's [Soft Device 110](https://www.nordicsemi.com/Software-and-Tools/Software/S110) v1 / [Soft Device 140](https://www.nordicsemi.com/Software-and-tools/Software/S140) V2, a binary object that gets included into any hex file for the micro:bit that manages control of the radio to allow the micro:bit to use the industry standard Bluetooth Low Energy protocols. diff --git a/software/testing.md b/software/testing.md index 8414d23..a94c404 100644 --- a/software/testing.md +++ b/software/testing.md @@ -2,7 +2,7 @@ layout: page order: title: Beta testing -heading: Beta testing apps and Editors +heading: Beta testing apps and Editors description: How to access beta versions of the micro:bit editors and apps permalink: /software/beta/ ref: software