docs: add tutorial chapters 01-09, firmware guide, and demo code

.gitignore

@@ -0,0 +1 @@
+tools/QPYcom_V4.2.0.zip

README.md

@@ -1,3 +1,110 @@
-# yttrium-board-turorial
-Yttrium 开发板 配套教程
+# YttriumEC718
+
+基于 **QuecPython + LVGL** 的 Quectel EC718 开发板综合 Demo 应用，480×320 横屏触控界面。
+
+## 硬件
+
+| 组件 | 型号 |
+|---|---|
+| 主控 | Quectel EC718 |
+| LCD | ST7796, 320×480 竖屏 → 硬件旋转 480×320 横屏 |
+| 触摸 | ft6x36 (I2C) |
+| 网卡 | W5500 (SPI) |
+
+## 部署
+
+将 `src/yttrium.py` 和 `icons/`、`images/` 目录放到设备 `U:/` 根目录，通过 REPL 启动：
+
+```python
+import example
+example.exec('/usr/yttrium.py')
+```
+
+## 功能清单
+
+### 主屏幕（5×3 图标网格）
+
+| 图标 | 功能 | 说明 |
+|---|---|---|
+| LED | LED 滑块 | PWM 调光（pin25），滑块控制亮度 |
+| Clock | 时钟 + 秒表 | 实时时钟 + 计次秒表 |
+| ADC | 电压仪表盘 | 三色弧段仪表，ADC0 实时采样 |
+| Calc | 计算器 | 四则运算 + 百分比，5×4 按钮 |
+| Comm | **通信协议 Hub** | 二级页面，4 个协议入口 |
+| Key | 虚拟键盘 | LVGL 内置键盘 + 文本框 |
+| Camera | 摄像头预览 | GC0308 取景框 + 快门键 |
+| QR | **饮品选购 Demo** | Coffee / Milk Tea 选购 → 付款二维码 |
+| Audio | 录音播放 | 波形显示 + Rec/Play/Stop |
+| USB | U 盘浏览器 | 文件列表 + 目录切换 |
+| Phone | 电话拨号 | 拨号键盘 + CALL/Back |
+| Game | **游戏 Hub** | 二级页面，3 个游戏入口 |
+| ETH | **以太网 Hub** | 二级页面，3 个功能入口 |
+| Buzzer | 蜂鸣器 | 蜂鸣器控制 |
+| Weather | 天气 | 天气信息展示 |
+
+### 通信协议 Hub（Comm）
+
+| 协议 | 功能 | 状态 |
+|---|---|---|
+| UART | 串口终端，TX/RX 收发 + 键盘输入 | ✅ 已调通 |
+| CAN | CAN 总线监控终端 | 界面就绪 |
+| AT | AT 命令交互终端，真实 atcmd 收发 | 界面就绪 |
+| RS485 | RS485 Modbus 终端 | 界面就绪 |
+
+### 游戏 Hub（Game）
+
+| 游戏 | 说明 |
+|---|---|
+| Snake | 贪吃蛇，34×20 网格，触摸滑动操控 |
+| 2048 | 经典 2048，4×4 网格，滑动合并 |
+| Tetris | 俄罗斯方块 |
+
+### 以太网 Hub（ETH）
+
+| 功能 | 说明 |
+|---|---|
+| IP | 网络信息（W5500 初始化、ipconfig、DHCP） |
+| PING | Ping 诊断工具 |
+| TCP | TCP Client 终端 |
+
+### 饮品选购 Demo（QR）
+
+- Coffee / Milk Tea 两个 Tab，各 4 个商品
+- 商品卡片：图片 + 名称 + 价格 + 勾选圆
+- 选中商品 → Pay → 弹出付款二维码 + 总价
+- 商品图片放 `U:/images/`
+
+## 目录结构
+
+```
+YttriumEC718/
+├── README.md
+├── src/
+│   └── yttrium.py          # 主应用（自包含，单文件 ~4300 行）
+├── icons/                  # 48×48 PNG 图标（~60 个）
+├── images/                 # 商品图片（100×70，8 张）
+├── firmware/               # EC718 固件
+└── _sch/                   # 原理图截图
+```
+
+## API 依赖
+
+| 模块 | 用途 |
+|---|---|
+| `lvgl` | GUI 框架 |
+| `machine` (LCD, Pin, UART) | 硬件驱动 |
+| `tp.ft6x36` | 触摸驱动 |
+| `misc` (PWM, ADC, Power) | 外设控制 |
+| `atcmd` | AT 指令发送 |
+| `ethernet` (W5500) | 以太网 |
+| `qrcode` | 二维码生成 |
+| `_thread`, `utime` | 线程 + 定时 |
+
+## 开发说明
+
+- 界面基类 `AppPage` 统一管理标题栏和返回按钮
+- 所有页面通过 `PAGE_MAP` 字典注册，`MainScreen._open_page()` 统一导航
+- 二级 Hub（Game / Comm / ETH）通过 `lv.scr_load()` 整页切换
+- 键盘输入采用 `lv.keyboard` + `lv.textarea` 模式，定时器 pin 住键盘位置
+- 参考正点原子 HMI 串口屏案例设计交互
 

