수록 현황:429 건의 뉴스/102 개의 AI 도구/413 개의 오픈소스 프로젝트/75 개의 학습 자료
홈뉴스오픈소스모델AI 도구학습 자료
홈 / 오픈소스 / muse-gadget-sdk

muse-gadget-sdk

ESP32 보드와 Raspberry Pi 또는 Linux 기기를 Muse 모바일 앱과 페어링되는 맞춤형 가젯으로 변환하는 오픈소스 SDK입니다.

CApache-2.0Framework
⭐ GitHubhttps://github.com/facebookincubator/muse-gadget-sdk
250
스타 수
+0
스타 증가율
2026년 10월 3일
최근 업데이트
8
클릭 수

1. 프로젝트 개요

Muse Gadget SDK는 ESP32 보드, Raspberry Pi 또는 기타 Linux 기기와 같은 시판 하드웨어를 iOS 및 Android의 Muse 모바일 앱과 페어링되는 "가젯"으로 변환하는 오픈소스 SDK로, 개발자가 하드웨어를 처음부터 설계하지 않고도 맞춤형 연결 기기를 구축할 수 있게 해줍니다.

2. 배경 및 포지셔닝

존재 이유

Muse Gadgets를 통해 메이커들은 디스플레이, 센서, 버튼, 마이크, 스피커, 액추에이터 등 자신만의 기기로 Muse 앱을 확장할 수 있습니다. 이 SDK는 페어링과 통신을 처리하는 펌웨어 및 클라이언트 코드를 제공하므로, 사용자는 가젯이 수행하는 기능 자체에 집중할 수 있습니다.

유사 프로젝트와의 차이점

  • 컴패니언 앱 지향: 기기는 일반적인 클라우드 대시보드가 아닌 개발자 모드 흐름을 통해 Muse 모바일 앱과 페어링됩니다.
  • 단일 저장소에 두 가지 기기군 포함: 마이크로컨트롤러용 C 기반 ESP32 펌웨어와 완전한 Linux 시스템용 Python 기반 SDK를 제공합니다.
  • 에이전트 친화적: 각 SDK에는 AGENTS.md가 포함되어 있어 AI 코딩 에이전트(Muse Code 포함)가 가젯의 빌드, 플래싱, 확장을 지원할 수 있습니다.
  • 설계 단계부터 해커 친화적: 이 프로젝트는 스스로를 "해커가 해커를 위해, 그저 재미로 만든 프로젝트"라고 설명하며, 따라서 커스텀 펌웨어에는 위험이 따르고 전적으로 사용자 본인의 책임하에 사용됩니다.

3. 기능 분류

🔌 ESP32 기기 SDK

ESP32 보드용 펌웨어 및 컴포넌트로, README에 다섯 가지 보드군이 문서화되어 있습니다. 예시:

  • ESP32-C5 DevKitC-1 (상태 표시등 및 버튼)
  • ideaspark ESP32 (1.9인치 디스플레이)
  • Seeed SenseCAP Indicator (4인치 화면)
  • Waveshare AMOLED 보드 (전체 UI, 푸시투토크)
  • Home Assistant Voice Preview (LED 링, 음성)

목적: 저가형 마이크로컨트롤러에서 화면, 오디오, 센서 가젯을 구축합니다.

🐧 Linux 기기 SDK

Raspberry Pi 또는 Bluetooth LE를 지원하는 다른 Linux 컴퓨터를 Muse 가젯처럼 인식되게 하는 Python 패키지(musegadget)입니다. 예시:

  • 셸 명령을 실행하는 system.run
  • 64KB 청크 단위로 파일에 접근하는 file.read / file.write
  • 가동 시간, 부하, 메모리, 디스크, 온도를 확인하는 device.health
  • Home Assistant 또는 시스템 관리를 위한 사용자 정의 명령

목적: 스마트폰에서 Linux 기기를 제어하고 모니터링합니다.

🖥️ 시뮬레이터 및 도구

