# cc-face

**Repository Path**: waveshare_esp32_s3/cc-face

## Basic Information

- **Project Name**: cc-face
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-27
- **Last Updated**: 2026-05-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Claude Code Robot Face Monitor

ESP32-S3 BLE 状态监视器，通过极简胶囊眼表情实时可视化 Claude Code 钩子事件状态。

```
Claude Code -> 钩子脚本 -> BLE 桥接 -> BLE -> ESP32 (机器人表情)
```

## 功能特性

- BLE GATT 服务器（设备名称：`Claude Code`）
- 11 种核心状态，每种状态映射到唯一的胶囊眼表情（一对一）
- 极简设计：两个胶囊形眼睛，无虹膜/瞳孔/眉毛/嘴巴
- 表情通过眼睛宽度和颜色的组合实现
- 非对称眼睛偏移（部分状态双眼同步偏移，增加动态感）
- 自适应眨眼频率（警觉时快 ~2.5s，困倦时慢 ~7s）
- 空闲呼吸动画（困倦状态下眼睛微微脉动）
- 深色海军蓝背景，极简矢量风格
- 底部居中状态文字标签
- 自动重连 BLE 桥接守护进程，支持 macOS LaunchAgent

## 硬件

ESP32-S3-LCD-1.9 开发板：
- 显示屏：SH8601 AMOLED 170x320（SPI，软件旋转 320x170 横屏）
- 触摸：FT3168（I2C，地址 0x15）
- SPI：CLK=10, MOSI=13, CS=12, DC=11, RST=9
- I2C：SDA=47, SCL=48

## 机器人面部布局

极简胶囊眼设计：两个对称的胶囊形（pill）眼睛，居中于 320x170 屏幕。

```
  ┌─────────────────────────────────────┐
  │            dark navy bg             │
  │                                     │
  │       ╭──╮         ╭──╮            │
  │       │  │         │  │  ← capsule │
  │       ╰──╯         ╰──╯    eyes    │
  │                                     │
  │           [state label]             │
  └─────────────────────────────────────┘
```

- 眼睛尺寸：统一 32×44px 竖直药丸形，宽度和 Y 偏移随状态微调
- 圆角半径：16px（完全胶囊形）
- 两眼间距：90px（中心到中心）
- 颜色：6 种语义色彩（青/亮蓝/暗蓝/绿/琥珀/红）

## 状态与表情映射表

12 种核心 Claude Code 状态，每种映射到唯一胶囊眼表情：

| # | Claude Code 事件 | 状态 | 表情描述 |
|---|---|---|---|
| 1 | 空闲 | `idle` | 青色药丸眼 + 呼吸微动 + 漂浮 zzz 动画 |
| 2 | 会话开始 | `session-start` | 亮蓝色宽眼，兴奋 |
| 3 | 会话结束 | `session-end` | 暗淡蓝色，渐隐 |
| 4 | 用户提交提示 | `prompt-submit` | 亮蓝色宽眼 + 顶部漂浮多层 `?` 思考动画（递增大小） |
| 5 | 工具执行前 | `pre-tool` | 青色药丸眼 + 两侧脉动波形条（忙碌处理） |
| 6 | 工具执行后 | `post-tool` | 亮蓝色药丸眼 + 两侧脉动波形条（忙碌处理） |
| 7 | 工具执行失败 | `tool-fail` | 红色宽眼，受惊，双眼上移 |
| 8 | 权限请求 | `perm-req` | 琥珀色宽眼，恳求 |
| 9 | 权限拒绝 | `perm-denied` | 红色窄眼，挫败 |
| 10 | 任务创建 | `task-created` | 亮蓝色药丸眼 |
| 11 | 任务完成 | `task-done` | 绿色药丸眼（与 task-created 形状一致） |

### 表情视觉参数

每个状态通过以下参数的唯一组合实现差异化：

| 参数 | 取值范围 | 说明 |
|---|---|---|
| 眼睛颜色 | 6 种 | 青/亮蓝/暗蓝/绿/琥珀/红 |
| 眼睛高度 | 统一 44px | 所有状态保持一致竖直药丸形 |
| 眼睛宽度 | 28-40px | 微调（窄眼=挫败，宽眼=惊讶/请求） |
| Y 轴偏移 | -2 ~ 0px | 双眼同步偏移（受惊上移） |

