Hot-Connect 组管理 (ETG.1020 §8.3)

Hot-Connect 把「扫描时可能不在场」的从站登记成一组。组表是扫描期登记：必须在 SetNetwork / 扫描前调用 AddGroup。扫描按 Alias 匹配，把组标成 present / absent。不调用 AddGroup 时所有从站仍是 mandatory（缺失即 AL_ERROR）。扫描时某组缺席不再算错，其余从站可以继续进 OP。

运行中插回不会自动进 OP。 主站可报 Offline/Online；应用层要自己处理状态机。不要指望插回去就自动进 OP；断电重连、换同型号也不会由主站自动拉回 OP。

典型应用：

• 工艺夹具 / 末端工具按需挂接，不接也要让产线主站正常跑
• 移动机器人 / AGV 上的可拆卸 IO 模块
• 工厂调试 / 临时探针，做完即拔

通过 darra::ethercat::master_hot_connect 命名空间下的自由函数管理 Hot-Connect 组。事件订阅请参见 事件 - SlaveIdentityMismatch。

扫描前登记

• AddGroup 必须在 SetNetwork / 扫描前调用
• 扫描缺席不卡 SAFEOP+ERROR
• 运行中插回不会自动进 OP；主站可报 Offline/Online，应用层自己处理状态机

Alias 地址硬性要求

• Alias Address (ESC 0x0012) 必须预先烧录到从站 EEPROM
• 必须 非 0 且 组内唯一
• Alias=0 的从站不支持 Hot-Connect (ETG.1020 §8.3)

可通过 EtherCAT 配置工具 / slave.WriteRegister(0x0012, ...) 一次性烧录。

HotConnectStatus 枚举

namespace darra::ethercat {

enum class HotConnectStatus : int {
    Unknown = -1,   // 组未注册或底层查询失败
    Absent  = 0,    // 组在当前扫描中未探测到
    Present = 1     // 组在当前扫描中探测到
};

}

HotConnectGroup 快照

HotConnectGroup 是组的一次性只读快照（由 Enumerate() 返回）。

struct HotConnectGroup {
    uint16_t groupId;             // 用户分配的组 ID, 1..65535
    uint16_t aliasAddress;        // 期望 Alias 地址 (必须非 0)
    uint32_t vendorId;            // 期望 VendorID, 0=不校验
    uint32_t productCode;         // 期望 ProductCode, 0=不校验
    bool     isPresent;           // 是否在当前扫描中探测到
    uint16_t detectedSlaveIndex;  // 探测到时匹配的 从站索引, 0=未匹配

    HotConnectStatus Status() const noexcept;
};

类别	字段	类型	读写	说明
组标识	groupId	uint16_t	只读	用户分配的组 ID（1..65535，同主站唯一）
	aliasAddress	uint16_t	只读	期望 Alias 地址（ESC 0x0012，非 0）
匹配条件	vendorId	uint32_t	只读	期望 VendorID，传 0 表示不校验
	productCode	uint32_t	只读	期望 ProductCode，传 0 表示不校验
探测结果	isPresent	bool	只读	当前扫描是否探测到
	detectedSlaveIndex	uint16_t	只读	命中时匹配的从站索引（1-based）
	Status()	HotConnectStatus	只读	等价于 isPresent ? Present : Absent

组管理函数

所有函数都在 darra::ethercat::master_hot_connect 命名空间下。每个主站最多支持 master_hot_connect::MaxGroups = 32 个 Hot-Connect 组。

AddGroup()

namespace darra::ethercat::master_hot_connect {

bool AddGroup(EtherCATMaster& m,
              uint16_t groupId,
              uint16_t alias,
              uint32_t vendorId = 0,
              uint32_t productCode = 0);

}

向扫描期组表登记一个 Hot-Connect 组。须在 SetNetwork / 扫描前调用。 运行中插回不会因本组登记而自动进 OP。

参数：

• m — 主站实例
• groupId — 组 ID（1..65535，同主站唯一）
• alias — Alias 地址（必须非 0）
• vendorId — 期望 VendorID（0 不校验）
• productCode — 期望 ProductCode（0 不校验）

返回值： true = 已写入组表；false = 未登记（底层库未就绪 / 参数非法 / 组表已满 / groupId 重复）。

RemoveGroup()

bool RemoveGroup(EtherCATMaster& m, uint16_t groupId);

删除指定组（恢复组内从站为 mandatory）。返回 false 表示该组未注册或底层库未就绪。

