在 HiBean 中接入自定义 Modbus RTU 设备

如果你的烘焙机、温控表或控制器支持 Modbus RTU，但没有出现在 HiBean 的设备列表中，可以根据厂家手册自行配置。

这不是自动识别流程。开始前，你需要拿到设备的串口参数和寄存器表。HiBean 会帮助你逐项验证，但不会猜测从站地址、寄存器或数据格式。

如果设备已经在 HiBean 中有专属入口，请优先使用专属入口。本文只讲 Custom Modbus / 自定义 Modbus。

先确认是否适合

这套流程适用于：

通过 USB-RS485 适配器连接的 Modbus RTU 设备
厂家明确提供串口参数和寄存器表的设备
只读取温度和状态的监测设备
能提供明确写入寄存器、反馈寄存器和安全值的可控设备

它不适用于 Modbus TCP，也不会扫描从站、寄存器或设备型号。

本文按 HiBean 桌面版编写。截图来自 macOS；Windows 中的配置步骤相同，但串口通常显示为 COM3、COM4 等名称，USB-RS485 适配器也可能需要先安装厂家驱动。不同版本的功能开放范围可能不同；如果添加设备页没有 Custom Modbus，请先更新 HiBean。

开始前准备

硬件

一台已上电、当前没有烘焙任务的设备
USB-RS485 适配器
正确连接的 A、B 信号线；是否需要 GND 以厂家接线图为准
安装在电脑上的适配器驱动（Windows 用户尤其需要确认）

厂家资料

至少准备好这些信息：

信息	常见示例
波特率	9600、19200
数据位、校验、停止位	8N1、8E1
从站 ID（Unit ID）	1
读取功能码	03 保持寄存器、04 输入寄存器
寄存器地址	40001、30005，或从 0 开始的 PDU 地址
数据类型	Int16、UInt16、Float32、BCD
字节与寄存器顺序	AB、ABCD、CDAB 等
数值换算	Scale、Offset
温度原始单位	摄氏度或华氏度

不要凭经验套用其他机型的寄存器表。型号相近，不代表地址和写入规则相同。

从 Artisan 迁移

如果设备已经能在 Artisan 中稳定读数，不必从厂家手册里重新找一遍所有参数。在 Artisan 的 Ports Configuration 中打开 MODBUS 页签，将现有配置按下面的对照表填入 HiBean。

Artisan 的 .aset 不是 HiBean Modbus JSON，不能直接导入。迁移的是串口参数和寄存器定义，不是 Artisan 的通道序号或验证状态。

先确认连接类型

Artisan 的 Type 可以是 Serial RTU、Serial ASCII、TCP 或 UDP。当前这篇 HiBean 指南只适用于 Serial RTU。如果 Artisan 里用的是 TCP、UDP 或 Serial ASCII，不能把参数照搬到本流程。

串口参数对照

Artisan	HiBean	迁移时注意
Type: Serial RTU	Custom Modbus RTU	只有 Serial RTU 属于本指南范围
Comm Port	串口	换了电脑或转接器后，需要重新选择当前系统的端口
Baud Rate	波特率	数值直接对应
Byte Size	数据位	例如 `8`
Parity: N / E / O	无校验 / 偶校验 / 奇校验	`N` 表示 None，`E` 表示 Even，`O` 表示 Odd
Stopbits	停止位	例如 `1`
Timeout	响应超时	Artisan 使用秒，HiBean 显示毫秒；`0.4` 秒等于 `400 ms`
Retries	无独立输入项	HiBean 使用自己的有界重试策略，不要把 Retries 数字填进超时字段
Delay	无直接对应	如果设备依赖“打开串口后延迟”，先确认 HiBean 能否稳定连接

Artisan 输入项对照

Artisan 用 Input 1 到 Input 10 表示位置通道，HiBean 则要求每个读取项明确选择它的用途，例如豆温、环境温度或火力反馈。

