Attempting to publish a tree
Dependencies: BLE_API mbed-dev-bin nRF51822
Fork of microbit-dal by
Diff: source/drivers/MicroBitRadio.cpp
- Revision:
- 1:8aa5cdb4ab67
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/source/drivers/MicroBitRadio.cpp Thu Apr 07 01:33:22 2016 +0100 @@ -0,0 +1,512 @@ +/* +The MIT License (MIT) + +Copyright (c) 2016 British Broadcasting Corporation. +This software is provided by Lancaster University by arrangement with the BBC. + +Permission is hereby granted, free of charge, to any person obtaining a +copy of this software and associated documentation files (the "Software"), +to deal in the Software without restriction, including without limitation +the rights to use, copy, modify, merge, publish, distribute, sublicense, +and/or sell copies of the Software, and to permit persons to whom the +Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. +*/ + +#include "MicroBitConfig.h" +#include "MicroBitRadio.h" +#include "MicroBitComponent.h" +#include "EventModel.h" +#include "MicroBitDevice.h" +#include "ErrorNo.h" +#include "MicroBitFiber.h" +#include "MicroBitBLEManager.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(); + + if(NRF_RADIO->EVENTS_READY) + { + NRF_RADIO->EVENTS_READY = 0; + + // Start listening and wait for the END event + NRF_RADIO->TASKS_START = 1; + } + + if(NRF_RADIO->EVENTS_END) + { + NRF_RADIO->EVENTS_END = 0; + + if(NRF_RADIO->CRCSTATUS == 1) + { + uint8_t sample = NRF_RADIO->RSSISAMPLE; + + MicroBitRadio::instance->setRSSI(sample); + } + + // Start listening and wait for the END event + NRF_RADIO->TASKS_START = 1; + } +} + +/** + * Constructor. + * + * Initialise the MicroBitRadio. + * + * @note This class is demand activated, as a result most resources are only + * committed if send/recv or event registrations calls are made. + */ +MicroBitRadio::MicroBitRadio(uint16_t id) : datagram(*this), event (*this) +{ + this->id = id; + this->status = 0; + this->group = 0; + this->queueDepth = 0; + this->rssi = 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 (ble_running()) + 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. + */ +FrameBuffer* 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; + + // Store the received RSSI value in the frame + rxBuf->rssi = getRSSI(); + + // Ensure that a replacement buffer is available before queuing. + FrameBuffer *newRxBuf = new FrameBuffer(); + + 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 + { + FrameBuffer *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; +} + +/** + * Sets the RSSI for the most recent packet. + * + * @param rssi the new rssi value. + * + * @note should only be called from RADIO_IRQHandler... + */ +int MicroBitRadio::setRSSI(uint8_t rssi) +{ + if (!(status & MICROBIT_RADIO_STATUS_INITIALISED)) + return MICROBIT_NOT_SUPPORTED; + + this->rssi = rssi; + + return MICROBIT_OK; +} + +/** + * Retrieves the current RSSI for the most recent packet. + * + * @return the most recent RSSI value or MICROBIT_NOT_SUPPORTED if the BLE stack is running. + */ +int MicroBitRadio::getRSSI() +{ + if (!(status & MICROBIT_RADIO_STATUS_INITIALISED)) + return MICROBIT_NOT_SUPPORTED; + + return this->rssi; +} + +/** + * Initialises the radio for use as a multipoint sender/receiver + * + * @return MICROBIT_OK on success, MICROBIT_NOT_SUPPORTED if the BLE stack is running. + */ +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 (ble_running()) + return MICROBIT_NOT_SUPPORTED; + + // If this is the first time we've been enable, allocate out receive buffers. + if (rxBuf == NULL) + rxBuf = new FrameBuffer(); + + 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); + + NRF_RADIO->SHORTS |= RADIO_SHORTS_ADDRESS_RSSISTART_Msk; + + // 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. + fiber_add_idle_component(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 the BLE stack is running. + */ +int MicroBitRadio::disable() +{ + // Only attempt to enable.disable the radio if the protocol is alreayd running. + if (ble_running()) + 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. + fiber_remove_idle_component(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 (ble_running()) + 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. + */ +void MicroBitRadio::idleTick() +{ + // Walk the list of packets and process each one. + while(rxQueue) + { + FrameBuffer *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. + * + * @return The buffer containing the the packet. If no data is available, NULL is returned. + * + * @note Once recv() has been called, it is the callers resposibility to + * delete the buffer when appropriate. + */ +FrameBuffer* MicroBitRadio::recv() +{ + FrameBuffer *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(FrameBuffer *buffer) +{ + if (ble_running()) + 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; +}