一、所选主题和项目介绍

1.1 项目背景

在智能家居和安防领域，防盗门状态监测是一个基础而重要的需求。传统的门磁报警系统通常采用独立工作模式，无法实现远程集中监控。当需要管理多个防盗门（如住宅的大门、后门、车库门，或办公室的多个入口）时，缺乏一个统一的、可视化的管理平台。本项目的创新在于将M5Stack CoreS3主控与Unit Limit行程开关结合，利用MQTT协议将门状态上报至树莓派，实现了一个从本地检测到远程Web集中监控的完整防盗门报警系统。

1.2 项目目标

本项目使用M5Stack CoreS3 V1.1开发板，配合3个Unit Limit行程开关，实现一款智能防盗门报警系统，主要功能如下：

1. 多门监测：支持3路独立防盗门（大门、后门、侧门）同时监测
2. 门状态检测：通过Unit Limit行程开关数字信号检测门开/关状态
3. 报警触发：门被打开时自动触发声光报警
4. 实时显示：2.0寸TFT触摸屏实时显示各门状态
5. MQTT数据上传：通过WiFi将门状态和报警事件上报至树莓派
6. Web远程监控：树莓派Flask Web面板集中显示所有门状态
7. 事件记录：记录门状态变化历史，支持回溯查询

1.3 创新点

1. 多门集中监控：单台CoreS3同时监测3路独立防盗门，实现集中管理
2. 行程开关检测：采用机械行程开关，性能稳定可靠，40万次机械寿命
3. 去抖动算法：软件去抖动算法确保门状态检测准确无误
4. 实时可视化：2.0寸IPS触摸屏实时显示门状态，红色报警醒目提示
5. Web远程面板：树莓派Flask Web提供深色主题仪表盘，手机/电脑均可访问
6. 模拟测试模式：Web服务器内置模拟数据生成器，方便调试和演示
7. 事件历史追踪：记录所有门状态变化事件，支持SQLite持久化存储

二、硬件介绍

2.1 主控设备

M5Stack CoreS3 (SKU: K128) — M5Stack开发套件系列第三代主机，采用ESP32-S3双核处理器，板载16MB Flash和8MB PSRAM，配备2.0寸电容触摸IPS屏，支持WiFi功能，具备丰富的Grove扩展接口。

2.2 传感器模块

Unit Limit (SKU: U145) — 行程开关单元，当开关柄受到外力闭合时，数字信号接口由3.3V高电平下拉至0V低电平，能够向MCU提供一个限位触发信号。适用于门磁检测、位置限位等场景。

2.3 硬件连接

CoreS3提供3路Grove扩展口，每路可连接一个Unit Limit行程开关：

连接说明：

• Unit Limit的HY2.0-4P线序：Black=GND, Red=5V, Yellow=NC, White=Digital Output
• CoreS3 Grove线序：Black=GND, Red=5V, Yellow=GPIO, White=GPIO
• 将Unit Limit的White线连接至CoreS3对应端口的White引脚（G1/G8/G17）

门状态检测原理：

• 门关闭 → 行程开关柄被门框按压闭合 → 输出0V低电平 (is_open=0)
• 门打开 → 行程开关柄释放 → 输出3.3V高电平 (is_open=1)

2.4 硬件框图

2.5 树莓派服务端

三、方案框图和项目设计思路

3.1 系统架构

3.2 设备启动流程

3.3 门状态检测与报警流程

四、原理图和PCB

4.1 原理图展示

4.2 PCB布局展示

4.3 硬件连接原理图

                   ┌───────────┐
                   │           │
    GND  ──────────┤ GND       │
                   │           │
    5V   ──────────┤ 5V        │
                   │           │
                   │  PORT.A   │
    G1   ──────────┤ White     │◄──── Unit Limit #1 (Main Door)
                   │           │
                   │  PORT.B   │
    G8   ──────────┤ White     │◀──── Unit Limit #2 (Back Door)
                   │           │
                   │  PORT.C   │
    G17  ──────────┤ White     │◀──── Unit Limit #3 (Side Door)
                   │           │
                   └───────────┘