esp32/simulator, esp32/tools, esp32/tests에 위치합니다. 예시:

  • 화면을 미리 볼 수 있는 데스크톱 UI 시뮬레이터(SDL 기반)
  • 보드별 빌드, 플래싱, 모니터링을 위한 tools/board.sh
  • ESP32 코드용 단위 테스트
  • esp32/devices 아래의 보드별 구성

목적: 편집-빌드-플래싱 반복 주기를 단축합니다.

🧩 스킬

skills/ 디렉터리에는 가젯과 코딩 에이전트가 할 수 있는 작업을 확장하는 추가 기능 모듈이 들어 있습니다.

목적: 에이전트 지원 개발을 위한 재사용 가능한 추가 기능입니다.

4. 주요 특징

  • 시판 하드웨어: 커스텀 PCB가 필요 없으며, 일반적인 ESP32 보드와 Raspberry Pi 모델이 작동합니다.
  • 스마트폰 페어링: Muse 앱의 개발자 모드에서 SDK 토큰을 사용해 기기를 연결합니다.
  • 풍부한 기기 UI: ESP32 빌드는 디스플레이(LVGL 기반 UI), 아바타, 오디오 입출력을 지원하며, 지원되는 보드에서는 푸시투토크도 지원합니다.
  • Linux 원격 제어: 앱에서 명령을 실행하고, 파일을 전송하며, 상태 지표를 읽어옵니다.
  • AI 지원 워크플로: AGENTS.md 파일이 설정 및 빌드 과정을 통해 코딩 에이전트를 안내합니다.
  • 관대한 라이선스: 메인 코드는 Apache-2.0 라이선스를 따르며, 서드파티 예외 사항이 명확히 명시되어 있습니다.

5. 역할별 활용 사례

  • 일반 개발자 / 메이커: ESP32 보드에서 휴대용 디스플레이, 음성 기기, 센서 가젯의 프로토타입을 만듭니다.
  • DevOps / SRE: 홈랩이나 엣지 Linux 기기를 스마트폰에 노출하여 빠른 명령 실행 및 상태 점검을 수행합니다(아래 권한 관련 참고 사항을 유의하세요).
  • 임베디드 엔지니어: 시뮬레이터와 보드 스크립트를 사용해 끊임없이 플래싱하지 않고도 펌웨어 UI를 반복 개선합니다.
  • 스마트홈 애호가: 음성 기기나 LED 링 기기 등 Home Assistant 중심의 가젯을 구축합니다.

6. 시작하기

필요한 자료 찾기

저장소를 탐색하고 각 SDK 디렉터리의 README를 읽어보세요:

git clone https://github.com/facebookincubator/muse-gadget-sdk.git
cd muse-gadget-sdk

문서: https://gadgets.muse.ai

설치 / 연동

먼저 gadgets.muse.ai/settings/sdk-tokens에서 SDK 토큰을 받아야 하며, gadgets.muse.ai/sdk-terms에서 Gadget SDK 약관을 검토해야 합니다.

ESP32 (ESP-IDF v6.0.1 필요):

cd esp32
idf.py menuconfig
idf.py build
idf.py -p /dev/cu.usbmodem1101 flash monitor

# 보드별 빌드
tools/board.sh ideaspark build

Linux / Raspberry Pi:

curl -fsSL https://raw.githubusercontent.com/facebookincubator/muse-gadget-sdk/main/linux/install.sh -o install.sh
bash install.sh --sdk-token mgst_…

기여하기

저장소의 CONTRIBUTING.md를 읽은 후 이슈나 풀 리퀘스트를 열어주세요: https://github.com/facebookincubator/muse-gadget-sdk

7. 프로젝트 구조

