mbed.org local branch of microbit-dal. The real version lives in git at https://github.com/lancaster-university/microbit-dal

Dependencies:   BLE_API nRF51822 mbed-dev-bin

Dependents:   microbit Microbit IoTChallenge1 microbit ... more

Embed: (wiki syntax)

« Back to documentation index

MicroBitMessageBus Class Reference

Class definition for the MicroBitMessageBus. More...

#include <MicroBitMessageBus.h>

Inherits EventModel, and MicroBitComponent.

Public Member Functions

 MicroBitMessageBus ()
 Default constructor.
virtual int send (MicroBitEvent evt)
 Queues the given event to be sent to all registered recipients.
int process (MicroBitEvent &evt, bool urgent=false)
 Internal function, used to deliver the given event to all relevant recipients.
virtual MicroBitListenerelementAt (int n)
 Returns the microBitListener with the given position in our list.
 ~MicroBitMessageBus ()
 Destructor for MicroBitMessageBus, where we deregister this instance from the array of fiber components.
virtual int add (MicroBitListener *newListener)
 Add the given MicroBitListener to the list of event handlers, unconditionally.
virtual int remove (MicroBitListener *newListener)
 Remove the given MicroBitListener from the list of event handlers.
int listen (int id, int value, void(*handler)(MicroBitEvent), uint16_t flags=EVENT_LISTENER_DEFAULT_FLAGS)
 Register a listener function.
int listen (int id, int value, void(*handler)(MicroBitEvent, void *), void *arg, uint16_t flags=EVENT_LISTENER_DEFAULT_FLAGS)
 Register a listener function.
template<typename T >
int listen (uint16_t id, uint16_t value, T *object, void(T::*handler)(MicroBitEvent), uint16_t flags=EVENT_LISTENER_DEFAULT_FLAGS)
 Register a listener function.
int ignore (int id, int value, void(*handler)(MicroBitEvent))
 Unregister a listener function.
int ignore (int id, int value, void(*handler)(MicroBitEvent, void *))
 Unregister a listener function.
template<typename T >
int ignore (uint16_t id, uint16_t value, T *object, void(T::*handler)(MicroBitEvent))
 Unregister a listener function.
virtual void systemTick ()
 The system timer will call this member function once the component has been added to the array of system components using system_timer_add_component.

Static Public Member Functions

static int setDefaultEventModel (EventModel &model)
 Define the default EventModel to use for events raised and consumed by the microbit-dal runtime.

Static Public Attributes

static EventModeldefaultEventBus = NULL
 Class definition for a MicroBitEvent.

Detailed Description

Class definition for the MicroBitMessageBus.

The MicroBitMessageBus is the common mechanism to deliver asynchronous events on the MicroBit platform. It serves a number of purposes:

1) It provides an eventing abstraction that is independent of the underlying substrate.

2) It provides a mechanism to decouple user code from trusted system code i.e. the basis of a message passing nano kernel.

3) It allows a common high level eventing abstraction across a range of hardware types.e.g. buttons, BLE...

4) It provides a mechanim for extensibility - new devices added via I/O pins can have OO based drivers and communicate via the message bus with minima impact on user level languages.

5) It allows for the possiblility of event / data aggregation, which in turn can save energy.

It has the following design principles:

1) Maintain a low RAM footprint where possible

2) Make few assumptions about the underlying platform, but allow optimizations where possible.

Definition at line 60 of file MicroBitMessageBus.h.


Constructor & Destructor Documentation

Default constructor.

Class definition for the MicroBitMessageBus.

Adds itself as a fiber component, and also configures itself to be the default EventModel if defaultEventBus is NULL.

The MicroBitMessageBus is the common mechanism to deliver asynchronous events on the MicroBit platform. It serves a number of purposes:

1) It provides an eventing abstraction that is independent of the underlying substrate.

2) It provides a mechanism to decouple user code from trusted system code i.e. the basis of a message passing nano kernel.

3) It allows a common high level eventing abstraction across a range of hardware types.e.g. buttons, BLE...

4) It provides a mechanim for extensibility - new devices added via I/O pins can have OO based drivers and communicate via the message bus with minima impact on user level languages.

5) It allows for the possiblility of event / data aggregation, which in turn can save energy.

It has the following design principles:

1) Maintain a low RAM footprint where possible

2) Make few assumptions about the underlying platform, but allow optimizations where possible. Default constructor.

Adds itself as a fiber component, and also configures itself to be the default EventModel if defaultEventBus is NULL.

Definition at line 61 of file MicroBitMessageBus.cpp.

