CodeAIR drones with a homemade remote
How a Firia CodeAIR classroom drone works out of the box, and how a handheld ESP32 game kit was turned into a remote control for it, with both sides written in Python.
1. At a glance
code.pyshort text messages
main.py| Drone | Firia Labs CodeAIR, a small indoor drone that students program in Python |
|---|---|
| Stock drone software | Firia's own build of CircuitPython, plus a flight controller based on the open-source Crazyflie project. Both are left exactly as shipped. |
| What was replaced on the drone | One file: the start-up program, main.py |
| Remote | LAFVIN Retro Game Kit, an ESP32-S3 handheld with a screen and ten buttons. Its game firmware was replaced with CircuitPython. |
| Radio | ESP-NOW, a direct chip-to-chip radio built into every ESP32. No Wi-Fi network, no Bluetooth, no pairing. |
The short version of why this works: the drone's main chip is an ordinary ESP32-S3 that runs whatever Python file it finds at start-up, and it already has a radio that speaks ESP-NOW. So a remote only has to be another ESP32 sending the right short messages, and the drone only needs a start-up file that listens for them.
2. The drone
The Firia Labs CodeAIR is sold to schools with a Python course called Fly with Python. Out of the box it has no remote control. Students write a program in a web page, load it over USB, and the drone flies that program by itself.
Inside, it is really two computers:
| Part | What it is | What it does |
|---|---|---|
| Main chip | ESP32-S3 | Runs the Python program. Handles USB, the radio, the lights, the two buttons, the speaker and the camera. |
| Flight controller | STM32, running firmware based on Crazyflie (it reports itself as "CodeAIR 1.1") | Keeps the drone level and steady hundreds of times a second. Reads the sensors and drives the motors. |
| Motion sensors | Gyroscope and accelerometer, compass, air-pressure sensor | Tell the flight controller which way is up and how the drone is turning. |
| Laser rangers | Three, pointing forward, up and down | Measure distance to a wall, the ceiling and the floor. The down one gives the height. |
| Flow sensor | A tiny low-resolution camera on the bottom | Watches the floor to work out how the drone is sliding. It needs a floor with some pattern on it. |
| Battery | One lithium cell, 600 mAh | Charges through the drone's USB-C port. |
The split matters for everything that follows. The Python side never touches the motors directly. It only tells the flight controller what it wants, such as "hover at 40 cm and drift forward at 20 cm a second", and the flight controller works out the rest.
3. The stock firmware, and how it works
On the main chip
- Firia's build of CircuitPython (version 9.0.4 on these drones). CircuitPython is a small version of Python for microcontrollers.
- A start-up file,
main.py. Whatever is in it runs every time the drone is switched on. From the factory it is two lines:import xflyandxfly.run(). - Built-in modules that the start-up file can use:
Module What it gives you codeairLights, buttons, speaker, battery voltage flightThe link to the flight controller: send flying instructions, read sensor values radioESP-NOW radio that sends and receives plain text xflyFiria's own remote-control program, written for their CodeX handheld - A USB drive called CODEAIR that shows up on a computer. Computers can read it but not write to it.
Programs get onto the drone through the course website (CodeSpace, in Chrome), which sends them down the
USB cable. The last program sent becomes
main.py.
On the flight controller
The flight controller speaks the Crazyflie project's protocol. The main chip uses it for two things:
- Sending "hover" instructions: forward speed, sideways speed, turning speed and a height to hold. These have to keep arriving, or the flight controller stops.
- Reading values back, ten times a second: the three laser distances, which way the drone is facing, and where it thinks it is on its own map of the floor.
Firia's remote mode (xfly)
The factory start-up program waits for a Firia CodeX handheld, pairs with it by infrared, and is then
flown by radio. The useful part is a piece inside it called FlightControl, which runs a flight
through fixed steps and enforces the safety rules:
| Step | What happens |
|---|---|
| On the ground | Waits. Refuses to take off unless it is sitting on the floor. |
| Countdown | About two seconds of warning tone while the flight controller settles. |
| Taking off | Motors start and it rises to about 30 cm. |
| Flying | Follows the remote. Won't move toward anything closer than 30 cm in front or above, and won't go above 3 m. |
| Landing | Comes down and stops the motors. It also does this by itself when the battery falls to 3.2 V. |
Firia's remote only moves the drone forward and back, up and down, and turns it. It has no sideways movement, and when nothing is pressed it simply asks for "zero speed".
4. The new drone program, and how it works
The new program is one Python file that replaces main.py. It does not replace Firia's
firmware. It uses it: the flying is still done by Firia's FlightControl, so all of the
rules in the table above still apply. The new file changes where the instructions come from and adds
what was missing.
What it does, ten times a second
- Reads the radio. Takes every message waiting from the remote and keeps the newest instructions.
- Checks the remote is still there. If nothing has arrived for half a second, it stops moving and lands.
- Reads the sensors from the flight controller.
- Runs the safety checks listed below.
- Works out where to go. Either what the pilot is asking for, or, if the pad is released, back toward the spot it is holding.
- Hands that to Firia's flight code, which applies its own rules and passes it to the flight controller.
- Sends a status message back to the remote: state, height, distances, battery.
- Updates the lights and the black box.
What it adds
| Addition | How it works |
|---|---|
| Sideways sliding | Firia's flight code always asks for zero sideways speed. The new program stands between that code and the flight controller and fills in its own sideways number on the way through. |
| Position hold | When the pad is released, the drone waits a moment to slow down, remembers where it is on its floor map, and from then on steers gently back toward that spot (at most 30 cm a second). In a measured 38-second flight it was typically about 4 cm from its spot, within 11 cm nine-tenths of the time, and 24 cm away at worst. |
| Lower ceiling | 1.5 m in place of 3 m, because the floor sensor loses track higher up. |
| Lost-remote landing | Half a second of silence from the remote and the drone lands itself. |
| Motor cut-offs | Motors stop if the drone tips over, if its speed readings become impossible (it has lost track of the floor), or if a landing hasn't finished after 8 seconds. |
| Several drones, one remote | Every drone runs the same file. Each message names the drone it is for, using the last number of that drone's radio address, and the others ignore it. On the ground, the chosen drone's lights are green and it flashes white when picked. |
| Reset from the remote | After a crash the flight controller locks itself. Holding a button on the remote restarts it. |
| Silence | The warning tones are switched off, at a teacher's request. One setting brings them back. |
| Flight log and black box | A running log of the flight is kept in memory and can be read over USB. A few bytes of permanent memory record how far each takeoff got and the battery voltage, so a freeze or power loss leaves a trace. |
How position hold works
The flight controller keeps a rough map position for the drone, in metres, built up from the flow sensor watching the floor. The hold is a short piece of arithmetic on top of that:
- Remember the map position at the moment the drone settles.
- Each tenth of a second, subtract: how far is the drone from that spot, and in which direction?
- Turn that direction into "forward" and "sideways" from the drone's own point of view, using the way it is facing.
- Ask for a speed toward the spot, in proportion to the distance, with a cap.
If the drone ever ends up more than 60 cm from its spot, it stops chasing and holds the new spot instead. If that happens twice in a flight, the hold turns itself off until the drone lands.
Going back is easy. Pressing a button on the drone in the first two seconds after switch-on
starts Firia's own remote mode instead. Putting the original two-line main.py back, or
running any program from the course website, removes the new program completely.
5. The remote (LAFVIN)
The LAFVIN Retro Game Kit is a handheld built around an ESP32-S3 (16 MB of storage, 8 MB of memory) with a 320×240 colour screen, a D-pad, A and B, and START, SELECT, MENU and OPTION buttons. It is sold as a kit for playing old console games.
Its firmware
| Stock | Now | |
|---|---|---|
| Firmware | A retro game emulator | CircuitPython 10.3.1, using the standard build for a generic ESP32-S3 board with the same chip and memory ("YD-ESP32-S3 N16R8") |
| Program | Built into the firmware | code.py, the remote itself, and safemode.py, a small helper that restarts the chip if it gives up |
| Extra libraries | None. Everything used is built into CircuitPython. |
Before anything was changed, the whole of the original flash memory was copied to a file, so the game firmware can be put back with one command.
What code.py does
- Reads the ten buttons and turns them into four numbers: forward, sideways, up and turn.
- Sends those numbers to the drone 20 times a second, along with any command (take off, land, stop, reset).
- Listens for the drone's status and shows it on the screen: link, state, battery, height, and distance to whatever is in front and above. On the ground it says in plain words why the drone will or won't take off.
- Remembers its settings (speed level, trim, which drone) in the chip's permanent memory.
- Looks after itself. If the program hits an error, it shows the error, saves it, and restarts in four seconds, while the drone lands itself. Every start is recorded with its reason.
The controls
| Button | What it does |
|---|---|
| START, held for 1 second | Take off |
| SELECT | Land |
| MENU | Emergency stop: motors off. Held for 2 seconds on the ground, it resets the drone. |
| D-pad | Forward, back, slide left, slide right |
| B / A | Climb / descend |
| OPTION + D-pad left or right | Turn on the spot |
| OPTION + D-pad up or down | Speed level, 1 to 5 |
| OPTION + A or B | Trim: a small steady push right or left |
| OPTION + SELECT | Switch to the next drone (only while on the ground) |
Hardware details, for anyone repeating this
- Two USB-C ports. Use the one labelled USB. The one labelled COM goes through a slow serial chip.
- Screen: an ILI9341-style panel on SPI. Clock on pin 18, data on 17, with 15, 7, 16 and 6 for command, select, reset and backlight. It needed one orientation setting found by trial.
- Buttons: each connects its pin to ground. Up 11, down 12, left 13, right 14, A 21, B 47, START 39, SELECT 40, MENU 5, OPTION 4.
- Speaker amplifier: always powered. Left unconnected, its three input pins (8, 9, 10) picked up noise and whined. Holding them low fixed it.
6. The radio messages
Both directions use ESP-NOW with short lines of plain text. The remote sends each message straight to one drone's radio address.
Remote to drone, 20 times a second
LAF3,<id>,<command>,<forward>,<right>,<up>,<turn>,<trim>,<drone>
LAF3,12,0,50,0,0,0,0,60 fly forward at 50 cm a second, drone number 60
| Field | Meaning |
|---|---|
id | Goes up by one for each new command. A command is repeated in five messages in case some are lost, and the drone acts on it once. |
command | 0 nothing, 1 take off, 2 land, 3 emergency stop, 4 reset |
forward, right, up | Speeds in cm a second, positive or negative, capped at 100 |
turn | Degrees a second, clockwise positive, capped at 100 |
trim | A small steady sideways push, sent separately so the drone can tell "pad released" from "trimmed" |
drone | The last number of the radio address of the drone this is for. Other drones ignore the message. |
Drone to remote, 10 times a second
AIR2,<state>,<front mm>,<up mm>,<down mm>,<battery mV>,<link lost>,<status bits>
AIR2,4,1830,2210,412,3910,0,30 flying, 41 cm up, 3.91 V
State is 0 on the ground, 1 and 2 during the countdown, 3 taking off, 4 flying, 5 landing and 6 holding a spot.
7. What changed from stock
| Piece | Changed? | Detail |
|---|---|---|
| Drone: CircuitPython firmware | unchanged | Firia's build, as shipped |
| Drone: flight controller firmware | unchanged | As shipped |
| Drone: Firia's modules, including the flight rules | unchanged | Used as they are |
Drone: main.py | replaced | Firia's two lines swapped for the new program. Fully reversible. |
| Remote: firmware | replaced | Game emulator swapped for CircuitPython. A full backup of the original exists. |
| Remote: program | new | code.py and safemode.py |
Nothing was soldered, opened or added to either device.
8. Using any ESP32 as the remote
Nothing here depends on the LAFVIN. ESP-NOW is part of every ESP32 that has Wi-Fi: the original ESP32,
the S2, the S3, the C3 and the rest. Any of them can fly the drone once the drone has the new
main.py. A remote has to do three things:
- Know the drone's radio address. It is the drone's Wi-Fi hardware address, six numbers long,
and one line of Python run on the drone prints it (
wifi.radio.mac_address). The last of the six is the "drone number" that goes at the end of each message. - Send a
LAF3line to that address at least a few times a second. Twenty is what the LAFVIN does. If the drone hears nothing for half a second, it lands. - Optionally, listen for
AIR2lines to show battery and height.
Here is a bare-minimum remote in CircuitPython: two buttons, take off and land. It is cut down from the working remote, but this short version has not itself been flown.
import time
import board, digitalio, espnow
DRONE = b"\xaa\xbb\xcc\xdd\xee\xff" # the drone's radio address
DRONE_NUMBER = DRONE[-1] # last number of that address
link = espnow.ESPNow()
peer = espnow.Peer(mac=DRONE)
link.peers.append(peer)
def button(pin): # a button wired from the pin to ground
b = digitalio.DigitalInOut(pin)
b.switch_to_input(pull=digitalio.Pull.UP)
return b
buttons = ((button(board.IO4), 1), # take off (use whichever pins your board has)
(button(board.IO5), 2)) # land
was_down = [False, False]
cmd_id = cmd = repeats = 0
while True:
for i, (b, command) in enumerate(buttons):
down = not b.value
if down and not was_down[i]: # a fresh press: start a new command
cmd_id = (cmd_id + 1) % 256
cmd, repeats = command, 5
was_down[i] = down
# forward, right, up, turn and trim are all 0 here: the drone just hovers
message = "LAF3,%d,%d,0,0,0,0,0,%d" % (cmd_id, cmd if repeats else 0, DRONE_NUMBER)
if repeats:
repeats -= 1
try:
link.send(message, peer)
except Exception:
pass # a missed message is fine, another follows
while True: # read whatever the drone has sent back
try:
packet = link.read()
except ValueError:
break
if packet is None:
break
if packet.msg.startswith(b"AIR2,"):
print(packet.msg)
time.sleep(0.05)
To steer, put numbers where the zeros are. A joystick, a tilt sensor, a phone app or a second ESP32 on a glove would all work the same way: turn the input into four numbers and send the line.
The same idea carries over to Arduino or MicroPython, since ESP-NOW is the same radio in each. Those were not tried here. Three things were learned the hard way and apply whatever the language:
- The messages must be text. Firia's
radiomodule on the drone expects text, and raw binary data made it throw errors. - The stock drone will not answer. Firia's own remote mode uses its own pairing and messages, which
are not documented. That is why the drone's
main.pyis replaced, and the firmware is left alone. - Check the cable. Some USB-C cables carry power only. The drone lights up and charges, but the computer never sees it.
9. What went wrong along the way
Worth knowing for anyone trying something similar.
Saving files on the drone caused the worst problems. An early version saved the flight log to the drone's drive after every landing. Saving took between 2 and 9 seconds, and for that long the drone could not hear the remote. Worse, one drone lost part of its own program, the kind of damage that happens when power is cut during a save. The program now writes no files at all. Its records go in a small area of memory that is designed to survive power cuts.
The remote would sometimes stop with a screen full of text. A record of every restart was added to find out why. It caught a radio error: the store of incoming messages had become scrambled, and that one error stopped the whole program. The remote now restarts just its radio and carries on.
The takeoff warning is one continuous tone, which the program switches on and off to make beeps. If the program stalls at the wrong moment, the tone never ends.
The floor matters more than the code. The drone knows where it is only by watching the floor. On a plain, shiny floor it drifts, and no program can fully correct that. A floor with a busy, high-contrast pattern made the biggest single difference.
One drone was lost to a crash. It broke the connector to one motor. With three propellers pushing and one not, a drone spins on the floor and flips.
A note on safety and support. This is a teacher's own project and has nothing to do with Firia Labs. The new programs are not Firia's software and Firia does not support them. Drones have spinning propellers: fly low, keep faces away, and keep a thumb near the stop button.