Interface MicrobitBluetoothConnection

A Bluetooth connection to a micro:bit device.

Events and methods rely on specific BLE services being present in the micro:bit's firmware. Which services are available depends on the firmware build for C++ and for a MakeCode program depends on the service blocks added from the Bluetooth extension.

The table below maps each event and method to the BLE service it requires. If a service is not present, the event will silently not fire (no error is raised) and methods that depend on it will throw.

Accelerometer Service

Button Service

  • buttonachanged, buttonbchanged events

Event Service

  • gesturechanged event — also requires the accelerometer hardware to be active; this happens automatically if the Accelerometer Service is present
  • buttonaaction, buttonbaction, buttonabaction events
  • logoaction event (V2 only)
  • microbitevent event
  • subscribeToEvent, sendEvent

IO Pin Service

LED Service

Magnetometer Service

Temperature Service

UART Service

interface MicrobitBluetoothConnection {
    status: ConnectionStatus;
    type: "bluetooth";
    addEventListener(
        type: "status",
        listener: (data: ConnectionStatusChange) => void,
    ): void;
    addEventListener(
        type: "backgrounderror",
        listener: (data: BackgroundErrorData) => void,
    ): void;
    addEventListener(type: "beforerequestdevice", listener: () => void): void;
    addEventListener(type: "afterrequestdevice", listener: () => void): void;
    addEventListener(type: "flash", listener: () => void): void;
    addEventListener(
        type: "accelerometerdatachanged",
        listener: (data: AccelerometerData) => void,
    ): void;
    addEventListener(
        type: "buttonachanged" | "buttonbchanged",
        listener: (data: ButtonData) => void,
    ): void;
    addEventListener(
        type: "magnetometerdatachanged",
        listener: (data: MagnetometerData) => void,
    ): void;
    addEventListener(
        type: "temperaturechanged",
        listener: (data: TemperatureData) => void,
    ): void;
    addEventListener(
        type: "pinchanged",
        listener: (data: PinData) => void,
    ): void;
    addEventListener(
        type: "gesturechanged",
        listener: (data: GestureData) => void,
    ): void;
    addEventListener(
        type: "buttonaaction" | "buttonbaction" | "buttonabaction",
        listener: (data: ButtonActionData) => void,
    ): void;
    addEventListener(
        type: "logoaction",
        listener: (data: ButtonActionData) => void,
    ): void;
    addEventListener(
        type: "microbitevent",
        listener: (data: MicrobitEventData) => void,
    ): void;
    addEventListener(
        type: "uartdata",
        listener: (data: UartData) => void,
    ): void;
    checkAvailability(): Promise<ConnectionAvailabilityStatus>;
    clearDevice(): void | Promise<void>;
    connect(options?: ConnectOptions): Promise<void>;
    disconnect(): Promise<void>;
    dispose(): void;
    flash(dataSource: FlashDataSource, options: FlashOptions): Promise<void>;
    getAccelerometerData(): Promise<AccelerometerData>;
    getAccelerometerPeriod(): Promise<number>;
    getAnalogPins(): Promise<number[]>;
    getBoardVersion(): BoardVersion;
    getInputPins(): Promise<number[]>;
    getLedMatrix(): Promise<LedMatrix>;
    getLedScrollingDelay(): Promise<number>;
    getMagnetometerBearing(): Promise<number>;
    getMagnetometerData(): Promise<MagnetometerData>;
    getMagnetometerPeriod(): Promise<number>;
    getTemperature(): Promise<number>;
    getTemperaturePeriod(): Promise<number>;
    initialize(): Promise<void>;
    readPins(): Promise<PinValue[]>;
    removeEventListener(
        type: "status",
        listener: (data: ConnectionStatusChange) => void,
    ): void;
    removeEventListener(
        type: "backgrounderror",
        listener: (data: BackgroundErrorData) => void,
    ): void;
    removeEventListener(
        type: "beforerequestdevice",
        listener: () => void,
    ): void;
    removeEventListener(type: "afterrequestdevice", listener: () => void): void;
    removeEventListener(type: "flash", listener: () => void): void;
    removeEventListener(
        type: "accelerometerdatachanged",
        listener: (data: AccelerometerData) => void,
    ): void;
    removeEventListener(
        type: "buttonachanged" | "buttonbchanged",
        listener: (data: ButtonData) => void,
    ): void;
    removeEventListener(
        type: "magnetometerdatachanged",
        listener: (data: MagnetometerData) => void,
    ): void;
    removeEventListener(
        type: "temperaturechanged",
        listener: (data: TemperatureData) => void,
    ): void;
    removeEventListener(
        type: "pinchanged",
        listener: (data: PinData) => void,
    ): void;
    removeEventListener(
        type: "gesturechanged",
        listener: (data: GestureData) => void,
    ): void;
    removeEventListener(
        type: "buttonaaction" | "buttonbaction" | "buttonabaction",
        listener: (data: ButtonActionData) => void,
    ): void;
    removeEventListener(
        type: "logoaction",
        listener: (data: ButtonActionData) => void,
    ): void;
    removeEventListener(
        type: "microbitevent",
        listener: (data: MicrobitEventData) => void,
    ): void;
    removeEventListener(
        type: "uartdata",
        listener: (data: UartData) => void,
    ): void;
    sendEvent(source: number, value: number): Promise<void>;
    setAccelerometerPeriod(value: number): Promise<void>;
    setAnalogPins(pins: number[]): Promise<void>;
    setInputPins(pins: number[]): Promise<void>;
    setLedMatrix(matrix: LedMatrix): Promise<void>;
    setLedScrollingDelay(delayInMillis: number): Promise<void>;
    setLedText(text: string): Promise<void>;
    setMagnetometerPeriod(value: number): Promise<void>;
    setNameFilter(name: string): void;
    setTemperaturePeriod(value: number): Promise<void>;
    subscribeToEvent(source: number, value: number): Promise<void>;
    triggerMagnetometerCalibration(): Promise<void>;
    uartWrite(data: Uint8Array): Promise<void>;
    writePinPwm(
        pin: number,
        options: { period: number; value: number },
    ): Promise<void>;
    writePins(data: PinValue[]): Promise<void>;
}

