Add API documentation and tutorial for the radio module.

Author: ntoll

docs/ble.rst

@@ -1,9 +1,17 @@
 Bluetooth
 *********
 
-While the BBC micro:bit has Bluetooth Low Energy (BLE) hardware it only has
-16k of RAM. The BLE stack alone takes up 12k RAM which means there's not enough
-room to (currently) run MicroPython.
+While the BBC micro:bit has hardware capable of allowing the device to work as
+a Bluetooth Low Energy (BLE) device, it only has 16k of RAM. The BLE stack
+alone takes up 12k RAM which means there's not enough room to run MicroPython.
 
 Future versions of the device may come with 32k RAM which would be sufficient.
 However, until such time it's highly unlikely MicroPython will support BLE.
+
+.. note::
+    MicroPython uses the radio hardware with the ``radio`` module. This allows
+    users to create simple yet effective wireless networks of micro:bit
+    devices.
+
+    Furthermore, the protocol used in the ``radio`` module is a lot simpler
+    than BLE, making it far easier to use in an educational context.

docs/index.rst

@@ -48,6 +48,7 @@ Projects related to MicroPython on the BBC micro:bit include:
     tutorials/direction
     tutorials/storage
     tutorials/network
+    tutorials/radio
     tutorials/next
 
 .. toctree::
@@ -56,21 +57,22 @@ Projects related to MicroPython on the BBC micro:bit include:
 
    microbit_micropython_api.rst
    microbit.rst
-   pin.rst
-   music.rst
-   image.rst
-   compass.rst
    accelerometer.rst
+   ble.rst
    button.rst
+   compass.rst
    display.rst
-   i2c.rst
-   uart.rst
-   spi.rst
    filesystem.rst
+   i2c.rst
+   image.rst
+   music.rst
+   neopixel.rst
    os.rst
+   pin.rst
+   radio.rst
    random.rst
-   neopixel.rst
-   ble.rst
+   spi.rst
+   uart.rst
 
 .. toctree::
    :maxdepth: 2

docs/radio.rst

@@ -0,0 +1,139 @@
+Radio
+*****
+
+.. py:module:: radio
+
+The ``radio`` module allows devices to work together via simple wireless
+networks.
+
+The radio module is conceptually very simple:
+
+* Broadcast messages are of a certain configurable length (up to 251 bytes).
+* Messages received are read from a queue of configurable size (the larger the queue the more RAM is used). If the queue is full, new messages are ignored.
+* Messages are broadcast and received on a preselected channel (numbered 0-100).
+* Broadcasts are at a certain level of power - more power means more range.
+* Messages are filtered by address (like a house number) and group (like a named recipient at the specified address).
+* The rate of throughput can be one of three pre-determined settings.
+* Send and receieve bytes to work with arbitrary data.
+* As a convenience for children, it's easy to send and receive messages as strings.
+* The default configuration is both sensible and compatible with other platforms that target the BBC micro:bit.
+
+To access this module you need to::
+
+    import radio
+
+We assume you have done this for the examples below.
+
+Constants
+=========
+
+.. py:attribute:: RATE_250KBIT
+
+    Constant used to indicate a throughput of 256 Kbit a second.
+
+.. py:attribute:: RATE_1MBIT
+
+    Constant used to indicate a throughput of 1 MBit a second.
+
+.. py:attribute:: RATE_2MBIT
+
+    Constant used to indicate a throughput of 2 MBit a second.
+
+
+Functions
+=========
+
+.. py:function:: on()
+
+    Turns the radio on. This needs to be explicitly called since the radio
+    draws power and takes up memory that you may otherwise need.
+
+.. py:function:: off()
+
+    Turns off the radio, thus saving power and memory.
+
+.. py:function:: config(**kwargs)
+
+    Configures various keyword based settings relating to the radio. The
+    available settings and their sensible default values are listed below.
+
+    The ``length`` (default=32) defines the maximum length, in bytes, of a
+    message sent via the radio. It can be up to 251 bytes long (254 - 3 bytes
+    for S0, LENGTH and S1 preamble).
+
+    The ``queue`` (default=3) specifies the number of messages that can be
+    stored on the incoming message queue. If there are no spaces left on the
+    queue for incoming messages, then the incoming message is dropped.
+
+    The ``channel`` (default=7) can be an integer value from 0 to 100
+    (inclusive) that defines an arbitrary "channel" to which the radio is
+    tuned. Messages will be sent via this channel and only messages received
+    via this channel will be put onto the incoming message queue. Each step is
+    1MHz wide, based at 2400MHz.
+
+    The ``power`` (default=0) is an integer value from 0 to 7 (inclusive) to
+    indicate the strength of signal used when broadcasting a message. The
+    higher the value the stronger the signal, but the more power is consumed
+    by the device. The numbering translates to positions in the following list
+    of dBm (decibel milliwatt) values: -30, -20, -16, -12, -8, -4, 0, 4.
+
+    The ``address`` (default=0x75626974) is an arbitrary name, expressed as a
+    32-bit address, that's used to filter incoming packets at the hardware
+    level, keeping only those that match the address you set. The default used
+    by other micro:bit related platforms is the default setting used here.
+
+    The ``group`` (default=0) is an 8-bit value (0-255) used with the
+    ``address`` when filtering messages. Conceptually, "address" is like a
+    house/office address and "group" is like the person at that address to
+    which you want to send your message.
+
+    The ``data_rate`` (default=radio.RATE_1MBIT) indicates the speed at which
+    data throughput takes place. Can be one of the following contants defined
+    in the ``radio`` module : ``RATE_250KBIT``, ``RATE_1MBIT`` or
+    ``RATE_2MBIT``.
+
+    If ``config`` is not called then the defaults described above are assumed.
+
+.. py:function:: reset()
+
+    Reset the settings to their default values (as listed in the documentation
+    for the ``config`` function above).
+
+.. note::
+
+    None of the following send or receive methods will work until the radio is
+    turned on.
+
+.. py:function:: send_bytes(message)
+
+    Sends a message containing bytes.
+
+.. py:function:: receive_bytes()
+
+    Receive the next incoming message on the message queue. Returns ``None`` if
+    there are no pending messages. Messages are returned as bytes.
+
+.. py:function:: send(message)
+
+    Sends a message string. This is the equivalent of
+    ``send_bytes(bytes(message, 'utf8'))`` but with ``b'\x01\x00\x01'``
+    prepended to the front (to make it compatible with other platforms that
+    target the micro:bit).
+
+.. py:function:: receive()
+
+    Works in exactly the same way as ``receive_bytes`` but returns
+    whatever was sent.
+
+    Currently, it's equivalent to ``str(receive_bytes(), 'utf8')`` but with a
+    check that the the first three bytes are ``b'\x01\x00\x01'`` (to make it
+    compatible with other platforms that may target the micro:bit). It strips
+    the prepended bytes before converting to a string.
+
+    A ``ValueError`` exception is raised if conversion to string fails.
+
+Examples
+--------
+
+.. include:: ../examples/radio.py
+    :code: python

