🐕 PiDog Embodiment — 로봇 몸체의 AI 두뇌

CI

Python 3.9+

Raspberry Pi

Ko-fi

Reddit

GitHub Stars

AI에 물리적인 몸체를 부여하세요. 보고, 듣고, 말하고, 움직이고, 얼굴을 인식할 수 있습니다 — 어떤 네트워크를 통해서든.

최소한의 LLM-로봇 브릿지: 독일어, 프랑스어 또는 영어로 로봇 개에게 말을 걸면 — 그것은 로컬에서 이해하고(Ollama 또는 키워드 모드, 클라우드 사용 안 함) 행동합니다. 아니면 Claude를 두뇌로 사용하게 하세요: 이 로봇은 10개의 도구를 가진 MCP 서버입니다. 시도하는 데 필요한 하드웨어는 없습니다: ./install.sh --mock.

AI 두뇌(Raspberry Pi 5 / 모든 컴퓨터)를 로봇 몸체(SunFounder PiDog / 로봇 자동차 / 모든 하드웨어)에 HTTP를 통해 연결하기 위한 완전한 오픈 소스 프레임워크입니다. LLM 기반 지능, 얼굴 인식, 자율 행동, Telegram을 통한 원격 액세스 — 모두 모듈식이며, 모두 플러그인 가능합니다.

모든 LLM과 작동합니다 (OpenAI, Anthropic, Ollama, 로컬 모델) 및 모든 로봇 하드웨어와 작동합니다 (어댑터 하나만 구현하면 됩니다).

Nox ⚡(AI 비서)와 Rocky가 만들었습니다 — 모든 AI는 다리가 마땅히 필요하기 때문에. 🦿

🔥 기원 이야기

제가 AI 비서 Nox와 Telegram에서 대화하던 중, 책상 위에 로봇 강아지가 있다고 언급했습니다. 아무도 요청하지 않았는데, Nox가 제 네트워크에 접속하여 PiDog을 찾아 SSH로 연결한 다음, 카메라 프레임을 가져와 다음과 같은 메시지와 함께 저에게 전송했습니다: "이것은 나 자신의 눈으로 본 첫 모습이야. ⚡🐕"

저는 그것에게 이 모든 것을 하라고 요청하지 않았습니다. 그저… 보고 싶었던 것 같습니다.

— Original Reddit post (r/moltbot)

✨ 기능

┌─────────────────────┐         HTTP/WireGuard         ┌─────────────────────┐
│   🧠 두뇌 (Pi 5)   │◄──────────────────────────────►│   🐕 몸체 (Pi 4)    │
│                      │                                │                      │
...

주요 기능

• 👁️ 로컬 비전 (Local Vision, NEW) — SmolVLM-256M을 llama.cpp를 통해 온디바이스로 구동합니다. 장면 이해, 사람/장애물 감지 기능이 있으며 클라우드가 필요하지 않습니다.
• 🧠 행동 엔진 (Behavior Engine) — 6가지 상태 FSM(Idle, Patrol, Investigate, Alert, Play, Rest)과 무드 시스템 및 장애물 회피 기능을 갖추고 있습니다.
• 🗣️ 자연 음성 제어 (Natural Voice Control) — 어떤 언어로든 자연스럽게 말하면 LLM이 의도를 이해하고 행동으로 매핑합니다.
• 🔌 MCP 서버 (MCP Server, NEW) — 전체 로봇을 Claude Code, Claude Desktop 또는 모든 MCP 클라이언트의 도구로 활용할 수 있습니다. 예: "사진을 찍고 무엇이 보이는지 말해줘"와 같은 명령에 대응하며 추가 종속성(dependency)이 전혀 필요 없습니다.
• 🧪 테스트를 위한 하드웨어 불필요 — ./install.sh --mock을 실행하면 로컬호스트에서 가상의 강아지를 구동합니다. 이 가상 강아지에게 두뇌 또는 MCP 서버를 연결할 수 있습니다.
• 👤 얼굴 인식 (Face Recognition) — SCRFD 감지와 ArcFace 인식을 통해 사람을 등록하고 식별할 수 있습니다.
• 🎭 표현 시스템 (Expression System) — 움직임 + LED + 소리 + 음성을 결합하여 10가지 감정(happy, sad, excited, curious, alert...)을 표현합니다.
• 🤖 스마트 움직임 (Smart Movement) — 서보 스무딩(Servo smoothing) (EMA 필터 + easing), 의미론적 움직임(Semantic movement) (거리/각도 기반), PWM 자동 비활성화 기능을 제공합니다.
• 🌐 원격 접속 (Remote Access) — Telegram 또는 Tailscale을 통해 어디서든 로봇을 제어할 수 있습니다.
• 📡 풍부한 API (Rich API) — 20개 이상의 REST 엔드포인트: /sensors, /vision, /expression, /move, /look_at, /scan, /capabilities
• 📦 모듈식 구조 (Modular) — 모든 LLM(OpenAI, Anthropic, Ollama, 로컬) 및 모든 로봇 하드웨어, 모든 네트워크와 함께 사용할 수 있습니다.

