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

DroneFiria Labs CodeAIR, a small indoor drone that students program in Python
Stock drone softwareFiria'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 droneOne file: the start-up program, main.py
RemoteLAFVIN Retro Game Kit, an ESP32-S3 handheld with a screen and ten buttons. Its game firmware was replaced with CircuitPython.
RadioESP-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:

PartWhat it isWhat it does
Main chipESP32-S3Runs the Python program. Handles USB, the radio, the lights, the two buttons, the speaker and the camera.
Flight controllerSTM32, 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 sensorsGyroscope and accelerometer, compass, air-pressure sensorTell the flight controller which way is up and how the drone is turning.
Laser rangersThree, pointing forward, up and downMeasure distance to a wall, the ceiling and the floor. The down one gives the height.
Flow sensorA tiny low-resolution camera on the bottomWatches the floor to work out how the drone is sliding. It needs a floor with some pattern on it.
BatteryOne lithium cell, 600 mAhCharges 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

On the flight controller

The flight controller speaks the Crazyflie project's protocol. The main chip uses it for two things:

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:

StepWhat happens
On the groundWaits. Refuses to take off unless it is sitting on the floor.
CountdownAbout two seconds of warning tone while the flight controller settles.
Taking offMotors start and it rises to about 30 cm.
FlyingFollows the remote. Won't move toward anything closer than 30 cm in front or above, and won't go above 3 m.
LandingComes 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

  1. Reads the radio. Takes every message waiting from the remote and keeps the newest instructions.
  2. Checks the remote is still there. If nothing has arrived for half a second, it stops moving and lands.
  3. Reads the sensors from the flight controller.
  4. Runs the safety checks listed below.
  5. 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.
  6. Hands that to Firia's flight code, which applies its own rules and passes it to the flight controller.
  7. Sends a status message back to the remote: state, height, distances, battery.
  8. Updates the lights and the black box.

What it adds

AdditionHow it works
Sideways slidingFiria'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 holdWhen 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 ceiling1.5 m in place of 3 m, because the floor sensor loses track higher up.
Lost-remote landingHalf a second of silence from the remote and the drone lands itself.
Motor cut-offsMotors 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 remoteEvery 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 remoteAfter a crash the flight controller locks itself. Holding a button on the remote restarts it.
SilenceThe warning tones are switched off, at a teacher's request. One setting brings them back.
Flight log and black boxA 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:

  1. Remember the map position at the moment the drone settles.
  2. Each tenth of a second, subtract: how far is the drone from that spot, and in which direction?
  3. Turn that direction into "forward" and "sideways" from the drone's own point of view, using the way it is facing.
  4. 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

StockNow
FirmwareA retro game emulatorCircuitPython 10.3.1, using the standard build for a generic ESP32-S3 board with the same chip and memory ("YD-ESP32-S3 N16R8")
ProgramBuilt into the firmwarecode.py, the remote itself, and safemode.py, a small helper that restarts the chip if it gives up
Extra librariesNone. 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

The controls

ButtonWhat it does
START, held for 1 secondTake off
SELECTLand
MENUEmergency stop: motors off. Held for 2 seconds on the ground, it resets the drone.
D-padForward, back, slide left, slide right
B / AClimb / descend
OPTION + D-pad left or rightTurn on the spot
OPTION + D-pad up or downSpeed level, 1 to 5
OPTION + A or BTrim: a small steady push right or left
OPTION + SELECTSwitch to the next drone (only while on the ground)

Hardware details, for anyone repeating this

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
FieldMeaning
idGoes 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.
command0 nothing, 1 take off, 2 land, 3 emergency stop, 4 reset
forward, right, upSpeeds in cm a second, positive or negative, capped at 100
turnDegrees a second, clockwise positive, capped at 100
trimA small steady sideways push, sent separately so the drone can tell "pad released" from "trimmed"
droneThe 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

PieceChanged?Detail
Drone: CircuitPython firmwareunchangedFiria's build, as shipped
Drone: flight controller firmwareunchangedAs shipped
Drone: Firia's modules, including the flight rulesunchangedUsed as they are
Drone: main.pyreplacedFiria's two lines swapped for the new program. Fully reversible.
Remote: firmwarereplacedGame emulator swapped for CircuitPython. A full backup of the original exists.
Remote: programnewcode.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:

  1. 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.
  2. Send a LAF3 line 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.
  3. Optionally, listen for AIR2 lines 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:

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.