GetGroupStatus()

HotConnectStatus GetGroupStatus(const EtherCATMaster& m, uint16_t groupId);

查询组当前的 Present / Absent 状态。组未注册或底层查询失败时返回 HotConnectStatus::Unknown。

Enumerate()

std::vector<HotConnectGroup> Enumerate(EtherCATMaster& m);

枚举主站当前所有已注册的 Hot-Connect 组。底层一次性把 C 端组结构数组（HotConnectGroupNative）拷出来转成 HotConnectGroup vector，最多 MaxGroups = 32 项。底层库未就绪 / 没有任何组时返回空 vector。

ClearAll()

bool ClearAll(EtherCATMaster& m);

清空当前主站的全部 Hot-Connect 组，常用于切换工艺方案 / 测试用例之间的复位。返回 true 只表示清空请求已发出（底层入口无返回值，无法回读清空结果）；false = 底层库未就绪，请求未发出（组表保持原样）。

GroupCount()

int GroupCount(const EtherCATMaster& m);

当前已注册组数（0..32）。

完整示例

#include "ethercat.hpp"
using namespace darra;
using namespace darra::ethercat;

int main() {
    EtherCATMaster master(dll);

    // 1. 扫描前登记组表（必须在 SetNetwork / 扫描前，不是运行中自动登记）
    master_hot_connect::AddGroup(master,
                                  /*groupId*/ 1,
                                  /*alias*/   0x1001,
                                  /*VID*/     0x00000002,
                                  /*PID*/     0x07D81052);

    // 2. 可拆卸 AGV IO 模块登记成组 #2（不校验 VID/PID）
    master_hot_connect::AddGroup(master, /*groupId*/ 2, /*alias*/ 0x2001);

    // 3. SetNetwork → Build。Init→PreOp 扫描按 Alias 匹配，缺席组标 absent
    master.SetNetwork("\\Device\\NPF_{...}").Build();

    // 4. 进入 OP — 扫描缺席不卡 SAFEOP+ERROR。运行中插回不会自动进 OP
    master.SetState(EcState::OP);
    master.Start();

    // 5. 业务运行中查询某组在不在（Present/Absent 是扫描结果，不是自动进 OP）
    auto status = master_hot_connect::GetGroupStatus(master, 1);
    printf("夹具组: %s\n",
           status == HotConnectStatus::Present ? "已挂接" :
           status == HotConnectStatus::Absent  ? "未挂接" : "未知");

    // 6. 列出所有组
    for (auto& g : master_hot_connect::Enumerate(master)) {
        printf("Group %u  alias=0x%04X  %s  detectedSlaveIndex=%u\n",
               g.groupId, g.aliasAddress,
               g.isPresent ? "Present" : "Absent",
               g.detectedSlaveIndex);
    }

    // 7. 切换工艺前清空所有 Hot-Connect 组（通常在重新 SetNetwork 前）
    master_hot_connect::ClearAll(master);

    return 0;
}

配合事件订阅

运行中插回不会自动进 OP。身份不符时 SDK 提供 OnHotPlug() 包装函数，把 master.Events().OnSlaveIdentityMismatch(...) 的参数直接打包成 HotPlugIdentityMismatchEvent 结构供消费：

struct HotPlugIdentityMismatchEvent {
    uint16_t masterIndex;
    uint16_t slaveIndex;
    uint32_t expectedVendor, expectedProduct, expectedRevision;
    uint32_t actualVendor,   actualProduct,   actualRevision;
};

using HotPlugCallback = std::function<void(const HotPlugIdentityMismatchEvent&)>;

void OnHotPlug(EtherCATMaster& m, HotPlugCallback cb);

示例：

darra::ethercat::OnHotPlug(master, [](const auto& e) {
    printf("从站 %u 身份不符:\n", e.slaveIndex);
    printf("  期望 VID=0x%08X PID=0x%08X RevID>=0x%08X\n",
           e.expectedVendor, e.expectedProduct, e.expectedRevision);
    printf("  实际 VID=0x%08X PID=0x%08X RevID=0x%08X\n",
           e.actualVendor, e.actualProduct, e.actualRevision);

    // UI 弹窗 / 提示用户检查或更换设备...
    // 操作员确认后调用:
    //   master_other::acknowledge_slave_replacement(master, e.slaveIndex);
});

详见 事件 - SlaveIdentityMismatch 与 属性与状态机 - 热插拔自修复。

参考

ETG.1020 §8.3 Hot-Connect Group 管理规则。