uBit.radio

Overview

The micro:bit V2's processor, the Nordic NRF52, is capable of radio communication via an on-board 2.4GHz communications module. uBit.radio provides a very easy way to communicate between multiple micro:bit boards.

A key principle of this component is privacy, which is built-in from the ground up. When you send data, there is nothing inherent in this protocol which can be used to identify you or your micro:bit. All devices look identical. Therefore, if you want to be able to identify yourself, you need to add this by yourself in your payloads.

Info

The primary function of the Nordic S113 SoftDevice is to provide a fully quantified Bluetooth Low Energy (BLE) stack. This allows for much more energy-efficient and secure communication between devices than uBit.radio.

Take a look at uBit.ble for more information on BLE functionality on the micro:bit V2.

Important

It is not currently possible to run the uBit.radio component and Bluetooth Low Energy (BLE) at the same time. If you want to use the uBit.radio functionality, you need to disable the BLE stack on your micro:bit by compiling the runtime with "MICROBIT_BLE_ENABLED": 0 in your codal.json file. See here for information on codal.json.

Using the radio

To write your radio enabled applications, you will likely want to use either the MicroBitRadioDatagram, or the MicroBitRadioEvent class.

Important

Before you use the radio, make sure to enable it with uBit.radio.enable().

Both of these are created for you as part of the standard uBit object, so this is a choice, not a compromise!

Sending datagrams

This is the most flexible way to use the radio, and lets you easily send and receive up to 32 bytes of data at a time. This data can be provided as array of bytes, a text string, or PacketBuffer.

You can send a packet at any time using the uBit.radio.datagram.send function.

Any other micro:bits in range will detect the transmitted packet, and make the packet available through the uBit.radio.datagram.recv function.

Any micro:bits receiving a datagram packet will also raise a MICROBIT_RADIO_EVT_DATAGRAM event to indicate that some data is ready to be read.

For example, imagine you were creating a simple remote control car with one micro:bit acting as a remote controller, and another connected to some servos on the car.

You might decide that simply sending a 1 means turn left, and a 2 means turn right, so you may write a program containing this for the remote control:

remotecontrol.cpp

    uBit.radio.enable();

    while(1)
    {
        if (uBit.buttonA.isPressed())
            uBit.radio.datagram.send("1");

        else if (uBit.buttonB.isPressed())
            uBit.radio.datagram.send("2");

        uBit.sleep(100);
    }

Then, you could set up a receiver handler on the car side, which takes advantage of the micro:bit's event system:

car.cpp

    void onData(Event e)
    {
        ManagedString s = uBit.radio.datagram.recv(); // Read what was in the buffer!

        if (s == "1")
        {
            uBit.io.P0.setServoValue(0);
            uBit.display.print("A");
        }

        if (s == "2")
        {
            uBit.io.P0.setServoValue(180);
            uBit.display.print("B");
        }
    }

    int main()
    {
        uBit.init();
        uBit.messageBus.listen(DEVICE_ID_RADIO, MICROBIT_RADIO_EVT_DATAGRAM, onData);
        uBit.radio.enable();

        while(1)
            uBit.sleep(1000);
    }

Note

The event used here is MICROBIT_RADIO_EVT_DATAGRAM, which is raised everytime the micro:bit receives a new datagram from somewhere else. For more information about events and handlers, have a look at the pages for Message Bus and Event.

You can also read more about how you can access exposed pins on the micro:bit on the uBit.IO page.

Sending PacketBuffers

If you prefer to send a raw series of bytes rather than a text string (which is much more common in communication networks), you can use the PacketBuffer type. This gives total freedom over the data being shared. Simply create a PacketBuffer of the size you need, and you can read or write data using standard C array syntax.

remotecontrol.cpp

uBit.radio.enable();

PacketBuffer b(1); // Create a packet containing just a single byte.

while(1)
{
    b[0] = 0;
    if (uBit.buttonA.isPressed())
        b[0] = 1;

    else if (uBit.buttonB.isPressed())
        b[0] = 2;

    uBit.radio.datagram.send(b);
    uBit.sleep(100);
}    

As before, you could now set up a receiver handler on the car side, which takes advantage of the micro:bit's event system:

car.cpp

void onData(MicroBitEvent e)
{
    PacketBuffer p = uBit.radio.datagram.recv();

    if (p[0] == 1)
    {
        uBit.io.P0.setServoValue(0);
        uBit.display.print("A");
    }

    if (p[0] == 2)
    {
        uBit.io.P0.setServoValue(180);
        uBit.display.print("B");
    }
}

int main()
{
    uBit.init();
    uBit.messageBus.listen(MICROBIT_ID_RADIO, MICROBIT_RADIO_EVT_DATAGRAM, onData);
    uBit.radio.enable();

    while(1)
        uBit.sleep(1000);
}

Using radio events

It is also possible to transparently send and receive events over the radio channel. This can provide very simple and easy to integrate support for event-driven applications. Once configured, an event raised on one micro:bit can be detected on another - in the just the same way as a local event such as a button click.

To use this functionality, all that is needed is to register the event codes that you would like to be sent over the radio, then write event handlers for the message bus as with all other events.

Note

See the documentation for uBit.messageBus for details of how to write event handlers.

For example, if you wanted to share an event called SOMETHING with another micro:bit whenever ButtonA is pressed, you might write code like this on the sending micro:bit:

event_sender.cpp

#define MY_APP_ID           4000
#define SOMETHING           1