本项目用KiCAD设计了专用接口转接板（PCB），用于连接 CoreS3 主控与多路 Unit Limit 行程开关。转接板将 CoreS3 三个 Grove 端口的 GPIO 信号通过自定义 PCB 走线分别引出至各路行程开关的数字输入引脚，实现了稳定的并行信号采集。

PORT.A 连接 (Main Door)：

PORT.B 连接 (Back Door)：

PORT.C 连接 (Side Door)：

4.4 GPIO分配

    │
    ├── G1: Unit Limit #1 (Main Door) - 数字输入
    │
    ├── G8: Unit Limit #2 (Back Door) - 数字输入
    │
    └── G17: Unit Limit #3 (Side Door) - 数字输入

4.5 树莓派服务端架构

    │
    ├── Mosquitto MQTT Broker (端口1883)
    │   订阅主题: fastbond4/+/+
    │
    ├── rpi_mqtt_data_service.py (Python守护进程)
    │   功能: 订阅MQTT消息、门事件存储、报警记录
    │
    ├── rpi_web_server.py (Flask Web服务器)
    │   功能: 门状态可视化面板、REST API、模拟数据模式
    │   端口: 5000
    │
    └── SQLite数据库 (door_alarm.db)
         ├── door_events: 门事件记录表
         ├── alarm_log: 报警日志表
         ├── door_status: 门当前状态表
         └── project_registry: 项目注册表

4.6 设计过程

五、软件流程和关键代码介绍

5.1 主程序结构 (CoreS3 firmware - main.py)

"""
CoreS3 V1.1 - 防盗门报警系统(多门监测+树莓派Web状态显示)

功能特性:
  1. 使用Grove端口连接多个Unit Limit行程开关
  2. 实时监测多个防盗门开关状态
  3. 门状态变化触发声音报警
  4. 2.0寸触摸屏多门状态可视化显示
  5. 通过MQTT上报门状态到树莓派服务端
"""

5.2 门状态检测模块

class DoorMonitor:
    """单门监测器，负责读取行程开关状态并去抖动"""

    def __init__(self, pin_num, door_name, door_id):
        self.pin = Pin(pin_num, Pin.IN)  # 初始化GPIO为数字输入
        self.name = door_name
        self.door_id = door_id
        self.current_state = 0
        self.last_stable_state = 0
        self.last_change_time = 0
        self.is_open = False
        self.last_mqtt_time = 0
        self.read_pin()

    def read_pin(self):
        """读取GPIO引脚电平"""
        try:
            return self.pin.value()
        except Exception:
            return 0

    def update(self, current_time):
        """
        更新门状态，使用去抖动算法
        
        Args:
            current_time: 当前时间戳(ms)
            
        Returns:
            bool: 状态是否发生变化
        """
        raw_value = self.read_pin()
        if raw_value != self.current_state:
            # 电平变化，记录变化时间
            self.current_state = raw_value
            self.last_change_time = current_time
        elif current_time - self.last_change_time >= DOOR_DEBOUNCE_MS:
            # 电平稳定超过去抖动时间，确认新状态
            if raw_value != self.last_stable_state:
                self.last_stable_state = raw_value
                self.is_open = (raw_value == 1)  # 1=高电平=门打开
                return True
        return False

5.3 报警管理系统