muse-gadget-sdk/
├── esp32/
│   ├── avatar/       # 아바타 그래픽 및 렌더링
│   ├── cmake/        # 빌드 구성
│   ├── components/   # 펌웨어 컴포넌트
│   ├── devices/      # 보드별 구성
│   ├── main/         # 핵심 펌웨어 코드
│   ├── simulator/    # 데스크톱 UI 미리보기
│   ├── tests/        # 단위 테스트
│   └── tools/        # 빌드 및 유틸리티 스크립트(board.sh)
├── linux/
│   ├── examples/     # 샘플 구현
│   ├── src/musegadget/  # 핵심 Python SDK
│   ├── tests/        # 테스트 스위트
│   └── install.sh    # 설치 프로그램
├── skills/           # 추가 기능 모듈
└── .github/          # 워크플로 및 문서 자산

8. 관련 생태계

  • Muse 앱 (iOS 및 Android): 가젯과 페어링되는 컴패니언 앱입니다.
  • ESP-IDF v6.0.1: ESP32 펌웨어용 Espressif의 개발 프레임워크입니다.
  • LVGL: 빌드 시점에 가져오는 임베디드 그래픽 라이브러리입니다.
  • SDL: 데스크톱 시뮬레이터에서 사용됩니다.
  • Home Assistant: 음성 및 사용자 정의 명령 가젯의 대상 생태계입니다.
  • uv 및 pytest: Linux SDK 개발 및 테스트에 사용됩니다.
  • Muse Code: AGENTS.md를 통해 지원되는 코딩 에이전트입니다.

9. 라이선스

  • ✅ 상업적 용도를 포함하여 Apache License 2.0에 따라 코드를 사용, 수정, 배포할 수 있습니다
  • ✅ 재배포 시 라이선스 및 저작권 표기를 유지해야 합니다
  • ❌ Jollybot 아바타가 Apache-2.0의 적용을 받는다고 가정하지 마세요. 이는 제외 대상입니다
  • ℹ️ 서드파티 컴포넌트는 자체 라이선스를 유지합니다: minimp3.h는 CC0-1.0, pixel_font.c는 BSD-2-Clause입니다
  • ℹ️ Gadget SDK의 사용은 gadgets.muse.ai/sdk-terms의 Gadget SDK 약관의 적용도 받습니다
  • ℹ️ 커스텀 펌웨어와 Linux SDK는 설치 계정(sudo 사용 가능 시 sudo 포함)의 권한으로 실행되므로, 본인 책임하에 사용하세요

10. 자주 묻는 질문

Q: SDK를 사용하려면 토큰이 필요한가요?
A: 네. 가젯을 플래싱하거나 페어링하기 전에 gadgets.muse.ai/settings/sdk-tokens에서 SDK 토큰을 받으세요.

Q: 어떤 ESP-IDF 버전을 사용해야 하나요?
A: ESP32 README에 ESP-IDF v6.0.1이 지정되어 있습니다.

Q: 어떤 Linux 시스템이 지원되나요?
A: Raspberry Pi 3B+, 4, 5, Zero 2 W 또는 Raspberry Pi OS Bullseye 이상, Debian 11 이상, Ubuntu 22.04 이상이 설치된 Bluetooth LE 지원 Linux 컴퓨터입니다.

Q: 하드웨어 없이 UI를 미리 볼 수 있나요?
A: 네, esp32/simulator의 데스크톱 시뮬레이터를 사용하세요.

Q: 제 주력 기기에서 실행해도 안전한가요?
A: Linux SDK는 설치한 사용자의 권한으로 셸 명령을 실행하고 파일에 접근할 수 있습니다. 전용 기기를 사용하는 것이 좋으며, 먼저 README를 읽어보세요.

11. 빠른 링크

12. 요약

Muse Gadget SDK는 메이커와 개발자에게 저렴한 ESP32 보드와 Linux 기기를 스마트폰과 연결되는 가젯으로 변환하는 실용적인 방법을 제공합니다. 하드웨어를 다루기 좋아하는 사람, 스마트홈 구축자, 그리고 관대한 Apache-2.0 라이선스 하에 AI 지원 펌웨어 개발을 원하는 모든 사람에게 적합합니다.