ctGateway Development Guide
2025.4.25 Release 1
directory
3 Install dependent tools and third-party libraries....
8. Simulation of the whole process
8.2 Run the gateway program in test mode
8.3 Modify the configuration file
9 Use the gateway management tool ManageTools
9.6 View the internal information of the gateway program
1 Overview
The GIT library of the project includes three directories: gateway program, gateway management tools, and documents.
The gateway management tool is a C# project, a windows program, and is currently only used as a secondary tool.
The gateway program is located in the ctGateway directory (with the same name as the project).
The gateway program runs on Linux and supports x86-64, Arm, and Arm64.
2 Preparation
The gateway program is compiled and run on linux, it is recommended to use Ubuntu 18.04, which can be downloaded from the Ubuntu official website ubuntu-18.04.6-live-server-amd64.iso.
Visual Studio projects are only used to edit the source code, and you need to use VS 2022, Community Edition.
Depends on the following third-party libraries (you need to download the source code for compilation):
|
name |
version |
|
openssl |
1.1.1k |
|
zlib |
1.2.11 |
|
mosquitto |
2.0.18 |
|
libmodbus-rtu-over-tcp |
If the version is not clear, take the latest version |
You can install third-party libraries and dependent utilities as needed if you encounter problems with the compilation gateway program.
3 Install dependent tools and third-party libraries
3.1 Make
The minimized ubuntu installation does not have a compilation tool and needs to be installed.
sudo apt install make
3.2 g++
To install the g++ compiler, you need to support C++11 (of course, it is generally supported).
sudo apt install build-essential (g++, this should include make)
3.3 zlib
sudo apt install zlib1g-dev (solve-lz needed)
3.4 unzip
sudo apt install unzip (required for installation libmodbus_rtu_over_tcp-master.zip)
3.5 libssl(OpenSSL)
sudo apt install libssl-dev (headers and libraries are not installed by default)
3.6 mosquitto(MQTT)
tar -zxvf mosquitto-2.0.18.tar.gz
cd mosquitto-2.0.18
Modify config.mk WITH_CJSON:=no
make
sudo make install
3.7 gdb
The gdb debugging tool, which is often used in development, is not required.
sudo apt install gdb
3.8 libmodbus_rtu_over_tcp
This is a derivative of libmodbus that supports rtu over tcp.
unzip libmodbus_rtu_over_tcp-master.zip
cd libmodbus_rtu_over_tcp-master
chmod 755 *.sh
./autogen.sh
If autoconif is not installed, then sudo apt-get install autoconf libtool and re-autogen.sh ./
./configure
make install
4 Compilation
The environment may need to be set up in advance, such as enabling the coredump file, adding the current directory to the environment variables, and setting the LD_LIBRARY_PATH, which is roughly similar to the following code:
ulimit -c unlimited
export PATH=.:$PATH
export LD_LIBRARY_PATH=/usr/local/lib/:$LD_LIBRARY_PATH
This can be done in a .profile, or it can be done manually after each login.
Upload the gageway, lib and third directories in the ctGateway directory of the source code to the my directory in the user's home directory (of course, you can choose other directories, but the following code needs to be modified accordingly):
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
If the compilation is successful, the final output will look like this:
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'
--------The compilation directory gwmain is complete
gwBuiltIn gwprotocol gwmain
Check the results。。。。。。
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 Run
Copy the SN file, otherwise it won't run:
cd ; sudo cp my/gateway/home/* /home/
After the compilation is successful, go to the publish directory and run the following command:
.. /bin/gwmain.exe
If the program is able to run, the first few lines will output as follows:
user@vm-ubuntu:~/my/gateway/publish$ .. /bin/gwmain.exe $1 $2 $3 $4 $5 $6 $7 $8 $9
[04-24 22:19:28 [main] [info] [gwmain_t.cpp : 133(_main)][0.00]endian:Little-Endian
[04-24 22:19:28 [main] [info] [gwmain_t.cpp : 150(_main)][0.00] Gateway version 1.0.0 2025.04.15 14:39
[04-24 22:19:28 [main] [info] [gwmain_t.cpp : 152(_main)][0.00]working directory /home/user/my/gateway/publish
6 Cross-compilation
This project has been compiled under different arm32 and arm64 cross-compilation toolchains, in principle, there is nothing special, just cross-compile all dependent libraries and programs according to the conventional method.
7 Source Code Structure
7.1 ctGateway
Gateway program.
7.1.1 third
Third-party dependency libraries, where CTFC is a Git submodule, contains the common code base and compilation system. The rest of the directories are headers of dependent third-party libraries to facilitate writing code, but be careful that these headers must be of the same version as the linked third-party libraries.
7.1.1.1 ctfc
In addition to the functions of CTFC, this project also uses the compilation system of CTFC.
The compilation script is located in ctfc/platform, the core is the config.mk, the characteristics of each platform are defined by a separate .mk file, such as linux.mk, and the optimization switch is defined by the fast.mk and debug.mk.
The function of makefile.mk is actually to replicate the platform configuration and optimization configuration to the platform.mk and optimize.mk.
The arm.mk and arm64.mk in the source code are configurations of two specific cross-compilation toolchains, and are meaningless unless they happen to use the same cross-compilation toolchain.
7.1.2 lib
This directory is used to output the compiled library files.
7.1.3 gateway
Source code for the gateway program.
7.1.3.1 gwBuiltIn
Built-in protocols, including Modbus and tunneling protocols. Compile to a static library.
7.1.3.2 gwmain
Program framework, including core basic functions, configuration, MQTT, etc.
7.1.3.3 pwprotocol
Plug-in protocol, compiled as a dynamic library. There is a demo protocol driver.
7.1.3.4 home
Hardware-related documents, including model number, serial number, SIM card information, etc., are provided by the hardware and may need to be modified according to the hardware. These files of the source code are placed in a suitable location for use by the virtual machine.
7.1.3.5 interface
Write the interfaces required for protocol drivers.
7.1.3.6 publish
The runtime directory contains the static files required for the configuration file and the www service. The SSL directory is the certificate required for MQTTS, the wwwroot directory is the virtual root directory of the www service, and the ca.cer, server.cer, and server.key are HTTPSRequired Certificates.
prefilledkey.txt is the pre-filled key of the national secret SM4 (that is, a bunch of keys numbered).
Several JSON files are configuration files.
7.2 doc
Documentation.
7.3 ManageTools
Gateway management tool, stand-alone C# project, contains only configuration files and program entry points, and the substantive functionality is implemented by dependent nuget packages.
8. Simulation of the whole process
8.1 Create an MQTT service
There are no special requirements for MQTT services in this project, for example, EMQX can be used.
EMQX is very easy to install and use.
https://www.emqx.io/zh/downloads?os=Windows
1
Download emqx-5.0.14-windows-amd64.tar.gz and unzip it
2
Enter the decompression path from the command line and start EMQX
cd c:\emqx
./bin/emqx start
You can also go to the bin directory to execute it
Note that the console may not look for command files from the current directory and must be appended with .\ or ./
Stop stop
Launch and enter the console console
Dashboard (web interface).
http://localhost:18083/
Default username and password: admin/public (in the configuration file in the etc directory)
After logging in, you will be asked to change your password to admin123
Set the display language and color in the bottom menu, which can be set to Chinese and bright colors
Create user user/user1234
The default port is 1883, which needs to be modified from the configuration file and needs to be restarted to take effect
Client software
MQTTX-Setup-1.8.0-x64.exe
8.2 Run the gateway program in test mode
Running the gateway program in test mode requires the addition of the "-test" parameter to start the built-in modbus-TCP service. The default settings include access to the built-in modbus-TCP service.
cd ; cd my/gateway/publish
.. /bin/gwmain.exe -test
If the program runs successfully, the first few lines of the output message are as follows:
user@vm-ubuntu:~/my/gateway/publish$ .. /bin/gwmain.exe -test
[04-25 14:15:16 [main] [info] [gwmain_t.cpp : 133(_main)][0.00]endian:Little-Endian
[04-25 14:15:16 [main] [info] [gwmain_t.cpp : 150(_main)][0.00] Gateway version 1.0.0 2025.04.15 14:39
[04-25 14:15:16 [main] [info] [gwmain_t.cpp : 152(_main)][0.00]working directory /home/user/my/gateway/publish
[04-25 14:15:16][TEST SERVER][INFORMATION][gwmain_test.cpp : 289(gwmain_test)][0.00] Main Process 2229 Service Process 2230
[04-25 14:15:21 [main] [info] [gwmain_test.cpp : 352(gwmain_test)][0.00] Service process created
One more service process.
8.3 Modify the configuration file
The default northbound configuration file defaultNorthConfig.json as follows:
{
"func": "connt",
"data": {
"comment": "Native Testing,
"type": "MQTTS",
"platform": "localtest",
"hostname": "mqtt.test.com",
"port": "8883",
"userid": "user",
"upwd": "user1234",
"ntp": "time.windows.com"
}
}
The meaning of configuration items is very simple and clear, and you need to set the hostname, port, user name, and password of MQTT correctly. Type indicates the method of connecting to the platform, and the available value is MQTT or MQTTS. "platform" is the name of the platform, which corresponds to the subdirectory with the same name in the SSL directory, if you use MQTTS, you need to replace the certificate file in this directory.
When configured correctly, you should be able to see the client connection from the MQTT server's management tool, and the MQTT client will be able to observe the data sent by the gateway program.
Don't modify the defaultNorthConfig.json directly, copy it as a northConfig.json to modify it. The program first looks for northConfig.json, and will only use defaultNorthConfig.json if it can't find it.
8.4 MQTT topic rules
|
device_gateway/reg |
Registration information, which is sent to the platform when the gateway starts |
|
device_gateway/gateway serial number/server |
The platform sends it to the gateway |
|
device_gateway/gateway serial number/client |
The gateway is sent to the platform |
When the gateway starts, a reg is sent to the "device_gateway/reg" for the platform to discover unknown gateways. The registration information is also sent to "device_gateway/gateway serial number/server", so if you do not follow the unknown gateway, you can not subscribe to the "device_gateway/reg" message.
9 Use the gateway management tool ManageTools
9.1 Compiling and Configuring
ManageTools is a C# winforms program, which can be compiled and run after opening ManageTools.sln with VS2022 and downloading dependencies.
The project is simple, mainly the configuration file:
northConfig.json is exactly the same as the gateway configuration file (but no default configuration file).
snList.txt contains a known gateway serial number in the format "Serial Number Name: Display Name". The serial number of the gateway for development has been preset (the serial number on the gateway is from home/sn.txt).
9.2 Startup
The program startup screen is as follows:
Multiple configurations are supported, the configuration file copies a few "data", changes to any other name, and the gateway management tool automatically retrieves all configurations.
9.3 Main Interface
After selecting the configuration, it looks like this:
On the left is the list of gateways, and on the right is the MQTT messages of the gateway, including uplink and downlink messages, which are automatically scrolled.
9.4 Gateway Details
Double-click a gateway in the left list on the main page to open the details window of a gateway:
Most of the buttons correspond directly to a message of the interaction protocol. This interface can only be operated on one gateway, and the buttons on the main interface are operated on all selected gateways.
On the left is the basic information of each message, and on the right is the content of the message.
9.5 File Synchronization
"FileSync" is similar to FTP, which can check the status of files on the gateway and transfer files in both directions:
9.6 View the internal information of the gateway program
The button "show" will send a "show" command to the gateway, and the gateway will return the internal state of the program:
Contains some important information about internal configuration and when resolving configuration (which can be used to spot configuration issues).
10 Source Code Guidelines
10.1 Compile CTFC
For the compilation of CTFC, please refer to the make.sh in the CTFC directory:
cd platform
make -f makefile.mk linux debug
cd ..
cd src
chmod 755 *.sh
makeall.sh
In fact, it is to go to the platform directory to set the compilation parameters, and then go to the strc directory to execute the makeall.sh.
makeall.sh main function is to compile each directory, and the compilation method for each directory is to copy the makefile.mk to a makefile and then make.
So in fact, this compilation system is the original make, and a little automation is achieved through sh.
10.2 Compile gateway
gateway calls the compilation system of CTFC, and the compilation entry is also makeall.sh.
10.3 Source Code Entry Points
The entry point of the gateway is the main function of the gwmain_t.cpp in the gwmain directory.