Hierarchy (View Summary)

Properties

status type

Methods

addEventListener checkAvailability clearDevice connect disconnect dispose flash getAccelerometerData getAccelerometerPeriod getAnalogPins getBoardVersion getInputPins getLedMatrix getLedScrollingDelay getMagnetometerBearing getMagnetometerData getMagnetometerPeriod getTemperature getTemperaturePeriod initialize readPins removeEventListener sendEvent setAccelerometerPeriod setAnalogPins setInputPins setLedMatrix setLedScrollingDelay setLedText setMagnetometerPeriod setNameFilter setTemperaturePeriod subscribeToEvent triggerMagnetometerCalibration uartWrite writePinPwm writePins

Properties

status

status: ConnectionStatus

Readonlytype

type: "bluetooth"

Methods

addEventListener

checkAvailability

clearDevice

connect

disconnect

dispose

flash

  • flash(dataSource: FlashDataSource, options: FlashOptions): Promise<void>

    Flash the micro:bit.

    Not all connection types support flashing. For example, radio bridge connections do not support flashing, and Bluetooth connections only support flashing on native platforms (not Web).

    Post-flash connection state differs by transport:

    • USB: The connection remains in ConnectionStatus.Connected state. USB connects to the micro:bit's interface chip (running DAPLink firmware), which is not affected by flashing the application processor, so the connection persists and serial communication is automatically reinitialised.

    • Bluetooth: The connection is always left in ConnectionStatus.Disconnected state. Bluetooth connects to the application processor directly, which reboots after flashing, so the connection is necessarily lost. Callers must call connect again after flashing.

    Parameters

    Returns Promise<void>

    Throws

    On flash failure. The error.code property indicates the failure type.

    Throws

    If data preparation fails.

getAccelerometerData

getAccelerometerPeriod

getAnalogPins

  • getAnalogPins(): Promise<number[]>

    Gets which pins are configured as analog. All other pins are digital (the default).

    Requires: IO Pin Service.

    Returns Promise<number[]>

    array of pin numbers (0-18) configured as analog.

    Throws

    with code not-connected if there is no connection.

getBoardVersion

getInputPins

  • getInputPins(): Promise<number[]>

    Gets which pins are configured as inputs. Input pins are monitored and their values reported via notifications. All other pins are outputs (the default).

    Requires: IO Pin Service.

    Returns Promise<number[]>

    array of pin numbers (0-18) configured as inputs.

    Throws

    with code not-connected if there is no connection.

getLedMatrix

getLedScrollingDelay

getMagnetometerBearing

getMagnetometerData

getMagnetometerPeriod

getTemperature