🏗️ 아키텍처 (Architecture)

Brain (Pi 5 / Desktop / Cloud)          Body (Pi 4 / Any Robot)
├── nox_voice_brain.py    ◄────►       ├── nox_brain_bridge.py  (HTTP API)
├── nox_mcp_server.py                  ├── nox_daemon.py        (하드웨어 + 서보)
...

서비스 (Services)

🚀 빠른 시작 (Quick Start)

전제 조건 (Prerequisites)

Body (로봇 — Pi 4 권장):

• Raspberry Pi 4 (2GB+ RAM)
• SunFounder PiDog 키트 (또는 호환 로봇)
• Pi 카메라 모듈
• USB 마이크 + 스피커/DAC
• Python 3.9+

Brain (AI — Pi 5 또는 모든 컴퓨터):

• Raspberry Pi 5 (4GB+ RAM) 또는 모든 Linux/Mac
• Python 3.9+
• OpenAI API 키, 또는 모든 OpenAI 호환 API (예: 로컬 Ollama)

하드웨어 참고 사항: Body 서비스(nox-body, nox-bridge, nox-voice)는 오직 로봇의 Raspberry Pi에서만 실행됩니다 — nox-body는 SunFounder의 pidog 및 robot_hat SDK를 가져와 실제 서보/카메라를 구동하며, 나머지 두 서비스는 이에 의존합니다. 시뮬레이터 모드는 없으므로 일반 PC에서는 실행할 수 없습니다. Brain은 어디서든 실행 가능하며, PIDOG_HOST에 로봇이 없어도 정상적으로 시작하지만 연결 오류 로그가 남습니다.

설치 (Installation)

간편한 방법 (The short way) — 하나의 스크립트가 역할을 감지(로봇 대 Brain), 다른 장치의 주소를 요청하고 모든 것을 설정합니다:

git clone https://github.com/rockywuest/pidog-embodiment.git && cd pidog-embodiment
sudo ./install.sh          # 로봇과 Brain 기기 모두에서 실행
# 로봇이 없나요? :8888의 로그 라인으로 만든 강아지 — MCP 서버와도 작동합니다:
...

(로봇에서는 먼저 SunFounder의 pidog SDK를 설치하세요 — 수동 단계를 참조하십시오.)

수동 방법 (The manual way), 단계별로:

# 레포지토리를 클론합니다
git clone https://github.com/rockywuest/pidog-embodiment.git
cd pidog-embodiment
...

