# m10-nl-programming

**Repository Path**: chenqi1233/m10-nl-programming

## Basic Information

- **Project Name**: m10-nl-programming
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-05
- **Last Updated**: 2026-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 行空板 M10 自然语言编程 — 使用说明

用自然语言描述功能，生成 Python 代码，通过 SSH 部署到行空板 M10 上运行。

**电脑不需要安装 Python**，只需 Windows 自带的 `ssh` / `scp`（OpenSSH 客户端）。

**仓库**：https://gitee.com/chenqi1233/m10-nl-programming  
**许可证**：[MIT](LICENSE)

### 从 Gitee 安装

```powershell
# 克隆到 Cursor skills 目录（示例）
git clone https://gitee.com/chenqi1233/m10-nl-programming.git "$env:USERPROFILE\.cursor\skills\m10-nl-programming"
```

其他 AI 工具路径见 [skill-install-paths.md](references/skill-install-paths.md)。

---

## 一、原理（先看这个）

```
你的电脑                     行空板 M10
────────                     ──────────
传文件 + 发命令  ──SSH──►    python3 执行程序
（.ps1 脚本）                （unihiker + pinpong）
```

- 电脑上的 `.ps1`：连接检测、上传程序
- M10 上的 `.py`：真正控制屏幕、传感器、引脚的程序

---

## 二、准备工作

### 硬件

- 行空板 M10
- USB Type-C 线（推荐）或 WiFi 与电脑同网段

### 行空板 SSH 信息

| 项 | 值 |
|---|---|
| USB 直连 IP | `10.1.2.3` |
| WiFi IP | 如 `192.168.199.x`（以实际为准） |
| 用户名 | `root` |
| 密码 | `dfrobot` |

### 电脑需要

| 需要 | 不需要 |
|------|--------|
| Windows 10/11 + OpenSSH（`ssh`/`scp`） | 本机 Python |
| PowerShell | Mind+（可选，另有一套用法） |

没有 OpenSSH：设置 → 应用 → 可选功能 → 添加 **OpenSSH 客户端**。

---

## 三、推荐流程（连接 → 选环境 → 运行）

### 用 AI Agent 时（两步弹窗）

```
① AskQuestion：行空板是否已连接？
      ↓ check_connection.ps1
② AskQuestion：选择 Python 环境（pyenv 版本 / uv）
      ↓ detect_python_env.ps1 → 写入 .m10-env.json
③ 自然语言说需求 → 生成代码 → 部署
```

