diff --git a/docs/ubit/radio.md b/docs/ubit/radio.md index f3e739a..ccaa0bd 100644 --- a/docs/ubit/radio.md +++ b/docs/ubit/radio.md @@ -5,7 +5,7 @@ The central processor unit (CPU) on the micro:bit is a Nordic Semiconductor [nRF51822](../resources/datasheets/nRF51822.pdf). In addition to being a general purpose computer processor, this chip also contains a built-in 2.4GHz radio module. This radio can be configured in a number of ways, and is primarily designed to run the Bluetooth Low Energy (BLE) protocol. However, it can also be placed into a much -simpler mode of operation based that allows simple, direct micro:bit to micro:bit communication. +simpler mode of operation that allows simple, direct micro:bit to micro:bit communication. The `MicroBitRadio` component is made up of three classes - `MicroBitRadio`, [`MicroBitRadioEvent`](radioevent.md) and [`MicroBitRadioDatagram`](radiodatagram.md). Together, these provide the ability to send general purpose data packets from one micro:bit to another, and to extend a message bus to span multiple micro:bits... @@ -33,7 +33,7 @@ which can be used to identify you or your micro:bit. All devices look identical. | Channel Rate | 1Mbps. | | Maximum Transfer Unit | Typically 32 bytes, but reconfigurable in code up to 1024 bytes. | | Addressing | All devices share the same address to guarantee user privacy. | -| Encryption | None. User level encryption (or BLE) should be considered if secture channels are required. | +| Encryption | None. User level encryption (or BLE) should be considered if secure channels are required. | | Meshing | None. (yet!) | | Error Detection | 16 bit hardware CRC. | | Transmisson Power| Eight user configurable settings from 0 (-30dbm) to 7 (+4dbm). | @@ -48,7 +48,7 @@ Both of these are created for you as part of the standard uBit object, so this i ### [MicroBitRadioDatagram](radiodatagram.md) This is the most flexible way to use the radio, and lets you easily send and receive up to 32 bytes of data at a time. -This data can be provided as array of bytes, a text string, or [`PacketBuffer`](../data-types/packetbuffer.md). +This data can be provided as an array of bytes, a text string, or [`PacketBuffer`](../data-types/packetbuffer.md). You can send a packet at any time using the `uBit.radio.datagram.send` function. @@ -126,7 +126,7 @@ If you prefer to send a raw series of bytes rather than a text string (which is This gives total freedom over the data being shared. Simply create a [`PacketBuffer`](../data-types/packetbuffer.md) of the size you need, and you can read or write data using standard C array syntax. -For example, here is an similar program using a [`PacketBuffer`](../data-types/packetbuffer.md): +For example, here is a similar program using a [`PacketBuffer`](../data-types/packetbuffer.md): ```cpp #include "MicroBit.h" @@ -167,6 +167,12 @@ void onData(MicroBitEvent e) { PacketBuffer p = uBit.radio.datagram.recv(); + if (p[0] == 0) + { + uBit.io.P0.setServoValue(90); + uBit.display.clear(); + } + if (p[0] == 1) { uBit.io.P0.setServoValue(0); @@ -194,7 +200,7 @@ int main() ### [MicroBitRadioEvent](radioevent.md) It is also possible to transparently send and receive events over the `MicroBitRadio` channel. This can provide very simple and easy to integrate -support for event driven applications. Once configured, an event raised on one micro:bit can be detected on another - in the just the same way as +support for event driven applications. Once configured, an event raised on one micro:bit can be detected on another - in just the same way as a local event such as a button click. To use this functionality, all that is needed is to register the event codes that you would like to be sent over the radio, then write event handlers @@ -303,25 +309,25 @@ int main()
####MicroBitRadio() #####Description -Constructor. +Constructor. + + Initialise the MicroBitRadio . - 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. + This class is demand activated, as a result most resources are only committed if send/recv or event registrations calls are made.
####MicroBitRadio(
uint16_t
id) #####Description -Constructor. +Constructor. + + Initialise the MicroBitRadio . - Initialise the MicroBitRadio . - #####Parameters @@ -329,65 +335,65 @@ Constructor. >
uint16_t
id !!! note - This class is demand activated, as a result most resources are only committed if send/recv or event registrations calls are made. + This class is demand activated, as a result most resources are only committed if send/recv or event registrations calls are made. ##setTransmitPower
####
int
setTransmitPower
(
int
power) #####Description -Change the output power level of the transmitter to the given value. +Change the output power level of the transmitter to the given value. + - #####Parameters >
int
power - a value in the range 0..7, where 0 is the lowest power and 7 is the highest. #####Returns -MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER if the value is out of range. +MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER if the value is out of range. ##setFrequencyBand
####
int
setFrequencyBand
(
int
band) #####Description -Change the transmission and reception band of the radio to the given channel +Change the transmission and reception band of the radio to the given channel + - #####Parameters >
int
band - a frequency band in the range 0 - 100. Each step is 1MHz wide, based at 2400MHz. #####Returns -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. +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. ##getRxBuf
####
FrameBuffer
getRxBuf
() #####Description -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. +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. + - #####Returns -a pointer to the current receive buffer. +a pointer to the current receive buffer. ##queueRxBuf
####
int
queueRxBuf
() #####Description -Attempt to queue a buffer received by the radio hardware, if sufficient space is available. +Attempt to queue a buffer received by the radio hardware, if sufficient space is available. + - #####Returns -MICROBIT_OK on success, or MICROBIT_NO_RESOURCES if a replacement receiver buffer could not be allocated (either by policy or memory exhaustion). +MICROBIT_OK on success, or MICROBIT_NO_RESOURCES if a replacement receiver buffer could not be allocated (either by policy or memory exhaustion). ##setRSSI
####
int
setRSSI
(
uint8_t
rssi) #####Description -Sets the RSSI for the most recent packet. +Sets the RSSI for the most recent packet. + - #####Parameters @@ -395,94 +401,94 @@ Sets the RSSI for the most recent packet. >
uint8_t
rssi - the new rssi value. !!! note - should only be called from RADIO_IRQHandler... + should only be called from RADIO_IRQHandler... ##getRSSI
####
int
getRSSI
() #####Description -Retrieves the current RSSI for the most recent packet. +Retrieves the current RSSI for the most recent packet. + - #####Returns -the most recent RSSI value or MICROBIT_NOT_SUPPORTED if the BLE stack is running. +the most recent RSSI value or MICROBIT_NOT_SUPPORTED if the BLE stack is running. ##enable
####
int
enable
() #####Description -Initialises the radio for use as a multipoint sender/receiver +Initialises the radio for use as a multipoint sender/receiver + - #####Returns -MICROBIT_OK on success, MICROBIT_NOT_SUPPORTED if the BLE stack is running. +MICROBIT_OK on success, MICROBIT_NOT_SUPPORTED if the BLE stack is running. ##disable
####
int
disable
() #####Description -Disables the radio for use as a multipoint sender/receiver. +Disables the radio for use as a multipoint sender/receiver. + - #####Returns -MICROBIT_OK on success, MICROBIT_NOT_SUPPORTED if the BLE stack is running. +MICROBIT_OK on success, MICROBIT_NOT_SUPPORTED if the BLE stack is running. ##setGroup
####
int
setGroup
(
uint8_t
group) #####Description -Sets the radio to listen to packets sent with the given group id. +Sets the radio to listen to packets sent with the given group id. + - #####Parameters >
uint8_t
group - The group to join. A micro:bit can only listen to one group ID at any time. #####Returns -MICROBIT_OK on success, or MICROBIT_NOT_SUPPORTED if the BLE stack is running. +MICROBIT_OK on success, or MICROBIT_NOT_SUPPORTED if the BLE stack is running. ##dataReady
####
int
dataReady
() #####Description -Determines the number of packets ready to be processed. +Determines the number of packets ready to be processed. + - #####Returns -The number of packets in the receive buffer. +The number of packets in the receive buffer. ##recv
####
FrameBuffer
recv
() #####Description -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. +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. + - #####Returns The buffer containing the the packet. If no data is available, NULL is returned. !!! note - Once recv() has been called, it is the callers responsibility to delete the buffer when appropriate. + Once recv() has been called, it is the callers responsibility to delete the buffer when appropriate. ##send
####
int
send
(
FrameBuffer \*
buffer) #####Description -Transmits the given buffer onto the broadcast radio. The call will wait until the transmission of the packet has completed before returning. +Transmits the given buffer onto the broadcast radio. The call will wait until the transmission of the packet has completed before returning. + - #####Parameters >
FrameBuffer \*
buffer #####Returns -MICROBIT_OK on success, or MICROBIT_NOT_SUPPORTED if the BLE stack is running. +MICROBIT_OK on success, or MICROBIT_NOT_SUPPORTED if the BLE stack is running. ____ [comment]: <> ({"end":"MicroBitRadio"})