int main()
{
    uBit.init();
    uBit.radio.enable();

    // Ensure the radio is listening out to forward our events
    uBit.radio.event.listen(MY_APP_ID, MICROBIT_EVT_ANY);

    while(1)
    {
        if (uBit.buttonA.isPressed())
            Event(MY_APP_ID, SOMETHING); // Send out our event!

        uBit.sleep(100);
    }
}

We can then write a handler that will be run on the other micro:bit when the radio receives your event (in this case, it scrolls a message on the display):

event_receiver.cpp

#define MY_APP_ID           4000
#define SOMETHING           1

void onSomething(Event e)
{
    uBit.display.scrollAsync("Something!");
}

int main()
{
    uBit.init();
    uBit.messageBus.listen(MY_APP_ID, SOMETHING, onSomething);
    uBit.radio.enable();

    while(1)
        uBit.sleep(1000);
}

Defining groups

It is easy to imagine situations where you would like to have different groups of micro:bits communicating independently.

For example, consider a classroom where 8 groups of four children are working on different projects - it would not be very useful if packets sent by one group interfered with the other groups!

To address this, uBit.radio allows users to define a group to which their micro:bit belongs.

Note

micro:bits can only ever be a member of one group at a time; any packets sent will only be received by other micro:bits in the same group.

Groups are simply numbers, and a micro:bit's group can be set at anytime by the programmer through the setGroup function. If a group is not specified, the default group of 0 will be used.

Example

int main()
{
    uBit.init();
    uBit.radio.setGroup(10);
}

Message Bus Info

Message Bus ID

Constant	Value
DEVICE_ID_RADIO	9
DEVICE_ID_RADIO_DATA_READY	10

Message Bus Events

Constant	Value
MICROBIT_RADIO_EVT_DATAGRAM	1

API

setTransmitPower

int

setTransmitPower

(

int

power)

Description

Change the output power level of the transmitter to the given value.

Parameters

int

power - a value in the range 0..7, where 0 is the lowest power and 7 is the highest.

Returns

MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER if the value is out of range.

---

setFrequencyBand

int

setFrequencyBand

(

int

band)

Description

Change the transmission and reception band of the radio to the given channel

Parameters

int

band - a frequency band in the range 0 - 100. Each step is 1MHz wide, based at 2400MHz.

Returns

MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER if the value is out of range, or MICROBIT_NOT_SUPPORTED if the BLE stack is running.

---

getRxBuf

FrameBuffer

getRxBuf

()

Description

Retrieve a pointer to the currently allocated receive buffer. This is the area of memory actively being used by the radio hardware to store incoming data.

Returns

a pointer to the current receive buffer.

---

queueRxBuf

int

queueRxBuf

()

Description

Attempt to queue a buffer received by the radio hardware, if sufficient space is available.

Returns

MICROBIT_OK on success, or MICROBIT_NO_RESOURCES if a replacement receiver buffer could not be allocated (either by policy or memory exhaustion).

---

setRSSI

int

setRSSI

(

int

rssi)

Description

Sets the RSSI for the most recent packet. The value is measured in -dbm. The higher the value, the stronger the signal. Typical values are in the range -42 to -128.

Parameters

int

rssi - the new rssi value.

Note

should only be called from RADIO_IRQHandler...

---

getRSSI

int

getRSSI

()

Description

Retrieves the current RSSI for the most recent packet. The return value is measured in -dbm. The higher the value, the stronger the signal. Typical values are in the range -42 to -128.

Returns

the most recent RSSI value or MICROBIT_NOT_SUPPORTED if the BLE stack is running.

---

enable

int

enable

()

Description

Initialises the radio for use as a multipoint sender/receiver

Returns

MICROBIT_OK on success, MICROBIT_NOT_SUPPORTED if the BLE stack is running.

---

disable

int

disable

()

Description

Disables the radio for use as a multipoint sender/receiver.

Returns

MICROBIT_OK on success, MICROBIT_NOT_SUPPORTED if the BLE stack is running.

---

setGroup

int

setGroup

(

uint8_t

group)

Description

Sets the radio to listen to packets sent with the given group id.

Parameters

uint8_t

group - The group to join. A micro:bit can only listen to one group ID at any time.

Returns

MICROBIT_OK on success, or MICROBIT_NOT_SUPPORTED if the BLE stack is running.

---

dataReady

int

dataReady

()

Description

Determines the number of packets ready to be processed.

Returns

The number of packets in the receive buffer.

---

recv

FrameBuffer

recv

()

Description

Retrieves the next packet from the receive buffer. If a data packet is available, then it will be returned immediately to the caller. This call will also dequeue the buffer.

Returns

The buffer containing the the packet. If no data is available, NULL is returned.

Note

Once recv() has been called, it is the callers responsibility to delete the buffer when appropriate.

---

send

int

send

(

FrameBuffer *

buffer)

Description

Transmits the given buffer onto the broadcast radio. The call will wait until the transmission of the packet has completed before returning.

Parameters

FrameBuffer *

buffer

Returns

MICROBIT_OK on success, or MICROBIT_NOT_SUPPORTED if the BLE stack is running.

---

Component Constructor

Advanced users only

Do not use this unless you really know what you're doing. It's usually best to use uBit.

MicroBitRadio()

Description

Constructor.

Initialise the MicroBitRadio .

Note

This class is demand activated, as a result most resources are only committed if send/recv or event registrations calls are made.

MicroBitRadio(

uint16_t

id)

Description

Constructor.

Initialise the MicroBitRadio .

Parameters

uint16_t

id

Note

This class is demand activated, as a result most resources are only committed if send/recv or event registrations calls are made.

---