Artisan	HiBean	迁移时注意
Input 1…10	独立的读取项	不保留序号；根据 Artisan 曲线的真实含义选择 BT、ET、火力等信号
Device	从站 ID（Unit ID）	Artisan 中 `0` 表示禁用该 Input，不应创建为 HiBean 读取项
Register	PDU 地址	Artisan 这一列是零基地址；在 HiBean 中开启使用 PDU 地址输入后填入同一数字
Function	寄存器区 / 功能码	`1` 线圈，`2` 离散输入，`3` 保持寄存器，`4` 输入寄存器
Decode	解码预设 / 数据类型	参照下方的 Decode 表
Divider	解析倍率（Scale）	空白为 `1`，`1/10` 为 `0.1`，`1/100` 为 `0.01`
Mode: C / F	设备原始温度单位	只描述寄存器中的温度单位，与 App 显示偏好无关
little-endian words	字节与寄存器顺序	仅影响 32 位数据；勾选对应 `CDAB`，未勾选对应 `ABCD`

Artisan 把前两个 Input 作为主 ET/BT 通道对，后面的 Input 两个一组用于额外设备。但 .aset 可能带有自定义标签和特殊用法，迁移时应以 Artisan 曲线的实际含义为准，不要只凭 Input 号码判断豆温和环境温度。

Decode 对照

Artisan Decode	HiBean 数据类型
uInt16	UInt16
sInt16	Int16
uInt32	UInt32
sInt32	Int32
BCD16	BCD16
BCD32	BCD32
Float32	Float32

Artisan 在这个页面中对 32 位数据使用全局 little-endian words 开关，HiBean 则为每个读取项单独保存顺序。16 位数据通常选 AB。只有厂家手册明确说明寄存器内两个字节反转时，才使用 BA、BADC 或 DCBA 等非标准顺序。

一个完整的迁移例子

假设 Artisan 中某个温度 Input 是：

text

Device: 1
Register: 0
Function: 3
Decode: sInt16
Divider: 1/10
Mode: C

在 HiBean 中配置为：

text

从站 ID: 1
寄存器区: 保持寄存器（FC03）
使用 PDU 地址输入: 开启
PDU 地址: 0
解码预设: int16 × 0.1
设备原始温度单位: 摄氏度

PDU 地址 0 在 HiBean 的厂商显示地址模式中等价于保持寄存器 40001。不要把 Artisan 的 Register: 0 改成 PDU 地址 40001。

在 HiBean 中填写寄存器与解码参数

不要直接搬过来的配置

Scan、optimize 和 fetch full blocks：HiBean 不扫描未知寄存器，读取请求由应用自行规划。
PID 中的 SV、P、I、D 寄存器：不等于 HiBean 的普通控制映射。
ON/OFF Action、writeSingle(...)、事件按钮和滑块命令：不会从 Artisan 自动转换。
Device 为 0 的 Input：这是 Artisan 的禁用项，不是 Modbus 从站 0。
Artisan 已经读到的数值：只能说明旧配置曾经可用，不能替代 HiBean 的逐项读取验证和控制安全恢复。

控制配置必须重建

Artisan 中能执行的写入命令，不代表它已满足 HiBean 的控制安全条件。在 HiBean 中配置火力、风力、滚筒或目标温度时，仍需要明确的反馈读取项、测试值、安全恢复值和完整验证。

本节的术语依据来自 Artisan 官方仓库的 MODBUS 配置界面、MODBUS 帮助和通道换算逻辑。

1. 进入自定义 Modbus 设置

在设备页选择添加设备，找到 Custom Modbus。你可以从空白配置开始，也可以导入别人提供或自己导出的 HiBean Modbus JSON 模板。

自定义 Modbus 的开始方式

导入只会预填字段，不会把设备标记为“已经验证”。选择模板前，HiBean 会再次要求你确认设备已经上电、接线完成，并且可以安全地进行读取和控制测试。

无论从空白配置开始还是导入模板，都必须从串口步骤重新验证，不能跳过。

2. 选择串口并验证链路

先选择 USB-RS485 适配器对应的串口，再按厂家手册填写波特率、数据位、校验、停止位和流控。

选择串口并填写串口参数

macOS 端口通常类似：

text

/dev/cu.usbserial-xxxx
/dev/cu.wchusbserial-xxxx

Windows 端口通常类似：

text

COM3
COM4

点击 测试串口 后，HiBean 只检查这个端口是否能够按当前参数打开。它不会在这一步读取寄存器，因此“串口可打开”不等于“已经找到 Modbus 设备”。

如果测试失败，先检查：

串口是否选对。
适配器是否被 Artisan、串口调试工具或另一个 HiBean 实例占用。
Windows 驱动是否正确安装。
串口参数是否和厂家手册一致。

3. 配置读取项

进入读取页后，先设置轮询周期和响应超时，再配置 HiBean 需要读取的数据。豆温（BT）是必填项，环境温度、进风温度、火力反馈等可以按设备能力添加。

