MojoScale Studio Docs
API Reference

joystick

Analog joystick module.

All modules Open Studio
Studio Docs Sensors & I/O

import joystick

The joystick module reads common two-axis analog joystick boards with VRx, VRy, and an optional push switch. The native firmware samples two ADC-capable GPIOs, auto-centers the stick on begin, and returns both raw ADC values and normalized axis values from -1.0 through 1.0. Use ``joystick.Joystick(...)`` to create independent joystick objects when a board has more than one stick. Use ADC1 pins when your script also uses WiFi, especially on ESP32-class boards, because ADC2 can time out while WiFi is active.

Quick example

import joystick
import system

left = joystick.Joystick(x_pin=34, y_pin=35, button_pin=32, deadzone=0.10)
right = joystick.Joystick(x_pin=36, y_pin=39)

def poll_stick():
    state = left.read()
    if state["ok"]:
        print(state["direction"], state["x"], state["y"], state["pressed"])

system.schedule("stick", 50, 50, -1, poll_stick)

import joystick

stick = joystick.Joystick(34, 35)
stick.calibrate()
print(stick.direction())

importjoystick

Analog joystick module.

The joystick module reads common two-axis analog joystick boards with VRx, VRy, and an optional push switch. The native firmware samples two ADC-capable GPIOs, auto-centers the stick on begin, and returns both raw ADC values and normalized axis values from -1.0 through 1.0. Use ``joystick.Joystick(...)`` to create independent joystick objects when a board has more than one stick. Use ADC1 pins when your script also uses WiFi, especially on ESP32-class boards, because ADC2 can time out while WiFi is active.

API 22 available

joystick.Joystick(x_pin: int, y_pin: int, button_pin: int = None, deadzone: float = None, samples: int = None, invert_x: bool = None, invert_y: bool = None, button_active_low: bool = None, attenuation: int = None) -> joystick_device

Create an independent analog joystick object.

Parameters
Name Type Pass as Required Description
x_pin int positional or keyword Yes ADC-capable GPIO connected to the joystick X/VRx output.
y_pin int positional or keyword Yes ADC-capable GPIO connected to the joystick Y/VRy output.
button_pin int positional or keyword No Optional GPIO connected to the push switch. Defaults to no button.
deadzone float positional or keyword No Optional normalized deadzone from 0.0 through 0.95. Defaults to 0.08.
samples int positional or keyword No Optional number of ADC samples per read. Defaults to 8.
invert_x bool positional or keyword No Optional boolean to reverse the X axis.
invert_y bool positional or keyword No Optional boolean to reverse the Y axis.
button_active_low bool positional or keyword No Optional boolean. Defaults to True for common joystick boards where the switch connects to ground when pressed.
attenuation int positional or keyword No Optional ADC attenuation in dB. Use 0, 2, 6, or 12. Defaults to 12.
Returns

joystick_device joystick_device object.

joystick.Joystick().calibrate(samples=64) -> dict

Set the current stick position as center.

Parameters
Name Type Pass as Required Description
samples int positional or keyword No Optional value. Defaults to 64.

joystick.Joystick().read(samples=None) -> dict

Read normalized axes, direction, and button.

Parameters
Name Type Pass as Required Description
samples int positional or keyword No Optional value. Defaults to None.

joystick.Joystick().raw(samples=None) -> dict

Read raw ADC values.

Parameters
Name Type Pass as Required Description
samples int positional or keyword No Optional value. Defaults to None.

joystick.Joystick().x(samples=None) -> float

Read normalized X position.

Parameters
Name Type Pass as Required Description
samples int positional or keyword No Optional value. Defaults to None.

joystick.Joystick().y(samples=None) -> float

Read normalized Y position.

Parameters
Name Type Pass as Required Description
samples int positional or keyword No Optional value. Defaults to None.

joystick.Joystick().direction(samples=None) -> str

Read direction text.

Parameters
Name Type Pass as Required Description
samples int positional or keyword No Optional value. Defaults to None.

joystick.Joystick().pressed() -> bool

Read the optional push switch.

joystick.Joystick().deadzone(value=None) -> float

Get or set this stick's deadzone.

Parameters
Name Type Pass as Required Description
value any positional or keyword No Optional value. Defaults to None.

joystick.Joystick().info() -> dict

Return this stick's configuration and state.

joystick.Joystick().close() -> bool

