@popolony2k

Building a Custom Drone Controller from Scratch — Part 5: BLE HID Gamepad Host

In the original Macross series, the SDF-1 doesn’t set out to fight anyone. It launches because an alien fleet is already on its way and there is no other choice. The ship is barely understood, its fold drive untested, its crew a mix of civilians and soldiers who never signed up for an interstellar war. They leave Earth with what they have, figure out the rest along the way, and somehow keep flying.

That’s roughly the spirit in which this project approaches Bluetooth gamepad support.

After Part 4, the drone flew. Tilt control — mapping the AtomS3’s accelerometer to roll and pitch — worked well enough to navigate a room. But holding a small board at a precise angle for minutes at a time is genuinely tiring. Fatigue tremors start showing up in the roll and pitch axes. After a few sessions the wrists were unhappy and the drone was responding to them more than to intent.

The obvious solution: a gamepad. The ESP32-S3 has a Bluetooth radio. Gamepads speak Bluetooth. The SDF-1 had a fold drive. Let’s fire it up and see where we end up.

The Fold Drive — BLE HID Host

The ESP32-S3 supports BLE — Bluetooth Low Energy. The Arduino ESP32 platform ships a BLE library (BLEDevice.h) that can act as a HID host: scan for devices advertising the HID service (UUID 0x1812), connect, subscribe to Input Report notifications, and read raw bytes. No extra lib_deps entry required — the library is already aboard.

The approach is deliberately simple. No gamepad abstraction layer, no universal report parser. Scan for HID, connect, log the raw bytes, figure out the format, map it to flight axes. Every controller does its own thing with HID reports, so the format has to be discovered per-device anyway.

Following the project’s discipline on dependencies, all of this lives in src/bt/ble_gamepad.cpp. Nothing outside that file ever sees a BLEDevice or a BLEClient. The rest of the firmware receives a GamepadAxes struct — normalised values in [−1, 1], fully decoded — and never knows whether they came from Bluetooth, a touchscreen, or a Zentradi battle pod.

The fold drive is spinning. Now we need somewhere to go.

Unexpected Destination — the iPega PG-9021S

In Macross, the first fold jump doesn’t go where anyone planned. The SDF-1 executes the fold and ends up near Pluto — not Earth orbit, not anywhere useful — with the entire civilian city of Macross dragged along for the ride. It is not the mission. But the ship is intact, the crew is alive, and they have no choice but to work with where they are.

The first controller in hand was an iPega PG-9021S — a telescoping gamepad designed for phones, with two analog sticks, a D-pad, four face buttons, and shoulder triggers. It supports multiple pairing modes triggered by different button combos at power-on.

The first attempt: HOME + X — Android Standard Gamepad mode. The controller connected, appeared in the BLE scan, handshaked — and then disconnected. Every time. The root cause, after some digging, was BLE bonding. Standard Gamepad mode requires a security handshake that the ESP32 Arduino BLE library doesn’t perform. Without it, the controller politely refuses to stay paired.

The second attempt: HOME + A. Connected. Stayed connected. Data flowing.

This is an undocumented mode added in a 2019 iPega firmware update, officially called “Direct Play.” Designed for mobile games that read touch input directly, bypassing Android’s controller API entirely. The name should have been a warning about the destination.

In HOME+A mode, the iPega does not present itself as a gamepad. It presents itself as a touchscreen.

Not Pluto. But intact. And flying.

Reverse-Engineering Zentradi Technology — the 17-Byte Report

The Zentradi’s technology was incomprehensible to humans at first contact. It took time, captured ships, and a lot of dangerous guesswork to figure out what any of it actually did. The understanding, when it came, was hard-won.

When the iPega connects in HOME+A mode, it advertises HID Usage Page 0x0D (Digitizer), Usage 0x04 (Touch Screen). Every input report is 17 bytes — four 4-byte contact blocks, followed by a 1-byte contact count. Exactly how a multi-touch phone screen reports fingers.

Each 4-byte contact block is little-endian bit-packed:

bit 0:      Tip Switch (1 = finger touching)
bit 1:      In Range
bits 2–3:   padding
bits 4–7:   Contact ID (always 0 — both sticks share it)
bits 8–19:  X coordinate  (0–1200)
bits 20–31: Y coordinate  (0–2200, top = 0)

Extracting X and Y from bytes b[1], b[2], b[3]:

uint16_t X = b[1] | ((b[2] & 0x0F) << 8);
uint16_t Y = (b[2] >> 4) | (b[3] << 4);

The controller’s screen is portrait internally, held in landscape. Physical UP/DOWN maps to X (up = X increases); LEFT/RIGHT maps to Y (left = Y increases).

Both sticks report Contact ID 0 — there is no field to distinguish left from right. The solution: Y coordinate. Values below 1000 are the left stick area; 1000 and above are the right stick area. The virtual touchscreen was laid out with enough separation that this split is reliable.

Technology understood. Now it can be used.

Calibration — Learning to Aim

Hikaru Ichijo wasn’t a natural in a Valkyrie on day one. He logged hours in the simulator, then more hours in real combat, learning how the machine responded before he could trust it.

Calibration here was simpler: move each stick to its extremes and resting center while logging raw reports. The numbers that came out:

Axis	Stick	Coordinate	Center	Range
Throttle	Left UP/DOWN	X	523	±300
Yaw	Left LEFT/RIGHT	Y	500	±240
Pitch	Right UP/DOWN	X	533	±145
Roll	Right LEFT/RIGHT	Y	1650	±120

Each axis normalises to [−1, 1]: (coordinate − center) / range. The result then passes through the same dead zone, expo curve, and slew-rate limiter used by the tilt controller — so switching between control modes doesn’t change the feel of the drone.

Both drones run altitude-hold firmware. Center stick means maintain altitude; deflect to climb or descend; release and the drone hovers wherever it is. The critical detail: the moment the stick returns inside the dead band, throttle snaps immediately back to neutral (0x80). Leave a residual value and the drone keeps climbing forever. Get that snap-back right and altitude control feels natural.

The FAST Packs — Mapping the Buttons

The FAST Packs in Macross weren’t part of the original Valkyrie design. They were add-ons — extra weapon and propulsion modules bolted onto a frame that was never built to carry them. They worked because the engineers understood the underlying system well enough to extend it.

Buttons in HOME+A mode appear as additional touch contacts at fixed (x, y) positions. The iPega is emulating PUBG Mobile’s on-screen button layout — each physical button maps to a virtual finger tap on a specific point of the touchscreen. There is no HID button bitmask. Discovery was purely empirical: press one button at a time, log the 17-byte report, note the coordinates.

Button	x	y	Drone command
A	332	2044	Arm + takeoff
B	780	1281	Land
X	241	1270	Emergency stop
Y	818	2020	360° flip
D-pad UP	723	544	Headless mode toggle
D-pad DOWN	352	562	Calibrate gyro
D-pad LEFT	534	379	Toggle screen on/off
LT	1173	416	Lock motors
R1	578	2041	Unlock motors

Detection uses ±30 pixel tolerance on each coordinate. Contacts are checked against this table before the stick zone classifier, so a button press near a zone boundary doesn’t accidentally register as axis movement.

Nine buttons. Working. The FAST Packs are on.

A Battle Won, A War Lost — the L1/RT/L3/R3 Investigation

Not every engagement in Macross ends cleanly. There are missions where the Valkyrie comes back intact but the objective wasn’t fully achieved — where you did everything right and it still wasn’t enough, for reasons outside your control.

Four buttons — L1, RT, L3, R3 — never appeared in any log. No contact, no matter how hard or how long they were pressed.

The controller was opened. The switches under all four had cracked solder joints — a common failure on telescoping gamepads that get repeatedly flexed. All four were resoldered. The controller went back together.

Plugged into an Android phone running a gamepad test app, in Standard Gamepad mode (HOME+X): all four buttons registered immediately. Clean signals. The hardware was fixed.

Back on the AtomS3, in HOME+A mode, with both analog sticks held deflected to keep two contacts active: press L1. The contact count never reached three. No third contact appeared for L1, RT, L3, or R3, in any combination.

The explanation is in what Direct Play mode actually emulates. PUBG Mobile’s touchscreen UI was designed for a phone. It never had L1, RT, L3, or R3 — those concepts don’t exist in a mobile touch game. The iPega’s firmware never assigned those buttons a position on the virtual screen. The hardware repair was real and complete. The limitation is a protocol design decision made years ago for a different platform entirely.

“It registers in Android’s controller test” and “it generates a contact in this HID profile” are two different questions. This was a useful reminder that confirming something works in one context says nothing about whether it works in another. The battle with the solder joints was won. The war for those four buttons was already lost before the controller was even opened.

We fly with nine.

The Zentradi Main Fleet — 8BitDo

In Macross, the first Zentradi ships are manageable. A squadron here, a patrol fleet there. The SDF-1 fights them off, learns their patterns, adapts. Then the main fleet arrives. Seven million warships. Not a battle. A wall.

With the iPega working, a natural question arose: could a proper console-style gamepad work? On hand: an 8BitDo SF30 Pro, an 8BitDo Zero 2, an 8BitDo Ultimate 2C, and an Xbox One S. All marketed as Bluetooth controllers. None of them connected. Every BLE scan came back empty.

LightBlue, a Bluetooth scanner app on a phone, also saw nothing from these controllers. But Android’s native Bluetooth pairing screen found the 8BitDo Zero 2 and Ultimate 2C instantly — listed as “Pro Controller.”

That name was the answer. “Pro Controller” is Nintendo’s Switch Pro Controller. 8BitDo’s Switch-emulation mode — activated by X+Start or the model-specific equivalent — makes the controller advertise itself as one. Android finds it because Android’s Bluetooth stack supports Classic Bluetooth, known as BR/EDR. The Pro Controller protocol runs over BR/EDR.

The ESP32-S3 does not support BR/EDR. There is no Classic Bluetooth radio on the die. This isn’t a software configuration — it’s the chip itself. Espressif’s own datasheet confirms it. The Bluepad32 project’s FAQ states it plainly:

“Only BLE gamepads are supported on ESP32-S3, since BR/EDR is not supported… Controllers like Switch, Wii, DualSense, DualShock, etc. only talk BR/EDR.”