Modbus 读取项列表

厂商手册地址和 PDU 地址

很多手册把保持寄存器写成 40001、40002，把输入寄存器写成 30001。这类数字通常是给人阅读的“厂商手册地址”，并不等于 Modbus 报文中的零基地址。

默认情况下，按厂家手册填写寄存器区和显示地址即可，HiBean 会显示换算后的 PDU 地址。只有资料明确给出零基地址时，才切换到 使用 PDU 地址输入。

如果设备返回 Illegal Address，第一件事就是检查有没有把 40001 和 PDU 地址 0 混用。

数据格式

每个读取项都要和厂家手册一致：

从站 ID
寄存器区 / 功能码
地址
数据类型
字节与寄存器顺序
Scale 和 Offset

例如，厂家写明寄存器原始值 1850 代表 185.0°C，通常需要把 Scale 设为 0.1。如果厂家给的是 32 位浮点数，还需要确认两个寄存器的顺序。

温度原始单位

温度读取项还有一个容易忽略的字段：设备原始温度单位。

读取项中的寄存器和温度单位设置

这个单位描述的是厂家寄存器里的数据，不是你在 HiBean 中选择的显示偏好。例如：

设备寄存器返回 392.0°F，这里就选择华氏度。
即使你习惯在 App 中查看摄氏度，也不要把这里改成摄氏度。

HiBean 会先按厂家单位解释寄存器数据，再按你的 App 温度偏好显示。默认值是摄氏度。

逐项验证

填写完成后，先点击 单次读取。看到合理的真实数据后才能保存读取项。

所有启用的读取项都通过单次读取后，点击下一步。HiBean 还会连续读取三次，确认整组配置可以稳定工作。这里失败时不要急着增加重试次数，先核对地址、数据格式、接线和设备状态。

4. 按需配置控制项

如果你只需要温度曲线，可以直接跳过控制步骤，把设备作为仅监测设备添加。这通常也是首次接入未知设备时更稳妥的做法。

只有在厂家明确提供以下资料时，才建议配置控制：

写入功能码和寄存器地址
允许写入的范围和步长
设备空闲时可以使用的安全恢复值
能确认控制结果的反馈读取项

控制项的验证设置

控制验证会真的向设备写入一次测试值。HiBean 随后读取对应反馈，确认动作生效，再写回并确认安全值。

开始前请确保：

设备没有在烘焙。
测试值不会点火、进豆、排豆或造成其他危险动作。
安全恢复值来自你的设备资料或已确认的空闲状态，不是猜测值。
反馈读取项和控制项表达的是同一个物理量。

控制结果未知时不要重复写入

如果请求超时、连接中断，或者反馈没有达到预期，HiBean 可能无法判断设备是否已经执行。此时不要立即重试。先观察设备状态，返回读取页重新验证读取项，再继续排查。

目标温度控制还需要单独选择厂家写入寄存器使用摄氏度还是华氏度。它同样与 App 显示偏好无关。

5. 复核并添加

最后一页会汇总串口参数、读取项、控制项和设备模式。给设备起一个容易识别的名称，再检查一遍配置。

复核并添加 Modbus 设备

如果没有配置控制项，页面会明确显示这是一个仅监测设备。添加成功后，HiBean 会关闭设置期间使用的临时连接，保存设备，并在正常运行连接中重新建立读取状态。

设置阶段完成过控制验证，不代表设备以后会永久保持可控。断线、修改配置或写入结果未知时，HiBean 会重新收紧控制状态。

6. 添加后修改配置

进入设备设置页，可以看到三个与 Modbus 有关的入口：

已添加设备的 Modbus 设置

只修改串口

更换 USB-RS485 适配器、系统重新分配端口，或厂家要求调整波特率时，使用串口。HiBean 会保留现有读取和控制映射，并重新检查它们是否还能在新链路上工作。

如果检查失败，旧配置会继续保留。

编辑完整配置

需要新增读取项、修改地址、调整数据格式或改变控制项时，使用 编辑 Modbus 配置。完整编辑会从串口步骤重新开始，所有受影响的读取和控制都要重新验证。

导出配置

使用 导出配置 可以保存一份 JSON 模板，方便在另一台电脑上或分享给使用同款设备的人。

已添加设备的设置页不提供“导入配置”。需要使用模板新增设备时，请回到添加设备页，从 Custom Modbus 入口导入。

