设备发现与连接

设备发现

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

from wuji_sdk import SdkManager

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

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

扫描局域网内通过以太网连接的 Wuji 设备。返回的 DiscoveredDevice 包含设备序列号和地址。

连接设备

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

自动连接

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")

按 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() 查询。

按手性连接

双手设备（如 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
)

多设备管理

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")

断开连接

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

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

目录