docs/tutorials/binary_count.gif

@@ -16,6 +16,7 @@ Introduction
     direction
     storage
     network
+    radio
     next
 
 Python is one of the `world's most popular <http://www.tiobe.com/index.php/content/paperinfo/tpci/index.html>`_ programming languages. Every day, without

docs/tutorials/fireflies.gif

@@ -0,0 +1,163 @@
+Radio
+-----
+
+Interaction at a distance feels like magic.
+
+Magic might be useful if you're an elf, wizard or unicorn, but such things only
+exist in stories.
+
+However, there's something much better than magic: physics!
+
+Wireless interaction is all about physics: radio waves (a type of
+electromagnetic radiation, similar to visible light) have some sort of property
+(such as their amplitude, phase or pulse width) modulated by a transmitter in
+such a way that information can be encoded and, thus, broadcast. When radio
+waves encounter an electrical conductor (i.e. an aerial), they cause an
+alternating current from which the information in the waves can be extracted
+and transformed back into its original form.
+
+Layers upon Layers
+++++++++++++++++++
+
+If you remember, networks are built in layers.
+
+The most fundamental requirement for a network is some sort of connection that
+allows a signal to get from one device to the other. In our networking
+tutorial we used wires connected to the I/O pins. Thanks to the radio module we
+can do away with wires and use the physics summarised above as the invisible
+connection between devices.
+
+The next layer up in the network stack is also different from the example in
+the networking tutorial. With the wired example we used digital on and off to
+send and read a signal from the pins. With the built-in radio on the
+micro:bit the smallest useful part of the signal is a byte.
+
+Bytes
++++++
+
+A byte is a unit of information that (usually) consists of eight bits. A bit is
+the smallest possible unit of information since it can only be in two states:
+on or off.
+
+Bytes work like a sort of abacus: each position in the byte is like a
+column in an abacus - they represent an associated number. In an abacus these
+are usually thousands, hundreds, tens and units (in UK parlance). In a byte
+they are 128, 64, 32, 16, 8, 4, 2 and 1. As bits (on/off
+signals) are sent over the air, they are re-combined into bytes by the
+recipient.
+
+Have you spotted the pattern? (Hint: base 2.)
+
+By adding the numbers associated with the positions in a byte that are set to
+"on" we can represent numbers between 0 and 255. The image below shows how this
+works with five bits and counting from zero to 32:
+
+.. image:: binary_count.gif
+
+If we can agree what each one of the 255 numbers (encoded by a byte) represents ~ such as a character ~ then we can start to send text one character per byte
+at a time.
+
+Funnily enough, people have already
+`thought of this <https://en.wikipedia.org/wiki/ASCII>`_ ~ using bytes to
+encode and decode information is commonplace. This approximately corresponds to
+the Morse-code "protocol" layer in the wired networking example.
+
+A really great series of child (and teacher) friendly explanations of "all
+things bytes" can be found at the
+`CS unplugged <http://csunplugged.org/binary-numbers/>`_ website.
+
+Addressing
+++++++++++
+
+The problem with radio is that you can't transmit directly to one person.
+Anyone with an appropriate aerial can receive the messages you transmit. As a
+result it's important to be able to differentiate who should be receiving
+broadcasts.
+
+The way the radio built into the micro:bit solves this problem is quite simple:
+
+* It's possible to tune the radio to different channels (numbered 0-100). This works in exactly the same way as kids' walkie-talkie radios: everyone tunes into the same channel and everyone hears what everyone else broadcasts via that channel. As with walkie-talkies, if you use adjacent channels there is a slight possibility of interference.
+
+* The radio module allows you to specify two pieces of information: an address and a group. The address is like a postal address whereas a group is like a specific recipient at the address. The important thing is the radio will filter out messages that it receives that do not match *your* address and group. As a result, it's important to pre-arrange the address and group your application is going to use.
+
+Of course, the micro:bit is still receiving broadcast messages for other
+address/group combinations. The important thing is you don't need to worry
+about filtering those out. Nevertheless, if someone were clever enough, they
+could just read *all the wireless network traffic* no matter what the target
+address/group was supposed to be. In this case, it's *essential* to use
+encrypted means of communication so only the desired recipient can actually
+read the message that was broadcast. Cryptography is a fascinating subject but,
+unfortunately, beyond the scope of this tutorial.
+
+Fireflies
++++++++++
+
+This is a firefly:
+
+.. image:: firefly.gif
+
+It's a sort of bug that uses bioluminescence to signal (without wires) to its
+friends. Here's what they look like when they signal to each other:
+
+.. image:: fireflies.gif
+
+The BBC have `rather a beautiful video <http://www.bbc.com/earth/story/20160224-worlds-largest-gathering-of-synchronised-fireflies>`_ of fireflies available online.
+
+We're going to use the radio module to create something akin to a swarm of
+fireflies signalling to each other.
+
+First ``import radio`` to make the functions available to your Python program.
+Then call the ``radio.on()`` function to turn the radio on. Since
+the radio draws power and takes up memory we've made it so *you* decide
+when it is enabled (there is, of course a ``radio.off()`` function).
+
+At this point the radio module is configured to sensible defaults that make
+it compatible with other platforms that may target the BBC micro:bit. It is
+possible to control many of the features discussed above (such as channel and
+addressing) as well as the amount of power used to broadcast messages and the
+amount of RAM the incoming message queue will take up. The API documentation
+contains all the information you need to configure the radio to your needs.
+
+Assuming we're happy with the defaults, the simplest way to send a message is
+like this::
+
+    radio.send("a message")
+
+The example uses the ``send`` function to simply broadcast the string
+"a message". To receive a message is even easier::
+
+    new_message = radio.receive()
+
+As messages are received they are put on a message queue. The ``receive``
+function returns the oldest message from the queue as a string, making space
+for a new incoming message. If the message queue fills up, then new incoming
+messages are ignored.
+
+That's really all there is to it! (Although the radio module is also powerful
+enough that you can send any arbitrary type of data, not just strings. See the
+API documentation for how this works.)
+
+Armed with this knowledge, it's simple to make micro:bit fireflies like this:
+
+.. include:: ../../examples/radio.py
+    :code: python
+
+The import stuff happens in the event loop. First, it checks if button A was
+pressed and, if it was, uses the radio to send the message "flash". Then it
+reads any messages from the message queue with ``radio.receive()``. If there is
+a message it sleeps a short, random period of time (to make the display more
+interesting) and uses ``display.show()`` to animate a firefly flash. Finally,
+to make things a bit exciting, it chooses a random number so that it has a 1 in
+10 chance of re-broadcasting the "flash" message to anyone else (this is how
+it's possible to sustain the firefly display among several devices). If it
+decides to re-broadcast then it waits for half a second (so the display from
+the initial flash message has chance to die down) before sending
+the "flash" signal again. Because this code is enclosed within a ``while True``
+block, it loops back to the beginning of the event loop and repeats this
+process forever.
+
+The end result (using a group of micro:bits) should look something like this:
+
+.. image:: mb-firefly.gif
+
+.. footer:: The image of binary counting is released under the licensing details listed here: https://en.wikipedia.org/wiki/File:Binary_counter.gif