Modbus프로그래밍 개발

ThingsBoard IoT Gateway Modbus接入完整튜토리얼：TCP/RTU设备데이터采集 RPC원격 제어与批量읽기优化实战

무료무료 기술 자료

이 글은 바로 읽을 수 있으며 기초 학습과 검색 유입에 적합합니다.

modbus기술팀璀璨会员 약 6 분 읽기

ThingsBoard IoT Gateway是ThingsBoard官方오픈소스的物联网게이트웨이，支持Modbus、MQTT、OPC-UA、BLE等多种프로토콜，可将现场工业设备데이터接入ThingsBoard物联网平台。本文详细介绍ThingsBoard IoT Gateway的Modbus연결器설정，包括TCP/RTU设备接入、데이터유형映射、批量읽기优化、RPC원격 제어、属性下行控制、TLS安全연결以及完整的工厂환경监控实战。

一、ThingsBoard IoT Gateway개요

1.1 什么是ThingsBoard IoT Gateway

ThingsBoard IoT Gateway是一个오픈소스的物联网게이트웨이软件，作为ThingsBoard平台与现场设备之间的桥梁。它运行在边缘设备（如树莓派、산업 제어机、服务器）上，通过各种工业프로토콜（Modbus、MQTT、OPC-UA、BLE、CAN等）采集现场设备데이터，然后通过MQTT프로토콜上传到ThingsBoard平台。同时支持平台下发的RPC원격 제어和属性更新，实现双向통신。

1.2 核心特性

  • 多프로토콜支持：Modbus TCP/RTU、MQTT、OPC-UA、BLE、CAN、Sigfox、HTTP等
  • 主从双모드：Modbus支持Master（主动읽기）和Slave（被动响应）两种모드
  • 데이터유형丰富：16int、32int、64int、float、double、bits、string等
  • 바이트序설정：支持BIG/LITTLE바이트序和字序独立설정
  • 批量읽기：连续레지스터可一次읽기，减少请求次数
  • 데이터变换：内置multiplier（乘）和divider（除）스케일 계수变换
  • RPC원격 제어：平台可通过RPC调用읽기或쓰기设备레지스터
  • 属性下行：平台属性变更可自动쓰기设备레지스터
  • 断线重连：自动重连机制，支持重试次数和대기时间설정
  • TLS安全：支持Modbus TCP over TLS加密传输
  • 本地存储：네트워크中断时데이터本地缓存，恢复后自动补传
  • 完全오픈소스：Apache 2.0프로토콜，商业使用무료

二、架构与工作원리

┌──────────────────────────────────────────────────────────────┐
│                    ThingsBoard 平台                           │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  设备管理    │  │  데이터可视化  │  │  规则引擎/告警      │  │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
└─────────┼────────────────┼─────────────────────┼─────────────┘
          │ MQTT (上行데이터/RPC下行/属性)
┌─────────▼─────────────────────────────────────────────────────┐
│              ThingsBoard IoT Gateway（边缘게이트웨이）                │
│  ┌────────────────────────────────────────────────────────┐  │
│  │                    연결器框架                             │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │  │
│  │  │ Modbus   │ │  MQTT    │ │ OPC-UA   │ │   BLE    │  │  │
│  │  │ Connector│ │Connector │ │Connector │ │Connector │  │  │
│  │  └────┬─────┘ └──────────┘ └──────────┘ └──────────┘  │  │
│  └───────┼────────────────────────────────────────────────┘  │
└──────────┼───────────────────────────────────────────────────┘
           │ Modbus TCP/RTU
┌──────────▼───────────────────────────────────────────────────┐
│                    现场设备层                                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
│  │ 온습도    │ │ 电力仪表  │ │  PLC     │ │ 变频器       │   │
│  │ 센서    │ │          │ │          │ │              │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘   │
└──────────────────────────────────────────────────────────────┘

三、安装与部署

3.1 Docker安装（推荐）

# 创建설정目录
mkdir -p ~/.tb-gateway/config
cd ~/.tb-gateway

# 拉取最新镜像
docker pull thingsboard/tb-gateway:latest

# 运行容器
docker run -it --name tb-gateway \
  -v ~/.tb-gateway/config:/config \
  -v ~/.tb-gateway/데이터:/데이터 \
  --device /dev/ttyUSB0:/dev/ttyUSB0 \
  --network host \
  thingsboard/tb-gateway:latest

