Gadget Panda

Open-source Python runtime สำหรับแหวน RING503PANDA IDEA → CODE → PROTOTYPE → COMMUNITY

Gadget Panda ไม่ใช่แอปสำเร็จรูป แต่เป็นชั้นโฮสต์ที่ Maker ใช้สแกน ต่อแหวน และรับเซ็นเซอร์บน Mac, Linux, Windows, Raspberry Pi

import asyncio
from gadgetpanda import Ring

async def main():
    ring = await Ring.find()
    ring.on("heart_rate", lambda s: print("HR", s.bpm))
    ring.on("imu", lambda samples: print(samples[0] if samples else ""))
    async with ring:
        await ring.set_raw_enabled(True)
        await asyncio.Event().wait()

asyncio.run(main())

ต้องการอะไร

• Python 3.11+
• Bluetooth LE บนเครื่อง (Mac ใช้ได้เลย, Linux ใช้ BlueZ, Windows ใช้ WinRT)
• แหวน RING503PANDA / RING503nPANDA
• ทดสอบบนเครื่องจริง — emulator ไม่มี BLE

แพ็กเกจนี้เป็น ชั้นโฮสต์ Python ฝั่งคอมพิวเตอร์ เท่านั้น

ติดตั้ง

cd gadgetpanda
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Docker (Linux — BLE / Wi‑Fi ผ่าน host)

บน Linux / Raspberry Pi ใช้คอนเทนเนอร์พร้อมส่ง BlueZ + NetworkManager จากโฮสต์ (macOS Docker ส่งวิทยุเข้าไปไม่ได้):

./scripts/docker-run.sh ring scan

รายละเอียด: docs/docker.md

MQTT bridge (ตัวเลือก)

pip install -e ".[mqtt]"

เริ่มใน 1 นาที

gadgetpanda ring scan
gadgetpanda ring live
gadgetpanda ring ui --demo
gadgetpanda ring ui --mode ppg
gadgetpanda ring ui EA1D0BD7-5438-F5F9-E624-9E8E750CCD38

บนแดชบอร์ดเลือกโหมดได้ว่าจะดึงชุดไหนจากแหวน: ทั้งหมด, ชีพจร BLE, PPG + ชีพจร, สัญญาณชีพ, การเคลื่อนไหว, กิจกรรม

แดชบอร์ด realtime เปิดที่ http://127.0.0.1:8765 — โทน Tesla (ดำ / แดง / ทอง) พร้อมโลโก้ Gadget Panda

pip install -e ".[ui]"

หรือรันตัวอย่าง

python examples/01_scan.py
python examples/02_heart_rate.py
python examples/03_sensors.py
python examples/04_imu_stream.py
python examples/05_mqtt_bridge.py
python examples/dog_01_scan.py

Fun dog

ชั้น gadgetpanda.dog สำหรับหุ่นสุนัขสนุก (X1) — คนละโปรโตคอลกับแหวน
ดู docs/dog/concept.md และ docs/dog/protocol.md

รีโมทเว็บเป็น React (build แล้วอยู่ในแพ็กเกจ):

pip install -e ".[ui]"
gadgetpanda dog ui --demo
gadgetpanda dog ui <addr>
# http://127.0.0.1:8766

# แก้ UI แล้ว build ใหม่:
# cd src/gadgetpanda/dog/ui/web && npm install && npm run build

Fun drone (V66)

ชั้น gadgetpanda.drone สำหรับโดรน Wi‑Fi สาย V66 / KY UFO
ดู docs/drone/concept.md และ docs/drone/protocol.md

# ต่อ Wi‑Fi hotspot ของโดรน (บังคับจาก CLI ได้)
gadgetpanda drone wifi join KY_UFO_xxxx
gadgetpanda drone connect --wifi KY_UFO_xxxx
gadgetpanda drone ui --wifi KY_UFO_xxxx
gadgetpanda drone ui --demo
# http://127.0.0.1:8767

API สั้น ๆ

เมธอด	ทำอะไร
Ring.scan() / Ring.find()	หาแหวน
connect() / disconnect()	ต่อ / ตัด
get_sport() get_health() get_temperature()	อ่านค่าทันที
set_spo2(True) set_sport_mode(True)	เปิดโหมดวัด
set_raw_enabled(True)	สตรีม 6D + PPG
get_sleep_history() get_sport_history()	ประวัติ
get_health_history(begin_ms)	ประวัติสุขภาพ
set_utc()	ตั้งเวลา (ทำให้อัตโนมัติตอนต่อ)

อีเวนต์ที่ใช้บ่อย: heart_rate, battery, sport, health, temperature, spo2, raw, imu, ppg, connected, disconnected

Gesture เบื้องต้นอยู่ใน gadgetpanda.gesture.MotionWatch — เป็นตัวช่วยจับ tap จากความเร่ง ไม่ใช่โมเดลสำเร็จรูป Maker ต่อโมเดลเองได้

โครงสร้างโปรเจกต์

gadgetpanda/
  src/gadgetpanda/
    protocol.py   # เฟรม FF LEN CMD CHK
    ring.py       # BLE host (bleak)
    gesture.py    # ทางลัด IMU
    cli.py
    dashboard/    # FastAPI + UI realtime
  examples/
  tests/
  docs/protocol.md

สเปกโปรโตคอลเต็มอยู่ที่ docs/protocol.md

แผนงานที่เปิดให้ต่อ

1. ทดสอบบนแหวนจริงแล้วปรับ timestamp / MTU ตามเครื่อง
2. ตัวจำแนก gesture ที่ดีขึ้น (flick, rotate, double tap)
3. WebSocket / OSC สำหรับ Unity และ Processing
4. บันทึก CSV สำหรับแล็บ
5. เอกสารภาษาอังกฤษฉบับเต็ม

Soft license

Honor-system feature keys (30-day, one device). ไม่ใช่ DRM — ดู docs/license.md และ license-portal/

gadgetpanda license features
gadgetpanda license activate gp_live_…
gadgetpanda license status
gadgetpanda license logout

สิทธิ์และที่มา

Gadget Panda ใช้สัญญาอนุญาต MIT

ขอบเขตที่เปิด:

• โค้ดโฮสต์ Python ใน src/gadgetpanda/
• ตัวอย่าง, เทส, เอกสาร maker ในโฟลเดอร์นี้

โปรโตคอล BLE ที่โฮสต์ใช้ถูกบันทึกใน docs/protocol.md เพื่อให้ Maker คุยกับแหวนได้
Heart Rate / Battery / Device Information เป็นมาตรฐาน Bluetooth SIG

ทดสอบ

หน่วยย่อยแบบ unittest (stdlib) ครอบคลุม protocol / models / stream / payload / gesture / ring / CLI / dashboard

PYTHONPATH=src python -m unittest discover -s tests/unit -v

หรือใช้ pytest ทั้งชุดเดิม + unittest

pytest
pytest tests/unit -q
pytest -m e2e

เส้นทางที่เทสแบบ e2e: สแกน → ต่อ → อ่านโปรไฟล์/แบต → กีฬา สุขภาพ อุณหภูมิ SpO2 ชีพจร → โปรไฟล์ผู้ใช้และประวัติ → สตรีม 6D/PPG + gesture → DFU/restore → CLI scan

เทสกับแหวนจริง

PANDA_E2E=1 pytest -m hardware