PiicoDev Transceiver | Getting Started Guide

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.

Make sure all the ID switches on your Transceiver(s) are OFF before applying power.

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

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.

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.

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!

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.

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.

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.

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!

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. 

We mentioned a few projects in the video for this guide. Here's the code we used to create those demos!