Every failed attempt was the correct outcome. Four controllers, many pairing modes, many attempts. All correct. No sequence, no library, no firmware trick changes this. It is the hardware. The only ESP32 variant with a dual-mode radio — BLE and BR/EDR together — is the original ESP32, not the S3, C3, C6, or H2 variants. The AtomS3 runs an S3.

Seven million warships. This one doesn’t get won today.

Do You Remember Love — What We Have

At the end of Macross, Earth is not what it was. The battle left marks that don’t erase. But Hikaru is alive. Misa is alive. The SDF-1 is battered but standing. And somewhere in the ruins, Minmay is still singing — because culture and music turned out to matter more than anyone expected, and the proof of that is that anyone is around to remember it.

The BLE gamepad mode works. The iPega PG-9021S in HOME+A mode — a touchscreen disguised as a gamepad, discovered by accident when the obvious path was blocked — gives full analog control of all four flight axes plus nine functional buttons. The flight feel matches the tilt controller for roll and pitch, with the ergonomic advantage of a real grip in your hands instead of a board held sideways.

Nine of thirteen buttons. Four will never come. SELECT and START are reserved by the controller’s firmware for mode-switching and never appear in any HID report. The iPega works with what it is, which is more than enough to fly.

8BitDo controllers cannot work on this hardware. The AtomS3’s ESP32-S3 simply does not have the radio they speak. That question has been asked thoroughly, answered conclusively, and put to rest.

The SDF-1 didn’t come home with everything it left with. But it came home. The drone flies. And somewhere out there, the universe is still very large.

Next: a second drone arrives, with a completely different protocol hidden inside — and it took a packet capture to find out what it actually spoke.

Enjoy — PopolonY2k

Building a Custom Drone Controller from Scratch — Part 4: Accelerometer Tilt Control

If you’ve seen Pacific Rim, you know the core idea behind a Jaeger: a pilot doesn’t push buttons to make the giant robot punch — they punch, and the robot punches with them. The machine reads the pilot’s body and mirrors it. That’s the exact idea behind the first control mode I built for the Maritaca Force 1 and Dr.One drones: you tilt the controller, the drone tilts with you.

No joystick, no buttons for movement — just an M5Stack AtomS3 in your hand, leaning the way you want the drone to fly. In this article I’ll walk through how that actually works under the hood: turning raw motion-sensor numbers into smooth flight commands, the gesture I use for throttle (which is not tilt-based, for a good reason), and a yaw-control redesign that turned out to accidentally fix a completely unrelated bug.

The big idea: tilt is data, not magic

Inside the AtomS3 sits a small chip that measures two different things: acceleration (how the board is oriented relative to gravity) and rotation rate (how fast it’s spinning). Tilt the board to the left, and gravity “pulls” more on one axis than another — from that pull, we can calculate an angle. That angle is the only ingredient we need for roll and pitch.

float pitchDeg = atan2f(imu.ax, sqrtf(imu.ay * imu.ay + imu.az * imu.az)) * (180.0f / M_PI);
float rollDeg  = atan2f(imu.ay, sqrtf(imu.ax * imu.ax + imu.az * imu.az)) * (180.0f / M_PI);

Don’t worry about the trigonometry — the short version is: atan2f converts the raw gravity readings on each axis into an angle in degrees. Tilt the board 15° to the right, and rollDeg comes out as roughly 15. That’s it. From here on, it’s all about turning that number into something a drone can actually use safely.

From a raw angle to a flight command

If we sent that raw angle straight to the drone, two things would go wrong immediately. First, your hand is never perfectly still — even resting flat, there’s a tiny natural tremor that the sensor happily reports as “tilt.” Second, a twitchy, instant response to every micro-movement would make the drone feel nervous and hard to fly precisely.

Two small ideas fix both problems:

Dead zone — ignore any tilt smaller than about 10°. Below that threshold, we treat the board as “flat,” even if the sensor reports a tiny non-zero number. This is what keeps the drone from drifting on its own just because your hand isn’t a tripod.
Expo curve — once you’re past the dead zone, small additional tilts produce small movements, and big tilts produce big movements, but the relationship isn’t a straight line — it curves, so fine control near the center is easier and the extremes are still reachable.

uint8_t AccelController::mapAxis(float value, float maxRange, float deadZone, float expo) {
    if (fabsf(value) &lt; deadZone) return 0x80; // 0x80 = neutral, dead-center

    float sign   = value &gt; 0.0f ? 1.0f : -1.0f;
    float scaled = (fabsf(value) - deadZone) / (maxRange - deadZone);
    if (scaled &gt; 1.0f) scaled = 1.0f;

    scaled = scaled * ((1.0f - expo) + expo * scaled); // the "curve"
    return (uint8_t)((0.5f + sign * scaled * 0.5f) * 254.0f);
}

One more ingredient, and this is the one that actually makes it feel like piloting rather than flicking a switch: a slew rate limiter. Even if you snap the board from flat to a hard tilt instantly, the output value isn’t allowed to jump instantly — it ramps there over a fraction of a second. It’s the same principle as a car’s steering having weight to it instead of feeling like an on/off switch. Tiny detail, huge difference in how trustworthy the drone feels in your hand.

Throttle: the one gesture that isn’t tilt

