Metadata-Version: 2.5
Name: gadgetpanda
Version: 0.1.1
Summary: Open-source Python runtime for RING503PANDA ring, SoftDog, and FLOW-UFO Wi‑Fi drones.
Project-URL: Documentation, https://github.com/gadgetpanda/gadgetpanda
Project-URL: Issues, https://github.com/gadgetpanda/gadgetpanda/issues
Author: Gadget Panda
License-Expression: MIT
License-File: LICENSE
Keywords: ble,drone,imu,maker,ppg,ring503panda,smart-ring,wearable,wifi
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.11
Requires-Dist: bleak>=0.22
Requires-Dist: pynacl>=1.5
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: mqtt
Requires-Dist: paho-mqtt>=2.1; extra == 'mqtt'
Provides-Extra: ui
Requires-Dist: fastapi>=0.115; extra == 'ui'
Requires-Dist: imageio-ffmpeg>=0.5; extra == 'ui'
Requires-Dist: uvicorn[standard]>=0.32; extra == 'ui'
Requires-Dist: websockets>=14.0; extra == 'ui'
Description-Content-Type: text/markdown

# Gadget Panda

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

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

```python
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 ฝั่งคอมพิวเตอร์** เท่านั้น

## ติดตั้ง

```bash
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 ส่งวิทยุเข้าไปไม่ได้):

```bash
./scripts/docker-run.sh ring scan
```

รายละเอียด: [docs/docker.md](docs/docker.md)

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

```bash
pip install -e ".[mqtt]"
```

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

```bash
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

```bash
pip install -e ".[ui]"
```

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

```bash
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/concept.md) และ [docs/dog/protocol.md](docs/dog/protocol.md)

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

```bash
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/concept.md) และ [docs/drone/protocol.md](docs/drone/protocol.md)

```bash
# ต่อ 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 ต่อโมเดลเองได้

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

```text
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](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](docs/license.md) และ [license-portal/](license-portal/)

```bash
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](docs/protocol.md) เพื่อให้ Maker คุยกับแหวนได้  
Heart Rate / Battery / Device Information เป็นมาตรฐาน Bluetooth SIG

## ทดสอบ

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

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

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

```bash
pytest
pytest tests/unit -q
pytest -m e2e
```

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

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

```bash
PANDA_E2E=1 pytest -m hardware
```
