## Core Concepts

This document introduces key terms and design concepts in laser sweeper vacuum development to help you better understand the platform architecture.

### Data Flow Solution

Due to the special nature of laser sweeper vacuums, multiple communication types are integrated in the data flow: dp data, p2p data, and oss data.

#### dp Data

For machine control and status functions, communication between devices and panels is completed through dpCode.

**Solution Characteristics:** Tuya's universal communication method with low developer access and understanding costs, but subject to data length limitations. Large data transmissions such as maps and paths cannot use this solution.

#### p2p Data

Using Tuya map protocol, the App connects to the sweeper vacuum using P2P, which is a point-to-point connection where data does not pass through the cloud. This solution is used for real-time map and real-time path push.

**Solution Characteristics:** Does not occupy server and server network bandwidth, low cost. More affected by network fluctuations. Less affected by external factors, high availability.

#### oss Data

Using Tuya map protocol, maps are uploaded to OSS cloud storage via API interface, and the panel polls the cloud to request oss files, downloads and parses them for rendering. This solution is used in cleaning records and multi-map management.

**Solution Characteristics:** Occupies large amounts of cloud storage resources and network traffic resources, high cost, less affected by network fluctuations.

### Map Coordinate System

When a robot performs a new cleaning task, the robot starts from the initial position and builds a map while cleaning to form a cleaning map and cleaning path. The map gradually expands and paths accumulate continuously. This process involves the world coordinate system, machine coordinate system, and the screen coordinate system displayed by the APP.

![Coordinate System](https://images.tuyacn.com/rms-static/5cbd0db0-ae38-11ef-aa47-ab559e071ba6-1732874256907.jpeg?tyName=coordinateSystem-en.jpeg)

#### World Coordinate System

The actual physical coordinate system, that is, the plane coordinate system of the room. Each time the robot cleans, a certain point in the world coordinate system is used as the starting point, and in this cleaning, the position of this starting point in the world coordinate system is unchanged. The world coordinate system is used to refer to and understand the machine coordinate system.

#### Machine Coordinate System

The robot takes the initial point as the origin and refers to the world coordinate system to establish the machine coordinate system. During the cleaning process, path points are all referenced to this origin to obtain coordinate values.

#### Screen Coordinate System

Used when the APP draws, with **R(0,0)** in the upper left corner of the screen as the origin of the coordinate system.

#### Map Coordinate Conversion

**Map Data**

The map formed by the machine after cleaning is an irregular polygon. For convenience of processing, the circumscribed rectangle of the polygon is taken as the map of the machine. The map data is an array in the form of UINT8_T. Before compression, the total pixel points of the map are Map_width \* Map_height, and the first data point of the map array, UINT8_T0, is the upper left corner R(0,0).

The machine origin is O(x,y), where x/y is the number of pixels relative to R. As the cleaning progresses, the width and height of the map will change, and the position of the origin O in the map array will also change (x/y values change).

Note: When the APP draws, the origin O is used as a fixed point, which is equivalent to the initial position of the robot in the world coordinate system.

**Path Data**

Path data is a collection of passed position points. Its coordinates are INT16 values. The current position point is P(x,y), and x/y is the value of point P relative to point O.

Note: Path coordinate transmission value = original path coordinate value \* 10, to balance accuracy and efficiency.

**Area Frame and Other Data**

Coordinate data such as area cleaning frames, no-go zone frames, virtual wall lines, and point-to-sweep points. Their coordinates are INT16 values. Coordinate point M(x,y), x/y is the value of point M relative to point O, based on the drawing coordinate system.

Note: Area frame coordinate transmission value = original area frame coordinate value \* 10, to balance accuracy and efficiency.

### P2P Communication

#### Introduction

P2P, in simple terms, refers to point-to-point communication. In the context of robotics, P2P is primarily used to establish a communication connection between the smartphone and the robot. This communication connection does not use a cloud server as a medium to transmit data (though a cloud server is needed to facilitate hole punching and connection establishment), allowing for savings in network and storage costs associated with using cloud servers in both local and wide area network environments. [Learn more](https://en.wikipedia.org/wiki/Peer-to-peer)

#### Interaction Command Description

After the robot is operational, it locally stores complete map and path data. When the user opens the device panel on the APP, a P2P connection is initiated. Once the connection is successfully established, the robot reports the locally cached map and path data.

**Map Data**

The map data is in full form. When the surrounding environment of the machine changes, the data will be updated. The machine needs to cache it locally first. After the connection is established for the first time, it must be reported, and then it can be reported periodically or when there are updates.

[Note] The reporting frequency is recommended: do not report if there is no change, report if there is a change greater than 5S.

**Path Data**

When the machine path data changes, in order to improve transmission efficiency, a combination of full and incremental methods is used to report:

After the APP establishes a connection for the first time, the machine responds by reporting the complete path through the full interface. Subsequently, it can actively report at scheduled intervals or when there are updates.

[Note] The reporting frequency is recommended: do not report if there is no change, report if there is a change greater than 2S.

#### Flowchart

Establishing a P2P connection between the panel and the device is a complex process. The APP provides multiple methods to complete the entire connection establishment process, as detailed below:

```mermaid
sequenceDiagram
actor User
User ->> Panel: Enter the map homepage
Panel ->> App: Call ty.p2p.P2PSDKInit to initialize the P2P SDK
App -->> Panel: Callback initialization status
Panel ->> App: Call ty.p2p.connectDevice to establish a P2P connection between the device and the app
App ->> Device: Establish connection
Device -->> App: Callback connection status
App -->> Panel: Callback connection status
Panel ->> App: Download map data through ty.p2p.downloadStream
Device -->> App: Send data through the P2P channel
Panel ->> App: Register onStreamPacketReceive event to listen for received data packet events
App -->> Panel: Notify panel of onStreamPacketReceive event
Panel ->> Panel: emit receiveMapData,
Panel ->> Panel: emit receivePathData
```

#### How to Develop

To enable panel developers to focus more on data processing, we have encapsulated the process of establishing a P2P connection into the `@ray-js/robot-data-stream` library.

```typescript
// Import the @ray-js/robot-data-stream module
import { StreamDataNotificationCenter, useP2PDataStream } from '@ray-js/robot-data-stream';

const onMapData = (mapDataStr: string) => {
    // The mapDataStr received here is the map data reported by the device
    // Your business logic
};

const onPathData = (pathDataStr: string) => {
    // The pathDataStr received here is the path data reported by the device
    // Your business logic
};

const { appendDownloadStreamDuringTask } = useP2PDataStream(
  // Device ID
    getDevInfo().devId,
    onMapData,
    onPathData,
    {
      // The tag for the App logs used in the mini-program; you can change it if needed. This tag is used for problem localization by uploading App logs when encountering online issues.
      logTag: APP_LOG_TAG,
      // Optional parameter: The robot uses visual recognition to throw out thumbnail overview data from here. If the robot does not have this function, this method can be ignored.
      onReceiveAIPicData,
      // Optional parameter: The robot uses visual recognition to throw out high-definition original images from here. If the robot does not have this function, this method can be ignored.
      onReceiveAIPicHDData,
    }
  );
```