This documentation is best viewed on the documentation site rather than GitHub or NPM package site.
This is a JavaScript library for micro:bit connections in browsers via USB and Bluetooth.
This project is a work in progress. We are extracting WebUSB and Web Bluetooth code from the micro:bit Python Editor and other projects. The API is not stable and it's not yet recommended that third parties use this project unless they are happy to update usage as the API evolves.
Demo page for this library.
Alpha releases are now on NPM.
micro:bit CreateAI is already using this library for WebUSB and Web Bluetooth.
This Python Editor PR tracks updating the micro:bit Python Editor to use this library.
Instantiate a WebUSB connection using createWebUSBConnection class and use it to connect to a micro:bit.
import { createWebUSBConnection } from "@microbit/microbit-connection";
const usb = createWebUSBConnection();
const connectionStatus = await usb.connect();
console.log("Connection status: ", connectionStatus);
Connection status is "CONNECTED" if connection succeeds.
Flash a universal hex that supports both V1 and V2:
import { createUniversalHexFlashDataSource } from "@microbit/microbit-connection";
await usb.flash(createUniversalHexFlashDataSource(universalHexString), {
partial: true,
progress: (percentage: number | undefined) => {
console.log(percentage);
},
});
This code will also work for non-universal hex files so is a good default for unknown hex files.
Alternatively, you can create and flash a hex for a specific micro:bit version by providing a function that takes a BoardVersion and returns a hex. This can reduce download size or help integrate with APIs that produce a hex for a particular device version. This example uses the @microbit/microbit-fs library which can return a hex based on board id.
import { MicropythonFsHex, microbitBoardId } from "@microbit/microbit-fs";
import { BoardId } from "@microbit/microbit-connection";
const micropythonFs = new MicropythonFsHex([
{ hex: microPythonV1HexFile, boardId: microbitBoardId.V1 },
{ hex: microPythonV2HexFile, boardId: microbitBoardId.V2 },
]);
// Add files to MicroPython file system here (omitted for simplicity)
// Flash the device
await usb.flash(
async (boardVersion) => {
const boardId = BoardId.forVersion(boardVersion).id;
return micropythonFs.getIntelHex(boardId);
},
{
partial: true,
progress: (percentage: number | undefined) => {
console.log(percentage);
},
},
);
For more examples of using other methods in the MicrobitWebUSBConnection class, see our demo code for our demo site.
By default, the micro:bit's Bluetooth service is not enabled. Visit our Bluetooth tech site page to download a hex file that would enable the bluetooth service.
Instantiate a Bluetooth connection using createWebBluetoothConnection class and use it to connect to a micro:bit.
import { createWebBluetoothConnection } from "@microbit/microbit-connection";
const bluetooth = createWebBluetoothConnection();
const connectionStatus = await bluetooth.connect();
console.log("Connection status: ", connectionStatus);
Connection status is "CONNECTED" if connection succeeds.
For more examples of using other methods in the createWebBluetoothConnection class, see our demo code for our demo site.
This software is under the MIT open source license.
We use dependencies via the NPM registry as specified by the package.json file under common Open Source licenses.
Full details of each package can be found by running license-checker:
$ npx license-checker --direct --summary --production
Omit the flags as desired to obtain more detail.
Trust, partnership, simplicity and passion are our core values we live and breathe in our daily work life and within our projects. Our open-source projects are no exception. We have an active community which spans the globe and we welcome and encourage participation and contributions to our projects by everyone. We work to foster a positive, open, inclusive and supportive environment and trust that our community respects the micro:bit code of conduct. Please see our code of conduct which outlines our expectations for all those that participate in our community and details on how to report any concerns and what would happen should breaches occur.