Open uCode

# 硬件设备接口

uCode v4.0 提供了硬件接入的能力，硬件接入实际就是增加操作硬件的可能, 并且抽象了一系列的接口用来描述, 统称为： 硬件设备 对应的接口名字为: DeviceConnectionInterface 简称为: Device，按照这套标准，用户就可以通过 uCode v4.0 标准的硬件连接流程连接对应的硬件

# 硬件设备连接步骤

插件生命周期的章节有介绍到, 硬件设备接口实例的生命周期.

这里会介绍硬件设备连接交互中每个步骤都会对应硬件连接设备接口的若干方法, 这里只会简单介绍对应关系

具体的接口的详细信息, 可以参照自定义硬件协议的章节

  1. 选择设备连接类型(可选)
  2. 环境检查(可选)
  3. 连接提示(可选)
  4. 设备扫描(可选)
  5. 设备连接
  6. 连接完状态

# (1) 选择设备连接类型

当一个硬件有多种连接方式的时候, 会有如下界面出现, 需要用户选择一种连接方式

连接协议都必须绑定一个连接类型, 这是作为连接类型的标识, 接口我们定义为: DeviceType

DeviceType (点击查看 API 文档)

为了更好的适应不同的连接类型, 我们划分了三种连接类型

  • AutoConnectDeviceType 自动连接类型
  • InputIdDeviceType 输入连接类型
  • DiscoverDeviceType 扫描连接类型

每种连接类型在 用户交互 都对应着不一样的用户界面.

# 自动连接类型 AutoConnectDeviceType

自动连接类型只有一个按钮, 主要用于, 无法获取搜索列表, 或者不需要提供搜索列表的连接类型

例如:

  • 固定的 IP 地址, 不需要进行搜索, 硬件连接设备
  • WebBluetooth, WebSerial, WebHID 等网络硬件协议 (由系统接管, 无法获取搜索列表), 这种类型的连接设备

自动连接类型的 TS 定义:

type AutoConnectDeviceType = {
  connectType: "auto";
  id: string; // 唯一标识ID
  name?: string; // 显示的名字
  icon?: string; // 图标 256 * 256
  tip?: DeviceConnectionTip; // 连接提示
};

# 输入连接类型 InputIdDeviceType

输入连接类型, 和自动连接类型对比, 多了一个输入信息的输入框, 所以叫 输入连接类型, 该类型会把 输入的数据, 作为 device.id 传入 DeviceConnectionInterface 的 connect 函数中

适合需要用户提供某些关键信息作为连接参数的连接类型:

例如:

  • 输入 IP 地址
  • 输入序列号

输入连接类型的 TS 定义:

type InputIdDeviceType = {
  connectType: "inputDeviceId";
  id: string; // 唯一标识ID
  name?: string; // 显示的名字
  icon?: string; // 图标 256 * 256
  tip?: DeviceConnectionTip; // 连接提示
  configInfo?: InputDeviceIdConfigType; // 输入配置
};

和自动连接类型不一样的是, 多了 ConfigInfo 用于配置输入的一些参数

export type InputDeviceIdConfigType = {
  inputPlaceholder?: string; // 输入提示
  verifyRegex?: string | RegExp; // 校验的正则
  invalidInputTip?: string; // 校验出错的提示
};

# 扫描连接类型 DiscoverDeviceType

扫描连接类型是, 提供一个设备列表, 可以让用户选择的连接方式

  • 串口
  • 客户端/移动端 蓝牙

以及其他大部分需要用户选择的连接类型

扫描连接类型的 TS 定义:

type DiscoverDeviceType = {
  connectType: "discover";
  id: string; // 唯一标识ID
  name?: string; // 显示的名字
  icon?: string; // 图标 256 * 256
  tip?: DeviceConnectionTip; // 连接提示
  scanTime?: number; // 扫描的时间 时间到达自动停止
};

扫描连接类型和前面的不太一样, 由于历史问题, 扫描连接类型需要单独提供一个 Discover 接口的实现, 后面注册的时候会提到

# (2) 环境检查

在 USV 0.7 新增了环境检查的连接步骤, 这是一个可选步骤

例如: 下面的动图举例了, 检查 uCodeLink 是否启动的例子

环境检查

环境检查的步骤新增了3个接口

  • enableCheckEnv() 该方法是同步的, 主要用于避免每次都会有 等待界面出现, 如果返回 false 则不会调用 checkEnv()
  • checkEnv() 环境检查接口, 异步接口, 抛出错误, 可以引导用户进行错误处理
  • handleError() 错误处理, 在上面的 UCodeLink 的案例中, 当用户点击了启动或者下载的按钮, 会调用 handleError() 进行下一步处理