Here’s a detail that surprised me during testing: both drones run what’s called altitude-hold firmware. Left alone, they actively fight to stay at whatever height they’re already at — like a Jaeger’s auto-balance systems quietly correcting your footing so you don’t topple over. That’s great for a beginner-friendly drone, but it means throttle can’t just be “tilt forward = climb” the way roll and pitch are tilt-based. Instead, throttle uses the only physical button on the AtomS3:

Press and hold the screen button → climb
Click once, then press and hold → descend
Let go → the drone snaps back to hovering at whatever height it just reached

That last part — snapping back to neutral the instant you release — took a real bug to discover. My first version kept whatever throttle value you’d built up even after you let go, which sounds harmless until you realize it means the drone keeps climbing (or sinking) forever after you’ve stopped touching anything. On altitude-hold firmware, “neutral” isn’t zero — it’s “stay right here,” so the fix was just snapping back to that neutral value the moment your thumb leaves the button.

The yaw redesign: when “more realistic” makes things worse

This is the part of the story I actually want to tell, because it’s a good example of a control scheme that looked elegant on paper and was miserable in practice.

My first idea for yaw (spinning the drone left/right in place) was to use the gyroscope’s twist-rate — physically rotate the flat board like a steering wheel lying on a table, and the drone spins to match. It’s the most “drift-compatible-pilot” idea of the whole project: your hand’s rotation becomes the robot’s rotation, no abstraction in between.

It was also nearly unflyable. Twisting a small board flat on your palm, with enough precision to stop exactly where you want, turns out to be a genuinely hard physical motion — much harder than tilting it, which your wrist already does naturally. Worse, any tiny ambient drift in the gyroscope reading (sensors are never perfectly zeroed) had a path all the way to the drone’s yaw command, which I suspect caused an unrelated mystery: the drone would slowly spin on the ground before even taking off, for no command I could find in the logs.

The fix ended up being almost embarrassingly simple. Instead of inventing a new gesture, I reused the existing one: a single click of the screen button toggles a “yaw mode,” and while it’s on, the same left/right tilt that normally controls roll gets rerouted to control yaw instead:

out.roll  = yawModeActive ? DroneAxis::NEUTRAL    : (uint8_t)_currentRoll;
out.yaw   = yawModeActive ? (uint8_t)_currentRoll : DroneAxis::NEUTRAL;

Click once, tilt left/right to spin in place; click again, and the same tilt goes back to strafing. No new motion to learn, and the gyroscope is no longer involved in flight at all — which meant that mystery ground-spin bug disappeared the moment this shipped, without me touching it directly. Sometimes the best fix for a bug is removing the entire mechanism it was hiding in.

What’s next

Tilt control gets you flying with nothing but your hand and a tiny screen, but it has a ceiling — there’s only so much precision your wrist can offer, and only one physical button to work with. In the next article, I’ll cover the second control mode I built: a full Bluetooth gamepad host running directly on the ESP32, including a very unexpected discovery about how a $15 controller pretends to be a touchscreen.

Enjoy

[]’s
PopolonY2k

Building a Custom Drone Controller from Scratch — Part 3: Firmware Architecture (HAL Pattern, Non-Blocking Loop, and the Flight State Machine)

In Part 1 we talked about why this project exists and what hardware it runs on, and in Part 2 we reverse-engineered the UDP protocol that lets an M5Stack AtomS3 talk to a cheap WiFi toy drone. Before going further into flight control and gamepad support, it’s worth stopping to look at how the firmware itself is put together — because the same skeleton ends up driving two completely different drones (Maritaca Force 1, the black E58-protocol drone, and Dr.One, the grey FLOW-WIFI drone) and two completely different input methods (accelerometer tilt and a Bluetooth gamepad) without duplicating the flight logic.

The full source is on GitHub: github.com/popolony2k/maritaca-e88-controller.

A quick tour of the project structure

The firmware is built with PlatformIO, using plain .cpp/.h files (no .ino) so everything can be unit-structured and reasoned about like normal C++. The layout looks like this:

src/
├── main.cpp                  # wiring + non-blocking main loop
├── hal/
│   ├── hal.h                  # BoardHal, DisplayHal, ImuHal, ButtonHal
│   ├── m5atoms3.h
│   └── m5atoms3.cpp           # only file that includes M5Unified.h
├── imu/
│   └── accelerometer.h/.cpp   # ImuData struct, filtering
├── comm/
│   ├── drone_protocol_base.h  # abstract DroneProtocolBase interface
│   ├── drone_protocol.h/.cpp  # WIFI_8K_ black drone (E58 8-byte)
│   ├── flow_wifi_protocol.h/.cpp # FLOW-WIFI grey drone (88-byte)
│   └── wifi_manager.h/.cpp    # WiFi station + auto-detect scan
├── bt/
│   ├── gamepad_axes.h         # normalized axes, no BLE deps
│   └── ble_gamepad.h/.cpp     # BLE HID host (iPega, 8BitDo)
├── control/
│   ├── accel_controller.h/.cpp   # tilt → roll/pitch/yaw/throttle
│   ├── gamepad_controller.h/.cpp # gamepad axes → DroneState
│   ├── flight_controller.h/.cpp  # the state machine
│   └── operation_mode.h
└── ui/
    └── display.h/.cpp         # pure renderer

