아두이노 우노 Q 조이스틱
조이스틱을 사용하면 2축 움직임과 버튼 누름을 감지할 수 있습니다. 게임 컨트롤러의 썸스틱과 같습니다. 이 튜토리얼에서는 조이스틱을 Arduino UNO Q에 연결하고, X/Y 축 값과 버튼 상태를 읽으며, 이를 방향 명령으로 변환하고, Telegram을 통해 원격으로 조이스틱 읽기를 확인하는 방법을 배웁니다.
※ 주의:
Arduino UNO Q ADC 차이점: Arduino UNO Q의 STM32 MCU는 12비트 ADC(값 0–4095, 중심 ~2048)를 가지고 있으며, 다른 많은 Arduino 보드와는 달리 10비트(0–1023)입니다. 기준 전압은 3.3V입니다. 조이스틱 위치를 매핑할 때 항상 이 값들을 사용하세요.
필요한 하드웨어
| 1 | × | Arduino UNO Q | 아마존 | |
| 1 | × | USB Cable for Arduino Uno Q | 아마존 | |
| 1 | × | 조이스틱 (Joystick) | 쿠팡 | 아마존 | |
| 1 | × | 점퍼케이블 | 쿠팡 | 아마존 | |
| 1 | × | (추천) 아두이노 우노용 스크루 터미널 블록 쉴드 | 쿠팡 | 아마존 | |
| 1 | × | (추천) Sensors/Servo Expansion Shield for Arduino Uno | 쿠팡 | 아마존 | |
| 1 | × | (추천) 아두이노 우노용 브레드보드 쉴드 | 쿠팡 | 아마존 | |
| 1 | × | (추천) 아두이노 우노용 케이스 | 쿠팡 | 아마존 | |
| 1 | × | (추천) 아두이노 우노용 프로토타이핑 베이스 플레이트 & 브레드보드 키트 | 아마존 |
공개: 이 포스팅 에 제공된 일부 링크는 아마존 제휴 링크입니다. 이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.
2축 조이스틱 정보
게임 컨트롤러, 장난감 컨트롤러, 산업용 기계에서 조이스틱을 사용한 경험이 있을 수 있습니다. 조이스틱은 두 개의 가변저항과 누름 버튼을 결합하여 세 개의 출력을 만듭니다:
- VRX: 아날로그 값(Arduino UNO Q에서 0–4095)은 가로 위치(X축)에 해당합니다
- VRY: 아날로그 값(Arduino UNO Q에서 0–4095)은 세로 위치(Y축)에 해당합니다
- SW: 내장 누름 버튼의 디지털 신호(누르면 풀업과 함께 LOW)
핀아웃
조이스틱 모듈은 5개의 핀이 있습니다:
- GND 핀: GND(0V)에 연결
- VCC 핀: 3.3V에 연결(Arduino UNO Q MCU는 3.3V에서 작동)
- VRX 핀: 가로축 — 아날로그 입력 핀에 연결되는 아날로그 출력
- VRY 핀: 세로축 — 아날로그 입력 핀에 연결되는 아날로그 출력
- SW 핀: 누름 버튼 출력 — 디지털 입력 핀에 연결(내부 풀업 사용)
작동 원리
- 썸스틱을 좌우로 움직이면 VRX 전압이 0V에서 3.3V로 변함 → ADC는 0에서 4095로 읽음
- 썸스틱을 상하로 움직이면 VRY 전압이 0V에서 3.3V로 변함 → ADC는 0에서 4095로 읽음
- 중앙/정지 위치에서 VRX와 VRY는 모두 대략 2048(중간 범위)을 읽음
- 썸스틱을 아래로 누르면 내부 버튼이 닫힘 — 풀업을 활성화하면 SW는 LOW를 읽음
※ 주의:
배선을 하기 전에 아래의 첫 번째 코드 예제를 실행하여 특정 조이스틱에서 어느 방향이 낮음/높음 값을 주는지 확인하세요. 축 방향은 제조업체마다 다를 수 있습니다.
배선 다이어그램
이 이미지는 Fritzing을 사용하여 만들어졌습니다. 이미지를 확대하려면 클릭하세요.
| 조이스틱 핀 | Arduino UNO Q 핀 |
|---|---|
| GND | GND |
| VCC | 3.3V |
| VRX | A0 |
| VRY | A1 |
| SW | D2 |
조이스틱을 위한 프로그래밍 방법
- 아날로그 축(VRX, VRY)의 경우 analogRead()로 ADC 값을 읽습니다:
int value_X = analogRead(A0); // 0 to 4095 on Arduino UNO Q
int value_Y = analogRead(A1);
- 버튼(SW)의 경우 내장 디바운싱 및 풀업 지원을 위해 ezButton 라이브러리를 사용합니다:
#include <ezButton.h>
ezButton button(2);
button.loop();
int state = button.getState(); // LOW = pressed, HIGH = released
- 아날로그 값을 방향 명령으로 변환하려면 임계값과 비교합니다. Arduino UNO Q의 12비트 ADC를 사용하면 ~1600 / ~2400을 저/고 임계값으로 사용합니다(중심은 ~2048):
if (value_X < 1600)
// LEFT
else if (value_X > 2400)
// RIGHT
MCU 코드
Arduino UNO Q는 두 개의 프로세서를 가지고 있습니다: STM32 MCU(실시간 하드웨어 제어 처리)와 Qualcomm MPU(Debian Linux 실행). 이 섹션에서는 STM32 MCU만 프로그래밍됩니다 — Linux 쪽은 유휴 상태로 유지됩니다. 나중 섹션에서는 두 프로세서가 함께 작동하는 방법을 보여줍니다.
예제 1: X 및 Y 아날로그 값 읽기
/*
* 이 Arduino UNO Q 코드는 newbiely.kr 에서 개발되었습니다
* 이 Arduino UNO Q 코드는 어떠한 제한 없이 공개 사용을 위해 제공됩니다.
* 상세한 지침 및 연결도에 대해서는 다음을 방문하세요:
* https://newbiely.kr/tutorials/arduino-uno-q/arduino-uno-q-joystick
*/
#define VRX_PIN A0 // Arduino UNO Q pin connected to VRX
#define VRY_PIN A1 // Arduino UNO Q pin connected to VRY
int value_X = 0; // stores X-axis ADC value (0 to 4095)
int value_Y = 0; // stores Y-axis ADC value (0 to 4095)
void setup() {
// nothing to set up — analog pins are inputs by default
}
void loop() {
// read 12-bit ADC values from joystick axes (0 to 4095 on Arduino UNO Q)
value_X = analogRead(VRX_PIN);
value_Y = analogRead(VRY_PIN);
// TO DO: use value_X and value_Y in your logic here
// Example: map X to a percentage
// int x_percent = map(value_X, 0, 4095, 0, 100);
delay(200);
}
빠른 단계
- Arduino UNO Q를 처음 사용하십니까? 진행하기 전에 아두이노 우노 Q 시작하기 튜토리얼을 따라 개발 환경을 준비하세요.
- 조이스틱 배선: 배선 다이어그램에 따라 GND를 GND에, VCC를 3.3V에, VRX를 A0에, VRY를 A1에 연결합니다.
- 연결: USB-C 케이블을 사용하여 Arduino UNO Q를 컴퓨터에 연결합니다.
- Arduino App Lab 열기: Arduino App Lab을 시작하고 Arduino UNO Q를 감지할 때까지 기다립니다.
- 새 앱 만들기: Create New App 버튼을 클릭합니다.
- 앱에 이름을 지정합니다. 예: DIYables_Joystick
- Create를 클릭하여 확인합니다.
- 새 앱 내부에 폴더 및 파일 집합이 생성됩니다.
- sketch/sketch.ino 파일을 찾습니다 — 여기에 MCU 스케치를 붙여 넣을 것입니다.
스케치 붙여넣기: 위의 MCU 코드를 복사하여 스케치 파일에 붙여 넣습니다. 다른 파일은 기본값으로 유지합니다.
- Install the library: Click the Add sketch library button (the open book icon with a + sign) in the left sidebar.
- Search for Arduino_RouterBridge created by Arduino and click the Install button.
Bricks
No bricks added...
Sketch Libraries
No sketch libra...
Files
python
sketch
.gitignore
README.md
app.yaml
sketch.ino
- Search for ezButton created by ArduinoGetStarted.com and click the Install button.
Bricks
No bricks added...
Sketch Libraries
No sketch libra...
Files
python
sketch
.gitignore
README.md
app.yaml
sketch.ino
- 업로드: Arduino App Lab에서 Run 버튼을 클릭하여 STM32로 컴파일하고 업로드합니다.
- 조이스틱 움직이기 — 코드를 TO DO 로직으로 확장하여 동작을 관찰하거나 Bridge 섹션으로 진행하여 라이브 읽기를 보세요.
- 전문가 팁: 조이스틱을 완전히 좌, 우, 상, 하로 움직여 실제 최소/최대 값을 찾으세요. 조이스틱에 따라 정확히 0 또는 4095에 도달하지 않을 수 있습니다.
예제 2: X, Y 값 및 버튼 상태 읽기
/*
* 이 Arduino UNO Q 코드는 newbiely.kr 에서 개발되었습니다
* 이 Arduino UNO Q 코드는 어떠한 제한 없이 공개 사용을 위해 제공됩니다.
* 상세한 지침 및 연결도에 대해서는 다음을 방문하세요:
* https://newbiely.kr/tutorials/arduino-uno-q/arduino-uno-q-joystick
*/
#include <ezButton.h>
#define VRX_PIN A0 // Arduino UNO Q pin connected to VRX
#define VRY_PIN A1 // Arduino UNO Q pin connected to VRY
#define SW_PIN 2 // Arduino UNO Q pin connected to SW
ezButton button(SW_PIN); // create ezButton with internal pull-up
int value_X = 0; // stores X-axis ADC value (0 to 4095)
int value_Y = 0; // stores Y-axis ADC value (0 to 4095)
void setup() {
button.setDebounceTime(50); // set debounce time to 50 milliseconds
}
void loop() {
button.loop(); // MUST call the loop() function first
// read 12-bit ADC values from joystick axes
value_X = analogRead(VRX_PIN);
value_Y = analogRead(VRY_PIN);
if (button.isPressed()) {
// TO DO: handle button press here
}
if (button.isReleased()) {
// TO DO: handle button release here
}
// TO DO: use value_X and value_Y in your logic here
delay(200);
}
빠른 단계
- 예제 1의 동일한 앱을 사용합니다.
- 스케치를 위의 코드로 교체합니다.
- 또한 SW를 D2 핀에 연결합니다(아직 하지 않은 경우).
- 업로드하고 조이스틱을 움직이고 버튼을 누릅니다.
- 전문가 팁: TO DO 섹션은 자신의 로직을 추가하는 곳입니다. 예를 들어 버튼 누름에서 LED를 토글합니다.
예제 3: 방향 명령으로 변환
/*
* 이 Arduino UNO Q 코드는 newbiely.kr 에서 개발되었습니다
* 이 Arduino UNO Q 코드는 어떠한 제한 없이 공개 사용을 위해 제공됩니다.
* 상세한 지침 및 연결도에 대해서는 다음을 방문하세요:
* https://newbiely.kr/tutorials/arduino-uno-q/arduino-uno-q-joystick
*/
#define VRX_PIN A0 // Arduino UNO Q pin connected to VRX
#define VRY_PIN A1 // Arduino UNO Q pin connected to VRY
// 12-bit ADC on Arduino UNO Q: center ~2048, range 0-4095
#define LEFT_THRESHOLD 1600
#define RIGHT_THRESHOLD 2400
#define UP_THRESHOLD 1600
#define DOWN_THRESHOLD 2400
#define COMMAND_NO 0x00
#define COMMAND_LEFT 0x01
#define COMMAND_RIGHT 0x02
#define COMMAND_UP 0x04
#define COMMAND_DOWN 0x08
int value_X = 0;
int value_Y = 0;
int command = COMMAND_NO;
void setup() {
// nothing to set up
}
void loop() {
// read 12-bit ADC values from joystick axes
value_X = analogRead(VRX_PIN);
value_Y = analogRead(VRY_PIN);
// convert analog values to direction commands
command = COMMAND_NO;
if (value_X < LEFT_THRESHOLD)
command = command | COMMAND_LEFT;
else if (value_X > RIGHT_THRESHOLD)
command = command | COMMAND_RIGHT;
if (value_Y < UP_THRESHOLD)
command = command | COMMAND_UP;
else if (value_Y > DOWN_THRESHOLD)
command = command | COMMAND_DOWN;
// NOTE: AT A TIME, THERE MAY BE NO COMMAND, ONE COMMAND, OR TWO COMMANDS
if (command & COMMAND_LEFT) {
// TO DO: add your left task here
}
if (command & COMMAND_RIGHT) {
// TO DO: add your right task here
}
if (command & COMMAND_UP) {
// TO DO: add your up task here
}
if (command & COMMAND_DOWN) {
// TO DO: add your down task here
}
}
빠른 단계
- 동일한 앱을 사용하고 스케치를 위의 코드로 교체합니다.
- 업로드하고 조이스틱을 모든 4방향으로 움직입니다.
- 각 TO DO 블록에 자신의 로직을 추가합니다(예: 왼쪽 명령이 활성화되면 digitalWrite(LED_PIN, HIGH)).
- 전문가 팁: 언제든지 명령 없음, 한 명령, 또는 두 동시 명령(예: UP과 LEFT 동시에)이 있을 수 있습니다 — 코드는 모든 경우를 처리해야 합니다.
Linux + MCU 브릿지 프로그래밍
Arduino UNO Q는 함께 작동하는 두 개의 프로세서를 가지고 있습니다: MPU(Qualcomm, Debian Linux 실행)와 MCU(STM32, Zephyr OS에서 Arduino 스케치 실행). 이들은 Arduino_RouterBridge 라이브러리를 통해 RPC를 사용하여 통신합니다 — 절대 원본 시리얼 포트를 통하지 않습니다.
- 조이스틱은 MCU(STM32)에 연결됩니다 — VRX는 A0에, VRY는 A1에, SW는 D2에 연결됩니다. MCU는 아날로그 값과 버튼 상태를 읽습니다.
- MPU는 조이스틱을 직접 읽을 수 없습니다 — MCU에 Bridge.call()을 통해 읽기를 요청해야 합니다. MCU는 현재 X, Y 값과 버튼 상태로 응답합니다.
- MPU는 Wi-Fi를 가지고 있습니다 — MPU는 Wi-Fi를 포함한 전체 Debian Linux를 실행하기 때문에 Telegram을 통해 조이스틱 읽기를 보고할 수 있습니다.
- 통신: Linux 쪽의 Bridge.call()은 MCU 쪽의 Bridge.provide() 함수를 호출합니다
- ⚠️ 예약됨: /dev/ttyHS1(Linux)과 Serial1(MCU)은 Arduino Router에서 사용됩니다 — 직접 열지 마세요.
간단히 말해서: MPU가 조이스틱 읽기를 요청 → MCU가 X, Y, 버튼 읽음 → MCU가 값 보고 → MPU가 로그하거나 전달.
MCU 스케치 — 브릿지 및 모니터 출력이 있는 조이스틱:
/*
* 이 Arduino UNO Q 코드는 newbiely.kr 에서 개발되었습니다
* 이 Arduino UNO Q 코드는 어떠한 제한 없이 공개 사용을 위해 제공됩니다.
* 상세한 지침 및 연결도에 대해서는 다음을 방문하세요:
* https://newbiely.kr/tutorials/arduino-uno-q/arduino-uno-q-joystick
*/
#include "Arduino_RouterBridge.h"
#include <ezButton.h>
#define VRX_PIN A0
#define VRY_PIN A1
#define SW_PIN 2
ezButton button(SW_PIN);
void get_joystick() {
button.loop();
int x = analogRead(VRX_PIN);
int y = analogRead(VRY_PIN);
const char* btn_state = (button.getState() == LOW) ? "PRESSED" : "RELEASED";
Monitor.print("x = ");
Monitor.print(x);
Monitor.print(", y = ");
Monitor.print(y);
Monitor.print(", button = ");
Monitor.println(btn_state);
}
void setup() {
Bridge.begin();
Monitor.begin();
button.setDebounceTime(50);
Bridge.provide("get_joystick", get_joystick);
Monitor.println("Joystick Bridge ready");
}
void loop() {}
Python 스크립트(Arduino App Lab) — Linux에서 조이스틱 폴링:
/*
* 이 Arduino UNO Q 코드는 newbiely.kr 에서 개발되었습니다
* 이 Arduino UNO Q 코드는 어떠한 제한 없이 공개 사용을 위해 제공됩니다.
* 상세한 지침 및 연결도에 대해서는 다음을 방문하세요:
* https://newbiely.kr/tutorials/arduino-uno-q/arduino-uno-q-joystick
*/
from arduino.app_utils import *
import time
def loop():
while True:
Bridge.call("get_joystick")
time.sleep(0.5)
App.run(user_loop=loop)
- 참고: MCU 스케치에서 Bridge.begin()이 호출되었는지, 그리고 스케치가 업로드되었는지 확인한 후 Linux 쪽에서 Python 스크립트를 실행하세요.
- ⚠️ 경고: Linux에서 /dev/ttyHS1을 직접 열거나 MCU에서 Serial1을 사용하지 마세요 — 이들은 Arduino Router에 의해 예약되어 있으며 액세스하면 브릿지가 끊깁니다.
빠른 단계
- MCU 스케치 업로드: Arduino App Lab을 열고, 새 앱을 만들고, 위의 브릿지 MCU 스케치를 sketch/sketch.ino에 붙여 넣고, ezButton 및 Arduino_RouterBridge 라이브러리를 설치하고, Run을 클릭합니다.
- Python 스크립트 추가: 위의 Python 코드를 동일한 앱의 Python 탭에 붙여 넣습니다.
- 앱 실행: Run을 클릭합니다 — Python 쪽은 500ms마다 조이스틱을 폴링합니다.
- 조이스틱을 움직이고 버튼을 누릅니다 — 콘솔에서 X, Y 및 버튼 상태 업데이트를 확인합니다.
- 콘솔 확인: Console 탭을 열고 → MCU Monitor 서브탭입니다.
App Lab 콘솔 출력
sketch.ino
1#include "Arduino_RouterBridge.h"
Serial Monitor
Python
Joystick Bridge ready
x = 2048, y = 2048, button = RELEASED
x = 512, y = 2048, button = RELEASED
x = 512, y = 200, button = RELEASED
x = 2048, y = 2048, button = PRESSED
Telegram 통합
Telegram을 통해 원격으로 어디서나 현재 조이스틱 위치 및 버튼 상태를 읽습니다.
아직 Telegram 봇이 없다면 진행하기 전에 아두이노 우노 Q - 텔레그램 봇을 보아 봇 토큰을 얻으세요.
MCU 스케치: 이전 브릿지 섹션에서 동일한 MCU 스케치를 유지합니다 — 변경 사항이 없습니다. STM32에 이미 업로드되어 실행 중인지 확인하세요.
Python 스크립트(Arduino App Lab) — 조이스틱 읽기용 Telegram 봇:
/*
* 이 Arduino UNO Q 코드는 newbiely.kr 에서 개발되었습니다
* 이 Arduino UNO Q 코드는 어떠한 제한 없이 공개 사용을 위해 제공됩니다.
* 상세한 지침 및 연결도에 대해서는 다음을 방문하세요:
* https://newbiely.kr/tutorials/arduino-uno-q/arduino-uno-q-joystick
*/
from arduino.app_utils import *
import requests
import time
BOT_TOKEN = "YOUR_BOT_TOKEN"
API_URL = f"https://api.telegram.org/bot{BOT_TOKEN}"
last_update_id = 0
def send_message(chat_id, text):
requests.post(f"{API_URL}/sendMessage", json={"chat_id": chat_id, "text": text})
def get_updates():
global last_update_id
resp = requests.get(f"{API_URL}/getUpdates", params={"offset": last_update_id + 1, "timeout": 5})
return resp.json().get("result", [])
def loop():
global last_update_id
updates = get_updates()
for update in updates:
last_update_id = update["update_id"]
msg = update.get("message", {})
chat_id = msg.get("chat", {}).get("id")
text = msg.get("text", "").strip()
if text == "/read":
result = Bridge.call("get_joystick")
send_message(chat_id, result)
else:
send_message(chat_id, "Commands:\n/read — read joystick X, Y position and button state")
time.sleep(1)
App.run(user_loop=loop)
- 참고: YOUR_BOT_TOKEN을 Telegram에서 @BotFather로부터 얻은 토큰으로 교체합니다.
- /read를 보내 현재 X, Y 위치 및 버튼 상태를 가져옵니다.
빠른 단계
- MCU 스케치 업로드: 이전 섹션에서 브릿지 MCU 스케치를 사용합니다(아직 하지 않은 경우 먼저 업로드합니다).
- Telegram 스크립트 붙여넣기: 위의 Python 코드를 Arduino App Lab의 앱의 Python 탭에 복사합니다.
- 토큰 설정: 스크립트의 YOUR_BOT_TOKEN을 실제 봇 토큰으로 교체합니다.
- 앱 실행: Run을 클릭합니다 — 봇이 Telegram 메시지를 수신 대기 시작합니다.
- 테스트: 조이스틱을 움직이고, /read를 보냅니다 — 봇이 X, Y 값과 버튼 상태로 응답합니다.
App Lab 콘솔 출력
sketch.ino
1#include "Arduino_RouterBridge.h"
Serial Monitor
Python
[2026-04-29 12:00:01] Telegram: /read
[2026-04-29 12:00:01] x = 2048, y = 2048, button = RELEASED
[2026-04-29 12:02:10] Telegram: /read
[2026-04-29 12:02:10] x = 512, y = 200, button = RELEASED
[2026-04-29 12:04:05] Telegram: /read
[2026-04-29 12:04:05] x = 2048, y = 2048, button = PRESSED
Telegram
12:45
Welcome to Telegram!
ArduinoBot
10:19
Chatting with Arduino...
BotFather
Yesterday
Your bot has been created.
ArduinoBot
bot
OpenClaw 통합
아두이노 우노 Q - OpenClaw 튜토리얼의 지침을 참고하여 OpenClaw를 이 튜토리얼에 맞게 조정할 수 있습니다.
애플리케이션/프로젝트 아이디어
- 원격 로봇 제어: Telegram을 통해 보낸 조이스틱 X/Y 값을 사용하여 로봇의 방향과 속도를 제어합니다
- 팬-틸트 카메라: X를 팬 서보 각도에, Y를 카메라 위치 지정을 위한 틸트 서보 각도에 매핑합니다
- 게임 컨트롤러: 조이스틱 위치를 네트워크를 통해 읽는 간단한 2인 게임을 만듭니다
- 크레인 제어: 조이스틱 방향 명령을 사용하여 모델 크레인 팔을 들어올리고, 내립니다, 흔듭니다
- 커서 제어: 조이스틱 값을 OLED 또는 TFT 디스플레이의 커서 움직임에 매핑합니다
도전 과제
- 쉬움: Telegram을 통해 조이스틱 버튼이 현재 눌렸거나 해제되었는지만 보고하는 /button Telegram 명령을 추가합니다
- 중간: X 및 Y 값을 방향 레이블(LEFT, RIGHT, UP, DOWN, CENTER)에 매핑하고 Telegram을 통해 원본 숫자 대신 레이블을 보냅니다
- 고급: 조이스틱 위치가 브릿지를 통해 실시간으로 서보 각도를 설정하는 2축 서보 팬-틸트 시스템을 구축합니다