|
| 1 | +--- |
| 2 | +title: "Getting Started with Modulino Joystick" |
| 3 | +description: "Complete guide for the Modulino Joystick input module and programming with Arduino and MicroPython." |
| 4 | +tags: |
| 5 | + - Modulino |
| 6 | + - Joystick |
| 7 | + - Input |
| 8 | + - Control |
| 9 | + - QWIIC |
| 10 | + - I2C |
| 11 | +author: 'Pedro Sousa Lima' |
| 12 | +hardware: |
| 13 | + - hardware/11.modulinos/modulinos/modulino-joystick |
| 14 | +software: |
| 15 | + - ide-v2 |
| 16 | + - web-editor |
| 17 | + - micropython |
| 18 | +--- |
| 19 | + |
| 20 | + |
| 21 | + |
| 22 | +The Modulino Joystick is a modular input device that provides two-axis analogue control with an integrated push button, making it perfect to add intuitive directional input to your projects! It uses the standardised Modulino form factor with QWIIC connectors for easy integration. |
| 23 | + |
| 24 | +## Hardware Overview |
| 25 | + |
| 26 | +### General Characteristics |
| 27 | + |
| 28 | +The Modulino Joystick features a two-axis analogue joystick with push button functionality: |
| 29 | + |
| 30 | +| Parameter | Condition | Minimum | Typical | Maximum | Unit | |
| 31 | +|-----------|-----------|---------|---------|---------|------| |
| 32 | +| X-Axis Range | - | 0 | 2048 | 4095 | - | |
| 33 | +| Y-Axis Range | - | 0 | 2048 | 4095 | - | |
| 34 | +| Resolution | - | - | 12 | - | bit | |
| 35 | + |
| 36 | +### Sensor Details |
| 37 | + |
| 38 | +The **Modulino Joystick** module features an analogue joystick with two potentiometers (horizontal and vertical axes) and an integrated push button. The joystick does not have native I²C capabilities. Instead, the readings are processed by the Modulino's onboard microcontroller (STM32C011F4), which provides I²C communication. |
| 39 | + |
| 40 | +One unique feature of this setup is the ability to change the I²C address via software, making it adaptable to different system configurations. |
| 41 | + |
| 42 | +The default I²C address for the **Modulino Joystick** module is: |
| 43 | + |
| 44 | +| Modulino I²C Address | Hardware I²C Address | Editable Addresses (HEX) | |
| 45 | +|----------------------|----------------------|--------------------------------------------------| |
| 46 | +| 0x40 | 0x20 | Any custom address (via software configuration) | |
| 47 | + |
| 48 | +### Pinout |
| 49 | + |
| 50 | + |
| 51 | + |
| 52 | +**Qwiic / I2C (1×4 Header)** |
| 53 | +| **Pin** | **Function** | |
| 54 | +|---------|---------------------------| |
| 55 | +| GND | Ground | |
| 56 | +| 3.3 V | Power Supply (3.3 V) | |
| 57 | +| SDA | I2C Data | |
| 58 | +| SCL | I2C Clock | |
| 59 | + |
| 60 | +These pads and the Qwiic connectors share the same I2C bus at 3.3 V. |
| 61 | + |
| 62 | +**Additional 1×4 Header (MCU Debug Signals)** |
| 63 | +| **Pin** | **Function** | |
| 64 | +|---------|-------------------| |
| 65 | +| PF2 | RESET (NRST) | |
| 66 | +| SWCLK | SWD Clock (PA14) | |
| 67 | +| SWDIO | SWD Data (PA13) | |
| 68 | +| TX1 | USART Transmit (PA9) | |
| 69 | + |
| 70 | +**1×4 Header (Joystick & MCU Signals)** |
| 71 | +| **Pin** | **Function** | |
| 72 | +|---------|---------------------------| |
| 73 | +| RX1 | USART Receive (PA10) | |
| 74 | +| PA0 | Joystick Horizontal Axis | |
| 75 | +| PA1 | Joystick Vertical Axis | |
| 76 | +| PA2 | Joystick Pushbutton | |
| 77 | + |
| 78 | +**Note:** The board is breadboard compatible with 1×4 headers spaced by 900 mil (22.86 mm). The joystick axes provide analogue values from 0-4095 (12-bit resolution), with centre position at approximately 2048. |
| 79 | + |
| 80 | +### Power Specifications |
| 81 | + |
| 82 | +| Parameter | Condition | Typical | Unit | |
| 83 | +|---------------------|-----------|---------|------| |
| 84 | +| Operating Voltage | - | 3.3 | V | |
| 85 | +| Current Consumption | - | ~3.4 | mA | |
| 86 | + |
| 87 | +The module includes a power LED that draws 1 mA and turns on as soon as it is powered. |
| 88 | + |
| 89 | +### Schematic |
| 90 | + |
| 91 | +The Modulino Joystick features an analogue joystick controlled through a microcontroller for I²C communication. |
| 92 | + |
| 93 | +The main components are the analogue joystick with two potentiometers and the **STM32C011F4** microcontroller (U1), which reads the analogue values and handles I²C communication. |
| 94 | + |
| 95 | +You can connect to the I²C pins (SDA and SCL) using either the **QWIIC connectors** (J1 and J2, this is the recommended method) or the **solderable pins** (J4). The board runs on **3.3V**, which comes from the QWIIC cable or the **3V3 pin** on J4. |
| 96 | + |
| 97 | +There's also a small power LED indicator that lights up when the board is on. |
| 98 | + |
| 99 | +You can grab the full schematic and PCB files from the [Modulino Joystick page](https://docs.arduino.cc/hardware/modulinos/modulino-joystick). |
| 100 | + |
| 101 | +## Programming with Arduino |
| 102 | + |
| 103 | +The Modulino Joystick is fully compatible with the Arduino IDE and the official Modulino library. The following examples showcase how to read joystick position and button state for gaming and control applications. |
| 104 | + |
| 105 | +### Prerequisites |
| 106 | + |
| 107 | +- Install the Modulino library via the Arduino IDE Library Manager |
| 108 | +- Connect your Modulino Joystick via QWIIC or solderable headers |
| 109 | + |
| 110 | +For detailed instructions on setting up your Arduino environment and installing libraries, please refer to the [Getting Started with Modulinos guide](../how-general). |
| 111 | + |
| 112 | +Library repository available [here](https://github.com/arduino-libraries/Arduino_Modulino). |
| 113 | + |
| 114 | +### Basic Example |
| 115 | + |
| 116 | +```arduino |
| 117 | +#include <Modulino.h> |
| 118 | +
|
| 119 | +ModulinoJoystick joystick; |
| 120 | +
|
| 121 | +void setup() { |
| 122 | + Serial.begin(9600); |
| 123 | + Modulino.begin(); |
| 124 | + joystick.begin(); |
| 125 | +} |
| 126 | +
|
| 127 | +void loop() { |
| 128 | + // Update joystick readings |
| 129 | + if (joystick.update()) { |
| 130 | + // Read X and Y axes (range: -128 to 127) |
| 131 | + int8_t x = joystick.getX(); |
| 132 | + int8_t y = joystick.getY(); |
| 133 | + |
| 134 | + // Check button state |
| 135 | + bool pressed = joystick.isPressed(); |
| 136 | + |
| 137 | + // Display readings |
| 138 | + Serial.print("X: "); |
| 139 | + Serial.print(x); |
| 140 | + Serial.print("\tY: "); |
| 141 | + Serial.print(y); |
| 142 | + Serial.print("\tButton: "); |
| 143 | + Serial.println(pressed ? "PRESSED" : "Released"); |
| 144 | + } |
| 145 | + |
| 146 | + delay(50); |
| 147 | +} |
| 148 | +``` |
| 149 | + |
| 150 | +### Key Functions |
| 151 | + |
| 152 | +- `update()`: Updates joystick state, returns `true` if values changed |
| 153 | +- `getX()`: Returns horizontal position (-128 to 127, centre = 0) |
| 154 | +- `getY()`: Returns vertical position (-128 to 127, centre = 0) |
| 155 | +- `isPressed()`: Returns button state (`HIGH` when pressed) |
| 156 | +- `setDeadZone(threshold)`: Sets the centre dead zone threshold (default 26) |
| 157 | + |
| 158 | +### Advanced Example - Direction Detection |
| 159 | + |
| 160 | +```arduino |
| 161 | +#include <Modulino.h> |
| 162 | +
|
| 163 | +ModulinoJoystick joystick; |
| 164 | +
|
| 165 | +// Movement thresholds |
| 166 | +const int8_t MOVE_THRESHOLD = 50; |
| 167 | +
|
| 168 | +void setup() { |
| 169 | + Serial.begin(9600); |
| 170 | + Modulino.begin(); |
| 171 | + joystick.begin(); |
| 172 | + |
| 173 | + // Set custom dead zone (smaller = more sensitive) |
| 174 | + joystick.setDeadZone(20); |
| 175 | + |
| 176 | + Serial.println("Joystick Direction Detector"); |
| 177 | +} |
| 178 | +
|
| 179 | +void loop() { |
| 180 | + if (joystick.update()) { |
| 181 | + int8_t x = joystick.getX(); |
| 182 | + int8_t y = joystick.getY(); |
| 183 | + bool button = joystick.isPressed(); |
| 184 | + |
| 185 | + // Determine direction |
| 186 | + String direction = "CENTRE"; |
| 187 | + |
| 188 | + if (y > MOVE_THRESHOLD) { |
| 189 | + direction = "DOWN"; |
| 190 | + } else if (y < -MOVE_THRESHOLD) { |
| 191 | + direction = "UP"; |
| 192 | + } |
| 193 | + |
| 194 | + if (x > MOVE_THRESHOLD) { |
| 195 | + direction += (direction == "CENTRE") ? "RIGHT" : " RIGHT"; |
| 196 | + } else if (x < -MOVE_THRESHOLD) { |
| 197 | + direction += (direction == "CENTRE") ? "LEFT" : " LEFT"; |
| 198 | + } |
| 199 | + |
| 200 | + // Display state |
| 201 | + Serial.print("Direction: "); |
| 202 | + Serial.print(direction); |
| 203 | + |
| 204 | + if (button) { |
| 205 | + Serial.println(" [ACTION!]"); |
| 206 | + } else { |
| 207 | + Serial.println(); |
| 208 | + } |
| 209 | + } |
| 210 | + |
| 211 | + delay(50); |
| 212 | +} |
| 213 | +``` |
| 214 | + |
| 215 | +## Programming with MicroPython |
| 216 | + |
| 217 | +The Modulino Joystick is fully compatible with MicroPython through the official Modulino MicroPython library. The following examples demonstrate how to read joystick position and button state in your MicroPython projects. |
| 218 | + |
| 219 | +### Prerequisites |
| 220 | + |
| 221 | +- Install the Modulino MicroPython library (see [Getting Started with Modulinos](./how-general) for detailed instructions) |
| 222 | +- Ensure Arduino Lab for MicroPython is installed |
| 223 | + |
| 224 | +### Basic Example |
| 225 | + |
| 226 | +```python |
| 227 | +from modulino import ModulinoJoystick |
| 228 | +from time import sleep |
| 229 | + |
| 230 | +joystick = ModulinoJoystick() |
| 231 | + |
| 232 | +while True: |
| 233 | + x = joystick.x |
| 234 | + y = joystick.y |
| 235 | + pressed = joystick.is_pressed |
| 236 | + |
| 237 | + if x is not None and y is not None: |
| 238 | + print(f"X: {x:4d} Y: {y:4d} Button: {'PRESSED' if pressed else 'Released'}") |
| 239 | + |
| 240 | + sleep(0.1) |
| 241 | +``` |
| 242 | + |
| 243 | +### Key Properties |
| 244 | + |
| 245 | +- `.x`: Returns horizontal position (-128 to 127, centre = 0) |
| 246 | +- `.y`: Returns vertical position (-128 to 127, centre = 0) |
| 247 | +- `.is_pressed`: Returns button state (True when pressed) |
| 248 | + |
| 249 | +### Advanced Example - Game Controller |
| 250 | + |
| 251 | +```python |
| 252 | +from modulino import ModulinoJoystick |
| 253 | +from time import sleep |
| 254 | + |
| 255 | +joystick = ModulinoJoystick() |
| 256 | + |
| 257 | +MOVE_THRESHOLD = 50 |
| 258 | + |
| 259 | +def get_direction(x, y): |
| 260 | + """Determine joystick direction""" |
| 261 | + direction = "CENTRE" |
| 262 | + |
| 263 | + if y > MOVE_THRESHOLD: |
| 264 | + direction = "DOWN" |
| 265 | + elif y < -MOVE_THRESHOLD: |
| 266 | + direction = "UP" |
| 267 | + |
| 268 | + if x > MOVE_THRESHOLD: |
| 269 | + direction += " RIGHT" if direction == "CENTRE" else " RIGHT" |
| 270 | + elif x < -MOVE_THRESHOLD: |
| 271 | + direction += " LEFT" if direction == "CENTRE" else " LEFT" |
| 272 | + |
| 273 | + return direction |
| 274 | + |
| 275 | +print("🎮 Game Controller Ready") |
| 276 | +print("Move joystick to control") |
| 277 | + |
| 278 | +while True: |
| 279 | + x = joystick.x |
| 280 | + y = joystick.y |
| 281 | + pressed = joystick.is_pressed |
| 282 | + |
| 283 | + if x is not None and y is not None: |
| 284 | + direction = get_direction(x, y) |
| 285 | + action = " [ACTION!]" if pressed else "" |
| 286 | + print(f"Direction: {direction:15s}{action}") |
| 287 | + |
| 288 | + sleep(0.1) |
| 289 | +``` |
| 290 | + |
| 291 | +## Troubleshooting |
| 292 | + |
| 293 | +### Sensor Not Reachable |
| 294 | + |
| 295 | +If your Modulino's power LED isn't on or the sensor isn't responsive: |
| 296 | +- Ensure both the board and the Modulino are connected to your computer |
| 297 | +- Verify that the power LEDs on both are lit |
| 298 | +- Check that the QWIIC cable is properly clicked into place |
| 299 | + |
| 300 | +### Inaccurate Values |
| 301 | + |
| 302 | +If the joystick values are not centred or accurate: |
| 303 | +- Allow the joystick to self-centre (release it completely) |
| 304 | +- Adjust the dead zone using `setDeadZone()` if needed |
| 305 | +- Ensure the module is on a stable surface |
| 306 | + |
| 307 | +### Library Issues |
| 308 | + |
| 309 | +See the [Getting Started with Modulinos](./how-general) guide for library installation troubleshooting. |
| 310 | + |
| 311 | +## Project Ideas |
| 312 | + |
| 313 | +Now that you've learned how to use your Modulino Joystick, try these projects: |
| 314 | + |
| 315 | +- **Robot Controller**: Control a wheeled robot with intuitive directional input |
| 316 | +- **Game Console**: Build retro-style games with joystick control |
| 317 | +- **Camera Pan/Tilt**: Control servo motors for camera movement |
| 318 | +- **Drone Controller**: Create a ground station for RC vehicles |
| 319 | +- **Menu Navigation**: Navigate through LCD menu systems |
| 320 | +- **Drawing Pad**: Control cursor position for digital art applications |
| 321 | +- **Lighting Control**: Adjust RGB LED colours by moving the joystick |
| 322 | +- **Mechanical Arm**: Control robotic arm positioning |
0 commit comments