uBit.radio.event

Overview

It is also possible to transparently send and receive events over the MicroBitRadio 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. See the documentation for the MicroBitMessageBus for details of how to write event handlers.

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

#define MY_APP_ID           4000
#define SOMETHING           1

int main()
{
    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())
            MicroBitEvent(MY_APP_ID, SOMETHING);

        uBit.sleep(1000);
    }
}

...and on the micro:bits wanting to receive the event:

#define MY_APP_ID           4000
#define SOMETHING           1

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

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

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

Message Bus ID

None.

Message Bus Events

None.

API

Constructor


MicroBitRadioEvent(
MicroBitRadio &
r)

Description

Constructor.

Creates an instance of MicroBitRadioEvent which offers the ability to extend the micro:bit's default EventModel to other micro:bits in the vicinity.

r

The underlying radio module used to send and receive data.

Parameters

MicroBitRadio &
r - The underlying radio module used to send and receive data.

listen


int
listen
(
uint16_t
id,
uint16_t
value)

Description

Associates the given event with the radio channel.

Once registered, all events matching the given registration sent to this micro:bit's default EventModel will be automatically retransmitted on the radio.

Parameters

uint16_t
id - The id of the event to register.

uint16_t
value - the value of the event to register.

Returns

MICROBIT_OK on success, or MICROBIT_NO_RESOURCES if no default EventModel is available.

Note

The wildcards MICROBIT_ID_ANY and MICROBIT_EVT_ANY can also be in place of the id and value fields.


int
listen
(
uint16_t
id,
uint16_t
value,
EventModel &
eventBus)

Description

Associates the given event with the radio channel.

Once registered, all events matching the given registration sent to the given EventModel will be automatically retransmitted on the radio.

Parameters

uint16_t
id - The id of the events to register.

uint16_t
value - the value of the event to register.

EventModel &
eventBus - The EventModel to listen for events on.

Returns

MICROBIT_OK on success.

Note

The wildcards MICROBIT_ID_ANY and MICROBIT_EVT_ANY can also be in place of the id and value fields.

ignore


int
ignore
(
uint16_t
id,
uint16_t
value)

Description

Disassociates the given event with the radio channel.

Parameters

uint16_t
id - The id of the events to deregister.

uint16_t
value - The value of the event to deregister.

Returns

MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER if the default message bus does not exist.

Note

MICROBIT_EVT_ANY can be used to deregister all event values matching the given id.


int
ignore
(
uint16_t
id,
uint16_t
value,
EventModel &
eventBus)

Description

Disassociates the given events with the radio channel.

Parameters

uint16_t
id - The id of the events to deregister.

uint16_t
value - The value of the event to deregister.

EventModel &
eventBus - The EventModel to deregister on.

Returns

MICROBIT_OK on success.

Note

MICROBIT_EVT_ANY can be used to deregister all event values matching the given id.

packetReceived


void
packetReceived
()

Description

Protocol handler callback. This is called when the radio receives a packet marked as using the event protocol.

This function process this packet, and fires the event contained inside onto the default EventModel .

eventReceived


void
eventReceived
(
MicroBitEvent
e)

Description

Event handler callback. This is called whenever an event is received matching one of those registered through the registerEvent() method described above. Upon receiving such an event, it is wrapped into a radio packet and transmitted to any other micro:bits in the same group.

Parameters

MicroBitEvent
e