docs/01_introduction/README.md

@@ -0,0 +1,150 @@
+# 开发板介绍
+
+## 概述
+
+Yttrium 开发板基于 **Quectel EG800Z QuecOpen** 模组（EC718 系列），支持 LTE Cat.1 蜂窝通信，搭载 QuecPython 运行环境，集成 LCD 触控屏、以太网、CAN、RS485、音频、摄像头等丰富外设，适合 IoT 应用快速原型开发。
+
+| 项目 | 说明 |
+|---|---|
+| 开发板型号 | EG800Z_LCD_V1.1（QEM800ZA-CN） |
+| 主控模组 | Quectel EG800Z QuecOpen（EC718 系列） |
+| 模组封装 | LCC |
+| 设计版本 | V1.1（2025-03-26） |
+| 制造商 | Quectel Wireless Solutions |
+
+## 硬件规格
+
+### 核心系统
+
+| 项目 | 规格 |
+|---|---|
+| 模组 | EG800Z QuecOpen |
+| 蜂窝网络 | LTE Cat.1 |
+| 运行环境 | QuecPython（OpenCPU） |
+| 存储 | 128Mbit SPI NOR Flash（XM25QH128C） |
+
+### 显示与触控
+
+| 项目 | 规格 |
+|---|---|
+| LCD 驱动 | ST7796 |
+| 分辨率 | 320×480 竖屏 → 硬件旋转 480×320 横屏 |
+| 接口 | SPI（16-pin FPC 连接器，FH34SRJ-16S-0.5SH） |
+| 触控 | ft6x36，I2C 接口 |
+| 背光 | PWM 调光（LCD_PWM1） |
+
+### 音频
+
+| 项目 | 规格 |
+|---|---|
+| 音频 Codec | ES8311 |
+| 功放 | CS8126S |
+| 接口 | PCM / I2S |
+| 麦克风 | 板载 MIC |
+| 扬声器 | 板载连接器（8-pin） |
+| 蜂鸣器 | 板载蜂鸣器 |
+
+### 通信接口
+
+| 接口 | 芯片/说明 |
+|---|---|
+| 以太网 | CH390D（W5500 兼容），RJ45 带集成变压器，SPI 接口 |
+| CAN | SIT65HVD230DR 收发器，3-pin 端子 |
+| RS485 | SIT3088EESA 收发器，3-pin 端子 |
+| USB | 双 USB-C 接口，XR21B1411IL16 USB-UART 桥接芯片 |
+| UART | Main UART（TX/RX/RTS/CTS/DTR/DCD/RI）、Debug UART |
+| I2C | I2C0 总线（连接触摸、Camera 等） |
+| SPI | SPI0（以太网/Flash 切换）、LCD SPI、Camera SPI |
+| SIM | 双 SIM 卡槽（USIM1 + USIM2） |
+
+### 其他外设
+
+| 外设 | 说明 |
+|---|---|
+| Camera | 6-pin FPC 连接器，支持 GC0308，I2C + SPI 接口 |
+| LED | 状态指示灯（Green）、网络指示灯（Green）、电源灯（Red） |
+| 按键 | PWRKEY、RESET、BOOT、用户按键 |
+| 天线 | U.FL 连接器（LTE 主天线，50Ω） |
+| ADC | ADC0、ADC1 测试点 |
+| GPIO | 多路 GPIO 引出（含 GPIO2/3/4/17 等） |
+
+## 电源系统
+
+| 电源轨 | 电压 | 最大电流 | 生成方式 |
+|---|---|---|---|
+| VBAT | 3.3V ~ 4.3V | 3A | DC 5V / USB VBUS 输入 → ETA2893E8A DC-DC（4V@3A） |
+| VDD_EXT | 由模组输出 | — | EG800Z 内部 LDO |
+| VDD_3V3 | 3.3V | 500mA | SGM2028-3.3 LDO |
+| VDD_2V8 | 2.8V | 300mA | SGM2019-ADJ LDO |
+| VDD_1V8 | 1.8V | 300mA | 板载 LDO（Camera 等外设供电） |
+
+电源输入方式：DC 5V 端子 / USB-C VBUS / 电池 VBAT。
+
+## Pin 定义
+
+### LCD 接口（J0501，16-pin FPC）
+
+| Pin | 信号 | 功能 |
+|---|---|---|
+| 1 | LED | 背光 PWM |
+| 2 | LCD_CS | SPI 片选 |
+| 3 | LCD_RST | 复位 |
+| 4 | LCD_RS | 指令/数据选择 |
+| 5 | SDI (MOSI) | SPI 数据输入 |
+| 6 | LCD_SCK | SPI 时钟 |
+| 7 | SDO (MISO) | SPI 数据输出 |
+| 8 | CTP_SCL | 触摸 I2C 时钟 |
+| 9 | CTP_RST | 触摸复位 |
+| 10 | CTP_SDA | 触摸 I2C 数据 |
+| 11 | CTP_INT | 触摸中断 |
+| 12 | SD_CS | SD 卡片选（可选） |
+
+### Camera 接口（J0503，6-pin FPC）
+
+| Pin | 信号 | 功能 |
+|---|---|---|
+| 1 | CAM_VDD | 模拟供电 |
+| 2 | CAM_VDDIO | IO 供电 |
+| 3 | CAM_I2C_SCL | I2C 时钟 |
+| 4 | CAM_I2C_SDA | I2C 数据 |
+| 5 | GND | 地 |
+| 6 | VCC | 电源 |
+
+### 主要 GPIO 映射
+
+| 模组 Pin | 功能 | 备注 |
+|---|---|---|
+| MAIN_TXD / MAIN_RXD | 主串口 | USB-UART 桥接 / RS485 切换 |
+| DBG_TXD / DBG_RXD | 调试串口 | 独立 Debug 通道 |
+| SPI0_CLK/SDI/SDO/CS | SPI0 | 以太网 / Flash 二选一（SEL_NET_FLASH 切换） |
+| LCD_SPI_* | LCD 专用 SPI | 独立 SPI 通道 |
+| I2C0_SCL/SDA | I2C0 | 触摸、Camera 共享 |
+| CAN_RXD/TXD/STB | CAN 总线 | STB 待机控制 |
+| PCM_CLK/SYNC/DIN/DOUT | 音频 PCM | 连接 ES8311 Codec |
+| ADC0 / ADC1 | ADC 输入 | 测试点引出 |
+| PWRKEY | 电源键 | 低电平开机 |
+| RESET_N | 复位 | 低电平复位 |
+| USB_BOOT | 烧录模式 | 进入下载模式 |
+| STATUS / NET_STATUS | LED 指示 | 模组状态 / 网络状态 |
+| WAKEUP0 | 唤醒 | 外部唤醒 |
+| LED_PWM4 | LED PWM | 可调光 LED |
+| BUZZER | 蜂鸣器 | GPIO 驱动 |
+
+## 板载接口布局
+
+参考 `datasheet/` 目录下的原理图和丝印图：
+
+- `EG800Z_LCD_SCH_V1.1_20250326.pdf` — 原理图（7 页）
+- `EG800Z_LCD_PCB_V1.1_20250326.pdf` — PCB 丝印图（Top + Bottom）
+
+## 开发资源
+
+| 资源 | 路径 |
+|---|---|
+| 固件包 | `firmware/` |
+| 烧录工具 | `tools/FlashTools_V4.1.19_2509010.zip` |
+| 串口工具 | `tools/sscom5.13.1.zip` |
+| Demo 代码 | `src/yttrium.py` |
+| 图标资源 | `icons/`、`images/` |
+| 烧录教程 | [02_firmwareFlashing](../02_firmwareFlashing/README.md) |
+| 运行教程 | [03_runDemo](../03_runDemo/README.md) |

