A radio transceiver is a device that can both transmit and receive radio signals, making it the perfect tool for communication on the go and remote projects! The PiicoDev Transceiver™ is a 915MHz radio that can send short messages up to 100m. What you do with those messages is up to you! Perhaps you're interested in collecting data from a remote weather station or controlling a distant piece of hardware.
Contents
- Hardware
- Setup Thonny
- Allow multiple instances of Thonny
- Download/Install PiicoDev Modules
- Transmit and Receive
- Groups and Addresses
- Multiple Transceivers on the same PiicoDev Bus
- Maximising Performance
- Conclusion
- Resources
- Project Ideas
This guide will walk through connecting a PiicoDev Transceiver to a dev. board and sending/receiving simple messages. We'll transmit some data and decide what to do with it on the other end to control some real hardware. To begin, select your dev. board below.
Hardware
We have a couple of options with how to set up the hardware for this guide.
- Option 1: Two of the same dev. board: This is perhaps the simplest approach. Select your dev board below and assemble two Transceivers. The programming setup will be the same for both dev. boards.
- Option 2: Two different dev. boards: This is a great way to demonstrate how the PiicoDev Transceiver makes it easy to send data between different dev boards. It's also a good option if you're working with a Raspberry Pi, as these require a lot of hardware to setup. Having a second, simpler dev. board can simplify the hardware setup.
- Option 3: One dev.board connected to two Transceivers: Great for when you only want to experiment on one dev. board. Check further down this guide for the Multiple Transceivers on the Same PiicoDev Bus section. The other examples in this guide can be used on a single dev. board too - they'll just require a little rework to combine Transmitter/Receiver code into the same script.
To set up a Raspberry Pi Pico you will need:
- A Raspberry Pi Pico (with Soldered Headers) or Pico W (with Soldered Headers)
- A PiicoDev Transceiver
- A PiicoDev Expansion Board for Raspberry Pi Pico
- A PiicoDev Cable
- (Optional) A PiicoDev Platform will keep everything mounted securely.
Plug your Pico into the expansion board. Make sure it is plugged in the correct orientation - Pin 0 on the expansion board should be to the left of the Pico's USB connector.
Connect your Transceiver to the expansion board with a PiicoDev Cable.
To setup a Raspberry Pi with a Transceiver you'll need:
- A Raspberry Pi single board computer (Pictured: Raspberry Pi 4 Model B)
- A PiicoDev Transceiver
- A PiicoDev Adapter for Raspberry Pi
- A PiicoDev Cable (100mm or longer is best for Raspberry Pi)
- (Optional) A PiicoDev Platform will keep everything mounted securely.
Mount the Adapter onto your Pi's GPIO. Make sure it is plugged in the correct orientation - An arrow on the Adapter will point to the Pi's Ethernet connector (on a Pi 3 the Ethernet connector and USB ports are swapped.)
Connect your Transceiver to the Adapter with a PiicoDev Cable.
To set up a micro:bit with a Transceiver you'll need:
- A micro:bit v2
- A PiicoDev Transceiver
- A PiicoDev Adapter for micro:bit
- A PiicoDev Cable
- (Optional) A PiicoDev Platform will keep everything mounted securely.
Plug your micro:bit into the Adapter, making sure the buttons on the micro:bit are facing up.
Connect your Transceiver to the Adapter with a PiicoDev Cable.
Make sure all the ID switches on your Transceiver(s) are OFF before applying power.
Setup Thonny
Allow multiple Instances of Thonny
By default you can only have one Thonny instance running at a time. Working with the Transceiver is much easier if we allow multiple instances of Thonny. This way you can open eg. two Thonny windows, and connect each to a different dev. board. In this case, we'll dedicate one window to each the transmitting and receiving dev. board.
- Click Tools > Options...
- Under the General tab, uncheck Allow only single Thonny instance
Download / Install PiicoDev Modules
To work with PiicoDev hardware, we need to download some drivers. The drivers provide all the functions to easily connect and communicate with PiicoDev hardware. Select your dev board from the options above.
We will need these files to work with the PiicoDev Transceiver:
- Save the following files to your preferred coding directory - In this tutorial, we save to My Documents > PiicoDev.
- Download the PiicoDev Unified Library: PiicoDev_Unified.py (right-click, "save link as").
- Download the device module: PiicoDev_Transceiver.py (right-click, "save link as")
- Upload the files to your Pico. This process was covered in the Setup Thonny section.
The PiicoDev Unified Library is responsible for communicating with PiicoDev hardware, and the device module contains functions for driving specific PiicoDev devices.
We will need these files to work with the PiicoDev Transceiver:
- Save the following files to your preferred coding directory - In this tutorial, we save to My Documents > PiicoDev.
- Download the PiicoDev Unified Library: PiicoDev_Unified.py (right-click, "save link as").
- Download the device module: PiicoDev_Transceiver.py (right-click, "save link as")
- Upload the files to your micro:bit. This process was covered in the Setup Thonny section.
The PiicoDev Unified Library is responsible for communicating with PiicoDev hardware, and the device module contains functions for driving specific PiicoDev devices.
Transmit and Receive
Transmitting
Use the .send()
method to transmit data. send()
accepts strings, values, and (string,value) tuples. The following are all valid ways to use send()
radio.send("Hello, World!") # send a string up to 59 characters long
radio.send(123) # send an integer or floating point number
radio.send( ("my number", 3.14159) ) # send labelled data as a tuple in the form: ("String label", numeric data)
Receiving
Check for new messages using the .receive()
method which returns True
when a new message is received. The message can be read from the .message
attribute. For example, you can print any received data with the following snippet:
if radio.receive():
print(radio.message)
.message
will adopt the type of whatever data type was sent (string, number or labelled data).
Example - Transmit and Receive Data
The following example transmits different kinds of data to a receiver. Make sure your receiver is running the receiver code before running the transmitter code. Your receiver ought to display the different incoming messages in the shell.
Transmitter Code: Transmits three different message types
# Demonstrate how to use the send() command # send() will accept strings, values, and "named values" which # are string,value pairs. from PiicoDev_Transceiver import PiicoDev_Transceiver from PiicoDev_Unified import sleep_ms radio = PiicoDev_Transceiver() # Text messages radio.send("Hello, World!") sleep_ms(1000) # Numbers (integer or floating point) radio.send(123) sleep_ms(1000) # Named Values named_data = ('temperature[degC]', 25.0) radio.send(named_data) sleep_ms(100) named_data = ('humidity[%]', 60.0) radio.send(named_data)
Receiver Code: Prints all received messages to the shell
# Listen for LED control messages # Valid messages set the state of the on-board LED from PiicoDev_Transceiver import PiicoDev_Transceiver from PiicoDev_Unified import sleep_ms radio = PiicoDev_Transceiver() while True: if radio.receive(): message = radio.message print(message) sleep_ms(50)
Remix - Remote Control
Let's create a simple remote controller! We'll set up the transmitter to periodically send On/Off control messages. The receiver will listen for valid messages and update the state of the Transceiver's on-board LED.
Transmitter Code:
# Send LED control messages to a listening receiver from PiicoDev_Transceiver import PiicoDev_Transceiver from PiicoDev_Unified import sleep_ms radio = PiicoDev_Transceiver() state = True while True: if state: radio.send('LED:ON') else: radio.send('LED:OFF') state = not state sleep_ms(1000)
Receiver Code:
# Listen for LED control messages # Valid messages set the state of the on-board LED from PiicoDev_Transceiver import PiicoDev_Transceiver from PiicoDev_Unified import sleep_ms radio = PiicoDev_Transceiver() while True: if radio.receive(): message = radio.message print(message) if message == 'LED:ON': radio.led = True if message == 'LED:OFF': radio.led = False sleep_ms(50)
Groups and Addresses
For projects with more than two Transceivers, you may want to manage radio traffic using groups and addresses.
Transceivers can be configured with a unique radio_address (0->127, default 0) parameter during initialisation. To send a private message to a specific Transceiver, include its address when calling the .send()
method. When the radio_address argument is not included, .send()
broadcasts to address 0
, which all Transceivers listen to.
Send a private message to a specific Transceiver (within the same group) by including its address in .send()
A group is a collection of PiicoDev Transceivers that may communicate. The PiicoDev Transceiver will only ever send/receive messages to/from Transceivers within its group. The group
parameter is a number 0->255 and is set during initialisation (default: 0).
Six PiicoDev Transceivers are shown divided into two groups. Messages may only be sent within a group, they will not cross between groups.
The following example shows:
- how to initialise a PiicoDev Transceiver within a specific group (
group=2
) and with a specific address (radio_address=1
) - how to send a private message within a group (to
address=3
)
from PiicoDev_Transceiver import PiicoDev_Transceiver
from PiicoDev_Unified import sleep_ms
radio = PiicoDev_Transceiver(group=2, radio_address=1) # Initialise this Transceiver in Group:2, as Radio Address 1
radio.send("This is a broadcast to everyone in group two")
sleep_ms(50)
radio.send("whisper to address three", address=3) # within my group!
Multiple Transceivers on the Same PiicoDev Bus
It's possible to connect multiple PiicoDev Transceivers to the same PiicoDev bus. You may want to do this to avoid setting up a second dev. board, or to create some kind of bridge/repeater between two Transceiver groups. In this example we'll set up two Transceivers on the same bus.
Begin by setting up unique IDs - this differentiates the Transceivers. In the initialisation code, we will use the id
argument to differentiate the transceivers. id
is a list that encodes the ID switch positions; 1=ON and 0=OFF. Use a fine pen or similar instrument to set the ID switches as follows:
- The transmitter will have all its ID switches off, and will be initialised with the argument
id=[0,0,0,0]
- the receiver will have ID1:ON and the rest off, and will be initialised with the argument
id=[1,0,0,0]
In this example code the transmitter will continuously send new labelled values. The receiver checks for new messages and prints them to the shell. When you run the code it should generate a nice sine wave in the plotter.
# Demonstrate how to use multiple PiicoDev Transceivers on the same bus from PiicoDev_Transceiver import PiicoDev_Transceiver from PiicoDev_Unified import sleep_ms from math import sin # Initialise two separate radios transmitter = PiicoDev_Transceiver(id=[0,0,0,0]) # each radio needs a unique ID switch setting receiver = PiicoDev_Transceiver(id=[1,0,0,0]) x = 0 # generates a sine wave while True: # TRANSMIT a new value from one Transceiver y = sin(x) # generate a new number transmitter.send( ('sine wave', y) ) # send the number x += 0.2 # increment the control variable sleep_ms(50) # RECEIVE any incoming messages and print if receiver.receive(): message = receiver.message print(message)
The receiver prints all received messages to the shell, generating a sine wave in the plotter.
The following table describes the actual I2C addresses that are selected by the ID switches. Advanced users may prefer to initialise the module with an explicit address, rather than the ID switch argument. It is also possible to define a custom address in user-code by using the .setI2Caddr()
method. Check the Micropython/Python Library and API documentation for more information.
Maximising Performance
From our field tests we've found the radio works well outdoors up to 100m, and indoors to 30m. Radio signals can be interfered with by metal objects and other electronics. For best performance you should keep metal away from each Transceiver's antenna. Other obstructions like walls, buildings and trees will affect the maximum range you can expect.
Over-the-air datarate can impact maximum range. You can trade off data rate for some extension in range. Data rate is set at initialisation by setting the speed
argument to 1, 2 or 3. For example, the following code initialises the Transceiver with the slowest data rate, which should give the maximum range.
radio = PiicoDev_Transceiver(speed=1)
The following table shows valid options for the speed argument.
speed= | Rate (kbps) | Description |
1 | 9.8 | Slowest, longer range |
2 | 115.2 | The default setting. Balanced speed/range performance |
3 | 300 | Fastest, shorter range |
Conclusion
Once you can send and receive data the world is your oyster! We've seen some simple examples with enormous potential - the LED remote controller example may form the foundations for a much more powerful project. Turning and LED on and off isn't too different from controlling an irrigation system or commanding a robot arm. At the end of the day it's all just information being transported from one point to another.
Check out the project ideas we've featured below if you'd like some more inspiration. Until next time, happy making!
Resources
This guide has taken every care to document the PiicoDev Transceiver to be useful for most makers. If you really want to look under the hood and explore the hardware and software, we've provided these additional resources.
- Hardware Repo for the PiicoDev Transceiver PCB
- Schematic
- MicroPython/Python Library and API documentation - Covers advanced library features implemented on the Transceiver that, for brevity, are not included in this guide.
Project Ideas
We mentioned a few projects in the video for this guide. Here's the code we used to create those demos!
Combine some additional PiicoDev hardware with an off-the-shelf Robot Arm Kit to create a radio-controlled Robot Arm!
This project requires
- 2x Dev. Boards and suitable PiicoDev adapters
- 2x PiicoDev Transceivers
- 3x PiicoDev Slide Potentiometers
- 1x PiicoDev Servo Driver
- 1x 3DOF Robot Arm Kit
The transmitter reads the value from each potentiometer, packs the data into a data message and sends the message to the receiver. The receiver unpacks the data message and interprets the values as angles to set for each servo in the robot arm.
This project uses the more advanced .send_bytes()
and .receive_bytes()
methods that give you maximum control over how you structure message payloads. Here, they're used along with pack() and unpack() to cram all three potentiometer values into a single message. At the time of writing, these methods are not compatible with .send()
and receive()
.
Transmitter Code
from PiicoDev_Unified import sleep_ms from PiicoDev_Transceiver import PiicoDev_Transceiver from PiicoDev_Potentiometer import PiicoDev_Potentiometer from struct import pack pot_claw = PiicoDev_Potentiometer(id=[0,1,0,0],minimum=43, maximum=110) pot_luff = PiicoDev_Potentiometer(id=[1,0,0,0],minimum=0, maximum=180) pot_slew = PiicoDev_Potentiometer(id=[0,0,0,0],minimum=10, maximum=170) radio = PiicoDev_Transceiver() while True: data = pack('>fff', pot_slew.value, pot_luff.value, pot_claw.value) radio.send_bytes(data) sleep_ms(20)
Receiver Code
from PiicoDev_Unified import sleep_ms from PiicoDev_Transceiver import PiicoDev_Transceiver from PiicoDev_Servo import PiicoDev_Servo, PiicoDev_Servo_Driver from struct import unpack controller = PiicoDev_Servo_Driver() radio = PiicoDev_Transceiver() claw = PiicoDev_Servo(controller, 3, min_us=600, max_us=2500) luff = PiicoDev_Servo(controller, 2, min_us=600, max_us=2500) slew = PiicoDev_Servo(controller, 1, min_us=600, max_us=2500) while True: if radio.receive_bytes(): # unpack structured data message (3 floating point numbers) angle_slew, angle_luff, angle_claw = unpack('>fff', radio.received_bytes) claw.angle = angle_claw luff.angle = angle_luff slew.angle = angle_slew print('{:3.0f} {:3.0f} {:3.0f}'.format(slew.angle, luff.angle, claw.angle)) sleep_ms(5)
A classic remote data-gathering project! Here we set up a transmitter outdoors to broadcast atmospheric data: Temperature, Barometric Pressure and Relative Humidity.
Our wireless receiver allows us to keep an eye on the weather from the comfort of indoors.
A PiicoDev Transceiver connected to a PiicoDev Atmospheric Sensor. Dev-board not shown. The Atmospheric Sensor samples temperature, barometric pressure, and humidity. |
A PiicoDev Transceiver connected to a PiicoDev OLED Module. Dev-board not shown. Three separate measurements are displayed. |
This project requires:
- 2x Dev. Boards and Adapters
- 2x PiicoDev Transceivers
- 1x PiicoDev Atmospheric Sensor BME280
- 1x PiicoDev OLED Module
- 4x PiicoDev Cables
- Driver files relevant to each PiicoDev module used. Check the guides for each module.
Transmitter Code:
# Weather Station Project - Transmitter # Collect atmospheric data from a PiicoDev Atmospheric Sensor (BME280) and # broadcast labelled values: Temperaure, Barometric Pressure, Relative Humidity # # Required PiicoDev Modules: # • PiicoDev Atmospheric Sensor BME280 # • PiicoDev Transceiver from PiicoDev_Transceiver import PiicoDev_Transceiver from PiicoDev_BME280 import PiicoDev_BME280 from PiicoDev_Unified import sleep_ms radio = PiicoDev_Transceiver() weather = PiicoDev_BME280() while True: tempC, presPa, humRH = weather.values() # read all data from the sensor pres_hPa = presPa / 100 # convert air pressure [Pascals -> hPa] (aka [mbar], if you prefer) print("{:5.2f} °C {:7.2f} hPa {:2.0f} %RH".format(tempC, pres_hPa, humRH)) # Transmit all the data radio.send( ('temperature[degC]', tempC) ) sleep_ms(200) radio.send( ('pressure[hPa]', pres_hPa) ) sleep_ms(200) radio.send( ('humidity[%]', humRH) ) sleep_ms(10000)
Receiver Code:
# Weather Station Project - Receiver # Receive atmospheric data and present on a display # # Required PiicoDev Modules: # • PiicoDev OLED Module # • PiicoDev Transceiver from PiicoDev_Transceiver import PiicoDev_Transceiver from PiicoDev_SSD1306 import create_PiicoDev_SSD1306 from PiicoDev_Unified import sleep_ms radio = PiicoDev_Transceiver() oled = create_PiicoDev_SSD1306() oled.text('hello', 10,10) oled.show() sleep_ms(500) tempC = 0.0 pres_hPa = 0.0 humRH = 0.0 loop_count = 0 while True: # Task 1: Receive and sort any new data if radio.receive(): m = radio.message print(radio.message) if radio.message[0] == "temperature[degC]": tempC = radio.message[1] if radio.message[0] == "pressure[hPa]": pres_hPa = radio.message[1] if radio.message[0] == "humidity[%]": humRH = radio.message[1] # Task 2: Periodically update the display on a much slower period if loop_count >= 200: loop_count = 0 oled.fill(0) temperature_string = str(round(tempC,1)) pressure_string = str(round(pres_hPa,2)) humidity_string = str(round(humRH)) oled.text('Weather Station', 1,0) oled.text(temperature_string + ' degC', 10,25) oled.text(pressure_string + ' hPa', 10,35) oled.text(humidity_string + ' % humidity', 10,45) oled.show() loop_count += 1 sleep_ms(50)
Did you know certain species of fireflies will spontaneously synchronise their flashes? How cool is that!? This project re-creates the firefly synchronisation effect using the on-board LED of the PiicoDev Radio. There's special code included for micro:bits that will take advantage of their brilliant 5x5 LED display for a much bigger light source.
General version
This version of the project uses the Transceiver's onboard LED to represent the firefly flash. It works on Raspberry Pi Pico and Micro:bit. ticks_ms() is not compatible with Raspbery Pi but can be replaced with time.monotonic()
# Simulate the natural phenomenon of synchronised fireflies # Run this code on multiple dev-boards. The Transceiver's LED will blink steadily # Each LED will gradually synchronise with other "fireflies" in the group. # This effect is achieved by sending a timestamp of when *this* firefly is blinking # Other fireflies listen for the timestamp and adjust their blink timing. from PiicoDev_Transceiver import PiicoDev_Transceiver from PiicoDev_Unified import sleep_ms from time import ticks_ms from random import randrange radio = PiicoDev_Transceiver() duration = 1000 period = 3000 last_flash = randrange(0, period) state = False def tune_flash(ref): global last_flash, state now = ticks_ms() err = ref - (now - last_flash) if abs(err) > 50: if state is True: # I'm ahead of another firefly last_flash -= 0.2 * err if state is False: # I'm lagging behind another firefly last_flash += 0.1 * err while True: if radio.receive(): message = radio.message print(message) tune_flash(message) now = ticks_ms() if state is False and now - last_flash > period: radio.led = True state = True last_flash = now # Wait some time before sending the timestamp (prevents RF collisions) wait_time = randrange(0, duration) sleep_ms(wait_time) radio.send(wait_time) if state is True and now - last_flash > duration: radio.led = False state = False sleep_ms(50)
Micro:bit V2 version
This version of the project uses the micro:bit's 5x5 LED display for a more impressive flash.
# Alternative Firefly project, specifically for micro:bit # Simulate the natural phenomenon of synchronised fireflies # Run this code on multiple dev-boards. The micro:bit's LED Display will blink steadily # Each display will gradually synchronise with other "fireflies" in the group. # This effect is achieved by sending a timestamp of when *this* firefly is blinking # Other fireflies listen for the timestamp and adjust their blink timing. from microbit import display from PiicoDev_Transceiver import PiicoDev_Transceiver from PiicoDev_Unified import sleep_ms from time import ticks_ms from random import randrange radio = PiicoDev_Transceiver() display.on() duration = 1000 period = 3000 last_flash = randrange(0, period) state = False def tune_flash(ref): global last_flash, state now = ticks_ms() err = ref - (now - last_flash) if abs(err) > 25: if state is True: # I'm ahead of another firefly last_flash -= 0.2 * err if state is False: # I'm lagging behind another firefly last_flash += 0.1 * err def update_display(state): if state is True: for x in range(5): for y in range(5): display.set_pixel(x,y,9) else: display.clear() while True: if radio.receive(): message = radio.message tune_flash(message) now = ticks_ms() if state is False and now - last_flash > period: state = True last_flash = now update_display(state) # Wait some time before sending the timestamp (prevents RF collisions) wait_time = randrange(0, round(0.5*duration)) sleep_ms(wait_time) radio.send(wait_time) if state is True and now - last_flash > duration: state = False update_display(state) sleep_ms(50)