ctGateway开发指南
2025.4.25 版本1
目录
1 概述
项目的GIT库下包括网关程序、网关管理工具和文档三个目录。
网关管理工具是C#项目，windows程序，目前仅作为辅助工具使用。
网关程序位于ctGateway目录（与项目同名）。
网关程序运行在linux系统上，支持x86-64、Arm、Arm64。
2 准备工作
网关程序在linux上编译运行，建议使用Ubuntu18.04，可以在Ubuntu官网下载ubuntu-18.04.6-live-server-amd64.iso。
Visual Studio 项目仅用来编辑源代码，需要使用VS 2022，社区版即可。
依赖如下几个第三方库（需要下载源码编译）：
|
名称 |
版本 |
|
openssl |
1.1.1k |
|
zlib |
1.2.11 |
|
mosquitto |
2.0.18 |
|
libmodbus-rtu-over-tcp |
版本不明确，取最新版 |
可以在编译网关程序遇到问题时再根据需要安装第三方库和依赖的工具软件。
3 安装依赖的工具和第三方库
3.1 Make
最小化的ubuntu安装没有编译工具，需要安装。
sudo apt install make
3.2 g++
安装g++编译器，需要支持C++11的版本（当然一般都是支持的）。
sudo apt install build-essential （g++，这个应该包含了make）
3.3 zlib
sudo apt install zlib1g-dev （解决-lz需要）
3.4 unzip
sudo apt install unzip （安装libmodbus_rtu_over_tcp-master.zip需要）
3.5 libssl(OpenSSL)
sudo apt install libssl-dev （默认没有安装头文件和库）
3.6 mosquitto(MQTT)
tar -zxvf mosquitto-2.0.18.tar.gz
cd mosquitto-2.0.18
修改config.mk WITH_CJSON:=no
make
sudo make install
3.7 gdb
gdb调试工具，开发经常用到，不是必须的。
sudo apt install gdb
3.8 libmodbus_rtu_over_tcp
这是libmodbus的一个衍生版，支持rtu over tcp。
unzip libmodbus_rtu_over_tcp-master.zip
cd libmodbus_rtu_over_tcp-master
chmod 755 *.sh
./autogen.sh
如果没有安装autoconif则 sudo apt-get install autoconf libtool 再重新./autogen.sh
./configure
make install
4 编译
环境可能需要预先设置一下，比如启用coredump文件、环境变量增加当前目录、设置LD_LIBRARY_PATH，大概类似如下代码：
ulimit -c unlimited
export PATH=.:$PATH
export LD_LIBRARY_PATH=/usr/local/lib/:$LD_LIBRARY_PATH
可以放在.profile，也可以每次登录后手工执行一遍。
源代码ctGateway目录下的gageway、lib和third三个目录上传至用户主目录下的my目录（当然你可以选择别的目录，不过下面的代码需要相应修改）：
cd
cd my/third/ctfc/platform
make -f makefile.mk linux debug
cd ../src
chmod 755 *.sh
makeall.sh
cd ../../../gateway
chmod 755 *.sh
makeall.sh
如果编译成功，最后的输出如下：
date;date;g++ -g -L../../lib/ -o gwmain.exe gwmain_t.o -Wl,-E -L../../third/ctfc/lib/ -lgwmain -lgwbuiltin -lmodbus -lmyhttpd -lenv -lmosquittopp -lmosquitto -lgmssl -lssl -lcrypto -lz -lpthread -ldl -latomic -lstdc++
Thu Apr 24 21:33:26 CST 2025
Thu Apr 24 21:33:26 CST 2025
date;mv gwmain.exe ../bin
Thu Apr 24 21:33:26 CST 2025
make[1]: Leaving directory '/home/user/my/gateway/gwmain'
--------编译目录 gwmain 完成
gwBuiltIn gwprotocol gwmain
检查结果。。。。。。
Thu Apr 24 21:33:26 CST 2025
total 27356
-rw-rw-r-- 1 user user 9147734 Apr 24 21:33 libgwbuiltin.a
-rw-rw-r-- 1 user user 17686232 Apr 24 21:33 libgwmain.a
-rwxrwxr-x 1 user user 1034128 Apr 24 21:33 libprotocol_demo.so
-rwxrwxr-x 1 user user 118168 Apr 24 21:33 libtestso2.so
-rwxrwxr-x 1 user user 12512 Apr 24 21:33 libtestso.so
-rw-rw-r-- 1 user user 12 Apr 22 22:23 readme.txt
total 8696
-rwxrwxr-x 1 user user 8903944 Apr 24 21:33 gwmain.exe
bin/gwmain.exe: ELF 64-bit LSB shared object, x86-64, version 1 (GNU/Linux), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 3.2.0, BuildID[sha1]=00f6bf8238b570b89db1837e76c4da07c97ba672, with debug_info, not stripped
user@vm-ubuntu:~/my/gateway$
5 运行
复制sn文件，否则无法运行：
cd ;sudo cp my/gateway/home/* /home/
编译成功后进入publish目录运行如下指令：
../bin/gwmain.exe
如果程序能够运行，前几行输出如下：
user@vm-ubuntu:~/my/gateway/publish$ ../bin/gwmain.exe $1 $2 $3 $4 $5 $6 $7 $8 $9
[04-24 22:19:28][main][信息][gwmain_t.cpp : 133(_main)][ 0.00]字节序 Little-Endian
[04-24 22:19:28][main][信息][gwmain_t.cpp : 150(_main)][ 0.00]网关程序版本 1.0.0 2025.04.15 14:39
[04-24 22:19:28][main][信息][gwmain_t.cpp : 152(_main)][ 0.00]工作目录 /home/user/my/gateway/publish
6 交叉编译
本项目在不同的arm32和arm64交叉编译工具链下编译过，原则上没什么特别的，按照常规方法将所有依赖库和程序交叉编译即可。
7 源码结构
7.1 ctGateway
网关程序。
7.1.1 third
第三方依赖库，其中ctfc是git子模块，包含公共基础代码和编译体系。其余目录是依赖的第三方库的头文件，方便编写代码，但是要注意，这些头文件必须和链接的第三方库的版本一致。
7.1.1.1 ctfc
本项目除了使用的ctfc的功能外还使用了ctfc的编译体系。
其编译脚本位于ctfc/platform，核心是config.mk，每个平台的特征由一个单独的.mk文件定义，如linux.mk，另外优化开关由fast.mk和debug.mk定义。
makefile.mk的功能实际上是把平台配置和优化配置复制到platform.mk和optimize.mk。
源码中的arm.mk和arm64.mk是两个特定的交叉编译工具链的配置，除非恰好使用同样的交叉编译工具链，否则没有实际意义。
7.1.2 lib
这个目录是用来输出编译产生的库文件的。
7.1.3 gateway
网关程序的源代码。
7.1.3.1 gwBuiltIn
内置协议，包括Modbus和隧道协议。编译为静态库。
7.1.3.2 gwmain
程序框架，包括核心基础功能、配置、MQTT等。
7.1.3.3 pwprotocol
外挂协议，编译为动态库。有一个演示协议驱动。
7.1.3.4 home
硬件相关的文件，包括型号、序列号、SIM卡信息等，这些由硬件提供，实际可能需要根据硬件修改。源码的这些文件放在合适的位置供虚拟机使用。
7.1.3.5 interface
编写协议驱动所需的接口。
7.1.3.6 publish
运行目录，包含了配置文件和www服务所需的静态文件。其中SSL目录下是MQTTS所需的证书，wwwroot是www服务的虚拟根目录，ca.cer、server.cer、server.key是HTTPS所需的证书。
prefilledkey.txt是国密sm4的预充注密钥（就是编了号的一堆密钥）。
几个json文件是配置文件。
7.2 doc
文档。
7.3 ManageTools
网关管理工具，独立C#项目，只包含配置文件和程序入口点，实质性功能由依赖的nuget包实现。
8 全流程模拟运行
8.1 建立MQTT服务
本项目对MQTT服务没有特别要求，例如可以使用EMQX。
EMQX安装使用非常简单。
https://www.emqx.io/zh/downloads?os=Windows
1
下载 emqx-5.0.14-windows-amd64.tar.gz ，解压
2
命令行下进入解压路径，启动 EMQX
cd c:\emqx
./bin/emqx start
进入bin目录执行也可以
注意控制台可能不从当前目录查找命令文件，必须加.\或./
停止 stop
启动并进入控制台 console
Dashboard（WEB界面）
http://localhost:18083/
默认用户名密码：admin/public（在etc目录下的配置文件里面）
登录后要求修改密码，改为admin123
在最下面一个菜单设置显示语言和颜色，可以设置为中文和亮色
创建用户user/user1234
默认端口1883，要从配置文件修改，要重启电脑才能生效
客户端软件
MQTTX-Setup-1.8.0-x64.exe
8.2 以测试模式运行网关程序
以测试模式运行网关程序需要增加“-test”参数，从而启动内置的modbus-TCP服务。默认设置包含对内置modbus-TCP服务的访问。
cd ; cd my/gateway/publish
../bin/gwmain.exe -test
如果程序成功运行，输出信息的最初几行如下：
user@vm-ubuntu:~/my/gateway/publish$ ../bin/gwmain.exe -test
[04-25 14:15:16][main][信息][gwmain_t.cpp : 133(_main)][ 0.00]字节序 Little-Endian
[04-25 14:15:16][main][信息][gwmain_t.cpp : 150(_main)][ 0.00]网关程序版本 1.0.0 2025.04.15 14:39
[04-25 14:15:16][main][信息][gwmain_t.cpp : 152(_main)][ 0.00]工作目录 /home/user/my/gateway/publish
[04-25 14:15:16][TEST SERVER][信息][gwmain_test.cpp : 289(gwmain_test)][ 0.00]主进程 2229 服务进程 2230
[04-25 14:15:21][main][信息][gwmain_test.cpp : 352(gwmain_test)][ 0.00]服务进程已创建
多了一个服务进程。
8.3 修改配置文件
默认的北向配置文件defaultNorthConfig.json如下：
{
"func": "connt",
"data": {
"comment": "本机测试",
"type": "MQTTS",
"platform": "localtest",
"hostname": "mqtt.test.com",
"port": "8883",
"userid": "user",
"upwd": "user1234",
"ntp": "time.windows.com"
}
}
配置项的含义都很简单明了，需要把MQTT的主机名、端口、用户名、密码都设置正确。“type”为连接平台的方式，可选值为“MQTT”或“MQTTS”。“platform”为平台的名称，对应SSL目录下同名子目录，如果使用MQTTS，需要替换掉这个目录下的证书文件。
配置正确后应该能从MQTT服务器的管理工具上看到客户端连接，使用MQTT客户端能观察到网关程序发送的数据。
不要直接修改defaultNorthConfig.json，复制为northConfig.json来修改。程序首先查找northConfig.json，找不到才会使用defaultNorthConfig.json。
8.4 MQTT topic规则
|
device_gateway/reg |
注册信息，网关启动时发送reg给平台 |
|
device_gateway/网关序列号/server |
平台发送给网关 |
|
device_gateway/网关序列号/client |
网关发送给平台 |
网关启动时额外发送reg给“device_gateway/reg”供平台发现未知的网关。注册信息也同时发送到“device_gateway/网关序列号/server”，因此如果不关注未知网关可以不订阅“device_gateway/reg”的消息。
9 使用网关管理工具ManageTools
9.1 编译和配置
网关管理工具ManageTools是C# winforms程序，用VS2022打开ManageTools.sln，下载完依赖项后即可编译运行。
项目很简单，主要是配置文件：
northConfig.json和网关程序的配置文件完全一样（但没有默认配置文件）。
snList.txt包含已知的网关序列号，格式为“序列号 name:显示名称”。已经预设了开发用的网关序列号（网关上序列号来自home/sn.txt）。
9.2 启动
程序启动界面如下：
支持多个配置，配置文件复制几个“data”，改为任何别的名字，网关管理工具自动检索所有配置。
9.3 主界面
选择配置进入之后是这样：
左边是网关列表，右边是网关的MQTT消息，包括了上下行消息，自动滚动。
9.4 网关详情
在主界面双击左边列表的一个网关可以打开一个网关的详情窗口：
大部分按钮直接对应交互协议的一种消息。这个界面只能对一个网关操作，主界面的按钮则是对选中的所有网关操作。
左边是每条消息的基本情况，右边是消息内容。
9.5 文件同步
“FileSync”类似FTP，能查看网关上的文件的状态，能双向传输文件：
9.6 查看网关程序内部信息
按钮“Show”会发送“show”指令给网关，网关会返回程序内部状态：
包含内部配置和解析配置时的一些重要信息（可以用来发现配置问题）。
10 源码指引
10.1 编译ctfc
Ctfc的编译可以参考ctfc目录下的make.sh：
cd platform
make -f makefile.mk linux debug
cd ..
cd src
chmod 755 *.sh
makeall.sh
实际上就是先去platform目录设置编译参数，然后去strc目录执行makeall.sh。
makeall.sh主要的功能是编译每个目录，而每个目录的编译方法是把makefile.mk复制为makefile然后make。
所以其实这个编译体系就是原生make，通过sh实现了一点自动化。
10.2 编译gateway
gateway调用ctfc的编译体系，编译入口同样是makeall.sh。
10.3 源码入口点
gateway的入口点在gwmain目录下的gwmain_t.cpp的main函数。