class DoorAlarmSystem:
    """防盗门报警系统主控类"""

    def __init__(self):
        self.doors = []
        self.mqtt = None
        self.mqtt_connected = False
        self.alarm_active = False
        self.last_alarm_time = 0

    def add_door(self, pin_num, door_name, door_id):
        """添加一个受监测的门"""
        door = DoorMonitor(pin_num, door_name, door_id)
        self.doors.append(door)
        return door

    def trigger_alarm(self):
        """触发报警"""
        self.alarm_active = True
        self.last_alarm_time = time.ticks_ms()

    def update_doors(self):
        """轮询所有门状态"""
        current_time = time.ticks_ms()
        for door in self.doors:
            if door.update(current_time):
                if door.is_open:
                    self.trigger_alarm()  # 门打开触发报警
                self.report_door_status(door, current_time)
            else:
                self.report_door_status(door, current_time)

5.4 MQTT数据上报

def report_door_status(self, door, current_time):
    """
    通过MQTT上报门状态到树莓派
    
    限制上报频率，每5秒上报一次当前状态
    门状态变化时立即上报
    """
    if current_time - door.last_mqtt_time < MQTT_REPORT_INTERVAL_MS:
        return
    door.last_mqtt_time = current_time
    if self.mqtt_connected and self.mqtt:
        self.mqtt.publish("door", {
            "door_id": door.door_id,
            "door_name": door.name,
            "is_open": 1 if door.is_open else 0,
            "timestamp": current_time
        })

5.5 屏幕显示

def display_status(self):
    """在CoreS3 2.0寸屏幕上显示所有门状态"""
    Widgets.fillScreen(0x000000)

    # 标题栏 - 有门打开时显示红色
    header = "=== DOOR ALARM ==="
    color = 0xFF0000 if self.get_open_count() > 0 else 0x00FF00
    Widgets.Label(header, 10, 5, 1.0, color, 0x000000, Widgets.FONTS.DejaVu12)

    # 报警闪烁条
    if self.alarm_active:
        Lcd.fillRect(0, 22, 320, 20, 0xFF0000)
        Widgets.Label("!!! ALARM TRIGGERED !!!",
                      20, 24, 1.0, 0xFFFFFF, 0x000000, Widgets.FONTS.DejaVu12)

    # 每个门的状态卡片
    for i, door in enumerate(self.doors):
        y = 50 + i * 50
        status_color = 0xFF0000 if door.is_open else 0x00FF00
        bg_color = 0x002000 if not door.is_open else 0x200000
        Lcd.fillRect(10, y, 300, 40, bg_color)
        Widgets.Label(door.name, 15, y + 2, 1.0, 0xFFFFFF, ...)
        Lcd.fillRect(200, y + 8, 90, 25, status_color)
        Widgets.Label("OPEN" if door.is_open else "CLOSED",
                      205, y + 12, 1.0, 0xFFFFFF, ...)

5.6 树莓派Web面板 (rpi_web_server.py)

# Flask Web应用，显示防盗门状态仪表盘
# 支持两种模式：
#   1. 真实模式: 连接MQTT Broker接收实时数据
#   2. 模拟模式: 内置随机数据生成器，方便演示

@app.route("/")
def index():
    """主页面，显示门状态仪表盘"""
    # 统计信息
    total_alarms = sum(s.get("alarm_count", 0) for s in door_statuses.values())
    open_doors = sum(1 for s in door_statuses.values() if s.get("is_open", 0))

    return render_template_string(HTML_TEMPLATE,
        doors=door_list,
        total_doors=3,
        open_count=open_doors,
        alarm_count=total_alarms,
        history=door_history[:20],
        ...)

5.7 树莓派数据存储服务

def store_door_event(project_id, door_id, door_name, is_open, raw_payload):
    """
    存储门事件到SQLite数据库
    
    当门打开时自动记录报警日志
    同时更新 door_status 表保持最新状态
    """
    conn = sqlite3.connect(DB_PATH)
    cursor = conn.cursor()
    now_str = datetime.now().strftime("%Y-%m-%d %H:%M:%S")

    # 记录门事件
    cursor.execute(
        "INSERT INTO door_events (...) VALUES (?, ?, ?, ?, ?, ?)",
        (now_str, project_id, door_id, door_name, is_open, raw_payload)
    )

    # 门打开时记录报警
    if is_open == 1:
        cursor.execute(
            "INSERT INTO alarm_log (...) VALUES (?, ?, ?, ?, ?, ?)",
            (now_str, project_id, door_id, door_name, "DOOR_OPEN", raw_payload)
        )

    # 更新门当前状态
    update_door_status(project_id, door_id, door_name, is_open, now_str)
    conn.commit()
    conn.close()

