ESP32 Pixel Clock

基于 ESP32-S3 的 OLED 像素时钟：大号时间、日期/星期、心知天气（含城市）、室内温湿度（DHT11），并通过网页配置 Wi-Fi 与其它选项。

目标芯片：esp32s3（ESP-IDF v6.x）

功能

• OLED（SSD1306 128×64），显示优先级：时间 > 日期 > 温湿度/天气；UI 中文（轻量 12×12 子集字库，约 1KB）
• 配网：无 Wi-Fi 时 SoftAP + 网页配置；STA 联网后仍开 Web，可用局域网 IP 随时改配置
• Wi-Fi 扫描：配置页扫描附近热点，支持手动输入 SSID
• 心知天气 HTTPS 实况（language=zh-Hans）；OLED 显示 location.name 与中文天气文案
• DHT11 室内温湿度（约 10 秒读取一次；协议参考 Adafruit DHT）
• SNTP 校时（默认时区 CST-8）

OLED 布局

0–27   HH:MM（大号 ×3）+ 秒 / AM·PM + 右上 WiFi 图标
28–39  周三 08-04（左）+ 位置名（右，如 北京）
40–51  室外25C 多云
52–63  室内26C 湿度55%

未校时时显示「同步 / 等待」；天气未就绪时为「室外--C 加载中」或「离线」。

中文字库为 UI + 天气用语 + 常见城市子集（tools/gen_font_cn.py），控制 Flash 占用。

硬件接线（默认）

外设	信号	GPIO
SSD1306 (I2C)	SDA	4
SSD1306 (I2C)	SCL	5
SSD1306	地址	0x3C
DHT11	DATA	7

DHT11：VCC → 3.3V，GND → GND，DATA → GPIO7，建议 4.7k–10k 上拉到 3.3V。

引脚与配置热点名称可在 idf.py menuconfig → Pixel Clock 中修改。

使用流程

1. 烧录固件并上电。
2. 若未保存过 Wi-Fi，设备开启热点：
   • SSID：PixelClock-Setup（默认）
   • 密码：12345678（默认）
   • 浏览器打开：http://192.168.4.1
3. 扫描并选择 Wi-Fi，填写密码；天气位置可用 ip 自动定位，保存后重启连网。
4. 联网后 OLED 显示时钟、城市与天气。
5. 之后可用 STA IP 访问配置页，例如：http://192.168.x.x/（与手机/电脑同一局域网）。

串口日志（示例）

I (...) dht11: T=26.0C H=55.0%
I (...) weather: city=北京 text=多云 temp=25C code=4
I (...) wifi_net: connected, IP: 192.168.x.x

网页可配置项

项	说明
Wi-Fi SSID / 密码	扫描选择或手动输入
Weather location	城市名 / 拼音 / ip 等
12h / 24h	时间显示制式
Brightness	OLED 对比度 0–255
°C / °F	温度单位
Weather refresh	天气刷新间隔（分钟）
Timezone	POSIX TZ，如 CST-8

配置保存在 NVS（clock 命名空间），下次上电自动连网。

相关 API：

方法	路径	说明
GET	/	配置页
POST	/save	保存并重启
GET	/api/scan	Wi-Fi 扫描 JSON
GET	/api/cfg	当前配置（不含密码；含解析到的 city）

编译与烧录

idf.py set-target esp32s3
idf.py build
idf.py -p PORT flash monitor

烧录方式一般选 UART。

默认使用 SINGLE_APP_LARGE（约 1500KB app 分区），适配 2MB Flash。中文字库仅含界面用字，勿直接塞入完整 GB2312。

源码结构

main/
  main.c                      # app_main 入口
components/pixel_clock/
  include/                    # 公共头文件
  src/                        # 驱动与业务库
  CMakeLists.txt
  Kconfig                     # 引脚 / AP 等配置

模块	职责
main.c	入口：NVS、状态、OLED、网络
app_types / app_state / app_config	类型、全局状态、NVS
oled / font_cn	SSD1306 + ASCII + 中文子集字模 + WiFi 图标
dht11	DHT11 读取
display	OLED 刷新任务
wifi_net	AP / STA、扫描、联网
web_server	配置网页与 REST
weather	心知天气、城市解析、SNTP

天气 API

使用心知天气实况接口：

https://api.seniverse.com/v3/weather/now.json?language=zh-Hans&unit=c

固件解析字段包括：now.temperature、now.code / now.text、location.name（位置名，中文）。

密钥写在 components/pixel_clock/src/weather.c（私钥直接请求）。请勿将含密钥的固件随意公开分发。

许可证

项目由 ESP-IDF SoftAP 示例改造而来；示例部分遵循其原有许可。其余应用代码按你后续声明为准。