convez.ai
AgenteAutomaçãoAvançado
JacksonTai2007

Sistema de Estacionamento Inteligente com ESP32

JacksonTai2007/esp32-smart-parking-system

Estacionamento inteligente com ESP32, RFID, sensores IoT e IA agentic

Ver no GitHub
InicialPluginScore · de 0 a 100

Projeto de controle de estacionamento baseado em ESP32 com detecção ultrassônica de veículos, autenticação RFID, controle de cancela servomotora e monitoramento de vagas via sensores infravermelhos. O sistema apresenta dashboard web em tempo real e utiliza fluxo de desenvolvimento colaborativo com agentes IA (Claude Code e Codex) na nuvem.

Instalação

$npx convez-ai JacksonTai2007/esp32-smart-parking-system

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
—
Issues abertas
1
Contribuidores
2

Casos de uso

  • Automação de controle de acesso em garagens e estacionamentos
  • Prototipagem de sistemas IoT com ESP32 e múltiplos sensores
  • Demonstração de fluxo colaborativo com agentes IA na nuvem para firmware embarcado

Veredito

Projeto bem estruturado e documentado que combina hardware complexo (RFID, servos, ultrassom, infravermelhos) com máquina de estados robusta em C++. O diferencial está no workflow de desenvolvimento com agentes IA na nuvem, tornando-se interessante tanto para aprendizado prático de IoT quanto para exploração de metodologias ágeis de engenharia de firmware.

README

A tradução para o português deste README ainda está na fila.

基于 ESP32 的智能停车场管理系统设计与实现

ESP32 Smart Parking System — 大学毕业设计项目

Arduino Compile

1. 项目简介

以 ESP32 为主控的智能停车场管理系统:超声波检测入口来车,RFID 刷卡鉴权, SG90 舵机模拟闸机起落,红外传感器实时监测车位占用,OLED 与本地 Web 页面 同步展示剩余车位与系统状态,蜂鸣器提供声音反馈。

核心演示流程:

车辆靠近入口 → 超声波检测 → OLED 显示"请刷卡" → RFID 合法刷卡
→ 蜂鸣器提示成功 → SG90 舵机开闸 → 车位传感器更新 → OLED/Web 显示剩余车位

2. 毕设定位

  • 课题:基于 ESP32 的智能停车场管理系统设计与实现
  • 当前阶段:Phase 1 MVP(最小可演示闭环),论文大纲见 docs/thesis-outline.md
  • 项目特色之一:采用云端 AI Agent 协作开发流程(见第 7 节), 开发过程本身可作为论文的工程方法章节素材
  • 答辩演示脚本见 docs/demo-script.md

3. 功能列表

Phase 1(本期已实现,待硬件实测)

  • ✅ RC522 RFID 刷卡识别 + 白名单鉴权(串口打印每张卡 UID,便于登记)
  • ✅ SG90 舵机闸机:开闸 → 保持 5 秒 → 自动关闸,全程非阻塞
  • ✅ HC-SR04 超声波入口来车检测(滞回 + 连续确认抗抖动)
  • ✅ 2~4 路红外车位检测(软件去抖、触发电平可配置)
  • ✅ OLED SSD1306 实时状态显示
  • ✅ 蜂鸣器提示(成功 1 短响 / 无效卡 3 短响 / 满位 1 长响)
  • ✅ 本地 Web 仪表盘 + JSON 状态 API + 手动开关闸(STA 失败自动开热点兜底)
  • ✅ 主业务状态机(IDLE → 来车 → 等待刷卡 → 放行/拒绝/满位)

Phase 2(规划,引脚已预留)

火焰/烟雾报警与风扇联动(GPIO 27/36/16)、入场记录与计费、数据持久化等。

4. 硬件清单

器件数量说明
ESP32 DevKit(WROOM-32)1主控
RC522 RFID 模块 + IC 卡/钥匙扣1 套刷卡鉴权(3.3V 供电)
SG90 舵机1模拟闸机
HC-SR04 超声波模块1入口来车检测
红外避障传感器2~4车位占用检测
OLED SSD1306 128×64(I2C)1状态显示
有源蜂鸣器模块1声音提示
5V 外接电源1舵机独立供电(与 ESP32 共地)
电阻 1kΩ + 2kΩ各 1HC-SR04 Echo 分压
面包板、杜邦线、小车模型若干搭建与演示