getTemperaturePeriod

  • getTemperaturePeriod(): Promise<number>

    Gets the micro:bit temperature sensor period.

    Requires: Temperature Service.

    Returns Promise<number>

    temperature period in milliseconds.

    Throws

    with code not-connected if there is no connection.

initialize

readPins

  • readPins(): Promise<PinValue[]>

    Reads current values of input pins. Unlike the pinchanged event (which only includes pins whose values changed), this returns every pin configured as an input, up to a firmware limit of 10 pins (lowest-numbered first).

    Requires: IO Pin Service.

    Returns Promise<PinValue[]>

    array of pin/value pairs.

    Throws

    with code not-connected if there is no connection.

removeEventListener

sendEvent

  • sendEvent(source: number, value: number): Promise<void>

    Send an event to the micro:bit's message bus.

    Requires: Event Service.

    Parameters

    • source: number

      Event source ID.

    • value: number

      Event value.

    Returns Promise<void>

    Throws

    with code not-connected if there is no connection.

setAccelerometerPeriod

  • setAccelerometerPeriod(value: number): Promise<void>

    Sets micro:bit accelerometer period.

    Requires: Accelerometer Service.

    Parameters

    • value: number

      The accelerometer period.

    Returns Promise<void>

    Throws

    with code not-connected if there is no connection.

setAnalogPins

  • setAnalogPins(pins: number[]): Promise<void>

    Sets which pins are configured as analog. All other pins become digital (the default).

    Requires: IO Pin Service.

    Parameters

    • pins: number[]

      array of pin numbers (0-18) to configure as analog.

    Returns Promise<void>

    Throws

    with code not-connected if there is no connection.

setInputPins

  • setInputPins(pins: number[]): Promise<void>

    Sets which pins are configured as inputs. Input pins are monitored and their values reported via notifications. All other pins become outputs (the default).

    Note: configuring a pin as input overrides any existing pin mode (e.g. touch sensing used by MakeCode "on pin pressed" blocks). The two cannot be used on the same pin simultaneously.

    Requires: IO Pin Service.

    Parameters

    • pins: number[]

      array of pin numbers (0-18) to configure as inputs.

    Returns Promise<void>

    Throws

    with code not-connected if there is no connection.

setLedMatrix

setLedScrollingDelay

  • setLedScrollingDelay(delayInMillis: number): Promise<void>

    Sets micro:bit LED scrolling delay.

    Requires: LED Service.

    Parameters

    • delayInMillis: number

      LED scrolling delay in milliseconds.

    Returns Promise<void>

    Throws

    with code not-connected if there is no connection.

setLedText

setMagnetometerPeriod

  • setMagnetometerPeriod(value: number): Promise<void>

    Sets micro:bit magnetometer period.

    Requires: Magnetometer Service.

    Parameters

    • value: number

      magnetometer period.

    Returns Promise<void>

    Throws

    with code not-connected if there is no connection.

setNameFilter

setTemperaturePeriod

  • setTemperaturePeriod(value: number): Promise<void>

    Sets the micro:bit temperature sensor period.

    Requires: Temperature Service.

    Parameters

    • value: number

      period in milliseconds.

    Returns Promise<void>

    Throws

    with code not-connected if there is no connection.

subscribeToEvent

  • subscribeToEvent(source: number, value: number): Promise<void>

    Register interest in a specific micro:bit message bus event. Tells the micro:bit to forward matching message bus traffic over BLE. Matching events are dispatched as microbitevent. Use 0 as the value to match all events from a source.

    For common message bus events, consider the higher-level alternatives: gesturechanged, buttonaaction, buttonbaction, buttonabaction.

    Requires: Event Service.

    Parameters

    • source: number

      Event source ID.

    • value: number

      Event value to match, or 0 for any.

    Returns Promise<void>

    Throws

    with code not-connected if there is no connection.

triggerMagnetometerCalibration

uartWrite

writePinPwm

  • writePinPwm(
        pin: number,
        options: { period: number; value: number },
    ): Promise<void>

    Sets PWM output on a pin.

    Requires: IO Pin Service.

    Parameters

    • pin: number

      Pin number (0-18).

    • options: { period: number; value: number }

      PWM configuration.

      • period: number

        Period in microseconds.

      • value: number

        Analog value (0-1024).

    Returns Promise<void>

    Throws

    with code not-connected if there is no connection.

writePins

Settings

Member Visibility

On This Page

Accelerometer ServiceButton ServiceEvent ServiceIO Pin ServiceLED ServiceMagnetometer ServiceTemperature ServiceUART Service
Properties
Methods