Three ideas repeat throughout this tree, and they’re the subject of the rest of this article:

A hardware abstraction layer (HAL) that keeps the M5Stack SDK out of almost every file.
A non-blocking main loop built entirely on millis() — no delay(), anywhere.
A flight state machine that’s shared by both drones and both input modes.

The HAL: one file gets to know about M5Unified

M5Unified is a great library — it gives you the display, the IMU, the button and the power management of the AtomS3 behind one consistent API. The problem is that once #include <M5Unified.h> shows up in a file, that file is now tied to this specific board. For a project that already juggles two drone protocols and two control schemes, we didn’t want a third axis of “which file is allowed to touch the hardware.”

So the rule is simple: only src/hal/m5atoms3.cpp includes M5Unified.h. Everything else — the flight controller, the display renderer, the accelerometer filter — talks to a set of plain interfaces defined in hal.h:

struct BoardHal {
    void (*begin)           ();
    void (*update)          ();
    int  (*getBatteryLevel) ();   // 0/25/50/75/100 in %
    bool (*isCharging)      ();   // always false on this hardware
};

struct ButtonHal {
    bool (*wasPressed)  ();
    bool (*wasReleased) ();
    bool (*pressedFor)  (uint32_t ms);
};

These are structs of function pointers, not abstract classes with virtual methods. The implementation, in m5atoms3.cpp, fills them in with non-capturing lambdas:

const BoardHal kBoard {
    .begin           = [] { auto cfg = M5.config(); M5.begin(cfg); },
    .update          = [] { M5.update(); },
    .getBatteryLevel = [] { return batteryLevel(); },
    .isCharging      = [] { return false; },
};

const ButtonHal kButton {
    .wasPressed  = []()            -> bool { return M5.BtnA.wasPressed(); },
    .wasReleased = []()            -> bool { return M5.BtnA.wasReleased(); },
    .pressedFor  = [](uint32_t ms) -> bool { return (bool)M5.BtnA.pressedFor(ms); },
};

A non-capturing lambda — one that doesn’t reference any outside variables — has no state of its own, so it decays to a plain function pointer at compile time. There’s no closure object, no heap allocation, no vtable lookup. kBoard.update() compiles down to exactly the same code as calling M5.update() directly, but every other file in the project now depends on hal.h (a tiny, dependency-free header) instead of the entire M5Unified SDK.

This pays off in a very concrete way: the battery-level logic — reading GPIO8/ADC2 through a voltage divider, averaging samples, applying hysteresis around the 25/50/75% boundaries — lives entirely inside m5atoms3.cpp as a couple of small static functions. The flight controller and the display just call kBoard.getBatteryLevel() and get back a number from 0–100. When the battery calibration changed (we covered that story in an earlier debugging session), not a single line outside m5atoms3.cpp needed to change.

A loop with no `delay()`

The AtomS3 in this project is doing a lot at once: polling a button, running an IMU filter, talking to a BLE gamepad, maintaining a WiFi connection, sending UDP control packets at a fixed rate, and redrawing a small LCD — all from a single loop(). If any one of those used delay(), everything else would stall for that duration. A drone waiting for its next 40 ms control packet doesn’t care that the display “only” wanted to sleep for 10 ms.

So the project has a hard rule: no delay() in loop(), ever. Every periodic task instead remembers the last time it ran and checks millis() on every pass:

static uint32_t _lastDisplayMs = 0;
static constexpr uint32_t DISPLAY_INTERVAL_MS = 100; // 10 Hz

void loop() {
    kBoard.update();
    wifi.update();
    imu.update(kImu);

    // ... gamepad + flight controller update, every iteration ...

    uint32_t now = millis();
    if (now - _lastDisplayMs >= DISPLAY_INTERVAL_MS) {
        _lastDisplayMs = now;
        display.update(/* ... */);
    }
}

The same pattern shows up at every layer, each with its own cadence chosen for a reason:

Drone control packets go out at ~25 Hz (every ~40 ms) — fast enough for responsive flight, matching what the original Android app does.
The keepalive packet (AA 80 80 00 80 00 80 55) fires every ~790 ms when the sticks are idle, so the drone doesn’t think the link has died.
The display redraws at 10 Hz — plenty for human eyes, and it keeps SPI traffic from competing with the more time-critical UDP and BLE work.
BLE scanning uses 5-second timed windows, restarted every 6 seconds while no gamepad is connected.

Because every one of these is just “a timestamp and a constant,” loop() can run thousands of times a second, doing almost nothing on most iterations and exactly the right thing the moment any of those windows elapses. Nothing ever blocks anything else.

One subtlety we ran into directly because of this design: WiFiUDP::begin() needs WiFi.mode() to have been called at least once to initialize the ESP32’s network stack — even on builds where WiFi is never actually connected. Skip it, and the drone protocol driver crashes during setup(), producing a silent boot loop. It’s a good reminder that “non-blocking” and “stateless” aren’t the same thing — some subsystems still have a required initialization order, even if nothing about them looks synchronous.

The flight state machine

All of the above exists to support the actual brain of the firmware: FlightController. It’s a small state machine with six states:

enum class FlightState {
    Idle,        // disarmed, sending keepalive packets
    Calibrating, // sending CaliGyro for 1.5 s before arming
    Arming,      // Unlock, then TakeOff
    Flying,      // active flight, 25 Hz control packets
    Landing,     // sending Land for 2 s, then back to Idle
    Emergency,   // EmergStop, then immediately back to Idle
};

The normal lifecycle is exactly what you’d expect:

Idle ──(double-click + WiFi ok)──▶ Calibrating ──▶ Arming ──▶ Flying
Flying ──(double-click)──▶ Landing ──▶ Idle
any state ──(triple-click)──▶ Emergency ──▶ Idle

Every transition goes through one function, enterState(), which resets all the per-state bookkeeping (button click counters, one-shot command timers, the “is this the first frame in this state” flag) and logs the transition to Serial. runState() then does whatever that state needs to do every frame: send the right command bytes, check elapsed time, and decide whether it’s time to move on.

Gestures, not menus

Remember — the only physical input in ACCEL mode is a single screen button (BtnA). Every gesture has to be encoded in click count and timing:

Single click in Flying toggles yaw on/off.
Double click in Idle arms and takes off (if WiFi is connected); double click in Flying starts landing.
Triple click, from any state, is an immediate emergency stop.
Press-and-hold (ACCEL mode, while Flying) drives the throttle — first hold = climb, click-then-hold = descend.

All of this is decided by a small amount of state — _clickCount, _lastReleaseMs, _buttonDown — updated once per frame in handleButton(). A click only “counts” once the double-click window (DOUBLE_CLICK_MS = 1000) has elapsed without a follow-up press, which is what lets a double-click and a hold-after-click (the throttle-down gesture) coexist on the same physical button.

In BLUETOOTH mode, the same state machine is driven by handleGamepadButtons() instead — rising edges on the gamepad’s button bitmask map directly to the same transitions (A = arm, B = land, X = emergency, etc.), so runState() itself doesn’t need to know or care which input method is active.

One state machine, two drones

This is the part that ties back to Part 2. Maritaca Force 1 (the WIFI_8K_ / E58-protocol drone) needs the full Calibrating → Arming(Unlock → TakeOff) → Flying sequence. Dr.One (the FLOW-WIFI drone) auto-arms the moment it receives a single TakeOff toggle — sending it through a multi-second calibration dance would just be wrong for that hardware.

Rather than branch the state machine on “which drone is this,” the abstract DroneProtocolBase interface exposes a single capability flag:

// FlightController::handleDoubleClick()
enterState(_deps.drone.supportsArmSequence()
           ? FlightState::Calibrating   // Maritaca Force 1
           : FlightState::Flying);      // Dr.One — auto-arms on TakeOff

and enterState() fires the one-shot TakeOff command itself when that flag is false:

if (s == FlightState::Flying) {
    _accel.begin();
    _gamepad.begin();
    if (!_deps.drone.supportsArmSequence()) {
        _oneShotCmd   = DroneCmd::TakeOff;
        _oneShotUntil = millis() + 1000;
    }
}

Everything else — gesture handling, throttle hold, the altitude-hold throttle logic, the landing and emergency paths — is shared. Swapping drones at boot is just a matter of which concrete DroneProtocolBase implementation gets injected into FlightController‘s constructor; WifiManager::scanForFirst() figures out which SSID is visible and the rest follows automatically.

Safety net: WiFi loss means emergency stop

Every call to runState() starts with one check, before the big switch statement:

if (!wifiOk && _state != FlightState::Idle && _state != FlightState::Emergency) {
    Serial.println("[Flight] WiFi lost — emergency stop");
    enterState(FlightState::Emergency);
    return;
}

If the AtomS3 ever drops its connection to the drone’s access point while armed, calibrating, flying, or landing, the very next frame forces an emergency stop — regardless of what gesture or gamepad input is happening. The same idea applies to losing the Bluetooth gamepad mid-flight in BLUETOOTH mode. Given that this whole project is one step away from “small spinning blades a meter from your face,” this single guard clause is arguably the most important seven lines in the firmware.

What’s next

With the skeleton in place — HAL, non-blocking loop, and a drone-agnostic state machine — the next two articles get to the fun part: turning physical input into flight commands. Part 4 covers the accelerometer/tilt control path (and the altitude-hold throttle gesture that took some real debugging to get right), and Part 5 covers building a BLE HID host from scratch to support a Bluetooth gamepad.

As always, the full source is on GitHub: github.com/popolony2k/maritaca-e88-controller. You can also see Maritaca Force 1 in action on the project’s YouTube playlist.

Enjoy
[]’s
PopolonY2k

Building a Custom Drone Controller from Scratch — Part 2: Reverse Engineering the UDP Protocol

In Part 1 we introduced the project: a custom WiFi flight controller for Eachine E88/E58 toy drones running on an M5Stack AtomS3. But before writing a single line of firmware, there was a much bigger problem to solve — nobody publishes the protocol these drones speak. No SDK, no documentation, no public spec. If you want to control one of these drones from your own hardware, you have to figure out the protocol yourself.

This is the story of how that happened — entirely through packet capture analysis.

The Tool: PCAPdroid