5. 接线表

完整接线说明与排查方法见 docs/pinout.md 和 docs/hardware-wiring.md,代码权威定义在 firmware/parking-system/config/Pins.h。

功能模块ESP32 引脚备注
I2C SDA / SCLOLED SSD1306GPIO 21 / 22I2C
RFID SCK / MISO / MOSIRC522GPIO 18 / 19 / 23SPI
RFID SS / RSTRC522GPIO 5 / 4CS、Reset
闸机舵机SG90GPIO 13外接 5V,共地
蜂鸣器BuzzerGPIO 14数字输出
超声波 Trig / EchoHC-SR04GPIO 25 / 26Echo 分压到 3.3V
车位 1~4红外传感器GPIO 32 / 33 / 34 / 3534/35 输入专用
火焰 / 烟雾 / 风扇Phase 2 预留GPIO 27 / 36 / 16本期不接

⚠️ 关键安全项:RC522 只能接 3.3V;SG90 外接 5V 并与 ESP32 共地; HC-SR04 Echo 建议 1kΩ+2kΩ 分压。

默认硬件假设(实测不符时只需改 config/Settings.h):开发板为 ESP32 DevKit (WROOM-32);车位传感器为红外避障模块,检测到物体输出 LOW (SLOT_OCCUPIED_LEVEL = LOW);蜂鸣器为高电平触发的有源模块;车位数 4 (可配 2~4);串口波特率 115200。

6. 软件架构

模块化固件 + 非阻塞 millis() 状态机,详见 docs/architecture.md。

模块职责
ParkingStateMachine主业务状态机
GateControllerSG90 舵机闸机控制(自动关闸)
RfidServiceRC522 读卡 + 白名单
UltrasonicService入口车辆靠近检测
SlotManager车位状态与剩余车位统计
DisplayServiceOLED 显示
AlertService蜂鸣器节奏
WebDashboard网页 + JSON API + Wi-Fi 管理

约定:GPIO 只在 config/Pins.h 定义;阈值/角度/时长/功能开关只在 config/Settings.h 定义;主循环无长 delay()。

7. 云端 AI Agent 工作流

本项目采用云端 AI 协作开发,完整流程见 docs/cloud-workflow.md:

  • Claude Code Cloud — 主功能开发、架构、跨文件实现、文档(守则:CLAUDE.md)
  • Codex Cloud — PR 审查、编译验证、可维护性检查(守则:AGENTS.md)
  • GitHub PR — 协作中心;GitHub Actions 自动编译检查
  • 用户本地 — 真实硬件接线、烧录、串口日志、阈值调试、答辩演示

云端 Agent 无法烧录与读取串口,每个 PR 都会明确标注 "云端已验证内容"与"需本地硬件验证内容"。

8. 如何在云端 / CI 编译

./scripts/compile.sh --install-deps   # 首次:安装 ESP32 core + 依赖库
./scripts/compile.sh                  # 之后:仅编译
  • FQBN:esp32:esp32:esp32;退出码 0 通过 / 1 代码错误 / 2 环境缺失
  • 依赖库:ESP32Servo、MFRC522、Adafruit GFX Library、Adafruit SSD1306
  • 每个 PR 由 GitHub Actions 自动编译(.github/workflows/arduino-compile.yml)
  • 受限网络的云端 Agent 容器(downloads.arduino.cc 等官方源被拦截、GitHub 放行): 先运行 ./scripts/setup-cloud-env.sh,它把 arduino-cli、ESP32 core、依赖库、ctags 全部改从 GitHub Releases 获取(已在 Claude Code Cloud 实测通过编译)

9. 如何本地烧录

# 安装 arduino-cli 后:
./scripts/compile.sh --install-deps      # 首次准备环境
./scripts/upload.sh /dev/ttyUSB0         # 烧录(Windows 用 COM 口)
arduino-cli monitor -p /dev/ttyUSB0 -c baudrate=115200   # 看串口日志

不用脚本时的原生 arduino-cli 命令(与 scripts/ 等价):

