아두이노 우노 Q 텔레그램 봇
텔레그램을 사용하여 어디서나 Arduino UNO Q를 제어하고 싶으신가요? 이 튜토리얼은 Arduino UNO Q 리눅스 측(Debian)에서 실행되고 /toggle_led 또는 /status와 같은 고정된 명령에 응답하는 텔레그램 봇을 만드는 방법을 보여줍니다 — AI나 클라우드 서비스가 필요 없습니다.
이 튜토리얼에서 배울 내용:
- BotFather를 사용하여 텔레그램 봇을 만들고 봇 토큰을 받는 방법
- Bridge를 통해 하드웨어 제어를 노출하는 MCU 스케치를 작성하는 방법
- Arduino UNO Q 리눅스 측에서 텔레그램 명령을 받고 MCU를 제어하는 Python 스크립트를 작성하는 방법
- 텔레그램에서 종단 간 제어를 테스트하는 방법
필요한 하드웨어
| 1 | × | Arduino UNO Q | 아마존 | |
| 1 | × | USB Cable for Arduino Uno Q | 아마존 | |
| 1 | × | (추천) 아두이노 우노용 스크루 터미널 블록 쉴드 | 쿠팡 | 아마존 | |
| 1 | × | (추천) Sensors/Servo Expansion Shield for Arduino Uno | 쿠팡 | 아마존 | |
| 1 | × | (추천) 아두이노 우노용 브레드보드 쉴드 | 쿠팡 | 아마존 | |
| 1 | × | (추천) 아두이노 우노용 케이스 | 쿠팡 | 아마존 | |
| 1 | × | (추천) 아두이노 우노용 프로토타이핑 베이스 플레이트 & 브레드보드 키트 | 아마존 |
공개: 이 포스팅 에 제공된 일부 링크는 아마존 제휴 링크입니다. 이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.
작동 원리
Arduino UNO Q는 두 개의 프로세서를 결합합니다:
- STM32 MCU — Arduino 스케치를 실행합니다. 실시간으로 하드웨어(LED, 릴레이, 센서 등)를 제어합니다.
- Qualcomm MPU — 완전한 Debian 리눅스를 실행합니다. Wi-Fi에 연결하고 텔레그램과 통신하는 Python 스크립트를 실행할 수 있습니다.
두 프로세서는 Bridge를 통해 통신합니다. MCU는 Bridge를 통해 하드웨어 함수를 노출하고, 리눅스 측의 Python 스크립트는 텔레그램 명령이 도착할 때 해당 함수를 호출합니다.
각 사용자 메시지에 대한 흐름은 다음과 같습니다:
- 사용자가 텔레그램 봇에 명령을 보냅니다: /toggle_led
- Python 스크립트가 Arduino UNO Q 리눅스 측에서 실행되고 텔레그램 API를 폴링하여 메시지를 받고 명령을 파싱합니다
- Python 스크립트가 Bridge.call("toggle_led", "")를 호출하여 MCU에 도달합니다
- MCU (STM32)가 LED를 전환하고 Bridge를 통해 결과를 반환합니다
- Python 스크립트가 텔레그램을 통해 사용자에게 응답을 보냅니다: LED is now ON
※ 주의:
Python 스크립트는 긴 폴링을 사용합니다 — 반복해서 텔레그램에 "새로운 메시지가 있나요?"라고 물어봅니다. 공인 IP 주소나 포트 포워딩 없이 작동하므로 모든 네트워크에서 실행됩니다.
| 기능 | 세부 사항 | |
|---|---|---|
| 명령 스타일 | 고정된 명령 (예 | /toggle_led, /status) |
| AI 모델 필요 | 없음 | |
| 메시징 채널 | 텔레그램만 해당 | |
| 실행 위치 | Arduino UNO Q 리눅스 측 (Debian) | |
| 공인 IP 필요 | 없음 (폴링 사용) |
※ 주의:
자연어 제어("LED를 켜기", "상태가 어떻게 되나요?")와 여러 채널(텔레그램, WhatsApp, Discord 등)을 원하시면 아두이노 우노 Q - OpenClaw 튜토리얼을 참조하세요.
사전 요구 사항
시작하기 전에 다음이 필요합니다:
- Arduino UNO Q가 실행 중이고 작동 중 — 먼저 아두이노 우노 Q 시작하기 튜토리얼을 따르세요
- Arduino App Lab이 설치되어 작동 중
- Bridge에 대한 이해 — 아두이노 우노 Q - Linux와 MCU 간의 통신 튜토리얼 참조
- 텔레그램 계정 — telegram.org에서 휴대폰 또는 데스크톱에 텔레그램을 설치하세요
- Arduino UNO Q가 Wi-Fi에 연결되어 리눅스 측이 인터넷에 접근할 수 있어야 합니다
단계 1 — BotFather로 텔레그램 봇 만들기
BotFather는 다른 봇을 만들고 관리하는 공식 텔레그램 봇입니다. Python 스크립트가 메시지를 보내고 받을 때 사용하는 키인 봇 토큰을 얻기 위해 사용합니다.
- 텔레그램을 열고 @BotFather를 검색하거나 이 링크를 열기: t.me/BotFather
- 채팅을 시작하고 다음을 보내기:
Telegram
12:45
Welcome to Telegram!
ArduinoBot
10:19
Chatting with Arduino...
BotFather
Yesterday
Your bot has been created.
BotFather
bot
- 봇의 표시 이름을 보내세요 (아무거나 괜찮습니다):
Telegram
12:45
Welcome to Telegram!
ArduinoBot
10:19
Chatting with Arduino...
BotFather
Yesterday
Your bot has been created.
BotFather
bot
- bot으로 끝나는 사용자 이름을 보내세요 (텔레그램 전체에서 고유해야 함):
Telegram
12:45
Welcome to Telegram!
ArduinoBot
10:19
Chatting with Arduino...
BotFather
Yesterday
Your bot has been created.
BotFather
bot
- 봇 토큰 복사 — 다음과 같이 생겼습니다:
1234567890:ABCDefGhIJKlmNoPQRsTUVwXYZ1234567890
※ 주의:
봇 토큰을 비밀로 유지하세요. 누구든지 봇 토큰을 가지고 있으면 봇을 통해 메시지를 보내고 받을 수 있습니다.
단계 2 — Arduino UNO Q 코드
MCU 코드
MCU 스케치는 Bridge를 통해 하드웨어 제어 함수를 노출합니다. 텔레그램 명령이 도착할 때 리눅스 측의 Python 스크립트가 이 함수를 호출합니다.
/*
* 이 Arduino UNO Q 코드는 newbiely.kr 에서 개발되었습니다
* 이 Arduino UNO Q 코드는 어떠한 제한 없이 공개 사용을 위해 제공됩니다.
* 상세한 지침 및 연결도에 대해서는 다음을 방문하세요:
* https://newbiely.kr/tutorials/arduino-uno-q/arduino-uno-q-telegram-bot
*/
#include "Arduino_RouterBridge.h"
// LED_BUILTIN is LED3 on the board, lights up RED, active LOW
// LOW = ON, HIGH = OFF
bool ledState = false;
unsigned long startMs = 0;
String toggle_led(String arg) {
ledState = !ledState;
digitalWrite(LED_BUILTIN, ledState ? LOW : HIGH);
Monitor.println(ledState ? "LED turned ON" : "LED turned OFF");
return ledState ? "ON" : "OFF";
}
String led_on(String arg) {
ledState = true;
digitalWrite(LED_BUILTIN, LOW);
Monitor.println("LED turned ON");
return "ON";
}
String led_off(String arg) {
ledState = false;
digitalWrite(LED_BUILTIN, HIGH);
Monitor.println("LED turned OFF");
return "OFF";
}
String get_status(String arg) {
unsigned long uptime = (millis() - startMs) / 1000;
String status = "MCU is running. Uptime: " + String(uptime) + "s. LED: ";
status += ledState ? "ON" : "OFF";
Monitor.println("Status requested: " + status);
return status;
}
void setup() {
Monitor.begin();
Bridge.begin();
pinMode(LED_BUILTIN, OUTPUT);
digitalWrite(LED_BUILTIN, HIGH); // Start with LED off (active LOW)
startMs = millis();
Bridge.provide_safe("toggle_led", toggle_led);
Bridge.provide_safe("led_on", led_on);
Bridge.provide_safe("led_off", led_off);
Bridge.provide_safe("get_status", get_status);
Monitor.println("Telegram Bot Bridge ready");
}
void loop() {
}
Python 코드
Python 스크립트는 Arduino UNO Q 리눅스 측에서 실행됩니다. 텔레그램 API를 폴링하여 새로운 메시지를 받고, 명령을 파싱하고, Bridge를 통해 MCU를 호출하고, 응답을 보냅니다.
/*
* 이 Arduino UNO Q 코드는 newbiely.kr 에서 개발되었습니다
* 이 Arduino UNO Q 코드는 어떠한 제한 없이 공개 사용을 위해 제공됩니다.
* 상세한 지침 및 연결도에 대해서는 다음을 방문하세요:
* https://newbiely.kr/tutorials/arduino-uno-q/arduino-uno-q-telegram-bot
*/
from arduino.app_utils import *
import urllib.request
import urllib.parse
import json
import time
# ── Configuration ────────────────────────────────────────────────────────────
BOT_TOKEN = "YOUR_BOT_TOKEN" # Replace with the token from BotFather
# ─────────────────────────────────────────────────────────────────────────────
TELEGRAM_API = "https://api.telegram.org/bot" + BOT_TOKEN
HELP_TEXT = (
"Available commands:\n"
"/toggle_led - Toggle the LED\n"
"/led_on - Turn LED on\n"
"/led_off - Turn LED off\n"
"/status - Get MCU status\n"
"/help - Show this message"
)
def telegram_get(method, params=None):
url = TELEGRAM_API + "/" + method
if params:
url += "?" + urllib.parse.urlencode(params)
with urllib.request.urlopen(url, timeout=30) as resp:
return json.loads(resp.read().decode())
def telegram_post(method, data):
url = TELEGRAM_API + "/" + method
payload = json.dumps(data).encode()
req = urllib.request.Request(
url, data=payload,
headers={"Content-Type": "application/json"}
)
with urllib.request.urlopen(req, timeout=10) as resp:
return json.loads(resp.read().decode())
def send_message(chat_id, text):
telegram_post("sendMessage", {"chat_id": chat_id, "text": text})
def handle_command(chat_id, command):
if command == "/toggle_led":
state = Bridge.call("toggle_led", "")
reply = "LED is now " + state
elif command == "/led_on":
Bridge.call("led_on", "")
reply = "LED is now ON"
elif command == "/led_off":
Bridge.call("led_off", "")
reply = "LED is now OFF"
elif command == "/status":
reply = Bridge.call("get_status", "")
elif command == "/help" or command == "/start":
reply = HELP_TEXT
else:
reply = "Unknown command. Send /help for a list of commands."
print(command + " from chat " + str(chat_id) + " -> " + reply)
send_message(chat_id, reply)
def main():
print("Telegram bot started. Waiting for commands...")
offset = None
while True:
try:
params = {"timeout": 20, "allowed_updates": ["message"]}
if offset is not None:
params["offset"] = offset
result = telegram_get("getUpdates", params)
for update in result.get("result", []):
offset = update["update_id"] + 1
msg = update.get("message", {})
chat_id = msg.get("chat", {}).get("id")
text = msg.get("text", "").strip()
# Strip bot username suffix (e.g. /toggle_led@my_bot)
command = text.split("@")[0].lower()
handle_command(chat_id, command)
except Exception as e:
print("Error: " + str(e))
time.sleep(5)
main()
빠른 단계
Arduino UNO Q를 처음 사용하시나요? 진행하기 전에 아두이노 우노 Q 시작하기 튜토리얼을 따라 개발 환경을 준비하세요.
- 연결: USB-C 케이블을 사용하여 Arduino UNO Q를 컴퓨터에 연결하세요.
- Arduino App Lab 열기: Arduino App Lab을 실행하고 Arduino UNO Q를 감지할 때까지 기다리세요. 첫 실행 시 몇 분이 걸릴 수 있습니다.
- 새 앱 만들기: Create New App 버튼을 클릭하세요.
- 앱 이름 지정: TelegramBot
- Create를 클릭하여 확인하세요.
- 새 앱 내에 폴더 및 파일 세트가 생성됩니다.
MCU 스케치 붙여넣기: sketch/sketch.ino를 열고 내용을 위의 MCU 코드로 바꾸세요.
Python 스크립트 붙여넣기: python/main.py를 엽니다. 기존의 모든 내용을 선택하고 삭제한 다음 위의 Python 코드를 붙여넣으세요. 기본 템플릿 코드는 완전히 교체되어야 합니다 — 추가하지 마세요.
자격 증명 설정: Python 코드에서 BOT_TOKEN을 BotFather에서 복사한 봇 토큰으로 바꾸세요.
- 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
- 업로드: Arduino App Lab에서 Run 버튼을 클릭하여 STM32로 컴파일 및 업로드한 다음 Python 스크립트를 시작하세요.
- 팁: Arduino App Lab을 백그라운드에서 계속 실행하세요. 텔레그램 명령이 MCU에 도달하려면 Python 스크립트가 실행 중이어야 합니다.
App Lab 콘솔 출력
sketch.ino
1#include "Arduino_RouterBridge.h"
Serial Monitor
Python
[2026-05-08 10:00:01] Telegram Bot Bridge ready
[2026-05-08 10:00:04] LED turned ON
[2026-05-08 10:00:09] Status requested: MCU is running. LED: ON
[2026-05-08 10:00:15] LED turned OFF
sketch.ino
1#include "Arduino_RouterBridge.h"
Serial Monitor
Python
[2026-05-08 10:00:01] Telegram bot started. Waiting for commands...
[2026-05-08 10:00:04] /toggle_led from chat 987654321 -> LED is now ON
[2026-05-08 10:00:09] /status from chat 987654321 -> MCU is running. LED: ON
[2026-05-08 10:00:15] /toggle_led from chat 987654321 -> LED is now OFF
사용 가능한 명령
봇이 실행 중이면 텔레그램에서 봇에 이 명령들을 보내세요:
| 명령 | 기능 |
|---|---|
| /toggle_led | 내장 LED를 켜거나 끄고 새로운 상태로 응답합니다 |
| /led_on | LED를 켭니다 |
| /led_off | LED를 끕니다 |
| /status | 현재 MCU 상태(가동 시간 및 LED 상태)를 반환합니다 |
| /help | 사용 가능한 모든 명령을 나열합니다 |
테스트하기
MCU Bridge 스케치가 업로드되어 있고 Python 스크립트가 Arduino App Lab 내에서 실행 중인지 확인하세요. 그러면 텔레그램을 열고 사용자 이름으로 봇을 찾아 명령을 보내세요:
Telegram
12:45
Welcome to Telegram!
ArduinoBot
10:19
Chatting with Arduino...
BotFather
Yesterday
Your bot has been created.
ArduinoBot
bot
봇이 응답하지 않으면 다음을 확인하세요:
- Arduino App Lab이 열려 있고 Python 스크립트가 실행 중인가요
- Arduino UNO Q가 Wi-Fi에 연결되어 있나요
- Python 코드에서 BOT_TOKEN이 올바르게 설정되어 있나요
- 설정한 Chat ID의 텔레그램 계정에서 메시지를 보내고 있나요
봇 확장하기
더 많은 하드웨어 제어를 추가하려면 다음 단계를 따르세요:
- MCU 측: MCU 스케치에서 새로운 Bridge.provide_safe() 호출을 추가합니다.
- Python 측: Python 스크립트에 새로운 elif command == "/your_command": 블록을 추가하고, Bridge.call("your_function", "")를 호출하고, 응답을 보냅니다.
예: 릴레이 제어 명령을 추가하려면, MCU에서 toggle_relay를 노출한 다음 Python 스크립트에 다음을 추가하세요:
elif command == "/toggle_relay":
result = bridge.call("toggle_relay", "")
bot.send_message(chat_id, result)
그러면 /help 응답 텍스트에 /toggle_relay — Toggle the relay를 추가하세요.
프로젝트 아이디어
이를 Arduino UNO Q MCU에 연결된 모든 하드웨어로 확장할 수 있습니다:
- 원격 LED 스트립 제어: /led_on과 /led_off를 보내 어디서나 장식용 조명을 전환합니다
- 센서 대시보드: /status를 사용하여 온도, 습도 또는 모션 센서 판독값을 주문형으로 받습니다
- 문 또는 게이트 제어: /unlock을 보내 전자 자물쇠를 여는 릴레이를 트리거합니다
- 경보 시스템: 폴링을 주기적인 MCU 상태 확인과 결합하여 임계값을 초과하면(예: 온도가 너무 높음) 텔레그램 메시지를 보냅니다
- 다중 명령 패널: 여러 장치에 대한 명령을 추가하고 하나의 텔레그램 채팅에서 전체 랩을 제어합니다
스스로 도전해보세요
더 나아갈 준비가 되셨나요?
- 쉬움: LED를 세 번 깜박이고 완료되면 "Done!"을 응답하는 /blink 명령을 추가합니다.
- 중간: 비밀번호 확인을 추가합니다 — 봇은 비밀 키워드로 시작하는 명령에만 응답합니다(예: /abc123 toggle_led). 그러면 누군가 봇 사용자 이름을 알아도 비밀번호 없이는 하드웨어를 제어할 수 없습니다.
- 고급: 온도 센서를 MCU에 연결하고, Bridge를 통해 노출하고, /temperature 명령을 추가하고, 온도가 설정된 임계값을 초과하면 봇이 자동으로 경보를 보내도록 구성합니다.