简介一份面向智能家居与物联网开发者的C家庭自动化系统源码包用于集中监控和配置灯光、开关及温湿度、风雨、紫外线、电/气/水等传感器仪表并支持向移动设备推送通知与警报。代码基于C实现整合了OpenZWave、EnOcean、MQTT自动发现、WebServer等模块兼顾本地控制与远程访问适合计算机、自动化、电子信息等专业学生用于课程设计、毕业设计或项目初期演示。资源包共2000个文件压缩后约14.19MB其中包含387个h头文件、270个cpp源文件及849个xml配置文件构成后端核心搭配192个js、86个html、49个css前端文件与Lua、Python辅助脚本可清晰梳理Web控制面板与设备通信链路目录结构便于按模块检索。内含README及文档说明下载后可按注释理解整体架构。目前已有39人学习使用适合具备一定C基础、希望学习家庭自动化系统设计思路或进行二次开发的读者。1. 一个能同时管EnOcean和Z-Wave的C网关内部长什么样做智能家居集成的人迟早会遇到一个坎不同厂家的设备用的是不同无线协议有的走Z-Wave有的走EnOcean还有一堆支持MQTT的Wi-Fi设备。大多数开源网关要么只支持一种协议要么用Python或Node.js写做大了性能撑不住。最近拆了一个C写的家庭自动化系统源码它把EnOcean和Z-Wave两类RF协议统一到一个mainworker调度进程里同时开着WebServer和MQTT桥接。编译出来是一个常驻服务能监控灯、开关、温度、风速、电力等设备也能把告警通知推到移动设备。这套源码的cpp文件职责分得比较清楚适合想研究协议接入、C服务端架构以及准备课程设计的人慢慢拆。以下内容我会按模块划分、数据流、实际操作、MQTT集成四个方向逐个展开。2. 拆文件mainworker、SQLHelper、WebServer的职责边界拿到源码包先别急着编译。我把根目录文件列了一遍结论是每个文件名都在说一个模块mainworker.cpp负责主调度SQLHelper.cpp管数据库EnOceanESP3和OpenZWave是两个协议适配器剩下的WebServer开头的三个文件处理HTTP访问。一个长期运行的网关守护进程至少要有三件事接收数据、存数据、被人问数据。这个项目里mainworker管接收SQLHelper管存WebServer那组文件管被人问。2.1 从文件名推断模块归属下面这张表对照了每个文件和它在系统里的位置重点是文件间的依赖方向。文件角色说明mainworker.cpp主调度初始化各子系统循环派发设备事件SQLHelper.cpp持久层把设备状态、历史记录写入SQLiteEnOceanESP3.cpp协议接入解析EnOcean ESP3电报帧OpenZWave.cpp协议接入通过OpenZWave库管理Z-Wave节点WebServer.cppHTTP服务监听端口解析请求并路由WebServerCmds.cpp命令处理处理/control、/status这类具体命令WebServerHandleGraph.cpp图表数据按时间范围聚合设备历史数据MQTTAutoDiscover.cppMQTT集成发布自动发现消息接入外部平台提示get_translations.bat是Windows下的批处理脚本用来拉取翻译资源和核心逻辑无关。我一般直接忽略它专注于上面这些源文件。这个模块划分的好处是每一层都有明确的依赖方向协议层不感知数据库mainworker不直接写HTTPWebServer也不碰串口。如果你要把这套代码改成课程设计优先替换的就是EnOceanESP3和OpenZWave这两个文件其他部分几乎不用动。2.2 协议网关EnOceanESP3与OpenZWave的选型逻辑EnOcean和Z-Wave是两套完全不同的无线体系。EnOcean主打能量采集很多传感器不需要电池靠微压或太阳能供电适合门磁、温湿度这类低功耗上报场景。Z-Wave则是有供电的mesh网络节点间可中继适合灯、插坐这类需要双向控制的设备。两者都以网关为中心但数据帧格式差异很大。EnOcean ESP3是串口帧协议一帧中包含同步头、数据长度、CRC8校验传感器数据则进一步根据EEP编码解析。EnOceanESP3.cpp做的事情就是监听串口byte流拼帧校验然后提取传感器值。OpenZWave是成熟的开源C库里面封装了Z-Wave的网络安全层和命令类。OpenZWave.cpp更像一个事件转发器把库回调里的节点状态转成统一的设备模型再抛给mainworker。在实际项目中我见过不少新手把OpenZWave的回调做成紧耦合的全局函数改设备一多就会出问题而这个文件的边界处理得不错。2.3 配置与数据库config和SQLHelper的配合config文件是启动时的设备说明书虽然没有扩展名但本质上是INI分节格式。它告诉mainworker有哪些设备、走什么协议、报警阈值在哪。比如下面这样[serial] enOcean_port /dev/ttyUSB0 enOcean_baud 57600 zwave_port /dev/ttyUSB1 [device:living_light] type switch protocol zwave node_id 5 name Living Room Light [device:garden_temp] type temperature protocol enocean eep A5-02-01 name Garden TemperatureenOcean_baud要特别注意ESP3串口默认是57600不是115200。node_id是Z-Wave网络里的短地址必须在控制器上先入网。eep是EnOcean Equipment Profile编码A5-02-01代表温度传感器。每个[device:xxx]段定义一个逻辑设备mainworker启动时统一注册进设备表。SQLHelper.cpp负责把设备状态写入SQLite。数据库不是自动建好的通常第一次运行时会执行类似下面的建表语句CREATE TABLE IF NOT EXISTS devices ( device_id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT UNIQUE, protocol TEXT, node_id INTEGER, last_update TEXT ); CREATE TABLE IF NOT EXISTS readings ( reading_id INTEGER PRIMARY KEY AUTOINCREMENT, device_id INTEGER, ts TEXT, val REAL, FOREIGN KEY(device_id) REFERENCES devices(device_id) );devices表存设备的元信息readings表存时间序列读数。高频写入时SQLite最容易卡在文件锁上我一般会在连接后加上PRAGMA synchronousNORMAL再把journal_mode设为WAL一次写入的IO成本会明显下降。这一步对后面跑历史曲线很有帮助否则设备一多写入和查询互相争锁WebServer的请求就会超时。3. 设备数据流从无线波到HTML曲线的中间环节模块拆完了但真正决定这套系统能不能扛住几十个设备并发上报的是mainworker里的数据流组织。这里的数据流分为三段协议线程收到原始信号封装成事件丢进队列工作线程从队列取事件写库并更新状态WebServer线程从数据库中聚合数据返回给前端。3.1 mainworker的线程模型与回调mainworker没有在串口回调里直接写数据库。串口I/O一旦阻塞整个网关都会丢帧。常见做法是多线程解耦串口读线程负责read和解析完成后构造一个事件对象投递到线程安全队列另一个工作线程消费这个队列再做数据库写入和MQTT发布。核心代码模型如下struct DeviceEvent { int device_id; double value; std::string dt; }; void mainworker::onProtocolData(int device_id, double value) { DeviceEvent ev{device_id, value, iso_timestamp_now()}; event_queue.push(ev); // 非阻塞入队 } void mainworker::processLoop() { for (;;) { DeviceEvent ev; if (event_queue.pop(ev)) { sqlHelper-writeReading(ev); // 写入历史 std::string json buildStatusJson(ev); // 构建状态JSON mqttAutoDiscover-publishDeviceState(ev, json); } std::this_thread::sleep_for(std::chrono::milliseconds(2)); } }event_queue是生产者和消费者之间的缓冲区目的是不让慢速的磁盘I/O拖累高速的串口收包。iso_timestamp_now()生成UTC时间字符串格式统一为YYYY-MM-DDTHH:MM:SSZ所有模块共用避免时区混乱。buildStatusJson只把设备ID和值拼成JSON供MQTT和WebServer复用。这个模型的线程分布大致是这样的线程角色数量处理内容serial reader每串口1个阻塞读串口拼帧后投递队列event worker1~2个消费队列写数据库并发布MQTThttp server1个监听端口解析HTTP请求并路由这里容易踩的坑是在onProtocolData里直接调用sqlHelper-writeReading。虽然SQLite库本身线程安全但多个协议线程同时写同一个连接时会排队锁库串口线程最终被I/O拖住。事件队列缓冲是这套系统最实用的设计之一。3.2 SQLHelper把瞬时值变成历史曲线历史曲线不是直接查询readings全表就能完成的。表里的数据会持续增长所以WebServerHandleGraph.cpp在响应/graph请求时通常会做时间分桶聚合。下面代码模拟了它的核心查询void WebServerHandleGraph::handle(const HttpRequest req) { int device_id parseDeviceId(req.query_string); std::string range req.query_value(range, hour); std::string sql SELECT ts, avg(val), max(val), min(val) FROM readings WHERE device_id? AND tsdatetime(now,? ) GROUP BY strftime(%Y-%m-%d %H:%M, ts); PreparedQuery q sqlHelper-prepare(sql); q.bindInt(device_id); q.bindText(rangeOffset(range)); // hour - -1 hour, day - -1 day auto rows q.execute(); // 压缩成JSON数组返回 }GROUP BY strftime(%Y-%m-%d %H:%M, ts)是SQLite里比较实用的降采样写法会把同一分钟内的多个读数聚合成一条。和avg, max, min三值组合在一起前端既能画均值线也能展示波动区间。注意rangeOffset映射必须用白名单例如hour映射到-1 hourday映射到-1 day绝不能把用户参数直接拼进SQL字符串否则会变成注入点。3.3 WebServerCmds与WebServerHandleGraph的请求处理链WebServer.cpp只负责TCP监听和HTTP解析拿到URL路径后转发给WebServerCmds。命令处理函数每条都很短典型的控制命令如下void WebServerCmds::handleControl(const HttpRequest req, HttpResponse res) { int device_id parseDeviceId(req.query_string); int new_state req.query_int(on); bool ok mainworker-setDeviceState(device_id, new_state); res.sendJson({\ok\: std::string(ok ? true : false) }); }setDeviceState会根据设备的协议类型转成对应的Z-Wave命令类或EnOcean发送帧再由协议模块从串口发出去。对WebServer来说控灯和控制插座没有区别只是device_id不同。把协议细节收敛在mainworker里HTTP接口就异常干净。到这里从无线模块到HTTP响应的数据路径已经完整。下一章实际跑一下先用虚拟设备验证链路。4. 在无硬件环境下跑通虚拟传感器与curl指令控制很多人在课程设计或演示阶段没有真EnOcean模块也没有Z-Wave网关。这套系统好在协议层是独立文件只要实现一个虚拟协议驱动在普通PC上就能完整跑通业务逻辑。下面从编译环境讲起到用curl控制逐步操作。4.1 准备编译环境从vscode配置c/c环境到生成可执行文件项目是多文件C工程不用CMake时可以直接用g编译。在Linux或MinGW终端下命令大概是g -stdc17 -O2 mainworker.cpp SQLHelper.cpp EnOceanESP3.cpp \ OpenZWave.cpp WebServer.cpp WebServerCmds.cpp MQTTAutoDiscover.cpp \ WebServerHandleGraph.cpp -o domoticgw -lsqlite3 -lcurl -lpthread-stdc17是因为代码里用到了std::optional和std::string_view低于17会报语法错误。-lpthread是PHP与多线程的依赖库。-lsqlite3需要提前装开发版Windows下用vcpkg安装比较省事。如果只是先跑逻辑可以临时把OpenZWave.cpp里#include openzwave/...头文件去掉用空函数占位。在VSCode里配置的话tasks.json里的command指向gargs里必须写清-I依赖路径。例如vcpkg安装的头文件通常位于C:/vcpkg/installed/x64-windows/include。只装C/C扩展不装依赖库编译一样过不了这是新手最常见的坎。4.2 修改config添加虚拟设备没有无线模块时我用一个virtual_protocol来模拟设备。它定时读取本地文件作为数据源每行格式为device_id,value然后调用协议层提交事件的入口。config里这样写[device:fake_temp] type temperature protocol virtual virtual_source /tmp/fake_temp.csv name Fake Temperaturevirtual_source指向一个CSV文件mainworker每秒读一次。这样做的目的是绕过无线硬件但后续的数据入库、MQTT发布、HTTP查询全部走真实链路验证价值很大。4.3 用curl调用WebServer命令控制设备编译成功并启动./domoticgw -c config后用curl直接调接口curl -s http://127.0.0.1:8080/control?device5on1 curl -s http://127.0.0.1:8080/status?device5 curl -s http://127.0.0.1:8080/graph?device5rangehour第一个命令把device 5的灯打开第二个查询实时状态第三个拉最近一小时的历史聚合点。这里参数含义如下参数示例值含义device5设备ID对应config里[device:xxx]的注册序号on0/1开关量1开0关不传则返回当前状态rangehour/daygraph接口的时间范围hour表示最近1小时如果返回不是合法JSON先看mainworker日志有没有设备注册失败。常见错误是config里node_id和数据库主键冲突直接把数据目录下的.db文件删掉重启就能解决。连续请求两次/status如果last_update时间戳在变化说明整条数据流是通的。5. 用MQTT自动发现把设备交给Home Assistant以及掉线排查技巧5.1 MQTTAutoDiscover的retained消息格式MQTTAutoDiscover.cpp的核心不是简单转发设备状态而是发布符合Home Assistant自动发现协议的配置消息。HA要求主题格式为homeassistant/{component}/{object_id}/configpayload是一个带name、state_topic、command_topic等字段的JSON。系统会为每个设备生成类似下面的消息{ name: Living Room Light, state_topic: domoticz/temp_status/5, command_topic: domoticz/set/5, payload_on: ON, payload_off: OFF, retain: true }state_topic是设备状态发布主题设备每次变化都会往这里推数据。command_topic是接受外部命令的主题HA控灯时往这里发ON/OFF。retained消息的作用是让HA重启后订阅时立刻拿到配置不必等下一次设备上报。5.2 用mosquitto_sub验证发现消息没有HA时用mosquitto_sub直接监听homeassistant/#主题就能确认消息是否正确发布mosquitto_sub -h localhost -t homeassistant/# -v如果一条都看不到先查MQTTAutoDiscover.cpp里的broker地址是不是localhost:1883再确认MQTT Broker允许匿名登录。常见坑是broker开了账号密码代码里没配用户名导致publish被拒。另外要注意清理旧的retained消息否则改完配置后HA仍会读到旧缓存mosquitto_pub -t homeassistant/switch/5/config -n -r-n表示空消息-r表示retain这条命令会清掉broker上对应的旧配置。很多排错排了半天最后发现是旧retained消息没清。5.3 设备掉线时的定位方法从日志到SQLite查询设备掉线时不要急着重启服务。我会按三个层次检查先看mainworker日志里有没有断连重连记录再看readings表里设备最后一条时间戳距离当前时间多久最后查数据库里各设备的延迟秒数SELECT device_id, MAX(ts) AS last_ts, (strftime(%s,now) - strftime(%s, MAX(ts))) AS age_sec FROM readings GROUP BY device_id;age_sec超过300秒的设备基本可以判定掉线。EnOcean无电池传感器掉线多半是串口被占用或系统休眠模块踢掉了USB设备Z-Wave设备掉线排除信号问题后需要检查临时路由表是否过期这比盲目重启更有价值。本文还有配套的精品资源点击获取