API.md

node-bbc-microbit API

1. Discovery
2. Connecting and disconnecting
3. Accelerometer
4. Buttons
5. Pin IO
6. LED Matrix
7. Magnetometer
8. Temperature
9. UART
10. Event

Require module

var BBCMicrobit = require('bbc-microbit');

Discovery

Single

BBCMicrobit.discover(callback(microbit));

All

function onDiscover(microbit) {
  // ...
}

BBCMicrobit.discoverAll(onDiscover);

BBCMicrobit.stopDiscoverAll(onDiscover);

By id

BBCMicrobit.discoverById(id, callback(microbit));

By address

BBCMicrobit.discoverByAddress(address, callback(microbit));

Properties:

microbit = {
  id: "<peripheral id>",
  address: "<BT address>"
};

Connecting and disconnecting

Connect and Set Up

microbit.connectAndSetUp(callback(error));

Disconnect

microbit.disconnect(callback);

Disconnect event

Add event listener for when micro:bit disconnects:

microbit.once('disconnect', callback);

Device Information

microbit.readDeviceName(callback(error, deviceName));

microbit.readModelNumber(callback(error, modelNumber));

microbit.readSerialNumber(callback(error, serialNumber));

microbit.readFirmwareRevision(callback(error, firmwareRevision));

Accelerometer

Units for x, y, and z is G's.

Data period

Read or write the period. Support values are: 1, 2, 5, 10, 20, 80, 160, or 640 ms.

microbit.readAccelerometerPeriod(callback(error, period));

microbit.writeAccelerometerPeriod(period, callback(error));

Read

microbit.readAccelerometer(callback(error, x, y, z));

Subscription

microbit.subscribeAccelerometer(callback(error));

microbit.unsubscribeAccelerometer(callback(error));

Event

microbit.on('accelerometerChange', function(x, y, z) {
  // ...
});

Buttons

Subscription

// for both buttons
microbit.subscribeButtons(callback(error));

microbit.unsubscribeButtons(callback(error));

// just button A
microbit.subscribeButtonA(callback(error));

microbit.unsubscribeButtonA(callback(error));

// just button B
microbit.subscribeButtonB(callback(error));

microbit.unsubscribeButtonB(callback(error));

Events

microbit.on('buttonAChange', function(value) {
  // ...
});

microbit.on('buttonBChange', function(value) {
  // ...
});

value interpretation:

• 0: not pressed
• 1: pressed
• 2: long press

Pin IO

pin must be between 0 and 20.

value must be between 0 and 255.

Configure modes

// AD mode
microbit.pinAnalog(pin, callback(error));

microbit.pinDigital(pin, callback(error));

// IO mode
microbit.pinInput(pin, callback(error));

microbit.pinOutput(pin, callback(error));

Read or write

microbit.readPin(pin, callback(error, value)); // pin must be configured as input

microbit.writePin(pin, value, callback(error)); // pin must be configured as output

Subscription

microbit.subscribePinData(callback(error));

microbit.unsubscribePinData(callback(error));

Event

microbit.on('pinDataChange', function(pin, value) {
  // ...
});

Advanced

// data is a Buffer with format: <pin> <value>, ...
microbit.readPinData(callback(error, data));

microbit.writePinData(data, callback(error));

// value is a buffer, n-bit of 0 means pin n is in digital mode, 1 means analog mode
microbit.readPinAdConfiguration(callback(error, value));

microbit.writePinAdConfiguration(value, callback(error));

// value is a buffer, n-bit of 0 means pin n  is in output mode, 1 means input mode
microbit.readPinIoConfiguration(callback(error, value));

microbit.writePinIoConfiguration(value, callback(error));

LED Matrix

Read/write raw data

value is a 5 byte Buffer. Each byte corresponds to a row, and column value is the n'th bit. 0 for off, 1 for on.

microbit.readLedMatrixState(callback(error, value));

microbit.writeLedMatrixState(value, callback(error));

Write text

text is a string that must be 20 characters or less

microbit.writeLedText(text, callback(error));

Text scrolling delay

delay is scrolling delay of text in ms.

microbit.readLedScrollingDelay(callback(error, delay));

microbit.writeLedScrollingDelay(delar, callback(error));

Magnetometer

Data period

Read or write the period. Support values are: 1, 2, 5, 10, 20, 80, 160, or 640 ms.

microbit.readMagnetometerPeriod(callback(error, period));

microbit.writeMagnetometerPeriod(period, callback(error));

Read

microbit.readMagnetometer(callback(error, x, y, z));

microbit.readMagnetometerBearing(callback(error, bearing));

Subscription

// x, y, and z values
microbit.subscribeMagnetometer(callback(error));

microbit.unsubscribeMagnetometer(callback(error));

// bearing
microbit.subscribeMagnetometerBearing(callback(error));

microbit.unsubscribeMagnetometerBearing(callback(error));

Event

microbit.on('magnetometerChange', function(x, y, z) {
  // ...
});

microbit.on('magnetometerBearingChange', function(bearing) {
  // ...
});

Temperature

Units for temperature is °C.

Data period

period is in ms.

microbit.readTemperaturePeriod(callback(error, period));

microbit.writeTemperaturePeriod(period, callback(error));

Read

microbit.readTemperature(callback(error, temperature));

Subscription

microbit.subscribeTemperature(callback(error));

microbit.unsubscribeTemperature(callback(error));

Event

microbit.on('temperatureChange', function(temperature) {
  // ...
});

UART

NOTE: UART service does nothing currently. It does not bridge the hardware serial pins to BLE!

data is a buffer.

Subscription

microbit.subscribeUart(callback(error));

microbit.unsubscribeUart(callback(error));

Event

microbit.on('uartData', function(data) {
  // ...
});

Write

microbit.writeUart(data, callback(error));

Event

Micro:bit Events

Events come in two varieties, reflected by the two corresponding characteristics:

Micro:bit Events emanate from the micro:bit and may be notified to the connected client.

Client Events emanate from the connected client and may be written to the connected micro:bit

Write event

microbit.writeEvent(id, value, callback);

Subscription

microbit.subscribeEvents(id, value, callback(error));

microbit.unsubscribeEvent(callback(error));

Event

microbit.on('event', function(id, value) {
  // ...
});