OpenDrift Pdb

OpenDrift is an open source drift gyro for RC drift cars, built around the Waveshare ESP32-S3 Touch AMOLED 1.64 board. It reads steering, throttle, and optional gain channels from a receiver, mixes driver steering with gyro correction, outputs steering and optional throttle signals, and exposes tuning through both the onboard touch UI and a WiFi web configurator.

OpenDrift v1.0 uses a dedicated selectable-rate control task, a single gyro filter, continuous yaw prediction, throttle-informed load-change prediction, and non-accumulating quiet-drift reference feedback. The goal is to make gyro setup less of a black box while keeping the active control path small enough to reason about.

See the current Technical Tuning Reference for the setup order, symptom table, surface-profile workflow, and findings from real track testing. The public tuning guide provides the shorter trackside workflow.

Developers and AI assistants can start with the project context and handoff, covering the development history, architecture, validated findings, safety constraints, current local work, and deferred investigations. It is a dated summary, not a verbatim chat archive; verify it against the current source.

Install Firmware

Visit opendriftrc.com for the project overview, wiring reference, and Open Beta firmware. The browser installer provides current AMOLED images with either PWM or CRSF receiver support, without an account, source compilation, or command-line tools. Historical round-display releases remain available but are frozen.

Current Features

• ESP32-S3 firmware using PlatformIO and Arduino.
• 280 x 456 AMOLED touch UI with swipeable pages and a permanent built-in background fallback.
• Up to 16 persistent custom AMOLED backgrounds, selectable from the display or web configurator. JPG, PNG, and WebP images can be converted locally at opendriftrc.com/backgrounds.
• Persistent AMOLED theme engine with light/dark text, seven accent palettes, and background-aware translucent control panels, based on work contributed by J3vb.
• Dedicated 250 Hz or 333 Hz IMU/control/steering task isolated from UI, WiFi, and logging work.
• Continuous yaw-acceleration prediction with throttle-informed look-ahead.
• Quiet-drift reference feedback that yields to driver steering and throttle changes.
• Receiver steering input.
• Optional receiver throttle sensing with automatic Performance Mode behavior.
• Receiver gyro gain input.
• Selectable GPIO 18 gyro-gain input or throttle passthrough output.
• Servo output with center, reverse, and travel settings.
• Servo quiet band for direct-drive steering buzz.
• Physical servo endpoint calibration for max left, center, and max right.
• Separate radio steering travel limit.
• Separate servo reverse and gyro reverse.
• Gyro tuning:
  • gain
  • deadband
  • maximum correction
  • smoothing
  • Drift Memory and limit
  • Hold Assist
  • Prediction
  • Countersteer Assist
  • Transition Speed
  • Driver Priority
  • Anti Wobble
• Up to 12 persistent named surface/driving profiles.
• Scrollable trackside profile selection on both displays.
• Do-nothing signal-loss behavior when steering input is lost.
• WiFi access point.
• Browser-based web configurator.
• Non-blocking PSRAM blackbox logging with controller, prediction, throttle, notch, chassis-motion, and correction telemetry.
• Parked blackbox archiving to sequential CSV files on AMOLED microSD, with an internal-flash fallback when no card is installed.
• Persistent settings stored in ESP32 preferences.
• Transition Speed adjustment centered at the neutral baseline of 50.
• Driver Priority adjustment that yields fast direct gyro gain as steering input increases; default 0 preserves the established response.
• Phase-aware Anti Wobble notch with a track-tested default of 50.
• Separate PWM and full-duplex CRSF targets for Waveshare AMOLED V1 and V2.
• Full-duplex CRSF steering, throttle, gain, link statistics, parameter telemetry, neutral failsafes, and EdgeTX tuning.
• CRSF channel routing to accessory PWM outputs: GPIO 1–8 on AMOLED V1 and GPIO 3–8 on AMOLED V2.

Hardware Routing

Supported Boards

The Waveshare ESP32-S3 Touch AMOLED 1.64 is the final and primary OpenDrift hardware target. New development, UI work, and release testing target this board.

Waveshare ships V1 and V2 revisions that require different firmware. V1 has its version silkscreen at the top of the PCB and uses LCD_CS on GPIO 9. V2 has the silkscreen beside the right-side pin headers and uses LCD_CS on GPIO 46. Select the exact revision in the web flasher.