六、演示

6.1 实物图

6.2 Web状态显示面板

启动服务器后访问 http://localhost:5000 可查看防盗门监控仪表盘：

6.3 数据运行

> python rpi_web_server.py --simulate

==================================================
  FastBond4 防盗门报警Web状态显示
==================================================
  模式: 模拟数据
  Web: http://0.0.0.0:5000
==================================================
[Simulate] Main Door CLOSED
[Simulate] ALARM: Back Door OPEN
[Simulate] Side Door CLOSED
[Simulate] Main Door CLOSED
[Simulate] Back Door CLOSED
[Simulate] ALARM: Side Door OPEN
[Simulate] Main Door CLOSED

6.4 树莓派数据服务运行

> python rpi_mqtt_data_service.py --broker localhost

==================================================
  FastBond4 MQTT防盗门报警数据存储服务
  Broker: localhost:1883
  数据库: /opt/rpi-door-alarm/door_alarm.db
  主题: fastbond4/+/+
==================================================
[MQTT] 已连接到服务器
[MQTT] 已订阅主题: fastbond4/+/+
[Door] Main Door (door_main) - CLOSED
[Door] Back Door (door_back) - OPEN
[Door] Side Door (door_side) - CLOSED

七、设计中遇到的难题和解决方法

7.1 行程开关信号抖动

问题描述：Unit Limit行程开关在机械接触瞬间会产生信号抖动，导致门状态误判。

解决方案：

1. 实现软件去抖动算法
2. 设置100ms去抖动窗口
3. 确认电平稳定后再更新门状态

# 去抖动算法
if raw_value != self.current_state:
    self.current_state = raw_value
    self.last_change_time = current_time
elif current_time - self.last_change_time >= DOOR_DEBOUNCE_MS:
    if raw_value != self.last_stable_state:
        self.last_stable_state = raw_value
        self.is_open = (raw_value == 1)
        return True

7.2 多门同时报警处理

问题描述：多个门同时打开时，报警信息和屏幕显示需要优先处理。

解决方案：

1. 每个门独立监测，互不干扰
2. 报警标志位独立管理
3. 屏幕显示所有门状态，报警门高亮红色

# 多门独立处理
def update_doors(self):
    current_time = time.ticks_ms()
    for door in self.doors:
        if door.update(current_time):
            if door.is_open:
                self.trigger_alarm()

7.3 MQTT上报频率控制

问题描述：频繁上报门状态可能导致MQTT消息拥堵和网络负载。

解决方案：

1. 限制周期性上报频率（每5秒）
2. 门状态变化时立即上报
3. 状态不变时不重复上报

# 上报频率控制
if current_time - door.last_mqtt_time < MQTT_REPORT_INTERVAL_MS:
    return

7.4 CoreS3 GPIO多路复用

问题描述：CoreS3的Grove端口数量和功能有限，需要合理分配。

解决方案：

1. 使用PORT.A (G1)、PORT.B (G8)、PORT.C (G17)三路独立GPIO
2. 每路连接一个Unit Limit
3. 根据端口物理位置分配门名称

# GPIO端口分配
self.add_door(1, "Main Door", "door_main")   # PORT.A
self.add_door(8, "Back Door", "door_back")     # PORT.B
self.add_door(17, "Side Door", "door_side")    # PORT.C

7.5 报警蜂鸣器控制

问题描述：门打开时需要发出声音报警，但不能持续鸣叫影响用户体验。

解决方案：

