#核心概念

本文档介绍激光扫地机开发中的关键术语和设计理念，帮助你更好地理解平台架构。

#数据流方案

激光扫地机由于品类的特殊性，在数据流上会集合多种通信类型：dp 数据、p2p 数据、oss 数据。

#dp 数据

针对一些机器控制、状态等功能，是通过 dpCode 的方式完成设备与面板的通信。

方案特点： 涂鸦通用的通信方式，开发者接入和理解成本较低，但是会收到数据长度的限制，比如地图、路径等大数据传输无法使用此方案。

#p2p 数据

使用涂鸦地图协议，App 使用 P2P 和扫地机进行连接，属于点对点连接，数据不经过云端。在实时地图和实时路径推送上会使用此方案。

方案特点： 不占用服务器和服务器网络带宽，成本较低。受网络波动影响较大。受外界因素影响较小，可用性较高。

#oss 数据

使用涂鸦地图协议，地图使用 api 接口上传 OSS 云存储，面板向云端轮询请求 oss 文件，并下载解析进行渲染。在清扫记录和多地图管理中会使用此方案。

方案特点： 占用大量云存储资源和网络流量资源，成本高，受网络波动较小。

#地图坐标系

机器人进行一次新清扫任务时，以机器人从初始位置出发，边清扫边建图，形成清扫地图和清扫路径，地图逐渐扩大，路径不断累积，过程中涉及世界坐标系、机器坐标系以及 APP 显示的屏幕坐标系统。

#世界坐标系

实际的物理坐标系，即房间的平面坐标系，机器人每次清扫时，以世界坐标系的某一个点作为起始点，而且在本次清扫中，这个起始点在世界坐标系中的位置是不变的。世界坐标系，用于参照和理解机器坐标系。

#机器坐标系

机器人以初始点为原点，参照世界坐标系，建立机器坐标系。清扫过程中，路径点均参照以该原点，得到坐标值。

#屏幕坐标系

APP 绘图时使用，以屏幕左上角 R(0,0) 为坐标系原点。

#地图坐标的转换

地图数据

机器清扫后形成的地图是一个不规则的多边形，为方便处理，取多边形的外接矩形，作为机器的地图。地图数据，是以 UINT8_T 形式的数组，压缩前，地图总像素点为 Map_width * Map_height，地图数组第一个数据点 UINT8_T0，即为左上角 R(0,0)。

机器原点 O(x,y)，x/y 为相对于 R 的像素个数。随着清扫的进行，地图宽高会改变，原点 O 在地图数组的位置也会变化（x/y 值改变）。

说明：APP 绘图时，以原点 O 作为固定，等同于世界坐标系下，机器人初始位置不变。

路径数据

路径数据是走过的位置点的集合，其坐标为 INT16 的值，当前位置点为 P(x,y)，x/y 为 P 点相对于 O 点的值。

说明：路径坐标传输值 = 路径坐标原值 * 10，以兼顾精度与效率。

区域框等数据

区域清扫框、禁区框、虚拟墙线、指哪扫哪点等坐标数据，其坐标为 INT16 的值，坐标点 M(x,y)，x/y 为 M 点相对于 O 点的值，基于绘制坐标系。

说明：区域框坐标传输值 = 区域框坐标原值 * 10，以兼顾精度与效率。

#P2P 通信

#简介

P2P 通俗讲实际上就是点对点的通信，在机器人业务中使用 P2P 主要是建立手机和机器人的通信连接，这种通信连接不经过云端服务器来作为媒介传递数据（但需要云端服务器做打洞建联），从而可以在局域网环境或者广域网环境下，节省使用云端服务器的网络及存储开销成本。查看更多

#交互指令说明

机器运行后，本地存储全量地图数据和路径数据，用户在 APP 上打开设备面板后，会发起 P2P 建连，当建立连接成功后，机器上报本地缓存的地图和路径数据。

地图数据

地图数据为全量形式，当机器周围环境发生变化时，此数据会更新，机器需先缓存在本地，首次建立连接后必须上报，之后可定时或有更新时主动上报。

【注意】上报频率建议无变化不上报、有变化大于 5S 的频率上报。

路径数据

当机器路径数据变化时，为提高传输效率，采用全量和增量结合方式上报：

APP 首次建立连接后，机器响应，通过全量接口，上报全量路径，之后可定时或有更新时主动上报。

【注意】上报频率建议无变化不上报、有变化大于 2S 的频率上报。

#流程图

面板与设备之间建立 P2P 是一个很复杂的过程，APP 提供了多个方法来完成整个建立连接的流程，具体如下：

sequenceDiagram
actor User
User ->> Panel: 进入地图首页
Panel->>App: 调用ty.p2p.P2PSDKInit,初始化P2P SDK
App-->>Panel:回调初始化状态
Panel->>App: 调用 ty.p2p.connectDevice，设备与app建立p2p连接
App->>Device: 建立连接
Device-->>App:回调连接状态
App-->>Panel:回调连接状态
Panel->>App:通过ty.p2p.downloadStream下载地图数据
Device-->>App:p2p通道发送数据
Panel->>App:注册onStreamPacketReceive事件，监听收到数据包事件
App-->>Panel:通知面板onStreamPacketReceive事件
Panel->> Panel: emit receiveMapData，
Panel->> Panel: emit receivePathData

#如何开发

为了能够让面板开发者能够更关注数据的处理，我们将建立 P2P 建立连接的过程封装到了 @ray-js/robot-data-stream 库中。

// 引入@ray-js/robot-data-stream模块
import { StreamDataNotificationCenter, useP2PDataStream } from '@ray-js/robot-data-stream';

const onMapData = (mapDataStr: string) => {
    // 这里收到的mapDataStr为设备上报的地图数据
    // 你的业务逻辑
};

const onPathData = (pathDataStr: string) => {
    // 这里收到的pathDataStr为设备上报的路径数据
    // 你的业务逻辑
};

const { appendDownloadStreamDuringTask } = useP2PDataStream(
  // 设备id
    getDevInfo().devId,
    onMapData,
    onPathData,
    {
      // 小程序使用的App日志的tag，有需要可以自行更改，用于后期遇到线上问题，通过上传App日志检索该tag进行问题定位
      logTag: APP_LOG_TAG,
      // 可选参数, 机器人使用视觉识别的缩略概况数据从这里抛出，如果机器没有此功能可以忽略此方法
      onReceiveAIPicData,
      // 可选参数, 机器人使用视觉识别的高清原图从这里抛出，如果机器没有此功能可忽略
      onReceiveAIPicHDData,
    }
  );