1. Radio syntax
1.1. Radio Module
radio
module allows microbits to send messages to each other via wireless networks.radio
module.- import radio
Import the radio module
from microbit import *
import radio
1.2. Radio On and Off
- radio.on()
Turns the radio on.
- radio.off()
Turns off the radio, thus saving power and memory.
from microbit import *
import radio
radio.on()
1.3. Radio settings
config
is not called then the defaults are used.- radio.config(length=32, queue=3, channel=7, power=6, address=0x75626974, group=0, data_rate=radio.RATE_1MBIT)
Configures various keyword based settings relating to the radio.
The
length
(default=32) defines the maximum length, in bytes, of a message sent via the radio. 1 character = 1 byte. 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 83 (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=6) 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 theaddress
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 theradio
module :RATE_1MBIT
orRATE_2MBIT
.Note
A lower data rate of of 250kbit/sec is supported in micro:bit V1, and may be possible with micro:bit V2, but it is not guaranteed to work on all devices. To access this hidden feature for compatibility with V1 pass
2
to thedata_rate
argument.
- radio.reset()
Reset the settings to their default values for the
config
function.
from microbit import *
import radio
radio.on()
radio.config(group=9, length=251)
- radio.send(message)
Sends a message string. This is the equivalent of
send_bytes(bytes(message, 'utf8'))
but withb'\x01\x00\x01'
prepended to the front (to make it compatible with other platforms that target the micro:bit).
from microbit import *
import radio
radio.on()
radio.config(group=9, length=251)
radio.send('hello')
- radio.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 first three bytes areb'\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 a string fails.
from microbit import *
import radio
radio.on()
radio.config(group=9, length=251)
radio.send('hello')
while True:
message = radio.receive()
if message:
display.scroll(message)
- radio.send_bytes(message)
Sends a message containing bytes.
- radio.receive_bytes()
Receive the next incoming message on the message queue. Returns
None
if there are no pending messages. Messages are returned as bytes.
- radio.receive_bytes_into(buffer)
Receive the next incoming message on the message queue. Copies the message into
buffer
, trimming the end of the message if necessary. ReturnsNone
if there are no pending messages, otherwise it returns the length of the message (which might be more than the length of the buffer).
- radio.receive_full()
Returns a tuple containing three values representing the next incoming message on the message queue. If there are no pending messages then
None
is returned.The three values in the tuple represent:
the next incoming message on the message queue as bytes.
the RSSI (signal strength): a value between 0 (strongest) and -255 (weakest) as measured in dBm.
a microsecond timestamp: the value returned by
time.ticks_us()
when the message was received.
This function is useful for providing information needed for triangulation and/or triliteration with other micro:bit devices.
from microbit import *
import radio
details = radio.receive_full()
if details:
msg, rssi, timestamp = details