Destructor for MicroBitMessageBus, where we deregister this instance from the array of fiber components.

Definition at line 546 of file MicroBitMessageBus.cpp.


Member Function Documentation

int add ( MicroBitListener newListener ) [virtual]

Add the given MicroBitListener to the list of event handlers, unconditionally.

Parameters:
listenerThe MicroBitListener to add.
Returns:
MICROBIT_OK if the listener is valid, MICROBIT_INVALID_PARAMETER otherwise.

Reimplemented from EventModel.

Definition at line 392 of file MicroBitMessageBus.cpp.

MicroBitListener * elementAt ( int  n ) [virtual]

Returns the microBitListener with the given position in our list.

Parameters:
nThe position in the list to return.
Returns:
the MicroBitListener at postion n in the list, or NULL if the position is invalid.

Reimplemented from EventModel.

Definition at line 527 of file MicroBitMessageBus.cpp.

int ignore ( int  id,
int  value,
void(*)(MicroBitEvent handler 
) [inherited]

Unregister a listener function.

Listeners are identified by the Event ID, Event value and handler registered using listen().

Parameters:
idThe Event ID used to register the listener.
valueThe Event value used to register the listener.
handlerThe function used to register the listener.
Returns:
MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler given is NULL.

Example:

 void onButtonBClick(MicroBitEvent)
 {
    //do something
 }

 uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);

 // the previously created listener is now ignored.
 uBit.messageBus.ignore(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);

Definition at line 283 of file EventModel.h.

int ignore ( int  id,
int  value,
void(*)(MicroBitEvent, void *)  handler 
) [inherited]

Unregister a listener function.

Listeners are identified by the Event ID, Event value and handler registered using listen().

Parameters:
idThe Event ID used to register the listener.
valueThe Event value used to register the listener.
handlerThe function used to register the listener.
Returns:
MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler given is NULL.

Example:

 void onButtonBClick(MicroBitEvent, void* data)
 {
    //do something
 }

 uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);

 // the previously created listener is now ignored.
 uBit.messageBus.ignore(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);

Definition at line 318 of file EventModel.h.

int ignore ( uint16_t  id,
uint16_t  value,
T *  object,
void(T::*)(MicroBitEvent handler 
) [inherited]

Unregister a listener function.

Listners are identified by the Event ID, Event value and handler registered using listen().

Parameters:
idThe Event ID used to register the listener.
valueThe Event value used to register the listener.
handlerThe function used to register the listener.
Returns:
MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler or object pointers are NULL.

Example:

 void SomeClass::onButtonBClick()
 {
    //do something
 }

 SomeClass s = new SomeClass();
 uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick);

 // the previously created listener is now ignored.
 uBit.messageBus.ignore(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick);

Definition at line 419 of file EventModel.h.

int listen ( int  id,
int  value,
void(*)(MicroBitEvent, void *)  handler,
void *  arg,
uint16_t  flags = EVENT_LISTENER_DEFAULT_FLAGS 
) [inherited]

Register a listener function.

An EventModel implementing this interface may optionally choose to override this method, if that EventModel supports asynchronous callbacks to user code, but there is no requirement to do so.

Parameters:
idThe source of messages to listen for. Events sent from any other IDs will be filtered. Use MICROBIT_ID_ANY to receive events from all components.
valueThe value of messages to listen for. Events with any other values will be filtered. Use MICROBIT_EVT_ANY to receive events of any value.
handlerThe function to call when an event is received.
argProvide the callback with in an additional argument.
flagsUser specified, implementation specific flags, that allow behaviour of this events listener to be tuned.
Returns:
MICROBIT_OK on success, or any valid error code defined in "ErrNo.h". The default implementation simply returns MICROBIT_NOT_SUPPORTED.
 void onButtonBClicked(MicroBitEvent, void* data)
 {
    //do something
 }

 // call onButtonBClicked when ever a click event from buttonB is detected.
 uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);

Definition at line 212 of file EventModel.h.

int listen ( uint16_t  id,
uint16_t  value,
T *  object,
void(T::*)(MicroBitEvent handler,
uint16_t  flags = EVENT_LISTENER_DEFAULT_FLAGS 
) [inherited]

Register a listener function.

A registration function to allow C++ member functions (methods) to be registered as an event listener.

Parameters:
idThe source of messages to listen for. Events sent from any other IDs will be filtered. Use MICROBIT_ID_ANY to receive events from all components.
valueThe value of messages to listen for. Events with any other values will be filtered. Use MICROBIT_EVT_ANY to receive events of any value.
handerThe function to call when an event is received.
flagsUser specified, implementation specific flags, that allow behaviour of this events listener to be tuned.
Returns:
MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler or object pointers are NULL.
 void SomeClass::onButtonBClicked(MicroBitEvent)
 {
    //do something
 }

 SomeClass s = new SomeClass();

 uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick);
