🎮Controller

{Game controller operation demonstration video}

Quaddle is compatible with firmware-supported BM769, GamepadSpace-Q34B, and GamepadSpace-Q37 Bluetooth gamepads.

Before powering on the controller, please dial the mode switch on the back of the controller to the D position.

{Image of the mode switch on the back of the controller}

The raw A/B and X/Y bits on the Q37 differ from those on the Q34B. The firmware automatically swaps them before mapping the controls to the physical labels printed on the gamepad. Users can therefore always follow the A, B, X, and Y labels shown on the gamepad itself.

Connecting and Getting Started

1

Power on

Press the Home button () to turn on the controller and make it discoverable, then start the robot. At startup, the robot scans for a supported controller for approximately 1 second. When one is found, the robot automatically enters GamepadClient mode and connects. Simultaneously, the controller will emit vibration feedback.

2

Finishing control

Return the left stick to the center to stop any movement it initiated and restore the standing posture. Click the Pair button at the top of the controller to power it off. If the controller disconnects unexpectedly, the robot program also automatically sends the "kup" safe-standing command.

Note

Wait for the gamepad to connect

A previously saved gamepad is given priority when reconnecting. Once connected, the sticks and buttons can directly control the robot.

No gamepad is found during startup

Bluetooth enters mobile App Server mode. If the mobile app is not connected, briefly press the mainboard BOOT button to clear the old gamepad information, return to gamepad scanning, and pair the current gamepad.

How to connect to the other gamepad

When the robot successfully connects to a controller for the first time, it saves the controller information. Upon the next power-up, it will connect only to the controller that was saved via Bluetooth and will not connect to other controllers. If you are sure you want to connect to another controller in this case, without connecting to the mobile app, first press the Home button on the new controller to power it on, and then briefly press the Boot button on the side of the robot. This will clear the previously saved controller Bluetooth information and then establish a Bluetooth connection with the new controller.

Holding the Boot button on the side of the robot for 2 seconds clears Wi-Fi configuration; it is not a gamepad-pairing operation.

If the mobile app is connected, briefly pressing Boot on the side of the robot will not interrupt the app session (just clear the previously saved controller Bluetooth information) or switch to gamepad mode.

Basic Functions

The image below shows all the function joysticks and buttons, and their functions after individual movement, long press, or click:

Model: Q34B

The left pad functions (UP, LEFT, RIGHT) are used only on the Quaddle Scout.

Macro Recording and Playback

Stage	Gamepad Operation	Result
Start recording	Hold the Program button for at least 1 second	Clears the old macro and starts recording. The serial output displays [MACRO] recording.
Record actions	Operate the sticks and buttons normally	Records up to 48 robot commands that were actually accepted, including the interval between adjacent commands.
Stop and save	Briefly press the Program button	Stops recording and retains the macro in runtime memory. The serial output displays the number of saved steps.
Start playback	Briefly press the Program button again	Plays from the first step using the recorded timing intervals.
Interrupt playback	Briefly press the Program button during playback, or execute another valid gamepad command	Stops the current playback immediately.
Clear the macro	Hold the Program button again, disconnect/re-pair, or restart	A long press clears the old macro and starts a new recording. Resetting the connection state or restarting clears the in-memory macro.

The BM769 right trigger (RT on the Q34B) is reported as R2 in firmware events, while the internal button-bit enum calls it ZR. ZR and R2 therefore refer to the same right trigger in this document. In the current code, pressing it first toggles R2 gyroscope balancing once. Continuing to use the left stick or D-pad while holding it also executes the corresponding combination action. O and T are additional face buttons on the Q34B/Q37 and are generally not present on the BM769.

Combination control functions

The image below shows the combination control functions:

Tips:

To trigger the combined control function, first press and hold the button, then immediately move the joystick or press the directional buttons on the left pad.

L2/LT(ZL) + Right Stick: Screen Expressions and Eye Color

Start with the right stick centered, hold L2/LT (named ZL in the code) button, and then move the right stick. As soon as the stick enters a direction, the firmware automatically switches to the eye view and applies the corresponding display effect.

Combination	Screen Effect	Behavior	Serial Command
Hold L2/LT + right stick up	Select the next eye color	Changes color once each time the stick enters the up direction. While continuing to hold L2, return the stick to center and move it up again to keep cycling.	vc*
Hold L2/LT + right stick left	Listening expression	Makes the eye-socket outline thicker and changes it to a pale version of the active palette. The effect ends when the stick leaves the left direction or L2 is released.	veL / vel
Hold L2/LT+ right stick right	Talking expression	Displays an animated pink mouth at the bottom of the screen and adds randomized eye movement. The effect ends when the stick leaves the right direction or L2 is released.	veT / vet
Hold L2/LT + right stick down	Cycle the eye mood	Each center-to-down movement advances through squint → happy → sad → normal. Returning to center or releasing L2 does not cancel the selected mood.	veP → veH → veS → ves

The colors cycle in this fixed order: blue → orange → pink → green → red → yellow → purple → blue.

The corresponding serial commands are: vcb (Blue), vco (Orange), vcp (Pink), vcg (Green), vcr (Red), vcy (Yellow), and vcv (Purple).

The selected color is saved in the robot's persistent configuration and remains selected after a restart.

Squint reduces the eye height to approximately one-half. Happy and sad reduce it to approximately two-thirds and reshape the upper and lower eye corners, respectively; happy also widens the eyes. These three moods are mutually exclusive, but the active mood can be combined with listening or talking. Listening and talking are temporary direction-held effects, and switching between left and right cancels the previous effect first. A mood remains active until the next downward cycle or another command resets it.

The right stick uses dominant-direction classification: for diagonal movements, the axis with the greater absolute displacement determines the selected action. The entry threshold is approximately 50, and the return-to-center threshold is approximately 30, which prevents jitter near a boundary. After L2/LT(ZL) has been used as a right-stick modifier, releasing it does not trigger its individual short- or long-press step-climbing action.

Operating Precautions

Scenario	Recommendation or Firmware Behavior
Performing rolls, jumps, handstands, step climbing, or similar actions	Place the robot on an open, level, non-slip surface, away from table edges, people, and fragile objects.
Using button combinations	Hold A/B/X/Y/ZR/R1 before moving the left stick or tapping the D-pad. Moving the stick first may initiate normal walking.
Rapidly changing the left-stick direction	The firmware discards older unexecuted stick-movement states and retains the latest direction, reducing control lag.
Gamepad disconnects or is turned off	The firmware clears pending gamepad commands and macro state, then queues kup for a safe standing posture. New input is required after reconnecting.
During Wi-Fi provisioning	If a gamepad is connected, the firmware may disconnect it temporarily to avoid BLE/Wi-Fi coexistence congestion. It scans and reconnects automatically after provisioning.
A D-pad module shortcut has no effect	Check that the corresponding sensor module is installed, its build option is enabled, and its interface is connected correctly.
An action name is unavailable on a particular robot model	The mapping sends the same action ID, but actual availability depends on the current robot model and its skill table.