设备发现与连接

设备发现

使用 SdkManager.scan() 扫描局域网内的 Wuji 设备：

from wuji_sdk import SdkManager

manager = SdkManager.instance()
devices = manager.scan()

for dev in devices:
    print(f"SN: {dev.sn}, 类型: {dev.device_type}, 地址: {dev.address}")

扫描局域网内以太网连接与本机 USB 接入的 Wuji 设备。返回的 DiscoveredDevice 包含设备序列号、地址和设备类型。device_type 为 DeviceType 枚举（WujiGlove / WujiHand2 / WujiHand），连接前即可判断设备类型。Unknown 表示扫描时未获取到类型或当前 SDK 版本不识别。

网络前提：以太网设备使用静态 IP，不使用 DHCP。扫描或连接前，把电脑上对应网卡设到同一网段（如 192.168.1.50，避开各设备默认地址），否则无法发现或连接设备。

Wuji Hand 2：左手 192.168.1.110，右手 192.168.1.111，地址详情与修改方式见 Wuji Hand 2 SDK 参考
Wuji Glove：左手 192.168.1.100，右手 192.168.1.101，配置步骤见 Wuji Glove 使用前准备
Wuji Hand：USB 直连，无需网络配置

连接设备

所有连接 API 中的 device_name 是本地别名，只用于后续按名取设备、组织资源路径，不参与设备选择，也不决定返回的句柄类型。返回类型由实际连上的设备型号决定。要求非空且不含 /、.。

选择连接方式

按当前发现的设备数量选择，各 API 详见自动连接、指定 SN 连接、指定地址连接、按 USB 连接与按手性连接：

scan() 当前能发现几台设备？
│
├─ 恰好一台 ──▶ auto_connect()——USB / 以太网都适用
│
└─ 多台 ▶ connect() 显式指定——sn / address / handedness 互斥，三选一
     ├─ sn=...——任何设备，最精确（USB 设备可先按 TransportType.Usb 筛出）
     ├─ address=...——已知设备 IP 时直连
     └─ handedness=...——按左右手（Wuji Hand 2 / Wuji Glove）
          └─ 多台同手性 ▶ AmbiguousHandedness ▶ 改用 sn

任一方式都可叠加连接选项配置超时、重试与设备共享。

自动连接

auto_connect() 连接当前发现的那台设备。若发现多台，会因目标无法唯一确定而失败，此时改用 connect() 显式指定：

glove = manager.auto_connect(device_name="glove")
print(f"已连接: {glove.serial_number}")

指定 SN 连接

通过设备序列号连接特定设备：

glove = manager.connect(sn="WG1JA00XXXXXXXXX", device_name="glove")

指定地址连接

通过 IP 地址和端口手动连接：

glove = manager.connect(address="192.168.1.100:50000", device_name="glove")

address 必须包含端口。IPv4 使用 IP:端口，当前不支持 IPv6。仅传入 IP 地址时，SDK 返回缺少端口错误，不再将该地址识别为 USB 路径。

按 USB 连接

Wuji Hand 通过 USB 接入。从 SdkManager.scan() 按 TransportType.Usb 筛选：

from wuji_sdk import SdkManager, TransportType

manager = SdkManager.instance()
usb_devices = [d for d in manager.scan() if d.transport_type == TransportType.Usb]

hand = manager.connect(sn=usb_devices[0].sn, device_name="wuji_hand")
print(f"已连接: {hand.serial_number} ({hand.handedness_name()})")

若 USB 总线上同时接入了触觉手套，且手性匹配，SDK 会自动配对接入。可通过 hand.is_tactile_attached() 查询，该状态反映当前在位情况，运行中拔出手套后转为 False。拔出后触觉状态流的 state 变为 0（不在位），其余触觉读取与订阅返回携带 tactile_not_present 的错误，手本体不受影响继续工作。重新接入手套需重新连接手。

按手性连接

双手设备（如 Wuji Hand 2、Wuji Glove）可直接按左右手连接，无需事先查询序列号。SDK 自动扫描局域网，按序列号第 4 位（J 为左手、K 为右手）筛选唯一目标：

from wuji_sdk import Handedness

# 连接右手设备
hand = manager.connect(handedness=Handedness.Right, device_name="wuji_hand_2")

# 连接左手手套
glove = manager.connect(handedness=Handedness.Left, device_name="wuji_glove")

handedness 与 sn、address 互斥，三者只能指定其一。

若网络中没有匹配手性的设备，抛出 DeviceNotFound。若存在多个同手性设备，抛出 AmbiguousHandedness 并列出所有候选序列号，此时请改用 sn 显式指定。

连接选项

通过 ConnectOptions 配置连接参数：

from wuji_sdk import ConnectOptions

options = ConnectOptions(
    timeout_ms=1000,   # 连接超时（毫秒）
    retry_count=3      # 重试次数
)

glove = manager.connect(
    sn="WG1JA00XXXXXXXXX",
    device_name="glove",
    options=options
)

enable_bridge（默认 True）控制是否允许多个 SDK 实例（含其他主机上的进程）连接同一设备。开启时本进程把已连接的设备共享出去。设为 False 表示独占，其他实例无法经本进程连接该设备。

多设备管理

SDK 支持同时连接多个设备，每个设备通过 device_name 唯一标识：

left = manager.connect(handedness=Handedness.Left, device_name="left_hand")
right = manager.connect(handedness=Handedness.Right, device_name="right_hand")

# 获取已连接设备列表
all_devices = manager.get_connected_devices()
for name, device in all_devices:
    print(f"{name}: {device.serial_number}")

# 按名称获取设备
left = manager.get_device(device_name="left_hand")

左右手用不同 device_name 即可同进程并存。重复连接同一活跃设备会抛出 SessionAlreadyExists 异常，不会断开前一次连接，沿用既有句柄即可。

断开连接

# 断开指定设备
manager.disconnect(device_name="glove")

# 或通过设备对象断开
glove.disconnect()

# 断开当前管理器中的所有设备
manager.disconnect_all()

断开连接后，该设备上的所有订阅会自动关闭。重新连接需要重新建立订阅。

SdkManager 负责维护设备连接。删除或替换设备对象不会断开连接。连接仅在调用 disconnect()、disconnect_all() 或进程退出时关闭。长时间运行的程序应在 finally 块中显式断开连接。使用 enable_bridge=False 独占连接时，未关闭的连接会阻止其他客户端接入设备。