ThinkLink

中文

English

中文

English

Appearance

1. 服务器配置 ​

1.1. ThingsBoard ​

ThinkLink不提供 ThingsBoard 服务器的搭建服务，但支持与已部署的 ThingsBoard 平台实现无缝数据对接。通过配置相关连接参数，TKL 可将设备数据实时同步至 ThingsBoard，便于用户进行可视化展示与高级应用开发。

1.1.1. 获取 ThingsBoard 连接信息 ​

  • Protocol：通信协议
  • Host：服务器地址
  • Port：服务端口
  • AccessToken：设备接入令牌

1.1.2. 填写 ThingsBoard信息 ​

📌操作说明：

  1. 登录 TKL 系统，进入「服务器配置」页面；
  2. 找到ThingsBoard 对接配置 区域；
  3. 填写上述四项必要信息；
  4. 点击「提交」保存配置；
  5. 配置完成后，请点击「重启」按钮以启动或更新 ThingsBoard 服务连接。

1.1.3. 在设备层面启用 ThingsBoard 功能 ​

仅完成服务器配置尚不足以激活数据同步。您还需在具体设备管理中开启 ThingsBoard 同步功能。

  1. 进入 TKL 的「设备管理」模块；
  2. 选择需要对接到 ThingsBoard 的设备；
  3. 在设备详情页中，找到并启用「ThingsBoard 功能」开关；
  4. 保存配置。

✅ 启用后，该设备及其属性、遥测数据、实体信息将自动同步至 ThingsBoard 平台。

1.1.4. 在 ThingsBoard 上查看设备 ​

当设备成功上行第一条数据时，ThingsBoard 将自动注册该设备（基于提供的 AccessToken），并在其设备列表中显示。注意事项：

  • 确保 AccessToken 正确无误，并已在 ThingsBoard 侧预先创建；
  • 若设备未出现，请检查网络连通性、端口开放情况以及 Access Token 是否绑定正确的设备；
  • 数据同步为双向：TKL 负责采集和处理数据，ThingsBoard 负责展示与规则引擎处理。

1.1.5. 附：如何创建网关的 Access Token ​

在 ThingsBoard 平台中为网关创建 Access Token 的步骤如下：

  1. 登录 ThingsBoard Web 界面；
  2. 创建或选择一个“网关”类型的设备；
  3. 进入该设备的“凭证”（Credentials）页面；
  4. 复制或生成Access Token；
  5. 将此 Token 填入 TKL 的服务器配置中。

1.2. HomeAssistant ​

HomeAssistant 服务器需由用户自行搭建，不属于 ThinkLink（TKL）系统的功能范围。TKL 提供与 HomeAssistant 的无缝对接能力，实现设备信息、属性及实体的自动发现与同步。

完成相关配置后，点击提交按钮，并在提示后点击重启，即可启动与 HomeAssistant 的服务连接。

【注意】若希望设备能在 HomeAssistant 中完整显示并正常使用，必须在对应设备的管理配置中开启HomeAssistant 功能。启用后，该设备及其属性、实体将在 HomeAssistant 页面中自动被发现并呈现。

1.2.1. 对接方式 ​

TKL 支持两种 Broker 模式与 HomeAssistant 进行集成：

  • 使用ThinkLink 的 MQTT Broker + 使用 HomeAssistant 的 MQTT Broker

无论选择哪种方式，请确保满足以下两个前提条件：

✅前提条件 1
物模型中已正确配置了 HomeAssistant 相关字段。
配置方法详见：章节 7.1

✅前提条件 2在目标设备的配置页面中已启用HomeAssistant 功能

1.2.2. 方式一：使用 ThinkLink 的 Broker ​

在此模式下，用户的 HomeAssistant 服务器作为 MQTT 客户端连接至 ThinkLink 的内置 MQTT Broker。

1.2.2.1. 配置步骤： ​

  1. 登录到您的 HomeAssistant 服务器；
  2. 进入MQTT 集成设置，添加一个新的 MQTT Broker；
  3. 填写 ThinkLink 的 Broker 连接信息，包括：
    • 地址（IP 或域名）
    • 端口
    • 用户名 / 密码
  4. 设置以下关键参数：
    • discovery_prefix（服务发现前缀）
    • manufacturer（厂商名称）
  5. 保存配置并重启 HomeAssistant 服务。

完成上述操作后，已启用 HomeAssistant 功能的设备将自动在 HomeAssistant 中被发现并展示为对应实体。

1.2.3. 方式二：使用 HomeAssistant 的 Broker ​

在此模式下，ThinkLink 作为 MQTT 客户端，主动连接至 HomeAssistant 内置的 Broker。

1.2.3.1. 在 HomeAssistant 中启用 MQTT Broker ​

ThinkLink 连接 HA 之前，HomeAssistant 的 MQTT 集成必须已在运行。

  1. 在 HomeAssistant 中进入 设置 → 设备与服务 → 添加集成，搜索 MQTT；
  2. 选择 MQTT 并完成 Broker 配置。若使用内置 Mosquitto 插件，Broker 地址为 localhost 或 HA 的 IP，端口 1883；
  3. 记下该 Broker 配置的用户名和密码。