# (3) 连接提示

在 USV 0.7 我们新增了连接提示一个专门的连接步骤, 在此之前, 输入连接类型是带有部分连接提示的功能, 现在扩展为通用的, 可以支持任何连接类型

目前我们支持 5 种连接提示:

  • text 纯文本
  • image 图片
  • video 视频
  • gif Gif 动画
  • markdown Markdown 文档

ConnectionTip 的 TS 类型:

type DeviceConnectionTip =
  | {
      type: "text";
      data: string;
    }
  | {
      type: "image";
      data: {
        src: string;
        text: string;
      }[];
    }
  | {
      type: "video";
      src: string;
    }
  | {
      type: "gif";
      src: string;
    }
  | {
      type: "markdown";
      data: string;
    };

# 文本类型 连接提示

纯文本的连接提示, 支持换行

{
  type: 'text',
  data: `1.短按一下机器人胸前按钮，胸口灯转为绿色时，对机器人说“播报IP地址”
2.打开YansheeApp，点击左上角图标展开左侧边栏，从“设置-机器人信息-IP地址”查看
3.连接Yanshee与显示器，鼠标悬浮于桌面右上角WiFi图标可查看到IP地址
4.确保uCode与Yanshee机器人在同一局域网`,
}

# 图片类型 连接提示

图片类型的连接 是一个数组, 可以支持滑动, 并且每张图片可以附带文字, 图片可以点击放大预览

图片链接, 可以是 base64 或者 url

{
      type: 'image',
      data: [
        {
          src: ImageTip,
          text: `UC计划中只有独角兽钢弹及新安州两部MS搭载，机体受到脑波映像影响直接反映的思考系统，凌驾于手动操纵MS的反应以及动作精度。而此系统与完全精神感应骨架组合开发出独角兽钢弹搭载特殊管制系统的NT-D系统，驾驶员与精神感应思想操纵系统交感下将独角兽钢弹提升至极限，此时机动性将会得到飞跃性的提升，透过精神感应系统的控制，其推进器从点火、推进到煞停的时间非常的短暂，速度甚至能用“瞬间移动”来形容，驾驶员将要承受强大的G力和对大脑的冲击力，一般人身体无法负担，考虑到这一点，所以大约只能发动5分钟左右。另外，NT-D发动时，精神框架会与生物传感器产生作用，在机体的附近产生像I-力场（I-Field）的光束排斥作用。
          `,
        },
        {
          src: 'https://img-baofun.zhhainiao.com/fs/32054fe01be9b24ecb512144b391181c.jpg',
          text: `UC计划中只有独角兽钢弹及新安州两部MS搭载，机体受到脑波映像影响直接反映的思考系统，凌驾于手动操纵MS的反应以及动作精度。而此系统与完全精神感应骨架组合开发出独角兽钢弹搭载特殊管制系统的NT-D系统，驾驶员与精神感应思想操纵系统交感下将独角兽钢弹提升至极限，此时机动性将会得到飞跃性的提升，透过精神感应系统的控制，其推进器从点火、推进到煞停的时间非常的短暂，速度甚至能用“瞬间移动”来形容，驾驶员将要承受强大的G力和对大脑的冲击力，一般人身体无法负担，考虑到这一点，所以大约只能发动5分钟左右。另外，NT-D发动时，精神框架会与生物传感器产生作用，在机体的附近产生像I-力场（I-Field）的光束排斥作用。
        `,
        },
      ],
}

# 视频类型 连接提示

视频提示, 只支持在线 URL, 调用的是系统自带的视频播放, 支持全屏

{
  type: 'video',
  src: 'https://edu-web.ubtrobot.com/ucode4/test/v4.9.0-1-dc9c9e57-2022_08_30_07_06/test-video-for-connection.mp4',
}

# (4) 扫描设备

这个是 DiscoverDeviceType 扫描连接类型 独有的连接步骤

scan device

如果定义为 DiscoverDeviceType 连接类型时, 需要实现一个新的接口实例

IDeviceDiscover

包含以下方法:

  • startDiscover 开始扫描
  • stopDiscover 停止扫描
  • dispatchOnDiscover 抛出设备发现设备的事件

# (5) 设备连接

无论是哪种连接方式, 连接接口都是必须提供的接口

  • connect 连接

设备开始连接的时候会调用这个接口, 接口方法是异步的, 抛出错误会跳到错误页面

# (6) 连接完状态

  • 连接成功, 自动关闭连接窗口,

连接成功

  • 连接失败, 显示连接错误信息

连接失败

← 内置硬件协议 →