Controller Parts API

Joystick and web controller parts for manual control

Controller parts provide manual input for steering, throttle, mode switching, and recording control.

Web Controllers

LocalWebController

Web-based controller using browser interface.

Import:

from donkeycar.parts.web_controller.web import LocalWebController

Constructor:

LocalWebController(port=8887)

port · int · default: "8887"

Port for web server

Outputs:

• angle: Steering angle (-1 to 1)
• throttle: Throttle value (-1 to 1)
• mode: Drive mode (user, local_angle, local)
• recording: Recording state (True/False)

Physical Joystick Controllers

JoystickController

Base class for physical joystick controllers.

Constructor:

JoystickController(poll_delay=0.0, throttle_scale=1.0, steering_scale=1.0,
                   throttle_dir=-1.0, dev_fn='/dev/input/js0',
                   auto_record_on_throttle=True)

poll_delay · float · default: "0.0"

Delay in seconds between joystick polls

throttle_scale · float · default: "1.0"

Scale factor for throttle (0.0 to 1.0)

steering_scale · float · default: "1.0"

Scale factor for steering (0.0 to 1.0)

throttle_dir · float · default: "-1.0"

Direction multiplier for throttle (1.0 or -1.0)

dev_fn · str · default: "/dev/input/js0"

Device path for joystick

auto_record_on_throttle · bool · default: "true"

Automatically start recording when throttle is applied

Methods:

run · (img_arr, mode, recording) -> (angle, throttle, mode, recording)

Returns control outputs based on joystick state

run_threaded · (img_arr, mode, recording) -> (angle, throttle, mode, recording)

Returns control outputs in threaded mode

update · () -> None

Polls joystick for input events (runs in separate thread)

shutdown · () -> None

Stops the controller thread

set_tub · (tub) -> None

Sets the tub for record deletion functionality

Button Mappings:

Common button functions across controllers:

• Mode toggle: Switch between user, local_angle, and local modes
• Record toggle: Start/stop manual recording
• Erase records: Delete last N records from tub
• Emergency stop: Immediately stop the vehicle
• Increase/Decrease throttle: Adjust max throttle scale
• Constant throttle: Toggle constant throttle mode

PS3JoystickController

PlayStation 3 controller support.

Constructor:

PS3JoystickController(dev_fn='/dev/input/js0', auto_record_on_throttle=True)

Default Button Mapping:

• Select: Toggle mode
• Circle: Toggle manual recording
• Triangle: Erase last 100 records
• Cross: Emergency stop
• D-Pad Up/Down: Increase/decrease max throttle
• Start: Toggle constant throttle
• L1/R1: Chaos monkey (test mode)
• Left stick horizontal: Steering
• Right stick vertical: Throttle

PS4JoystickController

PlayStation 4 controller support.

Constructor:

PS4JoystickController(dev_fn='/dev/input/js0', auto_record_on_throttle=True)

Default Button Mapping:

• Share: Toggle mode
• Circle: Toggle manual recording
• Triangle: Erase last 100 records
• Cross: Emergency stop
• L1/R1: Increase/decrease max throttle
• Options: Toggle constant throttle
• Left stick horizontal: Steering
• Right stick vertical: Throttle

XboxOneJoystickController

Xbox One controller support.

Constructor:

XboxOneJoystickController(dev_fn='/dev/input/js0', auto_record_on_throttle=True)

Default Button Mapping:

• A button: Toggle mode
• B button: Toggle manual recording
• X button: Erase last 100 records
• Y button: Emergency stop
• Right/Left shoulder: Increase/decrease max throttle
• Options: Toggle constant throttle
• Left stick horizontal: Steering
• Right stick vertical: Throttle
• Right trigger: Forward throttle (Forza mode)
• Left trigger: Reverse throttle (Forza mode)

LogitechJoystickController

Logitech F710 gamepad support.

Constructor:

LogitechJoystickController(dev_fn='/dev/input/js0', auto_record_on_throttle=True)

Default Button Mapping:

• Start: Toggle mode
• B: Toggle manual recording
• Y: Erase last 100 records
• A: Emergency stop
• Back: Toggle constant throttle
• L1/R1: Chaos monkey
• D-Pad Up/Down: Increase/decrease max throttle
• Left stick horizontal: Steering
• Right stick vertical: Throttle

RC Receiver

RCReceiver

Read RC receiver PWM signals via pigpio.

Constructor:

RCReceiver(cfg, debug=False)

cfg · object

Configuration object with RC GPIO pin settings

Required Config:

STEERING_RC_GPIO = 26
THROTTLE_RC_GPIO = 20
DATA_WIPER_RC_GPIO = 19
PIGPIO_STEERING_MID = 1500
PIGPIO_MAX_FORWARD = 2000
PIGPIO_STOPPED_PWM = 1500
PIGPIO_MAX_REVERSE = 1000
PIGPIO_INVERT = False
PIGPIO_JITTER = 0.025

Methods:

run · (mode, recording) -> (steering, throttle, mode, recording)

Returns RC control values

Usage Examples

Web Controller

from donkeycar.parts.web_controller.web import LocalWebController

ctr = LocalWebController(port=8887)
V.add(ctr,
      inputs=['cam/image_array'],
      outputs=['user/angle', 'user/throttle', 'user/mode', 'recording'],
      threaded=True)

PS4 Controller

from donkeycar.parts.controller import PS4JoystickController

ctr = PS4JoystickController(
    throttle_dir=-1.0,
    throttle_scale=cfg.JOYSTICK_MAX_THROTTLE,
    steering_scale=1.0,
    auto_record_on_throttle=cfg.AUTO_RECORD_ON_THROTTLE
)

ctr.set_deadzone(cfg.JOYSTICK_DEADZONE)

V.add(ctr,
      inputs=['cam/image_array'],
      outputs=['user/angle', 'user/throttle', 'user/mode', 'recording'],
      threaded=True)

RC Receiver

from donkeycar.parts.controller import RCReceiver

ctr = RCReceiver(cfg)
V.add(ctr,
      inputs=['user/mode', 'recording'],
      outputs=['user/angle', 'user/throttle', 'user/mode', 'recording'])

Configuration

Typical joystick configuration in myconfig.py:

CONTROLLER_TYPE = 'ps4'  # ps3, ps4, xbox, F710, etc.
JOYSTICK_MAX_THROTTLE = 0.5
JOYSTICK_STEERING_SCALE = 1.0
JOYSTICK_DEADZONE = 0.01
AUTO_RECORD_ON_THROTTLE = True