1.2.3.2. 在 ThinkLink 中配置客户端连接 ​

  1. 登录 TKL 系统，进入 系统管理 → 服务器配置；
  2. 找到 HomeAssistant 配置区域，将模式切换为使用 HomeAssistant Broker；
  3. 填写 HomeAssistant Broker 参数：
参数说明示例
ProtocolMQTT 连接协议mqtt
HostHomeAssistant 主机 IP 或域名192.168.1.100
PortHA 上的 MQTT Broker 端口1883
UsernameHA 侧配置的 MQTT 凭证用户名ha_user
PasswordHA 侧配置的 MQTT 凭证密码ha_pass
discovery_prefixHA MQTT 自动发现前缀（须与 HA 设置一致）/V32/{tcode}/HA
  1. 点击提交，再点击重启以激活连接。

此模式下，ThinkLink 主动向 HA Broker 发布设备发现和状态主题，HA 无需连接 TKL 的 Broker，即可自动将 TKL 设备注册为实体。

1.2.4. 验证 ​

完成后，ThinkLink 将通过 MQTT 协议向 HomeAssistant 发布设备信息，实现实体自动注册与状态同步。

✅ 验证是否成功：
进入 HomeAssistant 的 “设备与服务” 页面，查看是否有来自 ThinkLink 的新设备出现，并检查其传感器、开关等实体是否正常显示和更新。

1.3. BACnet ​

注意：BACnet 服务功能仅支持在独立部署的 TKE设备/网关(TKG)上使用，云版本（Cloud Service）暂不提供此功能。

ThinkLink（TKL）支持将物模型中的设备数据以标准 BACnet 协议对外暴露，便于与楼宇管理系统（BMS）进行集成。要实现完整的 BACnet 服务功能，需完成以下两个步骤：

  1. 在物模型中对相关字段进行 BACnet 属性配置；
  2. 在目标设备上启用 BACnet 功能并正确配置服务器参数。

1.3.1. BACnet 字段配置 ​

启用 BACnet 服务前，必须在物模型 中对需要对外映射的字段配置相应的 BACnet 属性。具体配置方法请参考文档第 7.1

1.3.2. 服务器配置 ​

为使 TKL 成功作为 BACnet 服务器运行，需在系统中配置以下核心参数。所有设置均位于运维管理 → BACnet 菜单下。

请确保已在设备管理 页面为对应设备开启 BACnet 服务，之后在此处完成详细配置，并将生成的 BACnet 点表导出提供给 BMS 平台使用。

配置项说明默认值是否可修改
IP 地址TKL 所在设备的本地 IP 地址，用于 BACnet 通信 若设为 0.0.0.0，表示绑定所有网络接口0.0.0.0是
PortBACnet 服务监听端口47808（十进制） （即 UDP 端口 0xBAC0）是，可根据 BMS 要求调整
Device IDBACnet 设备唯一标识符，必须在系统内唯一 需与 BMS 平台协商一致1是
Vendor Identifier厂商标识号，代表设备制造商99（非官方保留值，建议按实际填写）是
Device Name设备名称，用于在 BMS 中显示TKE是，建议按现场命名规范修改
Max APDU Length Accepted最大可接受 APDU 长度，影响通信效率和兼容性1024是，根据客户端能力调整
Segmentation Supported分段支持模式，定义设备是否支持分段传输segmentedBoth （发送和接收均可分段）是，可选： noSegmentation segmentedTransmit segmentedReceive segmentedBoth

完成上述配置后，请进入 点表管理模块查看或导出当前设备的 BACnet 对象列表（即点表），并交付给 BMS 集成方用于接入和监控。提示：

  • 修改配置后需重启 BACnet 服务或相关设备以生效。
  • 建议与 BMS 集成方确认上述参数的具体要求，避免因协议不匹配导致连接失败。
  • BACnet over IP 协议基于 UDP 构建，确保网络层面允许相应端口通行。

1.4. 第三方 MQTT ​

TKL 支持将解析后的设备遥测数据推送至第三方 MQTT Broker，使外部平台无需直接订阅 ThinkLink Broker 即可接收结构化设备数据。

1.4.1. 服务器配置 ​

进入系统管理 → 服务器配置，找到 ThirdParty 配置区域，填写以下参数：

参数说明示例
ProtocolMQTT 连接协议mqtt 或 mqtts
Host第三方 Broker 地址192.168.1.100
PortBroker 端口1883
Telemetry Topic发布设备遥测数据的主题/your/custom/topic
UsernameBroker 认证用户名user
PasswordBroker 认证密码pass

填写完成后，点击提交，再点击重启以激活连接。

1.4.2. 设备层面启用 ​

完成服务器配置后，需在目标设备上单独启用 ThirdParty 功能：

  1. 进入设备管理，打开目标设备；
  2. 在设备详情页中，启用 ThirdParty 开关；
  3. 保存配置。