Parameters:
idThe source of messages to listen for. Events sent from any other IDs will be filtered. Use MICROBIT_ID_ANY to receive events from all components.
valueThe value of messages to listen for. Events with any other values will be filtered. Use MICROBIT_EVT_ANY to receive events of any value.
objectThe object on which the method should be invoked.
handlerThe method to call when an event is received.
Returns:
MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler or object pointers are NULL.

Definition at line 378 of file EventModel.h.

int listen ( int  id,
int  value,
void(*)(MicroBitEvent handler,
uint16_t  flags = EVENT_LISTENER_DEFAULT_FLAGS 
) [inherited]

Register a listener function.

An EventModel implementing this interface may optionally choose to override this method, if that EventModel supports asynchronous callbacks to user code, but there is no requirement to do so.

Parameters:
idThe source of messages to listen for. Events sent from any other IDs will be filtered. Use MICROBIT_ID_ANY to receive events from all components.
valueThe value of messages to listen for. Events with any other values will be filtered. Use MICROBIT_EVT_ANY to receive events of any value.
handlerThe function to call when an event is received.
flagsUser specified, implementation specific flags, that allow behaviour of this events listener to be tuned.
Returns:
MICROBIT_OK on success, or any valid error code defined in "ErrNo.h". The default implementation simply returns MICROBIT_NOT_SUPPORTED.
 void onButtonBClicked(MicroBitEvent)
 {
    //do something
 }

 // call onButtonBClicked when ever a click event from buttonB is detected.
 uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);

Definition at line 164 of file EventModel.h.

int process ( MicroBitEvent evt,
bool  urgent = false 
)

Internal function, used to deliver the given event to all relevant recipients.

Normally, this is called once an event has been removed from the event queue.

Parameters:
evtThe event to send.
urgentThe type of listeners to process (optional). If set to true, only listeners defined as urgent and non-blocking will be processed otherwise, all other (standard) listeners will be processed. Defaults to false.
Returns:
1 if all matching listeners were processed, 0 if further processing is required.
Note:
It is recommended that all external code uses the send() function instead of this function, or the constructors provided by MicrobitEvent.

Definition at line 340 of file MicroBitMessageBus.cpp.

int remove ( MicroBitListener listener ) [virtual]

Remove the given MicroBitListener from the list of event handlers.

Parameters:
listenerThe MicroBitListener to remove.
Returns:
MICROBIT_OK if the listener is valid, MICROBIT_INVALID_PARAMETER otherwise.

Reimplemented from EventModel.

Definition at line 483 of file MicroBitMessageBus.cpp.

int send ( MicroBitEvent  evt ) [virtual]

Queues the given event to be sent to all registered recipients.

Parameters:
evtThe event to send.
 MicroBitMessageBus bus;

 // Creates and sends the MicroBitEvent using bus.
 MicrobitEvent evt(MICROBIT_ID_BUTTON_A, MICROBIT_BUTTON_EVT_CLICK);

 // Creates the MicrobitEvent, but delays the sending of that event.
 MicrobitEvent evt1(MICROBIT_ID_BUTTON_A, MICROBIT_BUTTON_EVT_CLICK, CREATE_ONLY);

 bus.send(evt1);

 // This has the same effect!
 evt1.fire()

Reimplemented from EventModel.

Definition at line 317 of file MicroBitMessageBus.cpp.

static int setDefaultEventModel ( EventModel model ) [static, inherited]

Define the default EventModel to use for events raised and consumed by the microbit-dal runtime.

The default EventModel may be changed at any time.

Parameters:
modelA new instance of an EventModel to use as the default.
Returns:
MICROBIT_OK on success.

Example:

Definition at line 127 of file EventModel.h.

virtual void systemTick (  ) [virtual, inherited]

The system timer will call this member function once the component has been added to the array of system components using system_timer_add_component.

This callback will be in interrupt context.

Reimplemented in MicroBitSystemTimerCallback, MicroBitButton, and MicroBitDisplay.

Definition at line 125 of file MicroBitComponent.h.


Field Documentation

EventModel * defaultEventBus = NULL [static, inherited]

Class definition for a MicroBitEvent.

It represents a common event that is generated by the various components on the micro:bit.

Definition at line 58 of file EventModel.h.