# Tự làm Robot Trợ Lý Học Tập

Một robot nhỏ chạy trên Raspberry Pi Zero 2 W: học sinh hỏi bài bằng giọng nói
hoặc văn bản, robot chụp ảnh trang vở khi cần, gửi lên AI, đọc câu trả lời ra
loa và hiển thị tóm tắt trên OLED.

[Bắt đầu cài đặt](#cài-đặt-từ-github) ·
[Đấu dây](#đấu-dây-nhanh) ·
[Dùng Codex tự cài](#dùng-codex-để-cài-tự-động) ·
[Báo cáo kỹ thuật](BAO_CAO_ROBOT_HOC_TAP.md)

![Robot trợ lý học tập minh họa](https://placehold.co/1200x675/png?text=Learning+Robot+Assistant)

> Ảnh/video phía trên là minh họa tạm. Khi hoàn thiện vỏ robot, thay bằng ảnh
> thật của sản phẩm và video demo học sinh tương tác với robot.

## Demo Tạm

![Khung video demo tạm](https://placehold.co/1200x675/png?text=Video+Demo+Robot+Hoc+Tap)

Nội dung video thật nên quay ngắn 45-60 giây: robot khởi động, học sinh hỏi một
câu đơn giản, robot chụp ảnh bài tập, đọc lời giải và chuyển bước bằng nút bấm.

## Robot Làm Được Gì

| Tính năng | Mô tả ngắn |
| --- | --- |
| Hỏi đáp học tập | Trả lời tiếng Việt, có bộ nhớ hội thoại như chat. |
| Chụp ảnh bài tập | Tự chụp khi câu hỏi cần nhìn trang vở, đề bài, hình vẽ. |
| Hướng dẫn từng bước | Bài nhiều bước sẽ đọc từng bước, bấm nút để sang bước tiếp theo. |
| Màn hình OLED | Hiện trạng thái, tóm tắt câu trả lời, link cấu hình bằng IP. |
| Giọng nói | TTS qua API, phát qua soundcard USB, mạch khuếch đại và loa rời. |
| Cấu hình qua web | Chọn Wi-Fi, AI provider, STT, TTS, âm thanh, prompt, camera rules. |
| Tự chạy khi cấp nguồn | Boot xong tự mở service robot, không cần màn hình HDMI. |
| Chế độ setup AP | Không có Wi-Fi thì tự phát `robotpi-setup` để cấu hình mạng. |

## Linh Kiện

Kiểm tra lại giá và tồn kho trước khi mua. Ảnh/link dưới đây dùng để tham khảo
ngoại hình linh kiện, không bắt buộc mua đúng nơi bán đó.

| Linh kiện | Gợi ý | Ảnh/link tham khảo | Ghi chú |
| --- | --- | --- | --- |
| Raspberry Pi | Raspberry Pi Zero 2 W | [Trang sản phẩm](https://www.raspberrypi.com/products/raspberry-pi-zero-2-w/) | Chỉ dùng Wi-Fi 2.4 GHz. |
| Thẻ nhớ | microSD 32 GB trở lên | Dùng thẻ 64 GB là hợp lý | 8 GB có thể cài OS Lite nhưng rất chật. |
| Camera | Camera webcam dùng cho Raspberry Pi - TH154 | [Ảnh camera][camera-th154-image] | Camera đang dùng cho robot. |
| Cáp camera | Cáp chuyển CSI FPC 15 Pin 1.0mm to 22 Pin 0.5mm | [Ảnh cáp][csi-adapter-image] | Dùng để nối camera/cáp CSI với Pi Zero 2 W. |
| OLED | OLED 1.3 inch I2C 128x64 SH1106 | [Ảnh OLED](https://www.addicore.com/products/oled-display-128x64-1-3in-monochrome) | Dùng I2C, địa chỉ thường là `0x3C`. |
| Soundcard | USB soundcard 2 cổng loa và mic | [Link mua][usb-soundcard] | Pi nhận thành thiết bị input/output âm thanh. |
| Loa | Loa 3020 8R 2W 2P1.25 | [Link mua][speaker-3020] | Loa rời gắn trong thân robot. |
| Khuếch đại | PAM8403 có volume, ngõ ra 2 kênh | [Link mua][pam8403] | Khuếch đại tín hiệu từ soundcard ra loa. |
| Micro | Micro cài áo 1.5m/3m | [Link mua][lav-mic] | Cắm vào cổng mic của soundcard USB. |
| Nút bấm | 1 nút nhấn thường | Loại nút 2 chân hoặc 4 chân đều được | Đấu GPIO27 xuống GND, không nối VCC. |
| Nguồn | Nguồn 5V ổn định | Ưu tiên nguồn tốt, dây ngắn | Pi Zero 2 W rất dễ lỗi nếu nguồn yếu. |
| Tuỳ chọn | Module motor/driver | Điều khiển bởi chân GPIO17 | Dùng cho chế độ robot nhảy theo nhạc. |

<p>
  <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/2/2d/Raspberry_Pi_Zero_2_W.jpg/1280px-Raspberry_Pi_Zero_2_W.jpg" width="32%" alt="Raspberry Pi Zero 2 W">
  <img src="https://www.addicore.com/cdn/shop/products/AD555-2.jpg?crop=center&height=1200&v=1689766876&width=1200" width="32%" alt="OLED SH1106">
  <img src="https://down-vn.img.susercontent.com/file/vn-11134207-7r98o-lz7rokz87g3xb8.webp" width="32%" alt="Camera TH154">
</p>

<p>
  <img src="https://down-vn.img.susercontent.com/file/vn-11134207-81ztc-mnd546qksop0ae.webp" width="32%" alt="Cáp chuyển CSI 15 pin sang 22 pin">
  <img src="https://placehold.co/600x450/png?text=USB+Soundcard+2+Cong" width="32%" alt="USB soundcard 2 cổng">
  <img src="https://placehold.co/600x450/png?text=PAM8403+Loa+Micro" width="32%" alt="Loa, mạch khuếch đại và micro">
</p>

## Đấu Dây Nhanh

### OLED SH1106 I2C

| OLED | Raspberry Pi Zero 2 W | Chức năng |
| --- | --- | --- |
| `VDD` | 3V3, physical pin `1` hoặc `17` | Nguồn 3.3 V |
| `GND` | GND, ví dụ physical pin `6`, `9`, `14` | Mass |
| `SCK` hoặc `SCL` | GPIO3/SCL, physical pin `5` | Clock I2C |
| `SDA` | GPIO2/SDA, physical pin `3` | Data I2C |

### Nút bấm điều khiển

| Nút bấm | Raspberry Pi Zero 2 W | Ghi chú |
| --- | --- | --- |
| Một chân nút | GPIO27, physical pin `13` | Input nút |
| Chân còn lại | GND, physical pin `14` hoặc GND bất kỳ | Kéo xuống mass khi bấm |

Code dùng pull-up nội bộ, vì vậy không nối VCC/3V3/5V vào nút.

### Camera, audio và motor

- Camera TH154 nối qua cáp chuyển CSI FPC 15 pin 1.0mm sang 22 pin 0.5mm để cắm
  vào cổng camera của Pi Zero 2 W.
- USB sound card cắm vào cổng micro-USB `USB` của Pi, không phải cổng `PWR`.
- Micro cài áo cắm vào cổng mic của soundcard USB.
- Ngõ loa của soundcard đưa vào PAM8403, sau đó từ PAM8403 ra loa 3020 8R 2W.
- GPIO17 là tín hiệu tuỳ chọn cho chế độ robot nhảy theo nhạc.

## Nạp Raspberry Pi OS

1. Dùng Raspberry Pi Imager ghi **Raspberry Pi OS Lite 64-bit** ra thẻ microSD.
2. Không cần cấu hình Advanced Settings trong Imager.
3. Ghi xong thì rút thẻ, cắm lại vào máy tính để thấy phân vùng `bootfs`.
4. Từ repo này, chạy script cấu hình thẻ trước lần boot đầu:

```bash
git clone https://github.com/thientranvan/learning_robot.git
cd learning_robot/raspi-headless-bootfs
chmod +x apply-to-bootfs.sh

PI_HOSTNAME='robotpi' \
PI_USER='pi' \
PI_PASSWORD='mat-khau-pi' \
WIFI_SSID='ten-wifi-2.4GHz' \
WIFI_PASSWORD='mat-khau-wifi' \
WIFI_COUNTRY='VN' \
./apply-to-bootfs.sh /media/$USER/bootfs
```

Script này tự bật SSH, tạo user, đặt hostname, cấu hình Wi-Fi, bật I2C cho OLED
và chuyển cổng micro-USB `USB` sang host mode để dùng sound card.

Sau đó eject thẻ, cắm vào Pi và cấp nguồn. Lần boot đầu có thể mất 3-5 phút và
có thể tự reboot thêm một lần.

## Cài Đặt Từ GitHub

SSH vào Pi bằng IP trong router:

```bash
ssh pi@<IP-cua-robot>
```

Cài robot:

```bash
sudo apt-get update
sudo apt-get install -y git
git clone https://github.com/thientranvan/learning_robot.git
cd learning_robot
cp robot/.env.example robot/.env
nano robot/.env
chmod +x install_on_pi.sh
./install_on_pi.sh
```

Không ghi API key thật vào tài liệu công khai. Sau khi cài, có thể nhập key qua
web admin:

```text
http://<IP-cua-robot>:8765/
```

Mặc định phần mềm hỗ trợ nhiều provider và cho chọn thứ tự ưu tiên/fallback:

| Tác vụ | Provider chính | Fallback |
| --- | --- | --- |
| Hỏi đáp, ảnh, hội thoại | OpenAI-compatible provider | OpenAI/Gemini/provider khác |
| Speech-to-text | Google Cloud Speech-to-Text | OpenAI-compatible STT |
| Text-to-speech | EverAI TTS hoặc provider TTS miễn phí | OpenAI/3FTool/provider khác |

Gợi ý nguồn miễn phí hoặc có free tier để thử nghiệm:

| Nhu cầu | Nguồn có thể thử |
| --- | --- |
| TTS tiếng Việt | EverAI, 3FTool, OpenAI TTS nếu có ngân sách. |
| STT tiếng Việt | Google Cloud Speech-to-Text, OpenAI-compatible audio transcription. |
| AI hỏi đáp/vision | Kiro AI, Gemini, Gemini CLI, OpenCode Free, OpenRouter, NVIDIA NIM, Ollama Cloud, Vertex AI. |

Hạn mức miễn phí có thể thay đổi theo thời điểm. Khi làm demo/thuyết trình, nên
chuẩn bị ít nhất 2 provider cho mỗi tác vụ để robot có fallback nếu một nguồn
hết quota hoặc lỗi token.

## Kiểm Tra Sau Khi Cài

```bash
systemctl status robot.service
cd ~/robot
python3 app.py status
python3 app.py camera-check
python3 app.py submit "Robot ơi, 2 + 3 bằng mấy?"
```

Nếu không có Wi-Fi hoặc chưa có Internet, robot giữ màn hình cấu hình mạng và
phát AP:

```text
SSID: robotpi-setup
URL: http://10.42.0.1:8765/
```

Khi đã vào LAN, robot hiển thị URL dạng IP:

```text
http://<IP-cua-robot>:8765/
```

## Dùng Codex Để Cài Tự Động

Nếu có máy tính dev và đã SSH được vào Pi, có thể nhờ Codex làm phần triển khai.
Ví dụ prompt:

```text
Tôi có Raspberry Pi tại pi@<IP-cua-robot>.
Hãy SSH vào Pi, cài Learning Robot từ repo này, giữ nguyên .env nếu có,
kiểm tra camera/OLED/audio, bật robot.service và báo lại URL quản lý bằng IP.
```

Deploy lại code từ máy dev sang Pi:

```bash
cd learning_robot
REMOTE=pi@<IP-cua-robot> ./deploy_to_pi.sh
```

## Giao Diện Quản Lý

Mở web admin trong cùng mạng LAN:

```text
http://<IP-cua-robot>:8765/
```

Các tab quan trọng:

| Tab | Dùng để |
| --- | --- |
| Hỏi robot | Gửi câu hỏi, chụp ảnh, chuyển bước, xoá hội thoại. |
| Nguồn AI | Cấu hình AI1-AI4, test token, chọn thứ tự fallback theo tác vụ. |
| Âm thanh | Chọn loa/mic, test loa, test mic, cấu hình TTS/STT. |
| Cấu hình | Prompt hệ thống, luật camera, trạng thái audio, sleep/screensaver. |
| Wi-Fi/Bluetooth | Quét mạng, nhập mật khẩu, kết nối loa Bluetooth. |

## Luồng Hoạt Động

```text
Người dùng bấm giữ nút và nói
  -> robot ghi âm qua USB sound card
  -> thả nút thì gửi STT
  -> AI hiểu câu hỏi và quyết định có cần chụp ảnh hay không
  -> nếu cần, robot báo chuẩn bị chụp và chụp bằng camera CSI
  -> AI trả lời dạng JSON
  -> robot đọc câu trả lời qua loa
  -> OLED hiển thị nội dung ngắn gọn
  -> hội thoại được lưu để hỏi tiếp
```

## Tài Liệu Kỹ Thuật

- [README.md](README.md): hướng dẫn cài đặt và vận hành nhanh.
- [BAO_CAO_ROBOT_HOC_TAP.md](BAO_CAO_ROBOT_HOC_TAP.md): tài liệu báo cáo chi tiết cho học sinh.
- [robot/README.md](robot/README.md): lệnh kỹ thuật và mô tả daemon.
- [raspi-headless-bootfs/README.md](raspi-headless-bootfs/README.md): cấu hình thẻ SD trước lần boot đầu.

## Ghi Chú Khi Công Khai

- Thay ảnh/video minh họa bằng ảnh thật của robot.
- Không đưa API key, mật khẩu Wi-Fi, file `.env`, log riêng tư lên GitHub.
- Nếu dùng ảnh linh kiện từ web trong slide/landing page công khai, kiểm tra
  quyền sử dụng hoặc thay bằng ảnh tự chụp.
- Khi thuyết trình, nên demo 3 tình huống: hỏi nhanh, chụp bài tập, hướng dẫn
  từng bước bằng nút bấm.

## Nguồn Ảnh Tham Khảo

- Raspberry Pi Zero 2 W: Wikimedia Commons và trang sản phẩm Raspberry Pi.
- OLED SH1106: Addicore product page.
- Camera TH154: ảnh sản phẩm do nhóm cung cấp.
- Cáp chuyển CSI 15 pin sang 22 pin: ảnh sản phẩm do nhóm cung cấp.
- USB soundcard, loa, PAM8403, micro: link Shopee do nhóm cung cấp.

[camera-th154-image]: https://down-vn.img.susercontent.com/file/vn-11134207-7r98o-lz7rokz87g3xb8.webp
[csi-adapter-image]: https://down-vn.img.susercontent.com/file/vn-11134207-81ztc-mnd546qksop0ae.webp
[usb-soundcard]: <https://shopee.vn/Card-Sound-c%E1%BB%95ng-USB-%C4%90%E1%BA%A7u-chuy%E1%BB%83n-USB-ra-%C3%A2m-thanh-3D-5.1-chuy%C3%AAn-d%C3%B9ng-cho-m%C3%A1y-vi-t%C3%ADnh-laptop.-i.291056307.16891147060>
[speaker-3020]: <https://shopee.vn/-C%C3%B3-s%E1%BA%B5n-Loa-3020-8R2W-2P1.25-thegioimodule-i.951399259.56350867916>
[pam8403]: <https://shopee.vn/PAM8403-M%E1%BA%A1ch-khu%E1%BA%BFch-%C4%91%E1%BA%A1i-%C3%A2m-thanh-C%C3%B3-%C4%91i%E1%BB%81u-ch%E1%BB%89nh-volume-6W-(ng%C3%B5-ra-2-k%C3%AAnh)-i.1292561517.45806039604>
[lav-mic]: <https://shopee.vn/MICRO-c%C3%A0i-%C3%A1o-1.5m-3m-s%E1%BB%AD-d%E1%BB%A5ng-d%E1%BA%A1y-h%E1%BB%8Dc-Livestream-h%E1%BB%8Dc-online-cho-PC-Laptop-%C3%94-t%C3%B4-M%C3%A1y-tr%E1%BB%A3-gi%E1%BA%A3ng-i.1405624091.57855260193>