The drone exposes its own WiFi access point. Its official Android app — the kind of generic white-label app that ships with these E88/E58 clones, often named something like WIFI_CAM or KY UFO — connects to that access point and talks to the drone over plain UDP, no encryption, no authentication. That makes it a perfect target for packet capture.

Using PCAPdroid (a packet capture app for Android that doesn’t require root), it’s possible to record every packet exchanged between the phone and the drone while flying it normally with the official app. The result is a .pcap file that can be opened in Wireshark for analysis.

This single technique — capture with the phone, analyze with Wireshark — was enough to fully reverse-engineer two completely different drone protocols, described below and in Part 6 of this series.

Step 1: Finding the Control Channel

The first question is always: which port is the drone listening on? Standard E58/E88 drones are documented (informally, around hobbyist forums) to use UDP port 50000 or 7099. A quick port scan against this drone showed those ports closed. The actual control channel turned out to be UDP port 8090 — non-standard, and only discoverable by capturing real traffic from the official app.

Filtering the capture by the drone’s IP address (192.168.4.153) and watching for periodic, fixed-size UDP packets immediately revealed the pattern: 8-byte packets sent roughly 25 times per second while the joystick was active.

Step 2: Decoding the Packet Format

Looking at several consecutive packets side by side made the structure obvious almost immediately — most bytes stayed at a constant value (0x80, the “neutral” position for a joystick axis), while one byte changed smoothly as the throttle stick moved:

66 80 80 80 80 00 00 99   ← all axes neutral
66 80 80 26 80 00 a6 99   ← throttle increasing
66 80 80 52 80 00 d2 99   ← throttle higher

From this, the 8-byte structure became clear:

[ 0x66 | Roll | Pitch | Throttle | Yaw | Cmd | XOR | 0x99 ]

Byte 0 — fixed header 0x66
Bytes 1–4 — Roll, Pitch, Throttle, Yaw, each centered at 0x80 (128)
Byte 5 — command flags (take-off, land, flip, etc.)
Byte 6 — checksum
Byte 7 — fixed footer 0x99

The checksum was the easiest part to confirm — byte 6 is simply the XOR of the four axis bytes. Take the second sample above: 0x80 ^ 0x80 ^ 0x26 ^ 0x80 = 0xA6. Matches exactly.

Step 3: The Missing Piece — App Mode Activation

Here’s where things got interesting. Sending these exact 8-byte packets to port 8090 did nothing. The drone simply ignored them.

The capture held the answer. Right after connecting, before any control packet appeared on port 8090, the app sent two tiny packets to a completely different port — UDP 8080, which is also the drone’s video streaming port:

42 76   → sent on connect: switches drone to WiFi/app control mode
42 77   → sent on disconnect: returns drone to 2.4 GHz RF controller mode

The drone normally boots in 2.4 GHz RF mode (controlled by its physical remote) and completely ignores WiFi commands until this two-byte handshake arrives. Once 42 76 is sent, the drone switches modes, the video stream starts instantly, and port 8090 starts accepting control packets. This single discovery — a two-byte “magic packet” hidden in the connection sequence — was the missing 10% that made the whole protocol work.

Step 4: The Keepalive Packet

One more detail surfaced while analyzing idle periods in the capture — moments where the joystick wasn’t being touched. Instead of going silent, the app kept sending a different 8-byte packet roughly every 790 ms:

AA 80 80 00 80 00 80 55

Notice the header and footer: 0xAA and 0x55 are the bitwise complements of 0x66 and 0x99 — a nice touch of symmetry from whoever designed this protocol. This keepalive almost certainly prevents the drone from timing out the connection and triggering a failsafe landing.

Step 5: Mapping the Command Flags

The command byte (byte 5) only changes when the user presses a button in the app — take off, land, flip, calibrate, etc. By isolating captures around each button press and comparing the command byte before and after, each flag could be matched to its function:

Bit	Value	Function
0	0x01	Auto take-off
1	0x02	Land
2	0x04	Emergency stop
3	0x08	360° flip
4	0x10	Headless mode
5	0x20	Lock
6	0x40	Unlock motors
7	0x80	Calibrate gyro

The Complete Picture

Putting it all together, the full control sequence for this drone (which we identified as a WIFI_8K_ variant — confirmed via its SSID WIFI_8K_Wf48702) looks like this:

Connect to the drone’s WiFi access point
Send 42 76 to UDP port 8080 — switches the drone into app control mode
Send 8-byte control packets to UDP port 8090 at ~25 Hz while flying
Send the AA…55 keepalive every ~790 ms when the stick is idle
Send 42 77 to UDP port 8080 on disconnect — returns the drone to RF mode

None of this is documented anywhere. It was all extracted, byte by byte, from real traffic captured between a phone and a drone.

Why This Matters

This kind of analysis isn’t just useful for toy drones. The same workflow — capture real traffic, isolate patterns, correlate user actions with byte changes — applies to any closed proprietary protocol: IoT devices, smart home gadgets, obscure consumer electronics. PCAPdroid plus Wireshark plus patience is a surprisingly powerful combination.

The full implementation of this protocol, including the packet encoder, checksum logic, and state machine that drives it, lives in the project’s source code: github.com/popolony2k/maritaca-e88-controller.