arduino-cli core install esp32:esp32 \
  --additional-urls https://espressif.github.io/arduino-esp32/package_esp32_index.json
arduino-cli lib install "ESP32Servo" "MFRC522" "Adafruit GFX Library" "Adafruit SSD1306"
arduino-cli compile --fqbn esp32:esp32:esp32 firmware/parking-system   # 编译
arduino-cli upload  -p /dev/ttyUSB0 --fqbn esp32:esp32:esp32 firmware/parking-system   # 烧录
arduino-cli monitor -p /dev/ttyUSB0 -c baudrate=115200                 # 串口监视

也可以用 Arduino IDE:打开 firmware/parking-system/parking-system.ino, 开发板选 "ESP32 Dev Module",安装上述 4 个库后编译上传。 scripts/upload.sh 仅限本地使用,云端 Agent 无串口硬件。

10. 如何配置 Wi-Fi

cd firmware/parking-system/config
cp WifiCredentials.example.h WifiCredentials.h
# 编辑 WifiCredentials.h 填入真实 SSID/密码(该文件已被 .gitignore 忽略,不会入库)
  • 不创建该文件也能编译运行:固件自动开启热点 ESP32-Parking (密码 parking123,可在 Settings.h 修改),手机连热点后访问 http://192.168.4.1/
  • STA 连接成功后串口会打印分配到的 IP,浏览器访问该 IP 即可; 运行中掉线会自动等待重连,超时后降级到 AP 热点
  • ⚠️ 安全边界:Web 手动开/关闸接口没有认证,同一网络内任何设备都能 触发物理闸机——仅限本地演示网络使用,绝不可暴露公网; 可在 Settings.h 置 ENABLE_WEB_MANUAL_GATE_CONTROL 0 关闭(接口返回 403, 仪表盘变为只读)

11. 如何添加 RFID 白名单

  1. 烧录后打开串口监视器(115200)
  2. 刷卡,记录日志:[RFID] New card UID: A1:B2:C3:D4
  3. 把 UID 填入 config/Settings.h 的 RFID_WHITELIST 数组(替换占位卡号)
  4. 重新编译烧录

12. 如何进行硬件实测

按 docs/hardware-wiring.md 的"上电自检顺序"逐模块接线, 对照 tests/README.md 的 12 项测试清单逐项验证, 把串口日志/照片按 docs/cloud-workflow.md 的反馈格式贴回 PR。 实测后通常需要校准 Settings.h:超声波阈值、红外触发电平、舵机角度、 蜂鸣器电平、OLED 地址。

最小验收标准(MVP 达标线,完整清单见 tests/README.md):

  • Arduino CLI 编译通过(本地或 CI 绿勾)
  • 烧录 ESP32 成功,串口 115200 能看到启动 banner 与各模块 init OK
  • 串口 / OLED / 网页能看到每个车位 FREE / OCCUPIED 状态
  • 遮挡、移开车位传感器时状态变化正确
  • 去抖生效:传感器抖动不会导致车位状态频繁跳变

13. 答辩演示流程

见 docs/demo-script.md:6 个场景(启动、合法卡入场、 无效卡拒绝、满位处理、Web 远程控制、复位收尾)+ 现场故障预案。

14. Phase 2 计划

  • 火焰 / 烟雾检测报警,风扇自动联动(引脚与 AlertPattern::ALARM 已预留)
  • 入场/出场记录与简单计费模型
  • 出口闸机与双向流程
  • 状态机主机端单元测试
  • 数据持久化与上位机/云平台对接(视进度取舍)

仓库结构

├── README.md / CLAUDE.md / AGENTS.md     # 首页 / 开发 Agent 守则 / 审查 Agent 守则
├── docs/                                 # 架构、引脚、接线、工作流、演示、论文大纲
├── firmware/parking-system/              # Arduino 固件(.ino + config/ + src/ + web/)
├── scripts/                              # compile.sh(云端/CI/本地)、upload.sh(仅本地)
├── .github/workflows/arduino-compile.yml # PR 自动编译检查
└── tests/                                # 测试说明与硬件测试清单

License

MIT(见 LICENSE)

Ver o original no GitHub

Bom para

Relacionados