Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Correcting typos and grammar in the uBit.radio documentation page. #41

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Correcting typos and grammar in the uBit.radio documentation page. #41

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 55 additions & 49 deletions docs/ubit/radio.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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...
Expand Down Expand Up @@ -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). |
Expand All @@ -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.

Expand Down Expand Up @@ -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"

Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -303,186 +309,186 @@ int main()
<br/>
####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.

<br/>
####MicroBitRadio( <div style='color:#a71d5d; display:inline-block'>uint16_t</div> id)
#####Description
Constructor.
Constructor.

Initialise the MicroBitRadio .

Initialise the MicroBitRadio .




#####Parameters

> <div style='color:#a71d5d; display:inline-block'>uint16_t</div> 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
<br/>
####<div style='color:#a71d5d; display:inline-block'>int</div> <div style='color:#795da3; display:inline-block'>setTransmitPower</div>( <div style='color:#a71d5d; display:inline-block'>int</div> 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

> <div style='color:#a71d5d; display:inline-block'>int</div> 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
<br/>
####<div style='color:#a71d5d; display:inline-block'>int</div> <div style='color:#795da3; display:inline-block'>setFrequencyBand</div>( <div style='color:#a71d5d; display:inline-block'>int</div> 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

> <div style='color:#a71d5d; display:inline-block'>int</div> 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
<br/>
####<div style='color:#a71d5d; display:inline-block'>FrameBuffer</div> <div style='color:#795da3; display:inline-block'>getRxBuf</div>()
#####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
<br/>
####<div style='color:#a71d5d; display:inline-block'>int</div> <div style='color:#795da3; display:inline-block'>queueRxBuf</div>()
#####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
<br/>
####<div style='color:#a71d5d; display:inline-block'>int</div> <div style='color:#795da3; display:inline-block'>setRSSI</div>( <div style='color:#a71d5d; display:inline-block'>uint8_t</div> rssi)
#####Description
Sets the RSSI for the most recent packet.
Sets the RSSI for the most recent packet.





#####Parameters

> <div style='color:#a71d5d; display:inline-block'>uint8_t</div> rssi - the new rssi value.

!!! note
should only be called from RADIO_IRQHandler...
should only be called from RADIO_IRQHandler...

##getRSSI
<br/>
####<div style='color:#a71d5d; display:inline-block'>int</div> <div style='color:#795da3; display:inline-block'>getRSSI</div>()
#####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
<br/>
####<div style='color:#a71d5d; display:inline-block'>int</div> <div style='color:#795da3; display:inline-block'>enable</div>()
#####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
<br/>
####<div style='color:#a71d5d; display:inline-block'>int</div> <div style='color:#795da3; display:inline-block'>disable</div>()
#####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
<br/>
####<div style='color:#a71d5d; display:inline-block'>int</div> <div style='color:#795da3; display:inline-block'>setGroup</div>( <div style='color:#a71d5d; display:inline-block'>uint8_t</div> 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

> <div style='color:#a71d5d; display:inline-block'>uint8_t</div> 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
<br/>
####<div style='color:#a71d5d; display:inline-block'>int</div> <div style='color:#795da3; display:inline-block'>dataReady</div>()
#####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
<br/>
####<div style='color:#a71d5d; display:inline-block'>FrameBuffer</div> <div style='color:#795da3; display:inline-block'>recv</div>()
#####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
<br/>
####<div style='color:#a71d5d; display:inline-block'>int</div> <div style='color:#795da3; display:inline-block'>send</div>( <div style='color:#a71d5d; display:inline-block'>FrameBuffer \*</div> 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

> <div style='color:#a71d5d; display:inline-block'>FrameBuffer \*</div> 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"})