What’s Next

In Part 3, we’ll move from protocol to firmware — the architecture decisions behind the AtomS3 codebase: the hardware abstraction layer, the non-blocking control loop, and the flight state machine that turns raw protocol bytes into a real, controllable drone.

Enjoy
[]’s
PopolonY2k

Building a Custom Drone Controller from Scratch — Part 1: Hardware and Motivation

Toy drones are everywhere. You can pick up an Eachine E88 or E58 for under $30, fly it around your living room, and have a decent time. But what happens when the official app stops working, the manufacturer disappears, or you simply want to understand what’s actually happening between your phone and that spinning plastic in the air?

That question is what started this project.

The Goal

Build a fully custom WiFi flight controller for Eachine E88/E58 toy drones, running on an M5Stack AtomS3 attached to an M5Stack Atomic Battery Base — a compact ESP32-S3 assembly with a built-in LCD, RGB LED, LiPo battery, and a single face button. No phone required. No official app. Full control over every byte sent to the drone.

The complete build process for the black drone — which we called Maritaca Force 1 — is documented in a YouTube playlist where you can follow the project from the very beginning, including hardware assembly, initial tests, and first flights. Watch the Maritaca Force 1 build playlist on YouTube.

The Hardware

M5Stack AtomS3 + Atomic Battery Base

The AtomS3 is a compact development board built around the ESP32-S3 (240 MHz dual-core, 8 MB Flash, 2 MB PSRAM), attached to the M5Stack Atomic Battery Base which adds a LiPo battery and an IP5306 power management IC. Together they form the controller unit used in this project:

Built-in 0.85″ 128×128 LCD (GC9107 driver, SPI) — small but enough for a real flight HUD
Built-in RGB LED via M5Unified
One face button (BtnA, GPIO 41) — the entire UI runs through this single input
WiFi 2.4 GHz built in — connects directly to the drone’s access point
LiPo battery via Atomic Battery Base — USB-C charging, fits in one hand
Battery level read directly via I2C (0x75) — no extra library needed, just two register reads

The Drones — Eachine E88 Clones

Both drones are E88 clones that expose a WiFi access point, stream MJPEG video over UDP, and accept flight commands via UDP packets using a protocol derived from the Eachine E58 family.

We have two drones in this project:

Maritaca Force 1 (black drone, WIFI_8K_ variant) — 8-byte UDP packets on port 8090
Dr.One (grey drone, FLOW-WIFI variant) — 88-byte wrapped packets on port 8800, with optical flow altitude hold

Both were fully reverse-engineered from packet captures. No SDK, no documentation.

The Build System

The firmware is written in C++ using PlatformIO and the Arduino framework, targeting the m5stack-atoms3 board. The only external library dependency is M5Unified — everything else (WiFi, BLE, UDP) comes from the ESP32 Arduino core.

Why Not Just Use the App?

The official apps are garbage. Laggy, ad-infested, and they break with OS updates.
Learning. Reverse engineering a proprietary UDP protocol from packet captures is a genuinely interesting exercise.
Control. Once you own the protocol, you can do things the app never supported — like controlling the drone with a physical BLE gamepad, or using the board’s accelerometer as a tilt controller.
The AtomS3 fits in your pocket. A dedicated hardware controller with a real display is more satisfying than a phone app.

What’s Coming in This Series

Part 1 (this post) — Hardware and motivation
Part 2 — Reverse engineering the UDP protocol with packet captures
Part 3 — Firmware architecture: HAL pattern, non-blocking loop, flight state machine
Part 4 — Accelerometer tilt control
Part 5 — BLE HID gamepad host on ESP32 (iPega PG-9021S)
Part 6 — Second drone: FLOW-WIFI reverse engineering

Enjoy

[]’s
PopolonY2k

The Fold Drive — BLE HID Host

Unexpected Destination — the iPega PG-9021S

Reverse-Engineering Zentradi Technology — the 17-Byte Report

Calibration — Learning to Aim

The FAST Packs — Mapping the Buttons

A Battle Won, A War Lost — the L1/RT/L3/R3 Investigation

The Zentradi Main Fleet — 8BitDo

Do You Remember Love — What We Have

Share this:

Like this:

The big idea: tilt is data, not magic

From a raw angle to a flight command

Throttle: the one gesture that isn’t tilt

The yaw redesign: when “more realistic” makes things worse

What’s next

Share this:

Like this:

A quick tour of the project structure

The HAL: one file gets to know about M5Unified

A loop with no delay()

The flight state machine

Gestures, not menus

One state machine, two drones

Safety net: WiFi loss means emergency stop

What’s next

Share this:

Like this:

The Tool: PCAPdroid

Step 1: Finding the Control Channel

Step 2: Decoding the Packet Format

Step 3: The Missing Piece — App Mode Activation

Step 4: The Keepalive Packet

Step 5: Mapping the Command Flags

The Complete Picture

Why This Matters

What’s Next

Share this:

Like this:

The Goal

The Hardware

M5Stack AtomS3 + Atomic Battery Base

The Drones — Eachine E88 Clones

The Build System

Why Not Just Use the App?

What’s Coming in This Series

Share this:

Like this:

A loop with no `delay()`