microbit: Add Multicast peer-to-peer radio capability

Integration of new radio mode that permits simple local area multicast communication
directly between micro:bits using the device's on board radio hardware.

It should be noted that this implementation build directly on the nrf51822
hardware. It is not a BLE protocol, and must (currently) be operated with BLE
disabled.

A standard on the wire configuration is defined, to promote future
interoperability between projects and languages. A lightweight
packet format is also defined and adhered to, so as to promote future
extensibility without sacrificing compatibility. The notion of groups is also
introduced, that enable multiple groups of children to work in the same area
without compromising each other's projects.

In adition to a low level packet radio driver, two higher level protocols are
defined that allow simple user datagram communication between micro:bits and
an EventBus protocol that allows the micro:bit's MessageBus to be extended to
other micro:bits.
This commit is contained in:
Joe Finney 2016-02-01 04:29:27 +00:00
parent e3a23988f6
commit d9d2343ab6
7 changed files with 962 additions and 0 deletions

173
inc/MicroBitRadio.h Normal file
View File

@ -0,0 +1,173 @@
#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.
*
*/
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.
*/
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.
*/
int send(PacketBuffer *buffer);
};
#endif

View File

@ -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

67
inc/MicroBitRadioEvent.h Normal file
View File

@ -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 registerEvent(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 deregisterEvent(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

View File

@ -40,6 +40,9 @@ set(YOTTA_AUTO_MICROBIT-DAL_CPP_FILES
"ble-services/MicroBitButtonService.cpp" "ble-services/MicroBitButtonService.cpp"
"ble-services/MicroBitIOPinService.cpp" "ble-services/MicroBitIOPinService.cpp"
"ble-services/MicroBitTemperatureService.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) execute_process(WORKING_DIRECTORY "../../yotta_modules/${PROJECT_NAME}" COMMAND "git" "log" "--pretty=format:%h" "-n" "1" OUTPUT_VARIABLE git_hash)

View File

@ -0,0 +1,413 @@
#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.
*
*/
int MicroBitRadio::setFrequencyBand(int band)
{
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.
*/
int MicroBitRadio::setGroup(uint8_t group)
{
// Record our group id locally, and also append it to the address of this device,
// to allow the RADIO module to filter for us.
this->group = group;
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, or MICROBIT_NOT_SUPPORTED if the microbitRadio has not been enabled.
*/
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.
*/
int MicroBitRadio::send(PacketBuffer *buffer)
{
if (buffer == NULL)
return MICROBIT_INVALID_PARAMETER;
if (buffer->length > MICROBIT_RADIO_MAX_PACKET_SIZE + 3)
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;
}

View File

@ -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 - 3);
// 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 - 3);
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 + 3)
return MICROBIT_INVALID_PARAMETER;
PacketBuffer buf;
buf.length = len+3;
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);
}

View File

@ -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::registerEvent(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::deregisterEvent(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)+3;
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);
}