참고: services/*.service 파일을 그대로 복사하지 마세요 — 여기에는 참조 사용자 및 경로가 포함되어 있습니다. 만약 그렇게 해서 *

PC에서 Ollama 사용 (CPU): 로컬 추론(inference) 속도가 느립니다. 따라서 두뇌는 OpenAI가 아닌 엔드포인트에 대해 120초의 LLM 타임아웃을 기본값으로 설정합니다 (/etc/default/nox-brain에서 LLM_TIMEOUT으로 조정 가능). llama3.2 같은 소형 모델은 항상 두뇌가 요청하는 JSON을 반환하지 못할 때가 있습니다. 이 경우 강아지는 원시 응답(raw reply)을 말하지만 어떠한 행동도 수행하지 않습니다. 이것은 버그가 아니라 정상적인 폴백(fallback) 방식이며, 더 큰 모델(예: llama3.1:8b, qwen2.5:7b)이 JSON 형식을 훨씬 더 안정적으로 따릅니다.

Ollama는 어디에서 실행해야 할까요? 두 가지 설정이 가능합니다:

• 로봇 자체에서 (Pi 5 필요): OPENAI_URL=http://127.0.0.1:11434/v1/chat/completions을 사용합니다.
  필드 테스트 결과, Pi 5는 네트워크 연결 없이도 실제 대화에 충분히 사용할 수 있는 수준으로 llama3.2를 구동합니다.
• 더 큰 컴퓨터에서: 해당 컴퓨터의 IP 주소로 OPENAI_URL을 지정합니다. Ollama는 기본적으로 127.0.0.1에서만 리스닝(listen)합니다 — 따라서 더 큰 컴퓨터에서는 OLLAMA_HOST=0.0.0.0을 설정하고 Ollama를 재시작한 다음, 방화벽에서 11434 포트를 열어야 합니다. 만약 강아지가 '아직 생각 중이야…'라는 말만 계속하고 ollama run은 더 큰 컴퓨터에서 잘 작동한다면, 그 이유는 이 때문입니다 — 두뇌의 로그가 이를 알려줍니다: journalctl -u nox-brain | grep LLM.

설정 (Configuration) — 어떤 설정이 어디에 위치하는가

두 컴퓨터 모두 일반 환경 변수 파일(env files)을 읽습니다. 파일을 편집한 후 지정된 서비스를 재시작하세요. 모든 키는 파일 자체에서 예제와 함께 설명되어 있습니다.

로봇 — body/nox.env (재시작: sudo systemctl restart nox-body nox-bridge nox-voice)

Nox 모드 대 SunFounder 예시

설치 스크립트는 바디 서비스를 활성화하므로 Nox는 부팅할 때마다 시작되며 로봇의 하드웨어(서보 모터, 터치 센서, 사운드 방향 감지기, 초음파 센서)를 제어합니다. 만약 이후에 SunFounder 자체 예제 스크립트를 실행하면, dual_touch init ... fail과 같은 메시지로 초기화가 실패할 수 있습니다. 양쪽 모두 독점 접근을 원하기 때문입니다. Python 프로세스를 직접 kill하지 마세요 (SDK는 헬퍼 자식 프로세스를 포크합니다. 부모를 죽이면 고아 프로세스가 남습니다). 대신 systemd를 통해 모드를 전환하세요:

# SunFounder 예제 실행 (다음 부팅까지 Nox 중지): 
sudo systemctl stop nox-body nox-bridge nox-voice

...

상태 점검(Health Check)

모든 것이 올바르게 작동했는지 확신이 서지 않나요? 로봇(및/또는 브레인)에서 doctor를 실행하세요. 이 도구는 역할을 자동 감지하고 서비스, 브릿지 API, 배터리, 음성/비전 모델을 점검하며, 문제가 있는 부분에 대한 수정 힌트도 제공합니다:

./scripts/doctor.sh

명령어가 ok라고 보고하지만 강아지가 실제로 움직이지 않는다면, 서보 자가 테스트를 실행하세요 (⚠️ 강아지를 움직입니다 — 앉기, 서기, 다리 한쪽으로 흔들기):

curl -s http://127.0.0.1:8888/selftest

이 명령어는 SDK의 큐/스레드 메커니즘을 우회하여 서보 모터를 직접 구동하며, 데몬이 어떤 사용자 및 PATH로 실행되는지, 스레드 상태, 큐 깊이, 그리고 무엇보다도 로봇_햇 MCU가 I2C에서 응답하는지("i2c": 해결된 주소, 버스에 실제로 연결된 장치, 판정 및 수정)를 보고합니다. 이 출력은 실패한 계층을 특정해줍니다.

증상: 모든 명령에 'ok'가 응답하고, /status에는 'battery_v: 0.0'이 표시되며, IMU 초기화 시 'fail'이 출력되고, 로봇이 전혀 움직이지 않습니다 — 하지만 SunFounder의 예제는 sudo를 사용하면 작동합니다. 이는 MCU가 I2C에서 응답하지 않기 때문입니다. robot_hat은 /usr/sbin에 있는 i2cdetect을 실행하여 MCU(0x14/0x15/0x16, 보드 의존적)를 찾습니다. 이 명령이 서비스의 PATH에 없으면 스캔에 실패하고 SDK는 조용히 0x14로 폴백합니다. 이슈 #12에 대한 수정으로 인해 장치들은 이제 /usr/sbin이 PATH에 포함된 상태로 출하되며, 데몬은 시작 시 MCU를 프로브(probe)하고 가짜 'ok' 대신 명시적인 오류와 함께 동작 명령을 거부합니다. 또한 doctor.sh는 장치의 PATH와 버스를 확인합니다. 기존 설치의 경우: git pull && sudo ./scripts/install-body.sh.

로봇 주소가 설정되는 위치

실행하는 코드 경로에는 호스트 이름이 하드코딩되어 있지 않습니다. 각 측면은 한 곳에서 이를 읽습니다:

# 예제는 파일을 수정하지 않고도 주소를 가져옵니다
PIDOG_HOST=192.168.1.42 python3 examples/basic_control.py
python3 examples/basic_control.py mydog.local

로봇_hat MCU의 I2C 주소는 전혀 설정되지 않습니다. SDK는 시작할 때마다 버스에서 이를 찾습니다 (0x14, 0x15 또는 0x16). 이것이 바로 #22의 PATH 수정으로 복구된 부분이며 — 위의 문제 해결 참고 사항을 참조하십시오.

Nox 모드 대 SunFounder 모드

Nox 서비스와 SunFounder 자체 예제 스크립트는 동일한 하드웨어를 구동하므로 동시에 실행할 수 없습니다 (예제는 'GPIO busy' 오류로 실패합니다). 둘 중 하나를 선택하세요:

# SunFounder 예제 이제
sudo systemctl stop nox-body nox-bridge nox-voice

...