启用后，每当设备有新数据上行时，ThinkLink 会将解析后的遥测数据推送至配置的主题。

1.5. Modbus TCP 服务器 ​

注意：Modbus TCP Server 功能仅支持独立部署的 TKE 或 TKG 设备，云版本（Cloud Service）暂不提供此功能。

TKL 可作为 Modbus TCP 从站服务器（Slave），将设备遥测数据以 Modbus 寄存器形式对外暴露，供 SCADA 系统、PLC 及其他 Modbus TCP 主站通过标准 Modbus 协议读取设备数据。

1.5.1. 服务器配置 ​

进入系统管理 → 服务器配置，找到 Modbus TCP Server 配置区域，配置以下参数：

参数说明默认值备注
PortModbus TCP 监听端口502确保该端口在网络层面对外开放
Coils线圈寄存器映射（可读写位寄存器）—映射设备布尔字段
Discrete Inputs离散量输入映射（只读位寄存器）—映射设备布尔字段
Input Registers输入寄存器映射（只读 16 位字寄存器）—映射设备数值字段
Holding Registers保持寄存器映射（可读写 16 位字寄存器）—映射设备数值字段

配置完成后，点击提交，再点击重启以启动 Modbus TCP 服务。

1.5.2. 设备层面启用 ​

Modbus TCP 寄存器的值来源于设备物模型字段。要将设备数据对外暴露：

  1. 在物模型中配置 Modbus TCP 字段映射；
  2. 在设备管理中为目标设备启用 Modbus TCP 功能。

启用后，Modbus TCP 主站即可通过配置的端口和寄存器地址读取 TKL 设备数据。

1.6. 组织参数（Org Params） ​

组织参数是当前组织（租户）级别的"环境变量"，集中保管在 系统管理 → 服务器配置 → 组织参数 中。一次维护，全租户共享，并由平台在执行下列脚本时作为入参 org_params 自动注入：

  • RPC 模型：rpc_script({ device, params, alarms, logger, org_params })
  • 物模型解析脚本：payload_parser(device, msg, thingModelId, noticeAttrs, org_params)
  • 触发模型：trigger_script(device, thingModelId, org_params)
  • MQTT 转发器脚本：forwardScript({ topic, msg, org_params })

💡 设计目的：把"对接外部系统所需的凭证 / 地址 / 业务标识"从脚本里剥离出来——脚本只负责逻辑，凭证写在组织参数里。换 webhook、轮换密钥、切换环境时只改一处，无需逐个修改 RPC/触发/转发器脚本。

1.6.1. 与 server_attrs / shared_attrs / params 的区别 ​

来源作用域写在哪里谁能看到
params单次 RPC 调用调用方在调用时传入调用方
device.shared_attrs单个设备设备 ↔ 平台双向同步该设备的运维
device.server_attrs单个设备平台侧设备详情页该设备的运维
org_params整个组织服务器配置 → 组织参数组织管理员（普通运维不可见）

典型用途：

  • 第三方机器人 Webhook（企业微信 / 钉钉 / Slack / Telegram）的 URL 或 key
  • 第三方 HTTP API 的 base URL、access key
  • 全组织共用的业务标识（如 BMS 接入方编号、运营商账号）
  • 不同环境（生产/测试）切换的常量

1.6.2. 配置方式 ​

进入 系统管理 → 服务器配置 → 组织参数，按"键值对"维护：

字段说明
Key在脚本中通过 org_params.<key> 读取，建议小写下划线命名（如 wecom_webhook_url）
Value字符串；若需结构化数据，请填 JSON 字符串并在脚本中 JSON.parse
Remark给平台操作者看的"这个参数怎么用"的说明，例如"企业微信告警机器人 webhook，每季度轮换"

配置完成后点击提交，新值即刻对该组织所有脚本生效（无需重启服务）。

1.6.3. 在脚本中读取 ​

javascript
// RPC：从 org_params 拿企业微信 webhook
function rpc_script({ device, params, alarms, logger, org_params }) {
    let webhook = org_params?.wecom_webhook_url;
    if (!webhook) {
        logger.error("wecom_webhook_url not configured in org_params");
        return null;
    }
    return [{
        sleepTimeMs: 0,
        type: "axios",
        dnMsg: {
            method: "POST",
            url: webhook,
            headers: { "Content-Type": "application/json" },
            data: { msgtype: "text", text: { content: params.content } },
            timeout: 5000
        }
    }];
}

1.6.4. 安全提示 ​

  • 组织参数页面仅组织管理员可访问——普通运维看不到 webhook key/secret，可放心存放敏感凭证
  • 一旦怀疑泄漏，在第三方平台重置密钥，回到本页面更新 value即可；所有引用该 key 的脚本自动使用新值
  • 建议每季度轮换一次 webhook/access key，并在 Remark 里记录上次轮换时间

⚠️ 不要把 org_params 的值写回到 device.server_attrs 或日志正文里——那等于把"安全藏起来的密钥"又暴露到调用方/日志读者面前。

Copyright © 2025 ThinkLink Email : info@manthink.cn