Microbug / MicroBitDAL_SB2_TEST

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of MicroBitDALImageRewrite by Joe Finney

inc/MicroBitMessageBus.h@1:3e0360107f98, 2015-04-16 (annotated)

Committer:
finneyj
Date:
Thu Apr 16 13:50:24 2015 +0000
Revision:
1:3e0360107f98
Child:
2:6597fe50dc94
Updates to include:; ;   - Asynchronous Scrolltext();   - First iteration of MessageBus implementation;   - Hardware configuration for SquareBoard protoype

Who changed what in which revision?

UserRevisionLine numberNew contents of line
finneyj 1:3e0360107f98 1 /**
finneyj 1:3e0360107f98 2 * Class definition for the MicroBitMessageBus.
finneyj 1:3e0360107f98 3 *
finneyj 1:3e0360107f98 4 * The MicroBitMessageBus is the common mechanism to deliver asynchronous events on the
finneyj 1:3e0360107f98 5 * MicroBit platform. It serves a number of purposes:
finneyj 1:3e0360107f98 6 *
finneyj 1:3e0360107f98 7 * 1) It provides an eventing abstraction that is independent of the underlying substrate.
finneyj 1:3e0360107f98 8 * 2) It provides a mechanism to decouple user code from trusted system code
finneyj 1:3e0360107f98 9 * i.e. the basis of a message passing nano kernel.
finneyj 1:3e0360107f98 10 * 3) It allows a common high level eventing abstraction across a range of hardware types.e.g. buttons, BLE...
finneyj 1:3e0360107f98 11 * 4) It provides a mechanims for extensibility - new devices added via I/O pins can have OO based
finneyj 1:3e0360107f98 12 drivers and communicate via the message bus with minima impact on user level languages.
finneyj 1:3e0360107f98 13 * 5) It allows for the possiblility of event / data aggregation, which in turn can save energy.
finneyj 1:3e0360107f98 14 * It has the following design principles:
finneyj 1:3e0360107f98 15 *
finneyj 1:3e0360107f98 16 * 1) Maintain a low RAM footprint where possible
finneyj 1:3e0360107f98 17 * 2) Make few assumptions about the underlying platform, but allow optimizations where possible.
finneyj 1:3e0360107f98 18 */
finneyj 1:3e0360107f98 19
finneyj 1:3e0360107f98 20 #ifndef MICROBIT_MESSAGE_BUS_H
finneyj 1:3e0360107f98 21 #define MICROBIT_MESSAGE_BUS_H
finneyj 1:3e0360107f98 22
finneyj 1:3e0360107f98 23 #include "mbed.h"
finneyj 1:3e0360107f98 24
finneyj 1:3e0360107f98 25 // Enumeration of core components.
finneyj 1:3e0360107f98 26 #define MICROBIT_CONTROL_BUS_ID 0
finneyj 1:3e0360107f98 27
finneyj 1:3e0360107f98 28 #define MICROBIT_BUS_ID_ANY 0
finneyj 1:3e0360107f98 29 #define MICROBIT_BUS_VALUE_ANY 0
finneyj 1:3e0360107f98 30
finneyj 1:3e0360107f98 31
finneyj 1:3e0360107f98 32
finneyj 1:3e0360107f98 33 struct MicroBitEvent
finneyj 1:3e0360107f98 34 {
finneyj 1:3e0360107f98 35 int source; // ID of the MicroBit Component that generated the event � e.g. MICROBIT_ID_LEFT_BUTTON.
finneyj 1:3e0360107f98 36 int value; // Component specific code indicating the cause of the event.
finneyj 1:3e0360107f98 37 int timestamp; // Time at which the event was generated. ms since power on?
finneyj 1:3e0360107f98 38 void *context; // context specfic data associated with the event.
finneyj 1:3e0360107f98 39 };
finneyj 1:3e0360107f98 40
finneyj 1:3e0360107f98 41 struct MicroBitListener
finneyj 1:3e0360107f98 42 {
finneyj 1:3e0360107f98 43 int id; // The ID of the component that this listener is interested in.
finneyj 1:3e0360107f98 44 int value; // Value this listener is interested in receiving.
finneyj 1:3e0360107f98 45 void (*cb)(MicroBitEvent *); // Callback function associated with this listener.
finneyj 1:3e0360107f98 46 MicroBitListener *next;
finneyj 1:3e0360107f98 47
finneyj 1:3e0360107f98 48 MicroBitListener(int id, int value, void (*messageBus)(MicroBitEvent *));
finneyj 1:3e0360107f98 49 };
finneyj 1:3e0360107f98 50
finneyj 1:3e0360107f98 51 struct MicroBitMessageBusCache
finneyj 1:3e0360107f98 52 {
finneyj 1:3e0360107f98 53 int seq;
finneyj 1:3e0360107f98 54 MicroBitListener *ptr;
finneyj 1:3e0360107f98 55 };
finneyj 1:3e0360107f98 56
finneyj 1:3e0360107f98 57
finneyj 1:3e0360107f98 58
finneyj 1:3e0360107f98 59 class MicroBitMessageBus
finneyj 1:3e0360107f98 60 {
finneyj 1:3e0360107f98 61 public:
finneyj 1:3e0360107f98 62
finneyj 1:3e0360107f98 63 /**
finneyj 1:3e0360107f98 64 * Constructor.
finneyj 1:3e0360107f98 65 * Anticipating only one MessageBus per device, as filtering is handled within the class.
finneyj 1:3e0360107f98 66 */
finneyj 1:3e0360107f98 67 MicroBitMessageBus();
finneyj 1:3e0360107f98 68
finneyj 1:3e0360107f98 69 /**
finneyj 1:3e0360107f98 70 * Send the given event to all regstered recipients.
finneyj 1:3e0360107f98 71 *
finneyj 1:3e0360107f98 72 * @param The event to send. This structure is assumed to be heap allocated, and will
finneyj 1:3e0360107f98 73 * be automatically freed once all recipients have been notified.
finneyj 1:3e0360107f98 74 */
finneyj 1:3e0360107f98 75 void send(MicroBitEvent *evt);
finneyj 1:3e0360107f98 76
finneyj 1:3e0360107f98 77 /**
finneyj 1:3e0360107f98 78 * Send the given event to all regstered recipients, using a cached entry to minimize lookups.
finneyj 1:3e0360107f98 79 * This is particularly useful for soptimizing ensors that frequently send to the same channel.
finneyj 1:3e0360107f98 80 *
finneyj 1:3e0360107f98 81 * @param evt The event to send. This structure is assumed to be heap allocated, and will
finneyj 1:3e0360107f98 82 * be automatically freed once all recipients have been notified.
finneyj 1:3e0360107f98 83 * @param c Cache entry to reduce lookups for commonly used channels.
finneyj 1:3e0360107f98 84 */
finneyj 1:3e0360107f98 85 void send(MicroBitEvent *evt, MicroBitMessageBusCache *c);
finneyj 1:3e0360107f98 86
finneyj 1:3e0360107f98 87 /**
finneyj 1:3e0360107f98 88 * Register a listener function.
finneyj 1:3e0360107f98 89 *
finneyj 1:3e0360107f98 90 * @param id The source of messages to listen for. Events sent from any other IDs will be filtered.
finneyj 1:3e0360107f98 91 * Use MICROBIT_ID_ANY to receive events from all components.
finneyj 1:3e0360107f98 92 *
finneyj 1:3e0360107f98 93 * @param value The value of messages to listen for. Events with any other values will be filtered.
finneyj 1:3e0360107f98 94 * Use MICROBIT_VALUE_ANY to receive events of any value.
finneyj 1:3e0360107f98 95 *
finneyj 1:3e0360107f98 96 * @param hander The function to call when an event is received.
finneyj 1:3e0360107f98 97 */
finneyj 1:3e0360107f98 98
finneyj 1:3e0360107f98 99 void listen(int id, int value, void (*handler)(MicroBitEvent *));
finneyj 1:3e0360107f98 100
finneyj 1:3e0360107f98 101 private:
finneyj 1:3e0360107f98 102 MicroBitListener *listeners; // Chain of active listeners.
finneyj 1:3e0360107f98 103 int seq; // Sequence number. Used to invalidate cache entries.
finneyj 1:3e0360107f98 104 };
finneyj 1:3e0360107f98 105
finneyj 1:3e0360107f98 106 #endif
finneyj 1:3e0360107f98 107
finneyj 1:3e0360107f98 108