**V0.4.5 及以上系统镜像**（见 [官方镜像说明](https://www.unihiker.com.cn/wiki/m10/burner)）默认 **pyenv 3.12.7** + 内置 **uv**。  
选手动或旧镜像可能只有系统 `python3`。环境详情见 [m10-python-env.md](references/m10-python-env.md)。

### 手动快速上手

打开 PowerShell，进入 `scripts` 目录：

```powershell
# 1. 检测连接
.\check_connection.ps1

# 2. 检测 pyenv / uv 环境
.\detect_python_env.ps1

# 3. 运行（指定 pyenv 3.12.7）
.\run_on_m10.ps1 ..\examples\print_hello.py -Mode pyenv -PythonBin /root/.pyenv/versions/3.12.7/bin/python3

# 4. 或用 uv 运行（V0.4.5+）
.\run_on_m10.ps1 ..\examples\print_hello.py -Mode uv -EnvFile ..\.m10-env.json
```

保存环境配置：

```powershell
.\detect_python_env.ps1 -SaveEnvFile ..\.m10-env.json
.\run_on_m10.ps1 ..\examples\print_hello.py -EnvFile ..\.m10-env.json
```

---

## 四、两个日常脚本

| 脚本 | 作用 |
|------|------|
| `check_connection.ps1` | ping + SSH 检测是否在线 |
| `detect_python_env.ps1` | 检测 pyenv 版本、是否含 uv |
| `run_on_m10.ps1` | 上传并按所选 pyenv/uv 环境执行 |

### 常用命令

```powershell
# 检测连接
.\check_connection.ps1

# 前台运行（跑完就结束，适合 LED 闪烁等）
.\run_on_m10.ps1 ..\examples\p24_led_blink.py

# 后台运行（适合屏幕常驻显示）
.\run_on_m10.ps1 ..\examples\hello_unihiker.py -Background

# 关闭后台程序
ssh root@10.1.2.3 "pkill -f hello_unihiker.py"
```

### WiFi 模式（换 IP）

```powershell
.\check_connection.ps1 -M10Host 192.168.199.102
.\run_on_m10.ps1 ..\examples\print_hello.py -M10Host 192.168.199.102
```

### 不用脚本、纯终端也行

```powershell
ping 10.1.2.3
ssh root@10.1.2.3 "python3 --version"

scp .\my.py root@10.1.2.3:/tmp/m10_nl/
ssh root@10.1.2.3 "python3 /tmp/m10_nl/my.py"
```

更多见 [references/no-python-workflow.md](references/no-python-workflow.md)。

---

## 五、配合 AI 使用（可选）

本文件夹同时是一套 **AI 技能包**。把文件夹交给 AI Agent 后，可用自然语言说需求，由 AI 生成代码并部署。

### 对话示例

```
给行空板 M10 编程，屏幕显示你好
P24 LED 闪 5 次
读取光线传感器显示在屏幕上
```

### AI 需要先确认（两步）

1. 行空板是否已连接（USB 或 WiFi）
2. 选择 Python 运行环境：pyenv 3.12.7 / 3.8.5 / **uv** / 系统 python3
3. 之后才会生成代码并部署

### 安装到 AI 工具

不同 AI 工具 skills 目录不同，见 **[references/skill-install-paths.md](references/skill-install-paths.md)**。

| 文件 | 给谁看 |
|------|--------|
| **README.md**（本文） | 人 — 连接、脚本、上手 |
| **SKILL.md** | AI — 生成代码的规范 |
| **skill-install-paths.md** | 人 — 装到 Cursor / Claude Code 等 |

没有 Skills 功能的 AI：对话里 @ 引用本文件夹，或让 AI 阅读 `SKILL.md`。

---

## 六、能做什么（自然语言示例）

| 你说 | 效果 |
|------|------|
| 打印 hello | M10 终端输出 hello |
| 屏幕显示你好，行空板 | 绿色文字常驻屏幕 |
| P24 LED 亮灭 5 次 | 外接 LED 闪 5 次 |
| 读取光线传感器显示在屏幕 | 数值实时刷新 |
| 按 A 键蜂鸣器响 | 按键 + 蜂鸣器 |
| 关闭屏幕程序 | 结束后台进程 |

更多代码示例见 `examples/` 和 [references/examples.md](references/examples.md)。

---

## 七、写程序时注意

### 1. 屏幕显示必须保持运行

画完不等待，画面一闪就没了：

```python
gui.draw_text(text="你好", x=35, y=150, color="#00FF00", font_size=24)
while True:
    time.sleep(0.05)   # 必须有
```

屏幕常驻部署时用 `-Background` 后台运行。

### 2. 板名写 `UNIHIKER`

```python
Board("UNIHIKER").begin()   # 对
Board("M10").begin()        # 错
```

### 3. 标准程序开头

```python
from pinpong.board import Board
from pinpong.extension.unihiker import *
from unihiker import GUI
import time

Board("UNIHIKER").begin()
gui = GUI()
```

---

## 八、文件夹说明

```
m10-nl-programming/
├── README.md                 ← 本文（使用说明）
├── SKILL.md                  ← AI 执行规范
├── scripts/
│   ├── check_connection.ps1  ← 日常必用
│   ├── run_on_m10.ps1        ← 日常必用
│   └── probe_*.py 等         ← 维护技能包时用，可忽略
├── examples/                 ← 示例程序
└── references/               ← 硬件、API、连接指南
```

---

## 九、常见问题

| 问题 | 处理 |
|------|------|
| ping 不通 | 检查 USB 线；WiFi 确认同网段 |
| SSH 连不上 | 等板子启动完；密码 `dfrobot` |
| 屏幕一闪就没 | 代码加 `while True: time.sleep(0.05)`，或 `-Background` |
| LED 不亮 | 查接线、限流电阻、引脚号 |
| 每次输密码 | 正常；可配置 SSH 公钥免密 |
| 没有 ssh 命令 | 安装 OpenSSH 客户端 |

---

## 十、更多文档

| 文档 | 内容 |
|------|------|
| [connection-guide.md](references/connection-guide.md) | 如何连接行空板 |
| [no-python-workflow.md](references/no-python-workflow.md) | 纯终端完整流程 |
| [m10-python-env.md](references/m10-python-env.md) | pyenv / uv 环境与镜像版本 |
| [skill-install-paths.md](references/skill-install-paths.md) | 装到各 AI 工具 |
| [m10-hardware.md](references/m10-hardware.md) | 硬件与引脚 |
| [unihiker-pinpong-api.md](references/unihiker-pinpong-api.md) | API 速查 |
| [code-templates.md](references/code-templates.md) | 代码模板 |

---

**参考**：实机常见 pyenv 3.12.7 + pinpong 0.6.2 + unihiker 0.0.29.0；以 `detect_python_env.ps1` 检测结果为准。镜像刷机见 [官方文档](https://www.unihiker.com.cn/wiki/m10/burner)。