Neil Johnson / microbit-ARMBand

Official Sheffield ARMBand micro:bit program

microbit/microbit-dal/source/drivers/MicroBitRadioEvent.cpp@0:b9164b348919, 2016-10-17 (annotated)

Committer:
MrBedfordVan
Date:
Mon Oct 17 12:41:20 2016 +0000
Revision:
0:b9164b348919
Official Sheffield ARMBand Micro:bit program

Who changed what in which revision?

UserRevisionLine numberNew contents of line
MrBedfordVan 0:b9164b348919 1 /*
MrBedfordVan 0:b9164b348919 2 The MIT License (MIT)
MrBedfordVan 0:b9164b348919 3
MrBedfordVan 0:b9164b348919 4 Copyright (c) 2016 British Broadcasting Corporation.
MrBedfordVan 0:b9164b348919 5 This software is provided by Lancaster University by arrangement with the BBC.
MrBedfordVan 0:b9164b348919 6
MrBedfordVan 0:b9164b348919 7 Permission is hereby granted, free of charge, to any person obtaining a
MrBedfordVan 0:b9164b348919 8 copy of this software and associated documentation files (the "Software"),
MrBedfordVan 0:b9164b348919 9 to deal in the Software without restriction, including without limitation
MrBedfordVan 0:b9164b348919 10 the rights to use, copy, modify, merge, publish, distribute, sublicense,
MrBedfordVan 0:b9164b348919 11 and/or sell copies of the Software, and to permit persons to whom the
MrBedfordVan 0:b9164b348919 12 Software is furnished to do so, subject to the following conditions:
MrBedfordVan 0:b9164b348919 13
MrBedfordVan 0:b9164b348919 14 The above copyright notice and this permission notice shall be included in
MrBedfordVan 0:b9164b348919 15 all copies or substantial portions of the Software.
MrBedfordVan 0:b9164b348919 16
MrBedfordVan 0:b9164b348919 17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
MrBedfordVan 0:b9164b348919 18 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
MrBedfordVan 0:b9164b348919 19 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
MrBedfordVan 0:b9164b348919 20 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
MrBedfordVan 0:b9164b348919 21 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
MrBedfordVan 0:b9164b348919 22 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
MrBedfordVan 0:b9164b348919 23 DEALINGS IN THE SOFTWARE.
MrBedfordVan 0:b9164b348919 24 */
MrBedfordVan 0:b9164b348919 25
MrBedfordVan 0:b9164b348919 26 #include "MicroBitConfig.h"
MrBedfordVan 0:b9164b348919 27 #include "MicroBitRadio.h"
MrBedfordVan 0:b9164b348919 28
MrBedfordVan 0:b9164b348919 29 /**
MrBedfordVan 0:b9164b348919 30 * Provides a simple broadcast radio abstraction, built upon the raw nrf51822 RADIO module.
MrBedfordVan 0:b9164b348919 31 *
MrBedfordVan 0:b9164b348919 32 * This class provides the ability to extend the micro:bit's default EventModel to other micro:bits in the vicinity,
MrBedfordVan 0:b9164b348919 33 * in a very similar way to the MicroBitEventService for BLE interfaces.
MrBedfordVan 0:b9164b348919 34 *
MrBedfordVan 0:b9164b348919 35 * It is envisaged that this would provide the basis for children to experiment with building their own, simple,
MrBedfordVan 0:b9164b348919 36 * custom asynchronous events and actions.
MrBedfordVan 0:b9164b348919 37 *
MrBedfordVan 0:b9164b348919 38 * @note This API does not contain any form of encryption, authentication or authorisation. Its purpose is solely for use as a
MrBedfordVan 0:b9164b348919 39 * teaching aid to demonstrate how simple communications operates, and to provide a sandpit through which learning can take place.
MrBedfordVan 0:b9164b348919 40 * For serious applications, BLE should be considered a substantially more secure alternative.
MrBedfordVan 0:b9164b348919 41 */
MrBedfordVan 0:b9164b348919 42
MrBedfordVan 0:b9164b348919 43 /**
MrBedfordVan 0:b9164b348919 44 * Constructor.
MrBedfordVan 0:b9164b348919 45 *
MrBedfordVan 0:b9164b348919 46 * Creates an instance of MicroBitRadioEvent which offers the ability to extend
MrBedfordVan 0:b9164b348919 47 * the micro:bit's default EventModel to other micro:bits in the vicinity.
MrBedfordVan 0:b9164b348919 48 *
MrBedfordVan 0:b9164b348919 49 * @param r The underlying radio module used to send and receive data.
MrBedfordVan 0:b9164b348919 50 */
MrBedfordVan 0:b9164b348919 51 MicroBitRadioEvent::MicroBitRadioEvent(MicroBitRadio &r) : radio(r)
MrBedfordVan 0:b9164b348919 52 {
MrBedfordVan 0:b9164b348919 53 this->suppressForwarding = false;
MrBedfordVan 0:b9164b348919 54 }
MrBedfordVan 0:b9164b348919 55
MrBedfordVan 0:b9164b348919 56 /**
MrBedfordVan 0:b9164b348919 57 * Associates the given event with the radio channel.
MrBedfordVan 0:b9164b348919 58 *
MrBedfordVan 0:b9164b348919 59 * Once registered, all events matching the given registration sent to this micro:bit's
MrBedfordVan 0:b9164b348919 60 * default EventModel will be automatically retransmitted on the radio.
MrBedfordVan 0:b9164b348919 61 *
MrBedfordVan 0:b9164b348919 62 * @param id The id of the event to register.
MrBedfordVan 0:b9164b348919 63 *
MrBedfordVan 0:b9164b348919 64 * @param value the value of the event to register.
MrBedfordVan 0:b9164b348919 65 *
MrBedfordVan 0:b9164b348919 66 * @return MICROBIT_OK on success, or MICROBIT_NO_RESOURCES if no default EventModel is available.
MrBedfordVan 0:b9164b348919 67 *
MrBedfordVan 0:b9164b348919 68 * @note The wildcards MICROBIT_ID_ANY and MICROBIT_EVT_ANY can also be in place of the
MrBedfordVan 0:b9164b348919 69 * id and value fields.
MrBedfordVan 0:b9164b348919 70 */
MrBedfordVan 0:b9164b348919 71 int MicroBitRadioEvent::listen(uint16_t id, uint16_t value)
MrBedfordVan 0:b9164b348919 72 {
MrBedfordVan 0:b9164b348919 73 if (EventModel::defaultEventBus)
MrBedfordVan 0:b9164b348919 74 return listen(id, value, *EventModel::defaultEventBus);
MrBedfordVan 0:b9164b348919 75
MrBedfordVan 0:b9164b348919 76 return MICROBIT_NO_RESOURCES;
MrBedfordVan 0:b9164b348919 77 }
MrBedfordVan 0:b9164b348919 78
MrBedfordVan 0:b9164b348919 79 /**
MrBedfordVan 0:b9164b348919 80 * Associates the given event with the radio channel.
MrBedfordVan 0:b9164b348919 81 *
MrBedfordVan 0:b9164b348919 82 * Once registered, all events matching the given registration sent to the given
MrBedfordVan 0:b9164b348919 83 * EventModel will be automatically retransmitted on the radio.
MrBedfordVan 0:b9164b348919 84 *
MrBedfordVan 0:b9164b348919 85 * @param id The id of the events to register.
MrBedfordVan 0:b9164b348919 86 *
MrBedfordVan 0:b9164b348919 87 * @param value the value of the event to register.
MrBedfordVan 0:b9164b348919 88 *
MrBedfordVan 0:b9164b348919 89 * @param eventBus The EventModel to listen for events on.
MrBedfordVan 0:b9164b348919 90 *
MrBedfordVan 0:b9164b348919 91 * @return MICROBIT_OK on success.
MrBedfordVan 0:b9164b348919 92 *
MrBedfordVan 0:b9164b348919 93 * @note The wildcards MICROBIT_ID_ANY and MICROBIT_EVT_ANY can also be in place of the
MrBedfordVan 0:b9164b348919 94 * id and value fields.
MrBedfordVan 0:b9164b348919 95 */
MrBedfordVan 0:b9164b348919 96 int MicroBitRadioEvent::listen(uint16_t id, uint16_t value, EventModel &eventBus)
MrBedfordVan 0:b9164b348919 97 {
MrBedfordVan 0:b9164b348919 98 return eventBus.listen(id, value, this, &MicroBitRadioEvent::eventReceived, MESSAGE_BUS_LISTENER_IMMEDIATE);
MrBedfordVan 0:b9164b348919 99 }
MrBedfordVan 0:b9164b348919 100
MrBedfordVan 0:b9164b348919 101 /**
MrBedfordVan 0:b9164b348919 102 * Disassociates the given event with the radio channel.
MrBedfordVan 0:b9164b348919 103 *
MrBedfordVan 0:b9164b348919 104 * @param id The id of the events to deregister.
MrBedfordVan 0:b9164b348919 105 *
MrBedfordVan 0:b9164b348919 106 * @param value The value of the event to deregister.
MrBedfordVan 0:b9164b348919 107 *
MrBedfordVan 0:b9164b348919 108 * @return MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER if the default message bus does not exist.
MrBedfordVan 0:b9164b348919 109 *
MrBedfordVan 0:b9164b348919 110 * @note MICROBIT_EVT_ANY can be used to deregister all event values matching the given id.
MrBedfordVan 0:b9164b348919 111 */
MrBedfordVan 0:b9164b348919 112 int MicroBitRadioEvent::ignore(uint16_t id, uint16_t value)
MrBedfordVan 0:b9164b348919 113 {
MrBedfordVan 0:b9164b348919 114 if (EventModel::defaultEventBus)
MrBedfordVan 0:b9164b348919 115 return ignore(id, value, *EventModel::defaultEventBus);
MrBedfordVan 0:b9164b348919 116
MrBedfordVan 0:b9164b348919 117 return MICROBIT_INVALID_PARAMETER;
MrBedfordVan 0:b9164b348919 118 }
MrBedfordVan 0:b9164b348919 119
MrBedfordVan 0:b9164b348919 120 /**
MrBedfordVan 0:b9164b348919 121 * Disassociates the given events with the radio channel.
MrBedfordVan 0:b9164b348919 122 *
MrBedfordVan 0:b9164b348919 123 * @param id The id of the events to deregister.
MrBedfordVan 0:b9164b348919 124 *
MrBedfordVan 0:b9164b348919 125 * @param value The value of the event to deregister.
MrBedfordVan 0:b9164b348919 126 *
MrBedfordVan 0:b9164b348919 127 * @param eventBus The EventModel to deregister on.
MrBedfordVan 0:b9164b348919 128 *
MrBedfordVan 0:b9164b348919 129 * @return MICROBIT_OK on success.
MrBedfordVan 0:b9164b348919 130 *
MrBedfordVan 0:b9164b348919 131 * @note MICROBIT_EVT_ANY can be used to deregister all event values matching the given id.
MrBedfordVan 0:b9164b348919 132 */
MrBedfordVan 0:b9164b348919 133 int MicroBitRadioEvent::ignore(uint16_t id, uint16_t value, EventModel &eventBus)
MrBedfordVan 0:b9164b348919 134 {
MrBedfordVan 0:b9164b348919 135 return eventBus.ignore(id, value, this, &MicroBitRadioEvent::eventReceived);
MrBedfordVan 0:b9164b348919 136 }
MrBedfordVan 0:b9164b348919 137
MrBedfordVan 0:b9164b348919 138
MrBedfordVan 0:b9164b348919 139 /**
MrBedfordVan 0:b9164b348919 140 * Protocol handler callback. This is called when the radio receives a packet marked as using the event protocol.
MrBedfordVan 0:b9164b348919 141 *
MrBedfordVan 0:b9164b348919 142 * This function process this packet, and fires the event contained inside onto the default EventModel.
MrBedfordVan 0:b9164b348919 143 */
MrBedfordVan 0:b9164b348919 144 void MicroBitRadioEvent::packetReceived()
MrBedfordVan 0:b9164b348919 145 {
MrBedfordVan 0:b9164b348919 146 FrameBuffer *p = radio.recv();
MrBedfordVan 0:b9164b348919 147 MicroBitEvent *e = (MicroBitEvent *) p->payload;
MrBedfordVan 0:b9164b348919 148
MrBedfordVan 0:b9164b348919 149 suppressForwarding = true;
MrBedfordVan 0:b9164b348919 150 e->fire();
MrBedfordVan 0:b9164b348919 151 suppressForwarding = false;
MrBedfordVan 0:b9164b348919 152
MrBedfordVan 0:b9164b348919 153 delete p;
MrBedfordVan 0:b9164b348919 154 }
MrBedfordVan 0:b9164b348919 155
MrBedfordVan 0:b9164b348919 156 /**
MrBedfordVan 0:b9164b348919 157 * Event handler callback. This is called whenever an event is received matching one of those registered through
MrBedfordVan 0:b9164b348919 158 * the registerEvent() method described above. Upon receiving such an event, it is wrapped into
MrBedfordVan 0:b9164b348919 159 * a radio packet and transmitted to any other micro:bits in the same group.
MrBedfordVan 0:b9164b348919 160 */
MrBedfordVan 0:b9164b348919 161 void MicroBitRadioEvent::eventReceived(MicroBitEvent e)
MrBedfordVan 0:b9164b348919 162 {
MrBedfordVan 0:b9164b348919 163 if(suppressForwarding)
MrBedfordVan 0:b9164b348919 164 return;
MrBedfordVan 0:b9164b348919 165
MrBedfordVan 0:b9164b348919 166 FrameBuffer buf;
MrBedfordVan 0:b9164b348919 167
MrBedfordVan 0:b9164b348919 168 buf.length = sizeof(MicroBitEvent) + MICROBIT_RADIO_HEADER_SIZE - 1;
MrBedfordVan 0:b9164b348919 169 buf.version = 1;
MrBedfordVan 0:b9164b348919 170 buf.group = 0;
MrBedfordVan 0:b9164b348919 171 buf.protocol = MICROBIT_RADIO_PROTOCOL_EVENTBUS;
MrBedfordVan 0:b9164b348919 172 memcpy(buf.payload, (const uint8_t *)&e, sizeof(MicroBitEvent));
MrBedfordVan 0:b9164b348919 173
MrBedfordVan 0:b9164b348919 174 radio.send(&buf);
MrBedfordVan 0:b9164b348919 175 }