The older Waveshare 1.28-inch round display build is deprecated and frozen. Its PlatformIO environment and implementation remain in the repository for experimentation, but no new firmware releases or feature-parity work are planned.

AMOLED V1 and the Round board use this PWM pinout:

GPIO 18 cannot provide throttle output and read receiver gain at the same time. To keep throttle sensing and gain adjustment, split the receiver throttle signal to GPIO 16 and the ESC rather than plugging the ESC into OpenDrift.

Make sure the receiver, ESP32 board, and servo power system share ground.

AMOLED V2 keeps receiver steering on GPIO 15 and throttle on GPIO 16, but moves steering output to GPIO 1 and the switchable gain/throttle connection to GPIO 2. Do not use GPIO 17/18 for OpenDrift signals on V2; Waveshare connects those pins to IMU_INT2 and TP_INT.

CRSF targets repurpose the receiver pins:

AMOLED V2 instead uses GPIO 1 for CRSF RX and GPIO 2 for CRSF TX while retaining GPIO 15 steering-servo output and GPIO 16 ESC output. All CRSF targets use the same full-duplex implementation and the separate OpenDriftCRSF settings namespace and do not overwrite a PWM tune.

CRSF builds can also mirror any receiver channel to accessory outputs from the WiFi web configurator. AMOLED V1 exposes GPIO 1–8; AMOLED V2 exposes GPIO 3–8 because GPIO 1/2 carry CRSF. Each enabled pin emits standard 50 Hz receiver PWM and returns to 1500 microseconds when the CRSF link is lost. These are 3.3 V signal outputs only: power lights and accessories separately and share ground.

Throttle sensing is not required for basic stabilization, but it is strongly recommended. With the throttle signal connected, OpenDrift can release settled-drift features during power changes instead of inferring those events from yaw alone. Treat it like a sensored-motor cable: the fallback works without it, while Performance Mode has substantially better phase awareness.

The servo should be powered from a suitable BEC or ESC receiver rail. Do not rely on the ESP32 board to power a steering servo. A DIY installation must feed the display/development board regulated 5 V, never an unregulated or 6 V-plus BEC output. The OpenDrift daughter boards under development include an onboard regulator. ESP32-S3 GPIOs are 3.3 V signal pins and are not 5 V tolerant.

Build And Upload

The firmware project is in:

OpenDrift/

Custom AMOLED Backgrounds

OpenDrift keeps the built-in galaxy image in firmware and can additionally store up to 16 user backgrounds in the board's FFat partition. Custom images must be 456 x 280 raw RGB565 files; the browser-based background converter creates the exact format locally from JPG, PNG, or WebP files.

To install one, join the gyro's OpenDrift WiFi network, open http://192.168.4.1, and use the AMOLED Backgrounds card. Uploaded images can be selected or deleted there, and can also be selected from the Backgrounds page on the AMOLED display. Keep the car stationary while an image is being written to flash. Leaving the selection on Built-in uses the factory background and consumes no additional storage.

Build with PlatformIO:

pio run

The default environment is waveshare_amoled_164. Build or upload it explicitly with:

pio run -e waveshare_amoled_164
pio run -e waveshare_amoled_164 -t upload

The custom PlatformIO board definition is included at OpenDrift/boards/waveshare_amoled_164.json.

AMOLED V2 uses separate targets:

pio run -e waveshare_amoled_164_v2
pio run -e waveshare_amoled_164_v2_crsf

CRSF builds are intentionally separate:

pio run -e waveshare_amoled_164_crsf

Both supported targets enable full-duplex CRSF, GPIO 16 ESC output, and neutral-hold arming. Telemetry uses GPIO 18 on AMOLED V1 and GPIO 2 on AMOLED V2.

Main dependencies are managed in OpenDrift/platformio.ini:

• SensorLib
• LovyanGFX
• ESP32Servo

First Power-On

On boot, OpenDrift initializes:

1. Display
2. Settings
3. IMU
4. Servo output
5. Receiver inputs
6. Touch
7. Gyro calibration
8. WiFi, if enabled
9. UI

Keep the car still during startup so gyro calibration can capture a clean yaw-rate offset.

Onboard UI Pages

Swipe left/right to move between pages.

Main