Close this joystick object.

joystick.begin(x_pin: int, y_pin: int, button_pin: int = None, deadzone: float = None, samples: int = None, invert_x: bool = None, invert_y: bool = None, button_active_low: bool = None, attenuation: int = None) -> bool

Initialize an analog joystick.

Parameters
Name Type Pass as Required Description
x_pin int positional or keyword Yes ADC-capable GPIO connected to the joystick X/VRx output.
y_pin int positional or keyword Yes ADC-capable GPIO connected to the joystick Y/VRy output.
button_pin int positional or keyword No Optional GPIO connected to the push switch. Defaults to no button.
deadzone float positional or keyword No Optional normalized deadzone from 0.0 through 0.95. Defaults to 0.08.
samples int positional or keyword No Optional number of ADC samples per read. Defaults to 8.
invert_x bool positional or keyword No Optional boolean to reverse the X axis.
invert_y bool positional or keyword No Optional boolean to reverse the Y axis.
button_active_low bool positional or keyword No Optional boolean. Defaults to True for common joystick boards where the switch connects to ground when pressed.
attenuation int positional or keyword No Optional ADC attenuation in dB. Use 0, 2, 6, or 12. Defaults to 12.
Returns

bool True when both axis pins resolve to ADC channels and the optional button is configured.

joystick.calibrate(samples: int = None) -> dict

Set the current stick position as center.

Keep the joystick released while calling this method. The module averages a short window and stores the result as ``center_x`` and ``center_y``.

Parameters
Name Type Pass as Required Description
samples int positional or keyword No Optional number of ADC samples to average. Defaults to 64.
Returns

dict Dict with ``ok``, ``x_pin``, ``y_pin``, stored ``center_x``, ``center_y``, and ``samples``.

joystick.read(samples: int = None) -> dict

Read joystick axis, direction, and button state.

Parameters
Name Type Pass as Required Description
samples int positional or keyword No Optional number of ADC samples for this read only.
Returns

dict Dict with ``ok``. When ``ok`` is true it includes ``x_pin``, ``y_pin``, ``button_pin``, ``raw_x``, ``raw_y``, ``center_x``, ``center_y``, normalized ``x`` and ``y`` values, ``magnitude``, ``angle``, ``direction``, ``pressed``, ``deadzone``, and ``samples``. Direction is one of ``center``, ``up``, ``down``, ``left``, ``right``, ``up_left``, ``up_right``, ``down_left``, or ``down_right``. When ``ok`` is false it includes ``error`` and ``hint``.

joystick.raw(samples: int = None) -> dict

Read raw ADC values from both joystick axes.

Parameters
Name Type Pass as Required Description
samples int positional or keyword No Optional number of ADC samples for this read only.
Returns

dict Dict with ``ok``, ``raw_x``, ``raw_y``, ``pressed``, and ``samples``.

joystick.x(samples: int = None) -> float

Read normalized X-axis position.

Parameters
Name Type Pass as Required Description
samples int positional or keyword No Optional number of ADC samples for this read only.
Returns

float Float from -1.0 through 1.0 after center calibration and deadzone.

joystick.y(samples: int = None) -> float

Read normalized Y-axis position.

Parameters
Name Type Pass as Required Description
samples int positional or keyword No Optional number of ADC samples for this read only.
Returns

float Float from -1.0 through 1.0 after center calibration and deadzone.

joystick.direction(samples: int = None) -> str

Read joystick direction as text.

Parameters
Name Type Pass as Required Description
samples int positional or keyword No Optional number of ADC samples for this read only.
Returns

str String direction such as ``center``, ``left``, ``right``, ``up``, ``down``, or a diagonal direction.

joystick.pressed() -> bool

Read the optional joystick push switch.

Returns

bool True when the configured button pin is pressed.

joystick.deadzone(value: float = None) -> float

Get or set the normalized joystick deadzone.

Parameters
Name Type Pass as Required Description
value float positional or keyword No Optional deadzone from 0.0 through 0.95.
Returns

float Float current deadzone.

joystick.info() -> dict

Return joystick module state.

Returns

dict Dict with initialization state, calibration state, pins, centers, deadzone, sampling, inversion flags, button polarity, ADC units, ADC channels, attenuation, last error, and hint.

joystick.reset() -> bool

Release ADC state and clear joystick configuration.

Returns

bool True when module state is cleared.