JSON 模板包含什么

JSON 模板会保存：

串口初值
轮询和超时设置
读取项
控制项

它不会保存：

设备名称、设备 ID 或云端 ID
当前连接状态
历史读数
读取验证结果
控制验证结果或控制授权状态

在另一台电脑导入后，原来的端口名称可能不存在。重新选择当前电脑上的端口，再从第一步完成全部验证。

让 AI 帮你转换 Artisan 配置

如果你已经在 Artisan 中配好了 Modbus，可以让 AI 按本页的字段对照生成 HiBean JSON。这里的 AI 只负责整理资料和转换格式，不能替你判断某个寄存器究竟是豆温、环境温度还是控制命令。

建议只把以下内容交给 AI：

Artisan .aset 文件中的 [Modbus] 段
厂家手册中与串口和寄存器有关的页面
你对每条 Artisan Input 实际用途的说明，例如 Input 1 = ET、Input 2 = BT

不建议把完整 .aset 上传给在线 AI。它可能还包含其他设备设置、网络信息、个人备注或与你当前任务无关的数据。发送前先检查并删除敏感内容。

可导入 JSON 示例

下面这份文件由 HiBean 当前的 Modbus profile 编码器生成，结构可以被 App 识别。它只是一个 BT + ET、9600/8N1、仅监测 的格式示例，不代表你的设备真的使用这些地址。

下载 JSON 示例

json

{
  "kind": "hibean.modbus.rtu.profile",
  "profileVersion": 1,
  "config": {
    "schemaVersion": 2,
    "transport": {
      "kind": "rtu",
      "serial": {
        "portName": "SELECT_LOCAL_PORT",
        "baudRate": 9600,
        "dataBits": 8,
        "parity": "none",
        "stopBits": 1,
        "flowControl": "none"
      }
    },
    "polling": {
      "intervalMs": 1000,
      "responseTimeoutMs": 500,
      "readRetries": 1
    },
    "readMappings": [
      {
        "id": "bean-temperature",
        "signal": "beanTemperature",
        "unitId": 1,
        "functionCode": 3,
        "pduAddress": 0,
        "valueType": "int16",
        "byteOrder": "ab",
        "scale": 0.1,
        "offset": 0.0,
        "rawTemperatureUnit": "celsius",
        "minimum": null,
        "maximum": null,
        "enabled": true
      },
      {
        "id": "environment-temperature",
        "signal": "environmentTemperature",
        "unitId": 1,
        "functionCode": 3,
        "pduAddress": 1,
        "valueType": "int16",
        "byteOrder": "ab",
        "scale": 0.1,
        "offset": 0.0,
        "rawTemperatureUnit": "celsius",
        "minimum": null,
        "maximum": null,
        "enabled": true
      }
    ],
    "controlMappings": []
  }
}

SELECT_LOCAL_PORT 是占位值。导入后必须选择当前电脑上的真实串口。示例中的 PDU 地址 0 和 1、数据类型、倍率、温度单位也必须按你的资料替换。

可以直接交给 AI 的提示词

把下面的提示词、本页链接，以及清理后的 Artisan 配置一起交给 AI：

text

请把我提供的 Artisan Serial RTU Modbus 配置转换成 HiBean Modbus profileVersion 1 JSON。

严格遵守以下规则：
1. 使用本文的 Artisan → HiBean 对照和 JSON 示例，不添加示例之外的字段。
2. Artisan Register 是零基 PDU 地址；不要把 Register 0 改成 40001。
3. Device 0 表示该 Input 已禁用，不生成读取项。
4. Divider 1/10 转为 scale 0.1，1/100 转为 0.01；Mode C/F 转为 rawTemperatureUnit celsius/fahrenheit。
5. 只有在我明确说明 Input 的实际用途时，才能映射成 beanTemperature、environmentTemperature、inletTemperature、heaterPower、fanSpeed、drumSpeed 或 targetTemperature。不要根据 Input 序号猜测。
6. 默认只生成监测配置，controlMappings 必须为空数组。不要转换 PID/SV、writeSingle(...)、ON/OFF Action、事件按钮、滑块或其他写命令。
7. portName 使用 SELECT_LOCAL_PORT，由我导入后选择本机串口。
8. 如果连接类型不是 Serial RTU，或缺少串口参数、Unit ID、用途、Function、Register、Decode、Divider、Mode、字序中的必要信息，先列出缺失项并停止，不要输出 JSON。
9. 信息完整时，只输出一个合法 JSON 代码块，不要附加解释，也不要声称配置已经通过设备验证。

