diff --git a/inc/MESEvents.h b/inc/MESEvents.h index 641429e..44d5554 100644 --- a/inc/MESEvents.h +++ b/inc/MESEvents.h @@ -68,4 +68,27 @@ #define MES_DEVICE_INCOMING_MESSAGE 8 +#define MES_DPAD_CONTROLLER_ID 1104 +#define MES_DPAD_BUTTON_A_DOWN 1 +#define MES_DPAD_BUTTON_A_UP 2 +#define MES_DPAD_BUTTON_B_DOWN 3 +#define MES_DPAD_BUTTON_B_UP 4 +#define MES_DPAD_BUTTON_C_DOWN 5 +#define MES_DPAD_BUTTON_C_UP 6 +#define MES_DPAD_BUTTON_D_DOWN 7 +#define MES_DPAD_BUTTON_D_UP 8 +#define MES_DPAD_BUTTON_1_DOWN 9 +#define MES_DPAD_BUTTON_1_UP 10 +#define MES_DPAD_BUTTON_2_DOWN 11 +#define MES_DPAD_BUTTON_2_UP 12 +#define MES_DPAD_BUTTON_3_DOWN 13 +#define MES_DPAD_BUTTON_3_UP 14 +#define MES_DPAD_BUTTON_4_DOWN 15 +#define MES_DPAD_BUTTON_4_UP 16 + +// +// Events that typically use radio broadcast: +// +#define MES_BROADCAST_GENERAL_ID 2000 + #endif diff --git a/inc/MicroBit.h b/inc/MicroBit.h index f800bad..903c976 100644 --- a/inc/MicroBit.h +++ b/inc/MicroBit.h @@ -35,6 +35,7 @@ #include "MicroBitMessageBus.h" #include "MicroBitBLEManager.h" +#include "MicroBitRadio.h" // MicroBit::flags values #define MICROBIT_FLAG_SCHEDULER_RUNNING 0x00000001 @@ -108,6 +109,7 @@ class MicroBit // Bluetooth related member variables. MicroBitBLEManager bleManager; + MicroBitRadio radio; BLEDevice *ble; /** diff --git a/inc/MicroBitBLEManager.h b/inc/MicroBitBLEManager.h index 3a897a9..8bac02b 100644 --- a/inc/MicroBitBLEManager.h +++ b/inc/MicroBitBLEManager.h @@ -39,6 +39,11 @@ #define MICROBIT_BLE_PAIR_SUCCESSFUL 0x08 #define MICROBIT_BLE_PAIRING_TIMEOUT 90 +#define MICROBIT_BLE_POWER_LEVELS 8 +#define MICROBIT_BLE_MAXIMUM_BONDS 4 +#define MICROBIT_BLE_ENABLE_BONDING true +#define MICROBIT_BLE_REQUIRE_MITM true +extern const int8_t MICROBIT_BLE_POWER_LEVEL[]; /** * Class definition for the MicroBitBLEManager. diff --git a/inc/MicroBitComponent.h b/inc/MicroBitComponent.h index bbac2bd..650b66a 100644 --- a/inc/MicroBitComponent.h +++ b/inc/MicroBitComponent.h @@ -44,6 +44,8 @@ #define MICROBIT_ID_GESTURE 27 // Gesture events #define MICROBIT_ID_THERMOMETER 28 +#define MICROBIT_ID_RADIO 29 +#define MICROBIT_ID_RADIO_DATA_READY 30 #define MICROBIT_ID_NOTIFY 1023 // Notfication channel, for general purpose synchronisation #define MICROBIT_ID_NOTIFY_ONE 1022 // Notfication channel, for general purpose synchronisation diff --git a/inc/MicroBitRadio.h b/inc/MicroBitRadio.h new file mode 100644 index 0000000..d34263f --- /dev/null +++ b/inc/MicroBitRadio.h @@ -0,0 +1,174 @@ +#ifndef MICROBIT_RADIO_H +#define MICROBIT_RADIO_H + +#include "mbed.h" + +/** + * Provides a simple broadcast radio abstraction, built upon the raw nrf51822 RADIO module. + * + * The nrf51822 RADIO module supports a number of proprietary modes of operation in addition to the typical BLE usage. + * This class uses one of these modes to enable simple, point to multipoint communication directly between micro:bits. + * + * TODO: The protocols implemented here do not currently perform any significant form of energy management, + * which means that they will consume far more energy than their BLE equivalent. Later versions of the protocol + * should look to address this through energy efficient broadcast techniques / sleep scheduling. In particular, the GLOSSY + * approach to efficienct rebroadcast and network synchronisation would likely provide an effective future step. + * + * TODO: Meshing should also be considered - again a GLOSSY approach may be effective here, and highly complementary to + * the master/slave arachitecture of BLE. + * + * TODO: This implementation only operates whilst the BLE stack is disabled. The nrf51822 provides a timeslot API to allow + * BLE to cohabit with other protocols. Future work to allow this colocation would be benefical, and would also allow for the + * creation of wireless BLE bridges. + * + * NOTE: This API does not contain any form of encryption, authentication or authorization. It's purpose is solely for use as a + * teaching aid to demonstrate how simple communications operates, and to provide a sandpit through which learning can take place. + * For serious applications, BLE should be considered a substantially more secure alternative. + */ + +// Status Flags +#define MICROBIT_RADIO_STATUS_INITIALISED 0x0001 + +// Default configuration values +#define MICROBIT_RADIO_BASE_ADDRESS 0x75626974 +#define MICROBIT_RADIO_DEFAULT_GROUP 0 +#define MICROBIT_RADIO_DEFAULT_TX_POWER 6 +#define MICROBIT_RADIO_DEFAULT_FREQUENCY 7 +#define MICROBIT_RADIO_MAX_PACKET_SIZE 32 +#define MICROBIT_RADIO_HEADER_SIZE 4 +#define MICROBIT_RADIO_MAXIMUM_RX_BUFFERS 4 + +// Known Protocol Numbers +#define MICROBIT_RADIO_PROTOCOL_DATAGRAM 1 // A simple, single frame datagram. a little like UDP but with smaller packets. :-) +#define MICROBIT_RADIO_PROTOCOL_EVENTBUS 2 // Transparent propogation of events from one micro:bit to another. + +// Events +#define MICROBIT_RADIO_EVT_DATAGRAM 1 // Event to signal that a new datagram has been received. + +struct PacketBuffer +{ + uint8_t length; // The length of the remaining bytes in the packet. includes protocol/version/group fields, excluding the length field itself. + uint8_t version; // Protocol version code. + uint8_t group; // ID of the group to which this packet belongs. + uint8_t protocol; // Inner protocol number c.f. those issued by IANA for IP protocols + + uint8_t payload[MICROBIT_RADIO_MAX_PACKET_SIZE]; // User / higher layer protocol data + PacketBuffer *next; // Linkage, to allow this and other protocols to queue packets pending processing. +}; + +#include "MicroBitRadioDatagram.h" +#include "MicroBitRadioEvent.h" + +class MicroBitRadio : MicroBitComponent +{ + uint8_t group; // The radio group to which this micro:bit belongs. + uint8_t queueDepth; // The number of packets in the receiver queue. + PacketBuffer *rxQueue; // A linear list of incoming packets, queued awaiting processing. + PacketBuffer *rxBuf; // A pointer to the buffer being actively used by the RADIO hardware. + + public: + MicroBitRadioDatagram datagram; // A simple datagram service. + MicroBitRadioEvent event; // A simple event handling service. + static MicroBitRadio *instance; // A singleton reference, used purely by the interrupt service routine. + + /** + * Constructor. + * + * Initialise the MicroBitRadio. Note that this class is demand activated, so most resources are only + * committed if send/recv or event registrations calls are made. + */ + MicroBitRadio(uint16_t id); + + /** + * Change the output power level of the transmitter to the given value. + * + * @param power a value in the range 0..7, where 0 is the lowest power and 7 is the highest. + * @return MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER if the value is out of range. + * + */ + int setTransmitPower(int power); + + /** + * Change the transmission and reception band of the radio to the given channel + * + * @param band a frequency band in the range 0 - 100. Each step is 1MHz wide, based at 2400MHz. + * @return 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. + * + */ + int setFrequencyBand(int band); + + /** + * Retrieve a pointer to the currently allocated recieve buffer. This is the area of memory + * actively being used by the radio hardware to store incoming data. + * + * @return a pointer to the current receive buffer + */ + PacketBuffer* getRxBuf(); + + /** + * Attempt to queue a buffer received by the radio hardware, if sufficient space is available. + * + * @return MICROBIT_OK on success, or MICROBIT_NO_RESOURCES if a replacement receiver buffer + * could not be allocated (either by policy or memory exhaustion). + */ + int queueRxBuf(); + + /** + * Initialises the radio for use as a multipoint sender/receiver + * @return MICROBIT_OK on success, MICROBIT_NOT_SUPPORTED if SoftDevice is enabled. + */ + int enable(); + + /** + * Disables the radio for use as a multipoint sender/receiver. + * @return MICROBIT_OK on success, MICROBIT_NOT_SUPPORTED if SoftDevice is enabled. + */ + int disable(); + + /** + * Sets the radio to listen to packets sent with the given group id. + * + * @param group The group to join. A micro:bit can only listen to one group ID at any time. + * @return MICROBIT_OK on success, or MICROBIT_NOT_SUPPORTED if the BLE stack is running. + */ + int setGroup(uint8_t group); + + /** + * A background, low priority callback that is triggered whenever the processor is idle. + * Here, we empty our queue of received packets, and pass them onto higher level protocol handlers. + * + * We provide optimised handling of well known, simple protocols and events on the MicroBitMessageBus + * to provide extensibility to other protocols that may be written in the future. + */ + virtual void idleTick(); + + /** + * Determines the number of packets ready to be processed. + * @return The number of packets in the receive buffer. + */ + int dataReady(); + + /** + * 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. + * + * NOTE: Once recv() has been called, it is the callers resposibility to + * delete the buffer when appropriate. + * + * @return The buffer containing the the packet. If no data is available, NULL is returned. + */ + PacketBuffer* recv(); + + /** + * Transmits the given buffer onto the broadcast radio. + * The call will wait until the transmission of the packet has completed before returning. + * + * @param data The packet contents to transmit. + * @return MICROBIT_OK on success, or MICROBIT_NOT_SUPPORTED if the BLE stack is running. + */ + int send(PacketBuffer *buffer); +}; + +#endif diff --git a/inc/MicroBitRadioDatagram.h b/inc/MicroBitRadioDatagram.h new file mode 100644 index 0000000..1521e72 --- /dev/null +++ b/inc/MicroBitRadioDatagram.h @@ -0,0 +1,77 @@ +#ifndef MICROBIT_RADIO_DATAGRAM_H +#define MICROBIT_RADIO_DATAGRAM_H + +#include "mbed.h" +#include "MicroBitRadio.h" + +/** + * Provides a simple broadcast radio abstraction, built upon the raw nrf51822 RADIO module. + * + * This class provides the ability to broadcast simple text or binary messages to other micro:bits in the vicinity + * It is envisaged that this would provide the basis for children to experiment with building their own, simple, + * custom protocols. + * + * NOTE: This API does not contain any form of encryption, authentication or authorisation. Its purpose is solely for use as a + * teaching aid to demonstrate how simple communications operates, and to provide a sandpit through which learning can take place. + * For serious applications, BLE should be considered a substantially more secure alternative. + */ + +class MicroBitRadioDatagram +{ + PacketBuffer *rxQueue; // A linear list of incoming packets, queued awaiting processing. + + public: + + /** + * Constructor. + */ + MicroBitRadioDatagram(); + + /** + * Retreives packet payload data into the given buffer. + * If a data packet is already available, then it will be returned immediately to the caller. + * If no data is available the EmptyString is returned, then MICROBIT_INVALID_PARAMETER is returned. + * + * @param buf A pointer to a valid memory location where the received data is to be stored. + * @param len The maximum amount of data that can safely be stored in 'buf' + * + * @return The length of the data stored, or MICROBIT_INVALID_PARAMETER if no data is available, or the memory regions provided are invalid. + */ + int recv(uint8_t *buf, int len); + + /** + * Retreives packet payload data into the given buffer. + * If a data packet is already available, then it will be returned immediately to the caller, + * in the form of a string. If no data is available the EmptyString is returned. + * + * @return the data received, or the EmptyString if no data is available. + */ + ManagedString recv(); + + /** + * Transmits the given buffer onto the broadcast radio. + * The call will wait until the transmission of the packet has completed before returning. + * + * @param buffer The packet contents to transmit. + * @param len The number of bytes to transmit. + * @return MICROBIT_OK on success. + */ + int send(uint8_t *buffer, int len); + + /** + * Transmits the given string onto the broadcast radio. + * The call will wait until the transmission of the packet has completed before returning. + * + * @param data The packet contents to transmit. + * @return MICROBIT_OK on success. + */ + int send(ManagedString data); + + /** + * Protocol handler callback. This is called when the radio receives a packet marked as a datagram. + * This function process this packet, and queues it for user reception. + */ + void packetReceived(); +}; + +#endif diff --git a/inc/MicroBitRadioEvent.h b/inc/MicroBitRadioEvent.h new file mode 100644 index 0000000..48d0259 --- /dev/null +++ b/inc/MicroBitRadioEvent.h @@ -0,0 +1,67 @@ +#ifndef MICROBIT_RADIO_EVENT_H +#define MICROBIT_RADIO_EVENT_H + +#include "mbed.h" +#include "MicroBitRadio.h" + +/** + * Provides a simple broadcast radio abstraction, built upon the raw nrf51822 RADIO module. + * + * This class provides the ability to extend the micro:bit's MessageBus to other micro:bits in the vicinity, + * in a very similar way to the MicroBitEventService for BLE interfaces. + * It is envisaged that this would provide the basis for children to experiment with building their own, simple, + * custom asynchronous events and actions. + * + * NOTE: This API does not contain any form of encryption, authentication or authorisation. Its purpose is solely for use as a + * teaching aid to demonstrate how simple communications operates, and to provide a sandpit through which learning can take place. + * For serious applications, BLE should be considered a substantially more secure alternative. + */ + +class MicroBitRadioEvent +{ + bool suppressForwarding; // A private flag used to prevent event forwarding loops. + + public: + + /** + * Constructor. + */ + MicroBitRadioEvent(); + + /** + * Associates the given MessageBus events with the radio channel. + * Once registered, all events matching the given registration sent to this micro:bit's + * MessageBus will be automatically retrasmitted on the radio. + * + * @param id The ID of the events to register. + * @param value the VALUE of the event to register. use MICROBIT_EVT_ANY for all event values matching the given ID. + * + * @return MICROBIT_OK on success. + */ + int listen(uint16_t id, uint16_t value); + + /** + * Disassociates the given MessageBus events with the radio channel. + * + * @param id The ID of the events to deregister. + * @param value the VALUE of the event to deregister. use MICROBIT_EVT_ANY for all event values matching the given ID. + * + * @return MICROBIT_OK on success. + */ + int ignore(uint16_t id, uint16_t value); + + /** + * 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 local MessageBus. + */ + void packetReceived(); + + /** + * 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 othe rmicro:bits in the same group. + */ + void eventReceived(MicroBitEvent e); +}; + +#endif diff --git a/source/CMakeLists.txt b/source/CMakeLists.txt index 0fddce0..b73cb45 100755 --- a/source/CMakeLists.txt +++ b/source/CMakeLists.txt @@ -41,6 +41,9 @@ set(YOTTA_AUTO_MICROBIT-DAL_CPP_FILES "ble-services/MicroBitButtonService.cpp" "ble-services/MicroBitIOPinService.cpp" "ble-services/MicroBitTemperatureService.cpp" + "ble-services/MicroBitRadio.cpp" + "ble-services/MicroBitRadioDatagram.cpp" + "ble-services/MicroBitRadioEvent.cpp" ) execute_process(WORKING_DIRECTORY "../../yotta_modules/${PROJECT_NAME}" COMMAND "git" "log" "--pretty=format:%h" "-n" "1" OUTPUT_VARIABLE git_hash) diff --git a/source/MicroBit.cpp b/source/MicroBit.cpp index a4129b0..bdd9083 100644 --- a/source/MicroBit.cpp +++ b/source/MicroBit.cpp @@ -105,6 +105,7 @@ MicroBit::MicroBit() : MICROBIT_ID_IO_P15,MICROBIT_ID_IO_P16,MICROBIT_ID_IO_P19, MICROBIT_ID_IO_P20), bleManager(), + radio(MICROBIT_ID_RADIO), ble(NULL) { } diff --git a/source/ble-services/MicroBitBLEManager.cpp b/source/ble-services/MicroBitBLEManager.cpp index 6baa022..f847533 100644 --- a/source/ble-services/MicroBitBLEManager.cpp +++ b/source/ble-services/MicroBitBLEManager.cpp @@ -21,13 +21,7 @@ #pragma GCC diagnostic pop #endif -#define MICROBIT_BLE_ENABLE_BONDING true -#define MICROBIT_BLE_REQUIRE_MITM true - #define MICROBIT_PAIRING_FADE_SPEED 4 -#define MICROBIT_BLE_POWER_LEVELS 8 -#define MICROBIT_BLE_MAXIMUM_BONDS 4 - const char* MICROBIT_BLE_MANUFACTURER = NULL; const char* MICROBIT_BLE_MODEL = "BBC micro:bit"; diff --git a/source/ble-services/MicroBitRadio.cpp b/source/ble-services/MicroBitRadio.cpp new file mode 100644 index 0000000..e118182 --- /dev/null +++ b/source/ble-services/MicroBitRadio.cpp @@ -0,0 +1,424 @@ +#include "MicroBit.h" + +/** + * Provides a simple broadcast radio abstraction, built upon the raw nrf51822 RADIO module. + * + * The nrf51822 RADIO module supports a number of proprietary modes of operation oher than the typical BLE usage. + * This class uses one of these modes to enable simple, point to multipoint communication directly between micro:bits. + * + * TODO: The protocols implemented here do not currently perform any significant form of energy management, + * which means that they will consume far more energy than their BLE equivalent. Later versions of the protocol + * should look to address this through energy efficient broadcast techbiques / sleep scheduling. In particular, the GLOSSY + * approach to efficient rebroadcast and network synchronisation would likely provide an effective future step. + * + * TODO: Meshing should also be considered - again a GLOSSY approach may be effective here, and highly complementary to + * the master/slave arachitecture of BLE. + * + * TODO: This implementation may only operated whilst the BLE stack is disabled. The nrf51822 provides a timeslot API to allow + * BLE to cohabit with other protocols. Future work to allow this colocation would be benefical, and would also allow for the + * creation of wireless BLE bridges. + * + * NOTE: This API does not contain any form of encryption, authentication or authorisation. Its purpose is solely for use as a + * teaching aid to demonstrate how simple communications operates, and to provide a sandpit through which learning can take place. + * For serious applications, BLE should be considered a substantially more secure alternative. + */ + +MicroBitRadio* MicroBitRadio::instance = NULL; + +extern "C" void RADIO_IRQHandler(void) +{ + // Move on to the next buffer, if possible. + MicroBitRadio::instance->queueRxBuf(); + NRF_RADIO->PACKETPTR = (uint32_t) MicroBitRadio::instance->getRxBuf(); + + // Start listening for the next packet. + NRF_RADIO->EVENTS_END = 0; + NRF_RADIO->TASKS_START = 1; +} + +/** + * Constructor. + * + * Initialise the MicroBitRadio. Note that this class is demand activated, so most resources are only committed + * if send/recv or event registrations calls are made. + */ +MicroBitRadio::MicroBitRadio(uint16_t id) : datagram() +{ + this->id = id; + this->status = 0; + this->group = 0; + this->queueDepth = 0; + this->rxQueue = NULL; + this->rxBuf = NULL; + + instance = this; +} + +/** + * Change the output power level of the transmitter to the given value. + * + * @param power a value in the range 0..7, where 0 is the lowest power and 7 is the highest. + * @return MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER if the value is out of range. + * + */ +int MicroBitRadio::setTransmitPower(int power) +{ + if (power < 0 || power >= MICROBIT_BLE_POWER_LEVELS) + return MICROBIT_INVALID_PARAMETER; + + NRF_RADIO->TXPOWER = (uint32_t)MICROBIT_BLE_POWER_LEVEL[power]; + + return MICROBIT_OK; +} + +/** + * Change the transmission and reception band of the radio to the given channel + * + * @param band a frequency band in the range 0 - 100. Each step is 1MHz wide, based at 2400MHz. + * @return 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. + * + */ +int MicroBitRadio::setFrequencyBand(int band) +{ + if (uBit.ble) + return MICROBIT_NOT_SUPPORTED; + + if (band < 0 || band > 100) + return MICROBIT_INVALID_PARAMETER; + + NRF_RADIO->FREQUENCY = (uint32_t)band; + + return MICROBIT_OK; +} + +/** + * 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. + * + * @return a pointer to the current receive buffer + */ +PacketBuffer* MicroBitRadio::getRxBuf() +{ + return rxBuf; +} + +/** + * Attempt to queue a buffer received by the radio hardware, if sufficient space is available. + * + * @return MICROBIT_OK on success, or MICROBIT_NO_RESOURCES if a replacement receiver buffer + * could not be allocated (either by policy or memory exhaustion). + */ +int MicroBitRadio::queueRxBuf() +{ + if (rxBuf == NULL) + return MICROBIT_INVALID_PARAMETER; + + if (queueDepth >= MICROBIT_RADIO_MAXIMUM_RX_BUFFERS) + return MICROBIT_NO_RESOURCES; + + // Ensure that a replacement buffer is available before queuing. + PacketBuffer *newRxBuf = new PacketBuffer(); + + if (newRxBuf == NULL) + return MICROBIT_NO_RESOURCES; + + // We add to the tail of the queue to preserve causal ordering. + rxBuf->next = NULL; + + if (rxQueue == NULL) + { + rxQueue = rxBuf; + } + else + { + PacketBuffer *p = rxQueue; + while (p->next != NULL) + p = p->next; + + p->next = rxBuf; + } + + // Increase our received packet count + queueDepth++; + + // Allocate a new buffer for the receiver hardware to use. the old on will be passed on to higher layer protocols/apps. + rxBuf = newRxBuf; + + return MICROBIT_OK; +} + +/** + * Initialises the radio for use as a multipoint sender/receiver. + * This is currently only possible if the BLE stack (Soft Device) is disabled. + * + * @return MICROBIT_OK on success, MICROBIT_NOT_SUPPORTED if SoftDevice is enabled. + */ +int MicroBitRadio::enable() +{ + // If the device is already initialised, then there's nothing to do. + if (status & MICROBIT_RADIO_STATUS_INITIALISED) + return MICROBIT_OK; + + // Only attempt to enable this radio mode if BLE is disabled. + if (uBit.ble) + return MICROBIT_NOT_SUPPORTED; + + // If this is the first time we've been enable, allocate out receive buffers. + if (rxBuf == NULL) + rxBuf = new PacketBuffer(); + + if (rxBuf == NULL) + return MICROBIT_NO_RESOURCES; + + // Enable the High Frequency clock on the processor. This is a pre-requisite for + // the RADIO module. Without this clock, no communication is possible. + NRF_CLOCK->EVENTS_HFCLKSTARTED = 0; + NRF_CLOCK->TASKS_HFCLKSTART = 1; + while (NRF_CLOCK->EVENTS_HFCLKSTARTED == 0); + + // Bring up the nrf51822 RADIO module in Nordic's proprietary 1MBps packet radio mode. + setTransmitPower(MICROBIT_RADIO_DEFAULT_TX_POWER); + setFrequencyBand(MICROBIT_RADIO_DEFAULT_FREQUENCY); + + // Configure for 1Mbps throughput. + // This may sound excessive, but running a high data rates reduces the chances of collisions... + NRF_RADIO->MODE = RADIO_MODE_MODE_Nrf_1Mbit; + + // Configure the addresses we use for this protocol. We run ANONYMOUSLY at the core. + // A 40 bit addresses is used. The first 32 bits match the ASCII character code for "uBit". + // Statistically, this provides assurance to avoid other similar 2.4GHz protocols that may be in the vicinity. + // We also map the assigned 8-bit GROUP id into the PREFIX field. This allows the RADIO hardware to perform + // address matching for us, and only generate an interrupt when a packet matching our group is received. + NRF_RADIO->BASE0 = MICROBIT_RADIO_BASE_ADDRESS; + + // Join the default group. This will configure the remaining byte in the RADIO hardware module. + setGroup(MICROBIT_RADIO_DEFAULT_GROUP); + + // The RADIO hardware module supports the use of multiple addresses, but as we're running anonymously, we only need one. + // Configure the RADIO module to use the default address (address 0) for both send and receive operations. + NRF_RADIO->TXADDRESS = 0; + NRF_RADIO->RXADDRESSES = 1; + + // Packet layout configuration. The nrf51822 has a highly capable and flexible RADIO module that, in addition to transmission + // and reception of data, also contains a LENGTH field, two optional additional 1 byte fields (S0 and S1) and a CRC calculation. + // Configure the packet format for a simple 8 bit length field and no additional fields. + NRF_RADIO->PCNF0 = 0x00000008; + NRF_RADIO->PCNF1 = 0x02040000 | MICROBIT_RADIO_MAX_PACKET_SIZE; + + // Most communication channels contain some form of checksum - a mathematical calculation taken based on all the data + // in a packet, that is also sent as part of the packet. When received, this calculation can be repeated, and the results + // from the sender and receiver compared. If they are different, then some corruption of the data ahas happened in transit, + // and we know we can't trust it. The nrf51822 RADIO uses a CRC for this - a very effective checksum calculation. + // + // Enable automatic 16bit CRC generation and checking, and configure how the CRC is calculated. + NRF_RADIO->CRCCNF = RADIO_CRCCNF_LEN_Two; + NRF_RADIO->CRCINIT = 0xFFFF; + NRF_RADIO->CRCPOLY = 0x11021; + + // Set the start random value of the data whitening algorithm. This can be any non zero number. + NRF_RADIO->DATAWHITEIV = 0x18; + + // Set up the RADIO module to read and write from our internal buffer. + NRF_RADIO->PACKETPTR = (uint32_t)rxBuf; + + // Configure the hardware to issue an interrupt whenever a task is complete (e.g. send/receive). + NRF_RADIO->INTENSET = 0x00000008; + NVIC_ClearPendingIRQ(RADIO_IRQn); + NVIC_EnableIRQ(RADIO_IRQn); + + // Start listening for the next packet + NRF_RADIO->EVENTS_READY = 0; + NRF_RADIO->TASKS_RXEN = 1; + while(NRF_RADIO->EVENTS_READY == 0); + + NRF_RADIO->EVENTS_END = 0; + NRF_RADIO->TASKS_START = 1; + + // register ourselves for a callback event, in order to empty the receive queue. + uBit.addIdleComponent(this); + + // Done. Record that our RADIO is configured. + status |= MICROBIT_RADIO_STATUS_INITIALISED; + + return MICROBIT_OK; +} + +/** + * Disables the radio for use as a multipoint sender/receiver. + * @return MICROBIT_OK on success, MICROBIT_NOT_SUPPORTED if SoftDevice is enabled. + */ +int MicroBitRadio::disable() +{ + // Only attempt to enable.disable the radio if the protocol is alreayd running. + if (uBit.ble) + return MICROBIT_NOT_SUPPORTED; + + if (!(status & MICROBIT_RADIO_STATUS_INITIALISED)) + return MICROBIT_OK; + + // Disable interrupts and STOP any ongoing packet reception. + NVIC_DisableIRQ(RADIO_IRQn); + + NRF_RADIO->EVENTS_DISABLED = 0; + NRF_RADIO->TASKS_DISABLE = 1; + while(NRF_RADIO->EVENTS_DISABLED == 0); + + // deregister ourselves from the callback event used to empty the receive queue. + uBit.removeIdleComponent(this); + + return MICROBIT_OK; +} + +/** + * Sets the radio to listen to packets sent with the given group id. + * + * @param group The group to join. A micro:bit can only listen to one group ID at any time. + * @return MICROBIT_OK on success, or MICROBIT_NOT_SUPPORTED if the BLE stack is running. + */ +int MicroBitRadio::setGroup(uint8_t group) +{ + if (uBit.ble) + return MICROBIT_NOT_SUPPORTED; + + // Record our group id locally + this->group = group; + + // Also append it to the address of this device, to allow the RADIO module to filter for us. + NRF_RADIO->PREFIX0 = (uint32_t)group; + + return MICROBIT_OK; +} + +/** + * A background, low priority callback that is triggered whenever the processor is idle. + * Here, we empty our queue of received packets, and pass them onto higher level protocol handlers. + * + * We provide optimised handling of well known, simple protocols and events on the MicroBitMessageBus + * to provide extensibility to other protocols that may be written in the future. + */ +void MicroBitRadio::idleTick() +{ + // Walk the list of packets and process each one. + while(rxQueue) + { + PacketBuffer *p = rxQueue; + + switch (p->protocol) + { + case MICROBIT_RADIO_PROTOCOL_DATAGRAM: + datagram.packetReceived(); + break; + + case MICROBIT_RADIO_PROTOCOL_EVENTBUS: + event.packetReceived(); + break; + + default: + MicroBitEvent(MICROBIT_ID_RADIO_DATA_READY, p->protocol); + } + + // If the packet was processed, it will have been recv'd, and taken from the queue. + // If this was a packet for an unknown protocol, it will still be there, so simply free it. + if (p == rxQueue) + { + recv(); + delete p; + } + } +} + +/** + * Determines the number of packets ready to be processed. + * @return The number of packets in the receive buffer. + */ +int MicroBitRadio::dataReady() +{ + return queueDepth; +} + +/** + * 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. + * + * NOTE: Once recv() has been called, it is the callers resposibility to + * delete the buffer when appropriate. + * + * @return The buffer containing the the packet. If no data is available, NULL is returned. + */ +PacketBuffer* MicroBitRadio::recv() +{ + PacketBuffer *p = rxQueue; + + if (p) + { + rxQueue = rxQueue->next; + queueDepth--; + } + + return p; +} + +/** + * Transmits the given buffer onto the broadcast radio. + * The call will wait until the transmission of the packet has completed before returning. + * + * @param data The packet contents to transmit. + * @return MICROBIT_OK on success, or MICROBIT_NOT_SUPPORTED if the BLE stack is running. + */ +int MicroBitRadio::send(PacketBuffer *buffer) +{ + if (uBit.ble) + return MICROBIT_NOT_SUPPORTED; + + if (buffer == NULL) + return MICROBIT_INVALID_PARAMETER; + + if (buffer->length > MICROBIT_RADIO_MAX_PACKET_SIZE + MICROBIT_RADIO_HEADER_SIZE - 1) + return MICROBIT_INVALID_PARAMETER; + + // Firstly, disable the Radio interrupt. We want to wait until the trasmission completes. + NVIC_DisableIRQ(RADIO_IRQn); + + // Turn off the transceiver. + NRF_RADIO->EVENTS_DISABLED = 0; + NRF_RADIO->TASKS_DISABLE = 1; + while(NRF_RADIO->EVENTS_DISABLED == 0); + + // Configure the radio to send the buffer provided. + NRF_RADIO->PACKETPTR = (uint32_t) buffer; + + // Turn on the transmitter, and wait for it to signal that it's ready to use. + NRF_RADIO->EVENTS_READY = 0; + NRF_RADIO->TASKS_TXEN = 1; + while (NRF_RADIO->EVENTS_READY == 0); + + // Start transmission and wait for end of packet. + NRF_RADIO->TASKS_START = 1; + NRF_RADIO->EVENTS_END = 0; + while(NRF_RADIO->EVENTS_END == 0); + + // Return the radio to using the default receive buffer + NRF_RADIO->PACKETPTR = (uint32_t) rxBuf; + + // Turn off the transmitter. + NRF_RADIO->EVENTS_DISABLED = 0; + NRF_RADIO->TASKS_DISABLE = 1; + while(NRF_RADIO->EVENTS_DISABLED == 0); + + // Start listening for the next packet + NRF_RADIO->EVENTS_READY = 0; + NRF_RADIO->TASKS_RXEN = 1; + while(NRF_RADIO->EVENTS_READY == 0); + + NRF_RADIO->EVENTS_END = 0; + NRF_RADIO->TASKS_START = 1; + + // Re-enable the Radio interrupt. + NVIC_ClearPendingIRQ(RADIO_IRQn); + NVIC_EnableIRQ(RADIO_IRQn); + + return MICROBIT_OK; +} + diff --git a/source/ble-services/MicroBitRadioDatagram.cpp b/source/ble-services/MicroBitRadioDatagram.cpp new file mode 100644 index 0000000..29091aa --- /dev/null +++ b/source/ble-services/MicroBitRadioDatagram.cpp @@ -0,0 +1,141 @@ +#include "MicroBit.h" + +/** + * Provides a simple broadcast radio abstraction, built upon the raw nrf51822 RADIO module. + * + * This class provides the ability to broadcast simple text or binary messages to other micro:bits in the vicinity + * It is envisaged that this would provide the basis for children to experiment with building their own, simple, + * custom protocols. + * + * NOTE: This API does not contain any form of encryption, authentication or authorisation. Its purpose is solely for use as a + * teaching aid to demonstrate how simple communications operates, and to provide a sandpit through which learning can take place. + * For serious applications, BLE should be considered a substantially more secure alternative. + */ + +/** + * Constructor. + */ +MicroBitRadioDatagram::MicroBitRadioDatagram() +{ + rxQueue = NULL; +} + +/** + * Retreives packet payload data into the given buffer. + * If a data packet is already available, then it will be returned immediately to the caller. + * If no data is available the EmptyString is returned, then MICROBIT_INVALID_PARAMETER is returned. + * + * @param buf A pointer to a valid memory location where the received data is to be stored. + * @param len The maximum amount of data that can safely be stored in 'buf' + * + * @return The length of the data stored, or MICROBIT_INVALID_PARAMETER if no data is available, or the memory regions provided are invalid. + */ +int MicroBitRadioDatagram::recv(uint8_t *buf, int len) +{ + if (buf == NULL || rxQueue == NULL || len < 0) + return MICROBIT_INVALID_PARAMETER; + + // Take the first buffer from the queue. + PacketBuffer *p = rxQueue; + rxQueue = rxQueue->next; + + int l = min(len, p->length - MICROBIT_RADIO_HEADER_SIZE - 1); + + // Fill in the buffer provided, if possible. + memcpy(buf, p->payload, l); + + delete p; + return l; +} + +/** + * Retreives packet payload data into the given buffer. + * If a data packet is already available, then it will be returned immediately to the caller, + * in the form of a string. If no data is available the EmptyString is returned. + * + * @return the data received, or the EmptyString if no data is available. + */ +ManagedString MicroBitRadioDatagram::recv() +{ + PacketBuffer *p = rxQueue; + rxQueue = rxQueue->next; + + ManagedString s((const char *)p->payload, p->length - MICROBIT_RADIO_HEADER_SIZE - 1); + + delete p; + return s; +} + +/** + * Transmits the given buffer onto the broadcast radio. + * The call will wait until the transmission of the packet has completed before returning. + * + * @param buffer The packet contents to transmit. + * @param len The number of bytes to transmit. + * @return MICROBIT_OK on success. + */ +int MicroBitRadioDatagram::send(uint8_t *buffer, int len) +{ + if (buffer == NULL || len < 0 || len > MICROBIT_RADIO_MAX_PACKET_SIZE + MICROBIT_RADIO_HEADER_SIZE - 1) + return MICROBIT_INVALID_PARAMETER; + + PacketBuffer buf; + + buf.length = len + MICROBIT_RADIO_HEADER_SIZE - 1; + buf.version = 1; + buf.group = 0; + buf.protocol = MICROBIT_RADIO_PROTOCOL_DATAGRAM; + memcpy(buf.payload, buffer, len); + + return uBit.radio.send(&buf); +} + +/** + * Transmits the given string onto the broadcast radio. + * The call will wait until the transmission of the packet has completed before returning. + * + * @param data The packet contents to transmit. + * @return MICROBIT_OK on success. + */ +int MicroBitRadioDatagram::send(ManagedString data) +{ + return send((uint8_t *)data.toCharArray(), data.length()); +} + +/** + * Protocol handler callback. This is called when the radio receives a packet marked as a datagram. + * This function process this packet, and queues it for user reception. + */ +void MicroBitRadioDatagram::packetReceived() +{ + PacketBuffer *packet = uBit.radio.recv(); + int queueDepth = 0; + + // We add to the tail of the queue to preserve causal ordering. + packet->next = NULL; + + if (rxQueue == NULL) + { + rxQueue = packet; + } + else + { + PacketBuffer *p = rxQueue; + while (p->next != NULL) + { + p = p->next; + queueDepth++; + } + + if (queueDepth >= MICROBIT_RADIO_MAXIMUM_RX_BUFFERS) + { + delete packet; + return; + } + + p->next = packet; + } + + MicroBitEvent(MICROBIT_ID_RADIO, MICROBIT_RADIO_EVT_DATAGRAM); +} + diff --git a/source/ble-services/MicroBitRadioEvent.cpp b/source/ble-services/MicroBitRadioEvent.cpp new file mode 100644 index 0000000..e3a1bec --- /dev/null +++ b/source/ble-services/MicroBitRadioEvent.cpp @@ -0,0 +1,88 @@ +#include "MicroBit.h" + +/** + * Provides a simple broadcast radio abstraction, built upon the raw nrf51822 RADIO module. + * + * This class provides the ability to extend the micro:bit's MessageBus to other micro:bits in the vicinity, + * in a very similar way to the MicroBitEventService for BLE interfaces. + * It is envisaged that this would provide the basis for children to experiment with building their own, simple, + * custom asynchronous events. + * + * NOTE: This API does not contain any form of encryption, authentication or authorisation. Its purpose is solely for use as a + * teaching aid to demonstrate how simple communications operates, and to provide a sandpit through which learning can take place. + * For serious applications, BLE should be considered a substantially more secure alternative. + */ + +/** + * Constructor. + */ +MicroBitRadioEvent::MicroBitRadioEvent() +{ + suppressForwarding = false; +} + +/** + * Associates the given MessageBus events with the radio channel. + * Once registered, all events matching the given registration sent to this micro:bit's + * MessageBus will be automaticlaly retrasmitted on the radio. + * + * @param id The ID of the events to register. + * @param value the VALUE of the event to register. use MICROBIT_EVT_ANY for all event values matching the given id. + * + * @return MICROBIT_OK on success. + */ +int MicroBitRadioEvent::listen(uint16_t id, uint16_t value) +{ + return uBit.MessageBus.listen(id, value, this, &MicroBitRadioEvent::eventReceived, MESSAGE_BUS_LISTENER_IMMEDIATE); +} + +/** + * Disassociates the given MessageBus events with the radio channel. + * + * @param id The ID of the events to deregister. + * @param value the VALUE of the event to deregister. use MICROBIT_EVT_ANY for all event values matching the given id. + * + * @return MICROBIT_OK on success. + */ +int MicroBitRadioEvent::ignore(uint16_t id, uint16_t value) +{ + return uBit.MessageBus.ignore(id, value, this, &MicroBitRadioEvent::eventReceived); +} + +/** + * Protocol handler callback. This is called when the radio receives a packet marked as an event + * This function process this packet, and fires the event contained inside onto the local MessageBus. + */ +void MicroBitRadioEvent::packetReceived() +{ + PacketBuffer *p = uBit.radio.recv(); + MicroBitEvent *e = (MicroBitEvent *) p->payload; + + suppressForwarding = true; + e->fire(); + suppressForwarding = false; + + delete p; +} + +/** + * 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 othe rmicro:bits in the same group. + */ +void MicroBitRadioEvent::eventReceived(MicroBitEvent e) +{ + if(suppressForwarding) + return; + + PacketBuffer buf; + + buf.length = sizeof(MicroBitEvent) + MICROBIT_RADIO_HEADER_SIZE - 1; + buf.version = 1; + buf.group = 0; + buf.protocol = MICROBIT_RADIO_PROTOCOL_EVENTBUS; + memcpy(buf.payload, (const uint8_t *)&e, sizeof(MicroBitEvent)); + + uBit.radio.send(&buf); +} +