## 钩子事件

核心 Claude Code 钩子事件在 `~/.claude/settings.json` 中注册：

| 钩子事件 | 触发时机 | ESP32 状态 | cc_hook.py 消息 |
|---|---|---|---|
| SessionStart | 会话开始 | session-start | `HOOK:SessionStart` |
| SessionEnd | 会话结束 | session-end | `HOOK:SessionEnd` |
| UserPromptSubmit | 用户提交提示 | prompt-submit | `HOOK:UserPromptSubmit` |
| PreToolUse | 工具执行前 | pre-tool | `HOOK:PreToolUse` |
| PostToolUse | 工具执行后 | post-tool | `HOOK:PostToolUse` |
| PostToolUseFailure | 工具失败 | tool-fail | `HOOK:PostToolUseFailure` |
| PermissionRequest | 权限请求 | perm-req | `HOOK:PermissionRequest` |
| PermissionDenied | 权限拒绝 | perm-denied | `HOOK:PermissionDenied` |
| TaskCreated | 任务创建 | task-created | `HOOK:TaskCreated` |
| TaskCompleted | 任务完成 | task-done | `HOOK:TaskCompleted` |

## 编译与烧录

```bash
idf.py build flash monitor
```

## 电脑端设置

### 1. 安装依赖

```bash
pip install bleak
```

### 2. 一键安装（BLE 桥接 + Claude Code 钩子）

```bash
./cc_service.sh install
```

此命令将：
- 复制 `cc_hook.py` 到 `~/.claude/`
- 在 `~/.claude/settings.json` 中添加所有钩子条目
- 安装并启动 macOS LaunchAgent（登录时自动启动）

### 3. 其他命令

```bash
./cc_service.sh status    # 检查安装状态
./cc_service.sh log       # 查看服务日志
./cc_service.sh scan      # 扫描 ESP32 设备
./cc_service.sh test      # 发送测试事件
./cc_service.sh restart   # 重启 BLE 桥接
./cc_service.sh uninstall # 卸载所有内容
```

## BLE 协议

服务 UUID：`0xFF00`

| 特征 | UUID | 方向 | 描述 |
|---|---|---|---|
| Write | `0xFF01` | PC -> ESP32 | 发送钩子事件 |
| Notify | `0xFF02` | ESP32 -> PC | 权限响应 |

### 消息（PC -> ESP32）

```
HOOK:<event>                    # 状态变更事件
```

## 项目结构

```
cc_esp32/
  main/main.c                   # 核心：BLE、状态机、机器人面部 UI、动画
  components/
    i2c_bsp/                     # I2C 驱动（FT3168 触摸）
    esp_touch/                   # 触摸输入处理
  cc_ble_bridge.py               # PC：BLE 桥接守护进程（Unix Socket IPC）
  cc_hook.py                     # PC：Claude Code 钩子事件发送器
  cc_service.sh                  # PC：macOS 服务管理器
```

## 技术细节

- **显示驱动**：SH8601 AMOLED，SPI 20MHz，16-bit RGB565
- **图形框架**：LVGL v8.4，双缓冲 DMA
- **面部组件**：每只眼 1 个 LVGL 对象（胶囊形）+ 6 个波形条 + 3 个思考 `?` 标签 + 3 个 zzz 标签
- **动画**：50ms 定时器驱动
  - 自适应眨眼（警觉 2.5s / 普通 3.5s / 困倦 5s / 空闲 7s）
  - 空闲呼吸脉动（sinf() 正弦波高度微调）
  - 思考漂浮动画（prompt-submit 时顶部多层 `?` 递增大小漂浮上升）
  - 忙碌波形条（pre-tool/post-tool 两侧垂直条脉动，音频波形效果）
  - 眼睛 Y 轴偏移（部分状态双眼同步偏移）
- **表情系统**：统一高度 + 颜色 + 宽度 + Y 偏移的组合
- **状态检测**：100ms 轮询 cc_target_state 变化，BLE GATT 写入触发
- **内存**：PSRAM 旋转缓冲区，DMA 绘图缓冲区