Shows the current gyro gain and provides:

• - / +: adjust stored gain when radio gain input is not overriding it.
• CAL: recalibrate gyro offset. Use this when the car is sitting still and the gyro seems biased.

Core

Primary correction limits:

• Deadband: yaw-rate zone ignored around zero.
• MAX CORRECTION: maximum gyro movement across the full calibrated endpoint-to-endpoint steering span. 50% equals center-to-endpoint authority; 100% can override one endpoint to the other.
• GYRO REV: reverses only the gyro correction direction.

Use GYRO REV when normal steering direction is correct, but the gyro counter-steers the wrong way.

Response

Fast controller behavior:

• SMOOTHING: the software yaw low-pass; 0.00 bypasses it completely.
• GYRO LPF: QMI8658 hardware filtering at 24 Hz, lower-latency 120 Hz, or Off for controlled testing.
• PREDICTION: continuous yaw-acceleration look-ahead.
• SERVO QUIET: suppresses very small physical servo-command changes.

Assistance

Slow quiet-drift behavior:

• COUNTERSTEER: chooses how much additional steady countersteer OpenDrift carries. Zero preserves the driver-led base response; higher values reduce the steering load on the driver without increasing fast yaw damping.
• HOLD ASSIST: controls how firmly the quiet-drift reference is retained.
• DRIFT MEMORY: feedback for deviation from a learned quiet-drift reference.

The Drift Memory limit remains available in the web configurator as an advanced limit.

Tail Response

TAIL SPEED is tuned separately from the core v1.0 controls:

• 50 is the Open Beta baseline response.
• Below 50 adds damping during deliberate entries and transitions.
• Above 50 releases some damping so the chassis can rotate faster.
• The effect is reduced in a settled drift and cannot reverse gyro correction.

Keep it at 50 unless deliberately collecting same-car experimental A/B data.

SMOOTH is intentionally inverted from raw filter math: higher numbers mean more smoothing and slower gyro response.

Deadband is applied as a soft deadband. Small yaw noise is still ignored, but correction fades in from zero instead of jumping as soon as yaw crosses the deadband value.

Conservative first-power values:

Tune symptoms:

Radio

Live receiver monitor:

• Steering pulse and signal state.
• Gain pulse and signal state.
• Current gain value.
• Calibration values.
• Position bars for steering and gain.

Use this page to confirm the receiver is connected and moving through a sensible range.

In a CRSF build the monitor shows channel 1 steering, channel 2 throttle, and channel 3 gain decoded from the digital link.

Steering

Steering output setup:

• TRV: scales driver steering input without reducing gyro correction authority.
• REV: reverses physical servo direction.
• Swipe once more to open the dedicated Physical Endpoints page.

Physical Servo Endpoints

The calibration page uses three large capture buttons. Each button starts red and turns green after it has captured the servo's actual physical PWM position:

• MAX LEFT: position the wheels at their safe physical left stop, then capture it.
• CENTER: capture the transmitter at neutral.
• MAX RIGHT: position the wheels at their safe physical right stop, then capture it.

OpenDrift saves the calibration after all three physical positions are captured on opposite sides of center. The saved endpoints become the final asymmetric servo map and hard clamp, so neither the driver nor gyro can push through them.

CRSF users can perform the same three captures from the EdgeTX OpenDrift.lua tool. Calibration state is persistent and shared: completing it on the radio turns the AMOLED buttons green, while completing it on the display updates the radio's Endpoints status to YES.

Suggested calibration flow:

1. Set servo direction first, then use steering/transmitter endpoint adjustment to position the wheels at the safe physical left stop and tap MAX LEFT.
2. Release steering to neutral and tap CENTER.
3. Position the wheels at the safe physical right stop and tap MAX RIGHT.
4. Confirm all three buttons are green and the page says SAVED - TAP TO RESET.
5. Return to Steering and verify the wheels remain inside both saved physical stops.

Changing REV, Servo Center, or Servo Travel after calibration deliberately clears the saved calibration because those changes alter the physical output map.

Servo reverse and gyro reverse are separate on purpose:

• Use REV on the Steering page when driver steering moves the wheels backward.
• Use GYRO REV on the Gyro page when driver steering is correct but gyro correction is backward.

Physical endpoint calibration and steering travel are separate on purpose:

• Use MAX LEFT, CENTER, and MAX RIGHT to set the servo's physical output limits.
• Use TRV to scale driver steering without reducing gyro authority.
• Use Max Correction to select how much of the calibrated physical range the gyro may command.

WiFi

Shows WiFi state and connected client count.

• WIFI ON/OFF: toggles the access point.

When WiFi is enabled, connect to the OpenDrift network and open:

http://192.168.4.1/

System

Basic firmware/system information. Tap the GPIO 18 mode button to switch between GAIN INPUT and THROTTLE OUT.

Profiles

The Profiles page lists the driving profiles created in the web configurator. Tap a profile to activate its complete driving tune. Swipe vertically when more than four profiles exist; the list supports up to 12 profiles.

Profiles save gain, deadband, max correction, smoothing, Prediction, Countersteer Assist, Driver Priority, Hold Assist, Drift Memory and its limit, and radio steering travel. Trackside adjustments automatically save back to the active profile.

Hardware and installation settings remain global, including gyro/servo direction, physical steering endpoints, servo center and travel, WiFi, logging, and GPIO mode. Switching surfaces therefore cannot disturb the car's physical setup.

Control and servo rate

OpenDrift defaults to 250 Hz for broad digital-servo compatibility. 333 Hz reduces the output interval from 4 ms to about 3 ms and can sharpen a fast supported servo, but it must only be used when the servo manufacturer explicitly rates the servo for 333 Hz operation. An unsupported update rate can cause heat, buzzing, erratic steering, or servo damage.

The setting is global and appears on the AMOLED System page, in the web configurator, and in the CRSF/EdgeTX parameter list. Restart OpenDrift after changing it so both the control task and steering PWM start at the selected rate.

Web Configurator

When WiFi is enabled, OpenDrift starts a web configurator at:

http://192.168.4.1/

Current web settings:

• Create named driving profiles from the current tune
• Activate or delete existing profiles
• Gyro gain
• Channel 3 gain minimum / maximum (0.00-6.00)
• Deadband
• Reverse gyro correction
• Max correction
• Smoothing
• Prediction strength
• Transition Speed
• Driver Priority
• Anti Wobble
• Drift memory
• Memory limit
• Hold Assist
• Servo reverse
• Servo center
• Servo travel
• Servo quiet band
• Steering max left / center / max right
• Radio steering travel
• Gain channel low / high
• GPIO 18 gain-input or throttle-output mode
• WiFi enabled on boot
• WiFi auto-off timeout
• Blackbox logging enabled
• Raw pitch, roll, acceleration, and surface-disturbance telemetry for chassis analysis

The web page also shows the active profile, live receiver pulse values for steering, throttle, and gain, plus the active GPIO 18 mode.

Use the web configurator when you want to make several changes quickly. Use the onboard UI when tuning trackside without a phone or laptop.

Onboard Blackbox Log

OpenDrift records fixed-size blackbox samples into a 4 MB circular PSRAM buffer at about 20 Hz while steering receiver signal is present.

Blackbox logging is disabled by default. Enable Onboard logging in the web configurator only when you want to collect data, then save settings.

No flash or filesystem writes occur while driving. Once the circular buffer is full, the oldest records are overwritten so the newest behavior remains available. Park the car before saving the RAM log to persistent storage.

On AMOLED hardware, an installed microSD card is preferred and each dump is saved as a new CSV (opendrift-blackbox-0001.csv, 0002, and onward). Existing sessions are preserved and numbering continues after reboot. Without an SD card, OpenDrift stores one compact binary archive in internal flash and converts it to CSV when downloaded through the web configurator.

The dedicated AMOLED Blackbox page shows the current RAM records, used and available space, captured duration, archive destination, saved-log statistics, and dump progress. It also provides logging, dump, and RAM-clear controls.

For acquisition/wobble testing, the web configurator's Control diagnostics card captures up to 45 seconds at control-loop rate. Start it before driving. With an SD card, the ordinary dump action also saves a matching numbered opendrift-diagnostics-0001.csv beside the blackbox CSV. Wait until dump completion before powering off. Without SD, download the timing CSV over WiFi before restarting; internal-flash dumps do not include this RAM-only capture. See IMU diagnostics and screen performance testing.

AMOLED USB maintenance and boot recovery

