# esp32-s3

**Repository Path**: opple/esp32-s3

## Basic Information

- **Project Name**: esp32-s3
- **Description**: 开发板项目，用来监控矿机的
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-30
- **Last Updated**: 2025-11-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ESP32‑S3 3.5" 面板方案与 Grafana 缓存中转（cache‑proxy）

本仓库包含两部分：
- `esp32-s3-3_5inch-001-sdk/`：基于 ESP‑IDF 5.x 与 LVGL 的 3.5 英寸屏方案 SDK，内含多个示例，重点示例为 `examples/20.panel_test`。
- `cache-proxy/`：为设备侧访问 Grafana/Prometheus 提供的缓存中转服务，支持 TTL 缓存与查询白名单，降低上游压力并提升稳定性。

## 目录结构
- `esp32-s3-3_5inch-001-sdk/`
  - `examples/20.panel_test/` 面板 UI 示例（ESP32‑S3 + 3.5" 彩屏），使用 LVGL 渲染卡片/文本样式行。
- `cache-proxy/`
  - `server.py` FastAPI 实现的中转服务
  - `requirements.txt` 依赖清单
  - `config/queries_whitelist.txt` 查询白名单（正则）
  - `README.md` 组件说明与部署示例

## 快速开始（固件）
前置条件：
- 已安装 ESP‑IDF 5.1（或兼容版本），并完成 `idf.py` 环境配置
- Python 3.10+、CMake、Ninja 等构建依赖

构建与烧录（示例：`20.panel_test`）：
```
cd esp32-s3-3_5inch-001-sdk/examples/20.panel_test
idf.py set-target esp32s3
idf.py build
# 将串口替换为实际端口名
idf.py -p /dev/cu.usbserial-xxxx flash monitor
```
常见说明：
- UI 使用 LVGL 渲染，头部（Header）可配置为文本模式，内容区多行卡片风格；也可按需求将某些行切换为“文本模式”。
- 编译过程中如出现 `deprecated` 或未使用函数告警，不影响功能；可后续做代码清理。

## cache‑proxy 的作用
设备直接访问 Grafana/Prometheus 时容易遇到：频繁请求、令牌分散管理、网络波动等问题。`cache-proxy` 作为“中间层”统一持有上游凭据，按 TTL 对查询结果缓存，并提供白名单限制，具备以下优势：
- 稳定性：TTL 命中直接返回缓存；过期进入 `stale-while-revalidate`，先回旧数据再后台刷新，降低抖动。
- 安全性：查询白名单（正则）限制仅允许的 PROMQL，避免任意查询被滥用；支持设备端可选鉴权（`X-Client-Token`）。
- 易用性：对设备暴露与 Grafana 一致的查询接口路径，便于无缝切换。

### 关键接口
- 兼容查询代理：
  - `GET /api/datasources/proxy/{ds}/api/v1/query?query=<promql>`
  - 响应头包含：`X-Cache: HIT|MISS|STALE|STALE-ERROR` 与合理的 `Cache-Control`
- 汇总接口（示例用于设备端 UI）：
  - `GET /api/summary`
  - 聚合示例：总算力（`hashrate_ths`）、分组功耗/温度（`10L/10R/11L/141_142` 及 `t.*` 指标）

### 环境变量（可选值与默认）
- `GRAFANA_URL`（默认 `http://111.6.69.26:3000`）：上游 Grafana 地址
- `GRAFANA_TOKEN`：Grafana 访问令牌（如无需可留空）
- `CLIENT_TOKEN`：设备端访问令牌；配置后设备需在请求头加 `X-Client-Token`
- `CACHE_TTL_MS`（默认 `15000`）：缓存生存期
- `STALE_MS`（默认 `60000`）：进入 stale 窗口的时长（后台刷新）
- `REQUEST_TIMEOUT_MS`（默认 `5000`）：上游请求超时
- `WHITELIST_PATH`（默认 `config/queries_whitelist.txt`）：查询白名单路径
- `GRAFANA_DS_ID`（默认 `1`）：默认数据源 ID（部分接口使用）

### 本地运行
```
cd cache-proxy
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export GRAFANA_URL=http://111.6.69.26:3000
export GRAFANA_TOKEN=""             # 若上游无需鉴权可留空
export CLIENT_TOKEN="replace-me"    # 如启用设备侧鉴权
export CACHE_TTL_MS=15000
export STALE_MS=60000
export WHITELIST_PATH=config/queries_whitelist.txt
uvicorn server:app --host 0.0.0.0 --port 8080
```

### Docker 运行
```
docker build -t grafana-cache-proxy cache-proxy
docker run -d \
  -e GRAFANA_URL=http://111.6.69.26:3000 \
  -e GRAFANA_TOKEN="" \
  -e CLIENT_TOKEN=replace-me \
  -e CACHE_TTL_MS=15000 \
  -e STALE_MS=60000 \
  -e WHITELIST_PATH=/app/config/queries_whitelist.txt \
  -p 8080:8080 grafana-cache-proxy
```

### 设备接入建议
- 将固件中的上游地址切换为中转地址（示例：`http://<proxy-host>:8080`）。
- 若启用设备端鉴权，请在请求头中加入 `X-Client-Token: <token>`。
- 其余路径参数与 Grafana 保持一致，无需改动解析逻辑。