# 매개변수설명：
# -v config:/config    설정文件目录
# -v 데이터:/데이터        데이터存储目录（离线缓存）
# --device             挂载시리얼 포트设备（RTU需要）
# --network host       使用主机네트워크（方便访问本地设备）

3.2 Docker Compose部署

# docker-compose.yml
version: "3.8"
services:
  tb-gateway:
    image: thingsboard/tb-gateway:latest
    container_name: tb-gateway
    re시작: unless-stopped
    network_mode: host
    volumes:
      - ./config:/config
      - ./데이터:/데이터
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
      - /dev/ttyUSB1:/dev/ttyUSB1
    environment:
      - TB_GW_LOG_LEVEL=INFO
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

3.3 原生安装（Ubuntu/Debian）

# 安装Python3和依赖
sudo apt update
sudo apt install -y python3 python3-pip python3-dev

# 安装ThingsBoard IoT Gateway
sudo pip3 install thingsboard-gateway

# 创建설정目录
sudo mkdir -p /etc/thingsboard-gateway/config
sudo mkdir -p /var/lib/thingsboard-gateway

# 복사默认설정
sudo cp -r /usr/local/lib/python3*/dist-packages/thingsboard_gateway/config/* \
  /etc/thingsboard-gateway/config/

# 启动服务
thingsboard-gateway -c /etc/thingsboard-gateway/config/tb_gateway.yaml

# 설정为systemd服务（可选）
sudo nano /etc/systemd/system/tb-gateway.service
# [Unit]
# Description=ThingsBoard IoT Gateway
# After=network.target
# [Service]
# ExecStart=/usr/local/bin/thingsboard-gateway -c /etc/thingsboard-gateway/config/tb_gateway.yaml
# Re시작=always
# User=root
# [Install]
# WantedBy=multi-user.target

sudo systemctl enable tb-gateway
sudo systemctl 시작 tb-gateway

四、主설정文件tb_gateway.yaml

# tb_gateway.yaml - ThingsBoard IoT Gateway主설정
thingsboard:
  host: "thingsboard.example.com"   # ThingsBoard平台주소
  port: 1883                         # MQTT포트
  remoteConfiguration: true          # 활성화远程설정（平台可修改게이트웨이설정）
  security:
    accessToken: "YOUR_GATEWAY_TOKEN"  # 게이트웨이访问令牌
  qos: 1                              # MQTT QoS等级
  storage:
    type: memory                      # 离线存储유형 memory/file/sqlite
    max_records_count: 100000         # 最大缓存记录数
    read_records_count: 100           # 每次补传记录数

connectors:
  - name: "Modbus TCP Connector"
    type: modbus
    configuration: modbus_tcp.json    # Modbus TCP연결器설정

  - name: "Modbus RTU Connector"
    type: modbus
    configuration: modbus_rtu.json    # Modbus RTU연결器설정

grpc:
  enabled: false                      # gRPC远程설정（ThingsBoard PE）

logs:
  level: INFO                         # 로그级别 DEBUG/INFO/WARNING/ERROR
  path: "/var/log/tb-gateway/"        # 로그目录

五、Modbus TCP设备接入

最常见的시나리오：通过以太网읽기Modbus TCP设备데이터。

// modbus_tcp.json - Modbus TCP연결器설정
{
  "master": {
    "slaves": [
      {
        // ====== 연결설정 ======
        "host": "192.168.1.100",       // 设备IP주소
        "port": 502,                    // 设备포트
        "type": "tcp",                  // 연결유형 tcp/udp/serial
        "method": "socket",             // 帧유형 socket(표준TCP)/rtu(RTU over TCP)
        "unitId": 1,                    // 슬레이브ID
        "device이름": "车间A온습도센서", // ThingsBoard上的设备名称
        "deviceType": "temperature_sensor", // 设备유형/설정文件

        // ====== 통신매개변수 ======
        "timeout": 35,                  // 超时时间（秒）
        "byteOrder": "BIG",             // 바이트序 BIG/LITTLE
        "wordOrder": "BIG",             // 字序 BIG/LITTLE（32位以上데이터有效）
        "retries": true,                // 失败重试
        "retryOnEmpty": true,           // 空响应重试
        "retryOnInvalid": true,         // 无效响应重试
        "pollPeriod": 5000,             // 轮询周期（毫秒）
        "connectAttemptTimeMs": 5000,   // 연결超时（毫秒）
        "connectAttemptCount": 5,       // 연결重试次数
        "waitAfterFailedAttemptsMs": 30000, // 연결失败后대기时间

        // ====== 属性（静态데이터，设备信息） ======
        "attributes": [
          {
            "tag": "firmware_version",  // 属性名
            "type": "string",           // 데이터유형
            "주소": 100,             // 레지스터주소
            "objectsCount": 8,          // 읽기레지스터数（string需要多个）
            "functionCode": 3           // 기능 코드 03=读유지 레지스터
          }
        ],

        // ====== 遥测（动态데이터，实时上报） ======
        "timeseries": [
          {
            "tag": "temperature",       // 遥测键名
            "type": "16int",            // 데이터유형 16int/32int/float/bits
            "주소": 0,               // 레지스터주소
            "objectsCount": 1,          // 읽기레지스터数
            "functionCode": 3,          // 기능 코드 03=读유지 레지스터
            "divider": 10               // 除数（레지스터 값/10，250→25.0）
          },
          {
            "tag": "humidity",
            "type": "16int",
            "주소": 1,
            "objectsCount": 1,
            "functionCode": 3,
            "divider": 10               // 652→65.2
          },
          {
            "tag": "pressure",
            "type": "32int",            // 32位整数（占2个레지스터）
            "주소": 2,
            "objectsCount": 2,
            "functionCode": 3,
            "multiplier": 0.1           // 乘数
          },
          {
            "tag": "relay_status",
            "type": "bits",             // 位유형（读코일）
            "주소": 0,
            "objectsCount": 1,
            "functionCode": 1,          // 기능 코드 01=读코일
            "bitTargetType": "bool"     // 转换为布尔值
          }
        ],

        // ====== 属性更新（平台→设备下行控制） ======
        "attributeUpdates": [
          {
            "tag": "set_temperature",   // 平台属性名
            "type": "16int",
            "주소": 10,              // 쓰기레지스터주소
            "functionCode": 6,          // 기능 코드 06=写单个레지스터
            "multiplier": 10            // 平台值25.0→쓰기250
          }
        ],

        // ====== RPC方法（平台远程调用） ======
        "rpc": [
          {
            "tag": "getTemperature",    // RPC方法名
            "type": "16int",
            "주소": 0,
            "objectsCount": 1,
            "functionCode": 3
          },
          {
            "tag": "setRelay",          // RPC写操作
            "type": "bits",
            "주소": 0,
            "objectsCount": 1,
            "functionCode": 5           // 기능 코드 05=写单个코일
          }
        ]
      }
    ]
  }
}

六、Modbus RTU시리얼 포트设备接入

// modbus_rtu.json - Modbus RTU시리얼 포트연결器설정
{
  "master": {
    "slaves": [
      {
        // ====== 시리얼 포트연결설정 ======
        "type": "serial",               // 시리얼 포트유형
        "port": "/dev/ttyUSB0",         // 시리얼 포트设备
        "method": "rtu",                // 帧유형 rtu/ascii
        "baudrate": 9600,               // 통신 속도
        "bytesize": 8,                  // 데이터 비트
        "parity": "N",                  // 패리티 N/E/O
        "stopbits": 1,                  // 정지 비트
        "strict": true,                 // 严格모드（低통신 속도使用문자间超时）

        "unitId": 1,
        "device이름": "电力仪表1号",
        "deviceType": "power_meter",

        "timeout": 35,
        "byteOrder": "BIG",
        "wordOrder": "BIG",
        "pollPeriod": 1000,             // 1秒轮询一次
        "retries": true,

        // ====== 遥测데이터 ======
        "timeseries": [
          {
            "tag": "voltage",
            "type": "16int",
            "주소": 0,
            "objectsCount": 1,
            "functionCode": 3,
            "divider": 10               // 2200→220.0V
          },
          {
            "tag": "current",
            "type": "16int",
            "주소": 1,
            "objectsCount": 1,
            "functionCode": 3,
            "divider": 100              // 135→1.35A
          },
          {
            "tag": "power",
            "type": "32int",
            "주소": 2,
            "objectsCount": 2,
            "functionCode": 3,
            "divider": 1000             // 297000→297.0kW
          },
          {
            "tag": "energy",
            "type": "32int",
            "주소": 4,
            "objectsCount": 2,
            "functionCode": 3
          },
          {
            "tag": "power_factor",
            "type": "16int",
            "주소": 6,
            "objectsCount": 1,
            "functionCode": 3,
            "divider": 1000             // 950→0.95
          }
        ],

        "attributeUpdates": [],
        "rpc": []
      },
      // ====== 同一条总线上的第二个设备 ======
      {
        "type": "serial",
        "port": "/dev/ttyUSB0",         // 同一个시리얼 포트
        "method": "rtu",
        "baudrate": 9600,
        "bytesize": 8,
        "parity": "N",
        "stopbits": 1,

        "unitId": 2,                    // 不同슬레이브ID
        "device이름": "电力仪表2号",
        "deviceType": "power_meter",

        "timeout": 35,
        "byteOrder": "BIG",
        "pollPeriod": 1000,

        "timeseries": [
          {
            "tag": "voltage",
            "type": "16int",
            "주소": 0,
            "objectsCount": 1,
            "functionCode": 3,
            "divider": 10
          }
        ],

        "attributeUpdates": [],
        "rpc": []
      }
    ]
  }
}

七、데이터유형详解

유형설명占用레지스터适用기능 코드
16int16位有符号整数103/04
16uint16位无符号整数103/04
32int32位有符号整数203/04
32uint32位无符号整数203/04
64int64位有符号整数403/04
float32位浮点数(IEEE754)203/04
double64位浮点数403/04
bits位/코일1(位)01/02/05/15
string문자串N03/04

7.1 바이트序与字序

  • byteOrder: BIG：大端바이트序（高바이트在前），大多数Modbus设备默认
  • byteOrder: LITTLE：小端바이트序（低바이트在前）
  • wordOrder: BIG：大字序（高字在前），32位데이터的两个레지스터顺序
  • wordOrder: LITTLE：小字序（低字在前）
  • 四种组合：BIG+BIG（ABCD）、BIG+LITTLE（CDAB）、LITTLE+BIG（BADC）、LITTLE+LITTLE（DCBA）
  • 不确定时用QModMaster읽기同一32位浮点数，对比四种组合哪个值合理

八、批量읽기优化

当设备有多个连续레지스터需要읽기时，使用批量읽기可以大幅减少请求次数，提高效率。

// 不推荐：每个레지스터单独请求（4次请求）
"timeseries": [
  {"tag": "temperature", "type": "16int", "주소": 0, "functionCode": 3},
  {"tag": "humidity",    "type": "16int", "주소": 1, "functionCode": 3},
  {"tag": "power",       "type": "16int", "주소": 2, "functionCode": 3},
  {"tag": "pressure",    "type": "16int", "주소": 3, "functionCode": 3}
]

// 推荐：批量읽기（1次请求읽기4个레지스터）
"timeseries": [
  {
    "tag": "${unitId}.${type}.${주소}",  // 自动生成键名
    "type": "16int",
    "functionCode": 3,
    "objectsCount": 1,
    "주소": "0-3",               // 주소范围，一次읽기
    "divider": 10
  }
]
// 上报结果：
// {"1.16int.0": 250, "1.16int.1": 652, "1.16int.2": 100, "1.16int.3": 1013}

// 自定义tag변수：
// ${unitId}     - 슬레이브ID
// ${type}       - 데이터유형
// ${주소}    - 레지스터주소
// ${device이름} - 设备名称

九、RPC원격 제어

ThingsBoard平台可以通过RPC调用远程읽기或쓰기Modbus设备레지스터。

// RPC설정예제
"rpc": [
  // 读操作：읽기온도
  {
    "tag": "getTemperature",
    "type": "16int",
    "주소": 0,
    "objectsCount": 1,
    "functionCode": 3
  },
  // 写操作：设置릴레이
  {
    "tag": "setRelay",
    "type": "bits",
    "주소": 0,
    "objectsCount": 1,
    "functionCode": 5           // 写单个코일
  },
  // 写操作：设置设定值
  {
    "tag": "setSetpoint",
    "type": "16int",
    "주소": 10,
    "objectsCount": 1,
    "functionCode": 6           // 写单个레지스터
  }
]

// 在ThingsBoard RPC디버깅终端调用：
// getTemperature
// 返回：{"temperature": 250}

// setRelay
// 매개변수：{"value": 1}  (1=ON, 0=OFF)

// setSetpoint
// 매개변수：{"value": 250}  (25.0°C)

// 通用RPC（无需预설정）：
// get type=16int;functionCode=3;objectsCount=1;주소=0;
// set type=16int;functionCode=6;objectsCount=1;주소=10;value=250;

十、属性下行控制

当平台上的共享属性值发生变化时，게이트웨이自动将新值쓰기Modbus设备레지스터。

"attributeUpdates": [
  {
    "tag": "target_temperature",   // 平台共享属性名
    "type": "16int",
    "주소": 10,                 // 쓰기레지스터
    "functionCode": 6,             // 写单个레지스터
    "multiplier": 10               // 平台值25.0→쓰기250
  },
  {
    "tag": "alarm_enable",
    "type": "bits",
    "주소": 5,
    "functionCode": 5              // 写코일
  }
]

// 工作流程：
// 1. 在ThingsBoard设备页面修改共享属性 target_temperature = 26.0
// 2. 平台通过MQTT下发属性更新通知
// 3. 게이트웨이收到通知，계산 26.0 * 10 = 260
// 4. 게이트웨이向Modbus设备레지스터10쓰기260（기능 코드06）
// 5. 设备设定온도变为26.0°C

十一、TLS安全연결

// Modbus TCP over TLS설정
{
  "master": {
    "slaves": [
      {
        "host": "secure-device.example.com",
        "port": 802,                  // TLS常用포트
        "type": "tcp",
        "method": "socket",
        "unitId": 1,
        "device이름": "安全设备",
        "deviceType": "secure_device",

        // TLS설정
        "tls": {
          "enabled": true,
          "cert": "/config/certs/client.crt",    // 클라이언트证书
          "key": "/config/certs/client.key",     // 클라이언트私钥
          "ca_certs": "/config/certs/ca.crt",    // CA证书
          "password": "key_password"             // 私钥密码（可选）
        },

        "timeout": 35,
        "byteOrder": "BIG",
        "pollPeriod": 5000,

        "timeseries": [
          {"tag": "temperature", "type": "16int", "주소": 0, "functionCode": 3}
        ],
        "attributeUpdates": [],
        "rpc": []
      }
    ]
  }
}

十二、Gateway Slave모드

게이트웨이也可以作为Modbus슬레이브运行，允许其他Modbus마스터읽기게이트웨이缓存的데이터。

// modbus_slave.json - 게이트웨이作为Modbus슬레이브
{
  "slave": {
    "type": "tcp",
    "host": "0.0.0.0",
    "port": 502,
    "method": "socket",
    "unitId": 1,
    "device이름": "Gateway_Slave",
    "deviceType": "gateway",

    "byteOrder": "BIG",
    "wordOrder": "BIG",
    "pollPeriod": 5000,
    "send데이터ToThingsBoard": true,

    // 슬레이브데이터映射（其他마스터可읽기这些주소）
    "timeseries": [
      {"tag": "gateway_temperature", "type": "16int", "주소": 0, "functionCode": 3},
      {"tag": "gateway_humidity",    "type": "16int", "주소": 1, "functionCode": 3}
    ],
    "attributes": [],
    "attributeUpdates": [],
    "rpc": []
  }
}

十三、完整实战：工厂환경监控系统

以下是一个完整的生产환경설정：监控3个车间的온습도、2台电力仪表、1台PLC，데이터전체上传ThingsBoard平台。

// factory_monitor.json - 工厂환경监控完整설정
{
  "master": {
    "slaves": [
      // ====== 车间A온습도（TCP） ======
      {
        "host": "192.168.1.101",
        "port": 502,
        "type": "tcp",
        "method": "socket",
        "unitId": 1,
        "device이름": "车间A-온습도",
        "deviceType": "env_sensor",
        "timeout": 35,
        "byteOrder": "BIG",
        "wordOrder": "BIG",
        "pollPeriod": 10000,
        "timeseries": [
          {"tag": "temperature", "type": "16int", "주소": 0, "functionCode": 3, "divider": 10},
          {"tag": "humidity",    "type": "16int", "주소": 1, "functionCode": 3, "divider": 10},
          {"tag": "dew_point",   "type": "16int", "주소": 2, "functionCode": 3, "divider": 10}
        ],
        "attributeUpdates": [
          {"tag": "alarm_temp_high", "type": "16int", "주소": 100, "functionCode": 6, "multiplier": 10}
        ],
        "rpc": [
          {"tag": "getTemp", "type": "16int", "주소": 0, "functionCode": 3}
        ]
      },
      // ====== 车间B온습도（TCP） ======
      {
        "host": "192.168.1.102",
        "port": 502,
        "type": "tcp",
        "method": "socket",
        "unitId": 1,
        "device이름": "车间B-온습도",
        "deviceType": "env_sensor",
        "timeout": 35,
        "byteOrder": "BIG",
        "pollPeriod": 10000,
        "timeseries": [
          {"tag": "temperature", "type": "16int", "주소": 0, "functionCode": 3, "divider": 10},
          {"tag": "humidity",    "type": "16int", "주소": 1, "functionCode": 3, "divider": 10}
        ],
        "attributeUpdates": [],
        "rpc": []
      },
      // ====== 电力仪表1（RTU，슬레이브1） ======
      {
        "type": "serial",
        "port": "/dev/ttyUSB0",
        "method": "rtu",
        "baudrate": 9600,
        "bytesize": 8,
        "parity": "E",
        "stopbits": 1,
        "unitId": 1,
        "device이름": "配电柜1-电力仪表",
        "deviceType": "power_meter",
        "timeout": 35,
        "byteOrder": "BIG",
        "wordOrder": "LITTLE",
        "pollPeriod": 5000,
        "timeseries": [
          {"tag": "voltage_a", "type": "16int", "주소": 0, "functionCode": 3, "divider": 10},
          {"tag": "voltage_b", "type": "16int", "주소": 1, "functionCode": 3, "divider": 10},
          {"tag": "voltage_c", "type": "16int", "주소": 2, "functionCode": 3, "divider": 10},
          {"tag": "current_a", "type": "16int", "주소": 3, "functionCode": 3, "divider": 100},
          {"tag": "power",     "type": "32int", "주소": 4, "functionCode": 3, "divider": 1000},
          {"tag": "energy",    "type": "32int", "주소": 6, "functionCode": 3}
        ],
        "attributeUpdates": [],
        "rpc": []
      },
      // ====== 电力仪表2（RTU，슬레이브2，同一条总线） ======
      {
        "type": "serial",
        "port": "/dev/ttyUSB0",
        "method": "rtu",
        "baudrate": 9600,
        "bytesize": 8,
        "parity": "E",
        "stopbits": 1,
        "unitId": 2,
        "device이름": "配电柜2-电力仪表",
        "deviceType": "power_meter",
        "timeout": 35,
        "byteOrder": "BIG",
        "wordOrder": "LITTLE",
        "pollPeriod": 5000,
        "timeseries": [
          {"tag": "voltage_a", "type": "16int", "주소": 0, "functionCode": 3, "divider": 10},
          {"tag": "power",     "type": "32int", "주소": 4, "functionCode": 3, "divider": 1000}
        ],
        "attributeUpdates": [],
        "rpc": []
      },
      // ====== PLC（TCP，批量읽기） ======
      {
        "host": "192.168.1.200",
        "port": 502,
        "type": "tcp",
        "method": "socket",
        "unitId": 1,
        "device이름": "生产线PLC",
        "deviceType": "plc",
        "timeout": 35,
        "byteOrder": "BIG",
        "pollPeriod": 2000,
        "send데이터OnlyOnChange": true,
        "timeseries": [
          {
            "tag": "${unitId}.${type}.${주소}",
            "type": "16int",
            "functionCode": 3,
            "objectsCount": 1,
            "주소": "0-15"
          }
        ],
        "attributeUpdates": [
          {"tag": "production_speed", "type": "16int", "주소": 100, "functionCode": 6}
        ],
        "rpc": [
          {"tag": "시작Production", "type": "bits", "주소": 0, "functionCode": 5},
          {"tag": "stopProduction",  "type": "bits", "주소": 1, "functionCode": 5}
        ]
      }
    ]
  }
}

十四、로그与排障

# 보기게이트웨이로그
docker logs -f tb-gateway

# 활성화DEBUG级别로그（排查통신문제）
# 修改tb_gateway.yaml: logs.level: DEBUG

# 常见로그설명：
# INFO - Modbus connector 시작ed           연결器启动成功
# INFO - Connected to modbus slave          연결设备成功
# WARNING - Modbus connection failed        연결失败（检查IP/포트/시리얼 포트）
# ERROR - Modbus request timeout            请求超时（检查设备是否在线）
# ERROR - Invalid response from slave       响应无效（检查바이트序/슬레이브ID）

# 测试Modbus设备是否可达
# TCP设备：
nc -zv 192.168.1.100 502

# RTU设备（用pymodbus测试）：
python3 -c "
from pymodbus.client import ModbusSerialClient
c = ModbusSerialClient(port='/dev/ttyUSB0', baudrate=9600, parity='E')
c.connect()
r = c.read_holding_registers(0, 5, device_id=1)
print(r.registers if not r.is오답() else r)
c.close()
"

# 检查시리얼 포트权限
ls -la /dev/ttyUSB0
sudo usermod -aG dialout $USER  # 将用户加入시리얼 포트组

十五、常见문제

문제原因解决方法
设备연결失败IP/포트错误或네트워크不通用nc测试포트，检查防火墙和路由
RTU无响应시리얼 포트 매개변수不일치核对통신 속도/데이터 비트/패리티/정지 비트
데이터值异常바이트序/字序错误尝试四种byteOrder/wordOrder组合
浮点数不对字序설정错误32位float需同时설정byteOrder和wordOrder
32位데이터异常objectsCount未设为232int/float必须objectsCount=2
RPC调用无响应方法名不일치检查rpc설정中的tag与调用方法名一致
属性下行不生效属性名不일치平台共享属性名必须与attributeUpdates.tag一致
시리얼 포트权限拒绝用户无시리얼 포트访问权限加入dialout组或用root运行
频繁断线重连pollPeriod过短或设备慢增大pollPeriod，检查timeout设置
데이터不上报게이트웨이연결되지 않음平台检查accessToken和平台주소포트

十六、학습자료

  • 官方문서：https://thingsboard.io/docs/iot-gateway/
  • Modbus연결器설정：https://thingsboard.io/docs/iot-gateway/config/modbus/
  • GitHub源码：https://github.com/thingsboard/thingsboard-gateway
  • Demo服务器：docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest
  • ThingsBoard平台：https://thingsboard.io/

ThingsBoard IoT Gateway的Modbus연결器提供了完整的工业设备接入能力，支持TCP/RTU双프로토콜、主从双모드、丰富的데이터유형和바이트序설정、批量읽기优化、RPC원격 제어和属性下行控制。本文提供的从基础TCP设备接入到完整工厂환경监控的实战설정，可直接用于生产환경部署。建议先用ThingsBoard官方Demo服务器测试설정，再逐步接入真实设备。

📦

VIP专属：ThingsBoard IoT Gateway Modbus설정包

JSON完整설정：批量읽기、RPC下行控制、timeseries映射、多슬레이브管理，可直接导入使用。

开通VIP即可下载完整代码，同时解锁 30+ 엔지니어링实战자료包：디버깅스크립트、速查表、项目模板、排查案例……

前往VIP자료库下载 → 月费仅9.9元 / 年费199元
후원미니 포스터공유
AI 추천 글
실제 프로젝트에 이 자료를 활용하시겠습니까?

도구 센터에서 프레임 분석, CRC 검증, 장비 디버깅을 진행하거나 요청을 제출하여 선정 및 연동 제안을 받아보세요.

엔지니어 회원

이 글을 실행 가능한 디버깅 자료로 활용하세요

가입하면 고급 프레임 분석, 자료 패키지 다운로드, 코드 예제, 엔지니어링 사례, 우선 기술 지원을 이용할 수 있어 실제 프로젝트 납품에 적합합니다.

고급 도구 무제한 이용
자료 패키지와 코드 패키지
완전한 엔지니어링 사례 라이브러리
우선 기술 지원 채널
회원 혜택 보기 먼저 디버깅 도구 사용
KEEP READING

관련 기술 자료

2026년 9월 17일 Node.js Modbus개발实战完整指南：modbus-serial库 TCP/RTU클라이언트 데이터분석与MQTT上云게이트웨이 2026년 9월 17일 FreeModbus프로토콜栈深度분석与STM32移植完整튜토리얼：RTU/TCP슬레이브개발 回调函数与源码详解 2026년 9월 17일 Modbus TLS安全通讯完整指南：Modbus TCP Security프로토콜 X.509证书인증与遗留设备安全업그레이드实战