All AMOLED V1/V2 PWM/CRSF builds, including the private GPIO8 target, support USB maintenance. No SD card is required for firmware updates. Hold USB MODE on the System page for 1.5 seconds while parked. The board restarts into an isolated mode with steering, throttle, and controller tasks inactive. Connect a data-capable USB cable and copy the correct build's application firmware.bin onto the firmware-update drive. Wait for Update Complete and automatic reboot; do not disconnect during writing. An inserted SD card appears separately as a read-only log drive. The maintenance restart button disconnects the volumes before returning to normal operation.

The SD-ready indication reports device-side readiness, not completion of the computer's filesystem mount. USB SD reads now use up to the existing 4 KB buffer with event-driven completion instead of per-sector polling. See USB SD performance testing if the drive appears but takes a long time to open; hardware validation is still required to measure the improvement.

For official builds previously using the single-app partition layout, install the full factory image once through the webflasher or perform a normal full PlatformIO upload: an app-only USB update cannot install a new partition table. The new layout keeps NVS and FFat at their existing addresses, but back up your tune/logs before upgrading. USB serial ports may re-enumerate after the switch to native TinyUSB. Do not erase the whole chip as part of the normal upgrade.

After three consecutive unfinished boots across software/watchdog resets, the next boot enters USB recovery before the IMU, outputs, and controller are started. Automatic recovery skips SD mounting so a bad card cannot block the updater. Successful normal startup clears the RTC failure audit after 15 seconds. Intentional USB-mode changes are excluded. Cold power loss/brownout starts a fresh audit; corrupt apps/bootloaders still require hardware BOOT recovery. The headless private Matrix builds retain their existing USB serial configuration; this AMOLED maintenance interface is not enabled on Matrix.

The web configurator shows the current log size and provides:

• Download CSV
• Clear RAM Log
• Dump RAM Log to SD card or internal flash, according to available storage
• Download saved CSV

Log rows include:

• Time
• Raw yaw rate
• Filtered yaw rate
• Roll and pitch gyro rates (gyro_x_dps, gyro_y_dps)
• Raw X/Y/Z acceleration in g
• Total acceleration magnitude and high-frequency acceleration delta
• A filtered surface_disturbance score from 0.0 to 1.0
• Requested gyro correction before Max Correction
• Limited gyro correction after Max Correction
• Applied gyro correction after the driver/gyro steering mix
• Correction saturation state
• Steering input and calibrated steering command
• Servo output
• Servo quiet band
• Throttle input
• Gain input and active gain
• Active deadband, max correction, smoothing, Prediction, Countersteer Assist, Driver Priority, Hold Assist, Drift Memory, and memory limit
• Driver Priority scale and effective live direct gain
• Predicted yaw, quiet-drift reference, reference error, steady countersteer contribution, and memory correction
• Driver steering activity and throttle-prediction blend
• Controller phase (0 idle, 1 entry, 2 settled, 3 transition) and reference-lock blend
• Anti Wobble notch depth, isolated residual, tracked notch frequency, transition-authority blend, and throttle-lift blend
• Steering/throttle/gain signal state and GPIO 18 mode

Suggested test workflow:

1. Connect to the OpenDrift WiFi network.
2. Open http://192.168.4.1/.
3. Enable onboard logging if it is off, then save settings.
4. Tap Clear RAM Log.
5. Drive the car.
6. Stop and leave the car parked for two seconds.
7. Dump the RAM log from the AMOLED Blackbox page, EdgeTX tool, or web configurator.
8. Download the saved CSV over WiFi, or remove/read the SD card later.

The CSV can be pasted into a spreadsheet or plotted to see whether the car spun because of delayed correction, overcorrection, max correction saturation, noisy yaw, or steering/radio behavior.

surface_disturbance still combines sudden acceleration-vector changes, roll/pitch rate, and low-g unloading indicators for analysis. OpenDrift v1.0 logs it but does not currently apply terrain correction.

Gyro Algorithm Overview

OpenDrift v1.0 runs this path at the selected 250 Hz or 333 Hz rate:

1. Read receiver steering, throttle, and IMU yaw.
2. Subtract calibrated gyro offset and apply soft deadband.
3. Apply the selected hardware gyro LPF and optional software yaw low-pass.
4. Estimate short-horizon yaw from filtered yaw acceleration.
5. Extend that horizon when throttle predicts application or a longer off-throttle load change.
6. Shape damping briefly during deliberate direction changes without changing the hard correction ceiling.
7. Apply the phase-aware Anti Wobble notch around the tracked 2.5-3.6 Hz wheel-resonance band while preserving slow chassis yaw and useful response outside that band.
8. Convert predicted yaw directly into correction with Gain.
9. Learn a slow yaw reference while driver steering and throttle are quiet.
10. Add optional Countersteer Assist from the slow learned reference only.
11. Apply Drift Memory only to error from that reference.
12. Prevent memory from pushing farther into correction saturation.
13. Limit signed gyro movement to the configured full-span Max Correction percentage, then mix it with driver steering and clamp the combined command.
14. Apply the calibrated physical endpoint map as the final hard servo limit.

Driver steering activity and throttle changes make the slow reference yield immediately. Neither disables the fast direct damping path.

Signal Loss Behavior

The standard PWM builds retain the existing do-nothing behavior: if steering input disappears, OpenDrift does not send a new servo command.

This leaves the servo at the last commanded position. It is intentionally a simple do-nothing behavior while failsafe strategy is still being evaluated.

The full CRSF build has deterministic behavior because all channels share one link state. A channel frame older than 50 ms centers steering and commands neutral throttle. Throttle remains locked until a valid link has held neutral for 500 ms after boot or reconnection.

Tuning

Use the Technical Tuning Reference rather than tuning every setting at once. The most important lessons from development are:

• Establish a mechanically sound car before blaming the gyro.
• Set the servo's internal anti-wobble only as high as it can run without buzzing; high servo torque/power can amplify internal oscillation.
• Treat Gain as the primary surface-dependent setting and store each surface in a profile.
• Tune entries with Gain, Max Correction, and Smoothing before adding slow reference feedback.
• Add Prediction in small steps only after the direct response is understood.
• Use Hold Assist for sustained-drift reference retention, then add only the minimum Drift Memory required.
• Use Countersteer Assist to choose driver-led versus gyro-led settled drifts without retuning Gain.
• Connect throttle sensing so OpenDrift can anticipate power and load changes.

OpenDrift v1.0 is the first public controller. Start from the conservative values in the tuning reference and save proven surface setups as profiles.

Future Work

• Servo resonance calibration: add a stationary calibration mode that sweeps a small steering command across a safe frequency range and captures high-rate chassis IMU data. Because the servo is rigidly mounted to the chassis, its buzz and self-oscillation should be measurable without another sensor. The first version should compare vibration energy, dominant resonances, settling, and left/right behavior to help evaluate internal servo anti-wobble, torque, power, and response settings and recommend OpenDrift quiet-band and correction-rate settings. Command shaping or resonance compensation should only follow after repeatable measurements show that it can reduce vibration without adding harmful control-loop delay.

Project Layout

Important folders:

• OpenDrift/src/main.cpp: main firmware loop and control mixing.
• OpenDrift/lib/GyroController: gyro filtering and correction generation.
• OpenDrift/lib/RadioInput: receiver PWM input capture.
• OpenDrift/lib/CrsfInput: bounded native CRSF frame decoding and telemetry.
• OpenDrift/lib/CrsfParameterDevice: bidirectional CRSF settings device.
• OpenDrift/lib/EscOutput: dedicated 50 Hz LEDC throttle output.
• OpenDrift/lib/Servo: servo output wrapper.
• OpenDrift/lib/Settings: persistent settings.
• OpenDrift/lib/UI: onboard touch UI.
• OpenDrift/lib/WebConfigurator: web settings page.
• OpenDrift/lib/WIFIManager: WiFi access point control.
• OpenDrift/lib/Backgrounds: persistent AMOLED background storage and recovery.
• OpenDrift/docs/Tuning.md: complete tuning and blackbox interpretation guide.
• OpenDrift/docs/CRSF-Experimental.md: CRSF wiring, failsafes, and validation workflow.
• OpenDrift/radio/edgetx: source for the OpenDrift EdgeTX tuning tool.
• OpenDrift/assets/backgrounds: built-in AMOLED fallback background data.
• OpenDrift/boards: custom PlatformIO board definitions.

License

See LICENSE.