HiBean 指南：<粘贴本页网址>
Artisan 配置：
<粘贴清理后的 [Modbus] 段>
Input 用途说明：
<例如 Input 1 = ET，Input 2 = BT>

AI 输出后，先逐项对照厂家手册。特别检查 functionCode、pduAddress、valueType、byteOrder、scale 和 rawTemperatureUnit。不要只因为 JSON 能被导入，就认为寄存器配置是正确的。

导入不是验证

HiBean 接受 JSON，只说明文件格式和字段范围合法。导入后仍必须从串口步骤开始，完成每条读取、连续读取和所有控制验证。AI 的回答不能替代真实设备测试。

常见问题

找不到串口

重新插拔 USB-RS485 适配器后点击刷新。
macOS 检查是否出现新的 /dev/cu.* 端口。
Windows 打开设备管理器，确认适配器对应的 COM 端口和驱动状态。
关闭可能占用串口的其他程序。

串口可以打开，但读取超时

“串口可打开”只说明电脑能访问适配器。继续检查设备供电、A/B 接线、波特率、校验、从站 ID 和响应超时。

Illegal Function

设备不支持当前功能码。确认该地址属于保持寄存器、输入寄存器、线圈还是离散输入。

Illegal Address

确认寄存器地址属于当前型号，并检查厂家显示地址与零基 PDU 地址是否混用。

数值很大、很小或跳动异常

依次检查数据类型、字节顺序、寄存器顺序、Scale、Offset 和温度原始单位。不要通过放宽有效范围来掩盖错误解码。

控制测试后设备状态不确定

停止重复写入，先在设备本体确认状态。回到读取项重新验证反馈，再根据 HiBean 的诊断信息检查功能码、地址、数据格式和安全恢复值。

仍然无法接入？

准备好以下信息后联系 HiBean 支持：

设备品牌和准确型号
厂家 Modbus 手册或寄存器表
USB-RS485 适配器型号
串口参数
HiBean 显示的安全诊断信息

请不要发送包含账号、密钥或其他私人信息的完整系统日志。

在 HiBean 中接入自定义 Modbus RTU 设备 ​

先确认是否适合 ​

开始前准备 ​

硬件 ​

厂家资料 ​

从 Artisan 迁移 ​

先确认连接类型 ​

串口参数对照 ​

Artisan 输入项对照 ​

Decode 对照 ​

一个完整的迁移例子 ​

不要直接搬过来的配置 ​

1. 进入自定义 Modbus 设置 ​

2. 选择串口并验证链路 ​

3. 配置读取项 ​

厂商手册地址和 PDU 地址 ​

数据格式 ​

温度原始单位 ​

逐项验证 ​

4. 按需配置控制项 ​

5. 复核并添加 ​

6. 添加后修改配置 ​

只修改串口 ​

编辑完整配置 ​

导出配置 ​

JSON 模板包含什么 ​

让 AI 帮你转换 Artisan 配置 ​

可导入 JSON 示例 ​

可以直接交给 AI 的提示词 ​

常见问题 ​

找不到串口 ​

串口可以打开，但读取超时 ​

Illegal Function ​

Illegal Address ​

数值很大、很小或跳动异常 ​

控制测试后设备状态不确定 ​

仍然无法接入？ ​

在 HiBean 中接入自定义 Modbus RTU 设备

先确认是否适合

开始前准备

硬件

厂家资料

从 Artisan 迁移

先确认连接类型

串口参数对照

Artisan 输入项对照

Decode 对照

一个完整的迁移例子

不要直接搬过来的配置

1. 进入自定义 Modbus 设置

2. 选择串口并验证链路

3. 配置读取项

厂商手册地址和 PDU 地址

数据格式

温度原始单位

逐项验证

4. 按需配置控制项

5. 复核并添加

6. 添加后修改配置

只修改串口

编辑完整配置

导出配置

JSON 模板包含什么

让 AI 帮你转换 Artisan 配置

可导入 JSON 示例

可以直接交给 AI 的提示词

常见问题

找不到串口

串口可以打开，但读取超时

Illegal Function

Illegal Address

数值很大、很小或跳动异常

控制测试后设备状态不确定

仍然无法接入？