docs/02_firmwareFlashing/README.md

@@ -0,0 +1,69 @@
+# 固件烧录
+
+本章介绍如何使用 **FlashTools** 将 QuecPython 固件烧录到 Yttrium 开发板（EG800Z 模组）。
+
+## 准备工作
+
+1. **烧录工具**：使用 `tools/` 目录下的 `FlashTools_V4.1.19_2509010.zip`，解压后运行 `FlashTools` 工具
+2. **固件文件**：解压 `EG800ZCNLAR05A01M04_Yttrium_OCPU_QPY.7z`，获取固件包（`.pac` 或 `.bin` 格式）
+3. **硬件连接**：通过 USB 转串口模块连接开发板的 UART 烧录口
+
+## 烧录步骤
+
+### 1. 解压烧录工具
+
+- 解压 `FlashTools_V4.1.19_2509010.zip`
+- 运行 `FlashTools.exe`
+
+### 2. 选择固件
+
+点击 Browse 选择固件：
+
+![选择固件](images/image.png)
+
+在 FlashTools 工具中选择解压后的固件文件里的 `quec_download_usb.ini` 文件，点击打开：
+
+![选择 ini 文件](images/image-1.png)
+
+### 3. 连接设备
+
+- 将开发板通过 USB 线连接至 PC
+- 找到 Quectel USB AT Port，确认其 COM 端口号
+
+### 4. 进入烧录模式
+
+- 选中端口号后，将右侧 Erase All (User Mode) 和 Erase NVM 两个选项打钩
+- 波特率选择 921600
+
+![烧录配置](images/image-2.png)
+
+### 5. 开始烧录
+
+FlashTools 工具识别到 COM 端口后，点击 **Reset and download** 按钮：
+
+![开始烧录](images/image-4.png)
+
+等待进度条走完，提示烧录成功：
+
+![烧录完成](images/image-3.png)
+
+### 6. 重启设备
+
+烧录完成后，按 RESET 键或重新上电，设备将以新固件启动。
+
+## 常见问题
+
+| 问题 | 可能原因 | 解决方法 |
+|---|---|---|
+| FlashTools 无法识别 COM 口 | 驱动未安装 | 安装对应 USB 转串口驱动（CH340 等） |
+| 烧录后无法启动 | 固件不匹配 | 确认固件文件与模组型号一致（EG800Z） |
+| 串口无响应 | 波特率或串口号错误 | 检查 COM 口配置，默认波特率 921600 |
+
+## 烧录后验证
+
+烧录成功后，使用串口工具（115200 波特率）连接开发板，在 REPL 中执行：
+
+```python
+>>> print('hello world')
+hello world
+```