1. 基于时间控制的报警闪烁
2. 报警持续500ms后自动停止
3. 门关闭后报警自动解除

# 报警控制
def trigger_alarm(self):
    self.alarm_active = True
    self.last_alarm_time = time.ticks_ms()

def update_alarm(self, current_time):
    if self.alarm_active:
        if current_time - self.last_alarm_time >= ALARM_BEEP_MS:
            self.alarm_active = False

7.6 Web面板实时刷新

问题描述：Web面板需要实时显示门状态变化，手动刷新体验差。

解决方案：

1. 前端JavaScript自动刷新（5秒间隔）
2. 深色主题设计，报警醒目
3. 状态卡片颜色变化即时反馈

function refreshPage() {
    location.reload();
}
setInterval(refreshPage, 5000);

八、心得体会

8.1 项目收获

1. GPIO编程：深入理解了ESP32-S3的GPIO输入处理和信号去抖动技术
2. 机械传感器：掌握了行程开关的工作原理和实际应用
3. 多任务处理：实现了多门同时监测的并发处理架构
4. MQTT通信：熟练运用MQTT协议进行设备到服务端的数据传输
5. Web可视化：使用Flask构建了专业的门状态监控仪表盘
6. 系统集成：完成了从硬件检测到Web远程监控的完整系统闭环

8.2 技术亮点

1. 去抖动算法：基于时间窗口的软件去抖动，确保状态检测准确
2. 多门并行监测：独立DoorMonitor实例，互不干扰并发处理
3. 报警优先级：门打开时立即触发报警，关闭时自动解除
4. MQTT频率控制：周期性上报+事件触发上报相结合
5. 深色主题Web：专业的暗色风格仪表盘，报警红色醒目
6. 双模式支持：Web服务器支持真实MQTT和模拟数据两种模式
7. SQLite持久化：门事件和报警日志持久化存储，支持历史查询
8. 一键部署：部署脚本自动完成树莓派服务端安装配置

8.3 改进建议

1. 短信/邮件通知：门打开时通过MQTT触发短信或邮件报警通知
2. 摄像头联动：门打开时自动触发摄像头拍照，留存现场证据
3. 低功耗模式：CoreS3实现深度睡眠，门打开时中断唤醒
4. 无线扩展：使用ESP-NOW扩展更多无线门磁传感器
5. 电子地图：Web面板增加建筑平面图，直观显示门位置
6. 语音报警：CoreS3扬声器播放语音提示（如"大门已打开"）
7. 访问控制：Web面板添加登录认证，防止未授权访问
8. 历史图表：增加门开关频率统计图表，分析使用模式

创意方向关联

本项目的技术创新为以下创意方向提供了新的思路：

1. 楼宇自动化

防盗门报警系统是楼宇自动化的核心安全组件：

• 智能门禁管理：行程开关检测技术可扩展为完整的门禁监控系统
• 安防联动：门状态可联动照明、空调、CCTV等设备
• 能源管理：检测门窗状态联动HVAC系统，实现节能

2. 人工智能在嵌入式系统中的应用

• 异常行为检测：通过门开关频率模式分析，AI识别异常行为
• 故障预测：分析行程开关响应时间变化，预测设备寿命
• 智能预警：结合历史数据建立门使用模型，智能识别入侵

3. 无线 / 5G / WiFi-7

• MQTT物联网：项目使用的MQTT协议可迁移到5G物联网设备
• 多设备协同：WiFi Mesh网络实现多楼层多设备联动
• 远程监控升级：5G/WiFi-7高带宽实现多路实时视频联动

技术迁移价值

本项目开发的技术方案可迁移到：

• 楼宇自动化：门窗监控、安防联动、能源管理
• 人工智能应用：异常行为检测、智能预警
• 无线通信：MQTT物联网、远程监控系统

致谢

感谢 DigiKey 和 电子森林 提供的FastBond4活动支持，本次活动链接：https://www.eetree.cn/page/digikey-fastbond