Tuya.com
简体中文
English
注册
登录开发者平台
简体中文
English
注册
登录开发者平台
Smart App SDK
search
根据文档目录筛选
Smart App SDK智能生活 App SDK鸿蒙开发指南扫地机 SDK扫地机 OSS 相关接口

扫地机 OSS 相关接口

更新时间：2025-12-16 07:25:31下载pdf

概述

扫地机 SDK 提供了完整的扫地机设备管理能力，包括云存储配置、实时数据通道、历史记录管理和文件下载等核心功能。

SDK 包:

  • @thingsmart/sweepersdk - 扫地机核心库

平台: HarmonyOS (ArkTS)

架构层次:

  • API 层: 对外公开的接口和数据模型

模块导入

// 扫地机核心接口
import { 
  IThingSweeperKit,                 // 扫地机核心接口
  IThingGyroAndVisualSweeperKit,   // 陀螺仪扫地机接口
  IThingResultCallback,             // 通用结果回调
  IThingSweeperDataListener,        // MQTT 数据监听器
  IThingSweeperByteDataListener,    // MQTT 字节数据监听器
  IThingByteDataListener,           // 字节数据监听器
  SweeperDataBean,                  // 地图数据模型
  SweeperByteDataBean,              // 字节数据模型
  SweeperCleanRecordBean,           // 清扫记录模型
  SweeperHistoryBean,               // 历史记录模型
  SweeperCurrentPathBean,           // 当前路径模型
  CloudConfigBean,                  // 云存储配置模型
  SweeperHistory                    // 历史记录模型
} from '@thingsmart/sweepersdk'

// 日志库
import { L } from '@thingsmart/thinglogmodule'

// 设备 SDK
import { TSmartDevice } from '@thingsmart/device'

// HarmonyOS 系统 API
import fs from '@ohos.file.fs'

1. IThingSweeperKit 核心接口

1.1 getInstance

功能描述

获取扫地机核心功能的单例实例。这是使用 SDK 的入口方法。

函数签名

static getInstance(): IThingSweeperKit

参数说明

无

返回值

类型 说明
IThingSweeperKit 扫地机核心接口实例（单例）

注意事项

  • 返回的是单例对象，多次调用返回同一实例
  • 使用前无需初始化，SDK 内部自动管理

使用示例

const sweeperKit = ThingSweeperKit.getInstance()

1.2 initCloudConfig

功能描述

初始化云存储配置。获取设备的云存储 bucket 信息，用于后续的文件下载等操作。

函数签名

initCloudConfig(
  devId: string, 
  callback: IThingResultCallback<string>
): void

参数说明

参数 类型 必填 说明
devId string 是 设备 ID
callback IThingResultCallback 是 回调接口（成功时返回 bucket 名称）

IThingResultCallback 接口定义

interface IThingResultCallback<T> {
  onSuccess(result?: T): void
  onFailure(errorCode: string, errorMsg: string): void
}

返回值

无（结果通过回调返回）

注意事项

  • 这是使用 SDK 其他功能的前置步骤
  • 成功后会缓存 bucket 信息，供后续使用
  • bucket 名称用于构建文件下载路径

使用示例

const callback: IThingResultCallback<string> = {
  onSuccess: (bucket?: string) => {
    L.i('SweeperDemo', `云存储配置成功: ${bucket}`)
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `云存储配置失败: ${errorCode} - ${errorMsg}`)
  }
}

ThingSweeperKit.getInstance().initCloudConfig('device_abc123', callback)

1.3 updateCloudConfig

功能描述

更新云存储配置。功能与 initCloudConfig 相同，用于刷新配置信息。

函数签名

updateCloudConfig(
  devId: string, 
  callback: IThingResultCallback<string>
): void

参数说明

参数 类型 必填 说明
devId string 是 设备 ID
callback IThingResultCallback 是 回调接口

返回值

无（结果通过回调返回）

注意事项

  • 内部实现与 initCloudConfig 相同
  • 用于更新缓存的配置信息

使用示例

const callback: IThingResultCallback<string> = {
  onSuccess: (bucket?: string) => {
    L.i('SweeperDemo', `配置更新成功: ${bucket}`)
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `配置更新失败: ${errorMsg}`)
  }
}

ThingSweeperKit.getInstance().updateCloudConfig('device_abc123', callback)

1.4 startConnectSweeperDataChannel

功能描述

开启扫地机实时数据通道，监听 MQTT 协议的地图数据推送（URL 格式）。

函数签名

startConnectSweeperDataChannel(
  listener: IThingSweeperDataListener
): void

参数说明

参数 类型 必填 说明
listener IThingSweeperDataListener 是 数据监听器

IThingSweeperDataListener 接口定义

interface IThingSweeperDataListener {
  /**
   * 地图数据接收回调
   * @param data - 地图数据（包含 URL、bucket、region 等）
   */
  onSweeperDataReceive(data: SweeperDataBean): void
  
  /**
   * 地图数据移除回调
   */
  onSweeperDataRemove(): void
}

SweeperDataBean 数据结构

interface SweeperDataBean {
  mapId: number       // 地图 ID
  bucket: string      // OSS Bucket
  file: string        // 文件路径
  region: string      // 区域
  expireTime: number  // 过期时间
}

返回值

无

注意事项

  • 调用前必须先执行 initCloudConfig
  • 使用设备 SDK 的 TSmartDevice.registerMsgListener() 监听 MQTT 消息
  • 监听器会持续接收实时数据，直到调用 stopConnectSweeperDataChannel
  • 数据格式为 URL 形式的地图路径

使用示例

const listener: IThingSweeperDataListener = {
  onSweeperDataReceive: (data: SweeperDataBean) => {
    L.i('SweeperDemo', `收到地图数据: mapId=${data.mapId}, file=${data.file}`)
    // 使用数据下载地图...
  },
  onSweeperDataRemove: () => {
    L.i('SweeperDemo', '地图数据已移除')
  }
}

ThingSweeperKit.getInstance().startConnectSweeperDataChannel(listener)

1.5 stopConnectSweeperDataChannel

功能描述

停止扫地机实时数据通道，取消 MQTT 监听。

函数签名

stopConnectSweeperDataChannel(): void

参数说明

无

返回值

无

注意事项

  • 调用后会注销 MQTT 监听器
  • 停止后如需再次使用，需重新调用 startConnectSweeperDataChannel

使用示例

ThingSweeperKit.getInstance().stopConnectSweeperDataChannel()
L.i('SweeperDemo', 'MQTT 数据通道已关闭')

1.6 startConnectSweeperByteDataChannel

功能描述

开启扫地机字节数据通道，监听 MQTT 协议的二进制地图数据（Byte Array 格式）。

函数签名

startConnectSweeperByteDataChannel(
  listener: IThingSweeperByteDataListener
): void

参数说明

参数 类型 必填 说明
listener IThingSweeperByteDataListener 是 字节数据监听器

IThingSweeperByteDataListener 接口定义

interface IThingSweeperByteDataListener {
  /**
   * 字节数据接收回调
   * @param data - 字节数据（包含二进制地图数据）
   */
  onSweeperByteDataReceive(data: SweeperByteDataBean): void
  
  /**
   * 字节数据移除回调
   */
  onSweeperByteDataRemove(): void
}

SweeperByteDataBean 数据结构

interface SweeperByteDataBean {
  mapId: number           // 地图 ID
  type: number            // 数据类型
  data: Uint8Array        // 二进制数据
}

返回值

无

注意事项

  • 调用前必须先执行 initCloudConfig
  • 适用于需要直接处理二进制地图数据的场景
  • 与 URL 数据通道互斥，同时只能开启一种

使用示例

const listener: IThingSweeperByteDataListener = {
  onSweeperByteDataReceive: (data: SweeperByteDataBean) => {
    L.i('SweeperDemo', `收到字节数据: mapId=${data.mapId}, size=${data.data.length}`)
    // 直接处理二进制数据...
  },
  onSweeperByteDataRemove: () => {
    L.i('SweeperDemo', '字节数据已移除')
  }
}

ThingSweeperKit.getInstance().startConnectSweeperByteDataChannel(listener)

1.7 stopConnectSweeperByteDataChannel

功能描述

停止扫地机字节数据通道，取消 MQTT 监听。

函数签名

stopConnectSweeperByteDataChannel(): void

参数说明

无

返回值

无

使用示例

ThingSweeperKit.getInstance().stopConnectSweeperByteDataChannel()
L.i('SweeperDemo', '字节数据通道已关闭')

1.8 getSweeperByteData

功能描述

从 OSS 下载字节数据文件。

函数签名

getSweeperByteData(
  bucket: string, 
  path: string, 
  listener: IThingByteDataListener
): void

参数说明

参数 类型 必填 说明
bucket string 是 OSS Bucket 名称（可从 initCloudConfig 获取）
path string 是 文件路径（OSS 上的相对路径）
listener IThingByteDataListener 是 字节数据监听器

IThingByteDataListener 接口定义

interface IThingByteDataListener {
  /**
   * 下载成功回调
   * @param bytes - 文件的字节数据
   */
  onSuccess(bytes: Uint8Array): void
  
  /**
   * 下载失败回调
   * @param code - 错误码
   * @param errorMsg - 错误消息
   */
  onFailure(code: number, errorMsg: string): void
}

返回值

无（结果通过回调返回）

注意事项

  • 调用前必须先执行 initCloudConfig
  • 文件数据以字节数组形式返回，需要自行保存到本地
  • bucket 参数通常使用 initCloudConfig 成功后缓存的值

使用示例

const listener: IThingByteDataListener = {
  onSuccess: (bytes: Uint8Array) => {
    L.i('SweeperDemo', `文件下载成功: ${bytes.length} 字节`)
    
    // 保存到本地文件
    const savePath = '/data/storage/el2/base/haps/entry/files/map.bin'
    const file = fs.openSync(savePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE)
    fs.writeSync(file.fd, bytes.buffer)
    fs.closeSync(file)
    
    L.i('SweeperDemo', `文件已保存到: ${savePath}`)
  },
  onFailure: (code: number, errorMsg: string) => {
    L.e('SweeperDemo', `文件下载失败: ${code} - ${errorMsg}`)
  }
}

ThingSweeperKit.getInstance().getSweeperByteData(
  'bucket-name',           // Bucket 名称
  'maps/layout/lay.bin',  // 文件路径
  listener
)

1.9 getCloudFileUrl

功能描述

获取云端文件的 URL 地址。

函数签名

getCloudFileUrl(
  bucket: string, 
  path: string
): string

参数说明

参数 类型 必填 说明
bucket string 是 OSS Bucket 名称
path string 是 文件路径

返回值

类型 说明
string 文件 URL 地址

使用示例

const url = ThingSweeperKit.getInstance().getCloudFileUrl(
  'bucket-name',
  'maps/layout/lay.bin'
)
L.i('SweeperDemo', `文件 URL: ${url}`)

1.10 getSweeperHistoryData

功能描述

获取扫地机历史记录（单地图，无时间范围）。

函数签名

getSweeperHistoryData(
  devId: string, 
  limit: number, 
  offset: number, 
  callback: IThingResultCallback<SweeperHistory>
): void

参数说明

参数 类型 必填 说明
devId string 是 设备 ID
limit number 是 每页数量
offset number 是 偏移量
callback IThingResultCallback 是 回调接口

返回值

无（结果通过回调返回）

使用示例

const callback: IThingResultCallback<SweeperHistory> = {
  onSuccess: (result?: SweeperHistory) => {
    if (result) {
      L.i('SweeperDemo', `获取历史记录成功`)
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `获取历史记录失败: ${errorMsg}`)
  }
}

ThingSweeperKit.getInstance().getSweeperHistoryData(
  'device_abc123',
  20,   // 每页 20 条
  0,    // 第一页
  callback
)

1.11 getSweeperHistoryDataWithTimeRange

功能描述

获取扫地机历史记录（单地图，带时间范围）。

函数签名

getSweeperHistoryDataWithTimeRange(
  devId: string, 
  limit: number, 
  offset: number, 
  startTime: number, 
  endTime: number, 
  callback: IThingResultCallback<SweeperHistory>
): void

参数说明

参数 类型 必填 说明
devId string 是 设备 ID
limit number 是 每页数量
offset number 是 偏移量
startTime number 是 开始时间戳
endTime number 是 结束时间戳
callback IThingResultCallback 是 回调接口

返回值

无（结果通过回调返回）

使用示例

const now = Date.now()
const oneWeekAgo = now - 7 * 24 * 60 * 60 * 1000

const callback: IThingResultCallback<SweeperHistory> = {
  onSuccess: (result?: SweeperHistory) => {
    if (result) {
      L.i('SweeperDemo', `获取历史记录成功`)
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `获取历史记录失败: ${errorMsg}`)
  }
}

ThingSweeperKit.getInstance().getSweeperHistoryDataWithTimeRange(
  'device_abc123',
  20,          // 每页 20 条
  0,           // 第一页
  oneWeekAgo,  // 一周前
  now,         // 现在
  callback
)

1.12 getSweeperMultiMapHistoryData

功能描述

获取扫地机多地图历史记录（无时间范围）。

函数签名

getSweeperMultiMapHistoryData(
  devId: string, 
  limit: number, 
  offset: number, 
  callback: IThingResultCallback<SweeperHistory>
): void

参数说明

参数 类型 必填 说明
devId string 是 设备 ID
limit number 是 每页数量
offset number 是 偏移量
callback IThingResultCallback 是 回调接口

返回值

无（结果通过回调返回）

使用示例

const callback: IThingResultCallback<SweeperHistory> = {
  onSuccess: (result?: SweeperHistory) => {
    if (result) {
      L.i('SweeperDemo', `获取多地图历史记录成功`)
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `获取历史记录失败: ${errorMsg}`)
  }
}

ThingSweeperKit.getInstance().getSweeperMultiMapHistoryData(
  'device_abc123',
  20,   // 每页 20 条
  0,    // 第一页
  callback
)

1.13 getSweeperMultiMapHistoryDataWithTimeRange

功能描述

获取扫地机多地图历史记录（带时间范围）。

函数签名

getSweeperMultiMapHistoryDataWithTimeRange(
  devId: string, 
  limit: number, 
  offset: number, 
  startTime: number, 
  endTime: number, 
  callback: IThingResultCallback<SweeperHistory>
): void

参数说明

参数 类型 必填 说明
devId string 是 设备 ID
limit number 是 每页数量
offset number 是 偏移量
startTime number 是 开始时间戳
endTime number 是 结束时间戳
callback IThingResultCallback 是 回调接口

返回值

无（结果通过回调返回）

使用示例

const now = Date.now()
const oneWeekAgo = now - 7 * 24 * 60 * 60 * 1000

const callback: IThingResultCallback<SweeperHistory> = {
  onSuccess: (result?: SweeperHistory) => {
    if (result) {
      L.i('SweeperDemo', `获取多地图历史记录成功`)
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `获取历史记录失败: ${errorMsg}`)
  }
}

ThingSweeperKit.getInstance().getSweeperMultiMapHistoryDataWithTimeRange(
  'device_abc123',
  20,          // 每页 20 条
  0,           // 第一页
  oneWeekAgo,  // 一周前
  now,         // 现在
  callback
)

1.14 deleteSweeperHistoryData

功能描述

删除扫地机历史清扫记录。

函数签名

deleteSweeperHistoryData(
  devId: string, 
  fileIdList: string[], 
  callback: IThingResultCallback<boolean>
): void

参数说明

参数 类型 必填 说明
devId string 是 设备 ID
fileIdList string[] 是 要删除的文件 ID 列表
callback IThingResultCallback 是 回调接口（返回删除结果）

返回值

无（结果通过回调返回）

使用示例

const callback: IThingResultCallback<boolean> = {
  onSuccess: (result?: boolean) => {
    if (result) {
      L.i('SweeperDemo', '历史记录删除成功')
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `删除失败: ${errorMsg}`)
  }
}

ThingSweeperKit.getInstance().deleteSweeperHistoryData(
  'device_abc123',
  ['file_001', 'file_002'],  // 要删除的文件 ID
  callback
)

1.11 getSweeperCurrentPath

功能描述

获取扫地机当前路径信息（地图路径和路线路径）。

函数签名

getSweeperCurrentPath(
  devId: string, 
  bucket: string | undefined, 
  callback: IThingResultCallback<SweeperCurrentPathBean>
): void

参数说明

参数 类型 必填 说明
devId string 是 设备 ID
bucket string | undefined 否 OSS Bucket 名称（可选，优先使用传入值，否则使用缓存）
callback IThingResultCallback 是 回调接口

SweeperCurrentPathBean 数据结构

interface SweeperCurrentPathBean {
  mapPath: string     // 地图文件路径
  routePath: string   // 路线文件路径
}

返回值

无（结果通过回调返回）

注意事项

  • 调用前必须先执行 initCloudConfig
  • 如果传入 bucket 参数，优先使用传入值
  • 否则使用 initCloudConfig 缓存的 bucket
  • 如果配置已缓存，直接构建路径返回，无需网络请求

使用示例

const callback: IThingResultCallback<SweeperCurrentPathBean> = {
  onSuccess: (result?: SweeperCurrentPathBean) => {
    if (result) {
      L.i('SweeperDemo', `地图路径: ${result.mapPath}`)
      L.i('SweeperDemo', `路线路径: ${result.routePath}`)
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `获取路径失败: ${errorMsg}`)
  }
}

// 方式1：使用缓存的 bucket
ThingSweeperKit.getInstance().getSweeperCurrentPath(
  'device_abc123',
  undefined,
  callback
)

// 方式2：指定 bucket
ThingSweeperKit.getInstance().getSweeperCurrentPath(
  'device_abc123',
  'custom-bucket-name',
  callback
)

1.12 sweeperFileNameUpdateWithDevId

功能描述

重命名地图文件（多层地图场景）。

函数签名

sweeperFileNameUpdateWithDevId(
  devId: string, 
  id: number, 
  name: string, 
  callback: IThingResultCallback<boolean>
): void

参数说明

参数 类型 必填 说明
devId string 是 设备 ID
id number 是 多层地图 ID
name string 是 新名称
callback IThingResultCallback 是 回调接口（返回重命名结果）

返回值

无（结果通过回调返回）

使用示例

const callback: IThingResultCallback<boolean> = {
  onSuccess: (result?: boolean) => {
    if (result) {
      L.i('SweeperDemo', '地图重命名成功')
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `重命名失败: ${errorMsg}`)
  }
}

ThingSweeperKit.getInstance().sweeperFileNameUpdateWithDevId(
  'device_abc123',
  1,               // 地图 ID
  'Living Room',   // 新名称
  callback
)

2. IThingGyroAndVisualSweeperKit 陀螺仪扫地机接口

2.1 getInstance

功能描述

获取陀螺仪扫地机功能的单例实例。

函数签名

static getInstance(): IThingGyroAndVisualSweeperKit

参数说明

无

返回值

类型 说明
IThingGyroAndVisualSweeperKit 陀螺仪扫地机接口实例（单例）

使用示例

const gyroSweeperKit = ThingGyroAndVisualSweeperKit.getInstance()

2.2 queryLatestCleanRecord

功能描述

查询最新一次清扫记录（流服务 1.0 / V2 版本）。

函数签名

queryLatestCleanRecord(
  devId: string, 
  start: string, 
  size: number, 
  callback: IThingResultCallback<SweeperCleanRecordBean>
): void

参数说明

参数 类型 必填 说明
devId string 是 设备 ID
start string 是 起始位置（首次请求传空字符串，后续请求传上次响应的 startRow）
size number 是 每次调用返回的最大条目数
callback IThingResultCallback 是 回调接口

SweeperCleanRecordBean 数据结构

interface SweeperCleanRecordBean {
  subRecordId: number     // 子记录 ID
  cleanArea: number       // 清扫面积
  cleanTime: number       // 清扫时长
  startTime: number       // 开始时间
  endTime: number         // 结束时间
  data: string            // 路径数据
  startRow: string        // 下次请求的起始位置
}

返回值

无（结果通过回调返回）

使用示例

const callback: IThingResultCallback<SweeperCleanRecordBean> = {
  onSuccess: (result?: SweeperCleanRecordBean) => {
    if (result) {
      L.i('SweeperDemo', `清扫面积: ${result.cleanArea}m²`)
      L.i('SweeperDemo', `清扫时长: ${result.cleanTime}s`)
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `查询失败: ${errorMsg}`)
  }
}

ThingGyroAndVisualSweeperKit.getInstance().queryLatestCleanRecord(
  'device_abc123',
  '',      // 首次请求
  100,     // 每次最多 100 条
  callback
)

2.3 queryLatestCleanRecordV2

功能描述

查询最新一次清扫记录（流服务 2.0 / V3 版本）。

函数签名

queryLatestCleanRecordV2(
  devId: string, 
  start: string, 
  size: number, 
  callback: IThingResultCallback<SweeperCleanRecordBean>
): void

参数说明

同 queryLatestCleanRecord

返回值

无（结果通过回调返回）

注意事项

  • 使用 V3.0 API，支持更多特性
  • 参数和返回值与 V2 版本相同

使用示例

ThingGyroAndVisualSweeperKit.getInstance().queryLatestCleanRecordV2(
  'device_abc123',
  '',
  100,
  callback
)

2.4 getHistoryCleanRecordList

功能描述

查询历史清扫任务数据。

函数签名

getHistoryCleanRecordList(
  devId: string, 
  offset: number, 
  limit: number, 
  startTime: number, 
  endTime: number, 
  callback: IThingResultCallback<SweeperHistoryBean>
): void

参数说明

参数 类型 必填 说明
devId string 是 设备 ID
offset number 是 从哪个条目开始返回
limit number 是 每页返回的最大条目数
startTime number 是 查询时间范围的开始时间（时间戳）
endTime number 是 查询时间范围的结束时间（时间戳）
callback IThingResultCallback 是 回调接口

SweeperHistoryBean 数据结构

interface SweeperHistoryBean {
  total: number                 // 总条目数
  records: SweeperCleanRecord[] // 清扫记录列表
}

interface SweeperCleanRecord {
  id: string          // 记录 ID
  startTime: number   // 开始时间
  endTime: number     // 结束时间
  cleanArea: number   // 清扫面积
  cleanTime: number   // 清扫时长
}

返回值

无（结果通过回调返回）

使用示例

const callback: IThingResultCallback<SweeperHistoryBean> = {
  onSuccess: (result?: SweeperHistoryBean) => {
    if (result) {
      L.i('SweeperDemo', `总记录数: ${result.total}`)
      result.records.forEach(record => {
        L.i('SweeperDemo', `记录: ${record.id}, 面积: ${record.cleanArea}m²`)
      })
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `查询失败: ${errorMsg}`)
  }
}

const now = Date.now()
const oneWeekAgo = now - 7 * 24 * 60 * 60 * 1000

ThingGyroAndVisualSweeperKit.getInstance().getHistoryCleanRecordList(
  'device_abc123',
  0,            // 第一页
  20,           // 每页 20 条
  oneWeekAgo,   // 一周前
  now,          // 现在
  callback
)

2.5 getCleanRecordDetail

功能描述

查询历史清扫任务详情（流服务 1.0 / V2 版本）。

函数签名

getCleanRecordDetail(
  devId: string, 
  subRecordId: number, 
  start: string, 
  size: number, 
  callback: IThingResultCallback<SweeperCleanRecordBean>
): void

参数说明

参数 类型 必填 说明
devId string 是 设备 ID
subRecordId number 是 要查询的清扫任务 ID
start string 是 起始位置
size number 是 每次调用返回的最大条目数
callback IThingResultCallback 是 回调接口

返回值

无（结果通过回调返回）

使用示例

const callback: IThingResultCallback<SweeperCleanRecordBean> = {
  onSuccess: (result?: SweeperCleanRecordBean) => {
    if (result) {
      L.i('SweeperDemo', `清扫详情: 面积=${result.cleanArea}m², 时长=${result.cleanTime}s`)
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `查询详情失败: ${errorMsg}`)
  }
}

ThingGyroAndVisualSweeperKit.getInstance().getCleanRecordDetail(
  'device_abc123',
  12345,   // 子记录 ID
  '',      // 首次请求
  100,
  callback
)

2.6 getCleanRecordDetailV2

功能描述

查询历史清扫任务详情（流服务 2.0 / V3 版本）。

函数签名

getCleanRecordDetailV2(
  devId: string, 
  subRecordId: number, 
  start: string, 
  size: number, 
  mapId: number, 
  datatype: number, 
  callback: IThingResultCallback<SweeperCleanRecordBean>
): void

参数说明

参数 类型 必填 说明
devId string 是 设备 ID
subRecordId number 是 清扫任务 ID
start string 是 起始位置
size number 是 每次返回的最大条目数
mapId number 是 子地图 ID
datatype number 是 地图类型
callback IThingResultCallback 是 回调接口

返回值

无（结果通过回调返回）

使用示例

ThingGyroAndVisualSweeperKit.getInstance().getCleanRecordDetailV2(
  'device_abc123',
  12345,  // 子记录 ID
  '',     // 首次请求
  100,
  1,      // 地图 ID
  0,      // 数据类型
  callback
)

2.7 deleteHistoryCleanRecord

功能描述

删除历史清扫任务。

函数签名

deleteHistoryCleanRecord(
  devId: string, 
  uuids: string[], 
  callback: IThingResultCallback<boolean>
): void

参数说明

参数 类型 必填 说明
devId string 是 设备 ID
uuids string[] 是 每个清扫任务的唯一 ID（UUID 列表）
callback IThingResultCallback 是 回调接口（返回删除结果）

返回值

无（结果通过回调返回）

注意事项

  • UUID 参数会被转换为逗号分隔的字符串发送给服务器
  • 格式："uuid1,uuid2,uuid3"

使用示例

const callback: IThingResultCallback<boolean> = {
  onSuccess: (result?: boolean) => {
    if (result) {
      L.i('SweeperDemo', '删除成功')
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `删除失败: ${errorMsg}`)
  }
}

ThingGyroAndVisualSweeperKit.getInstance().deleteHistoryCleanRecord(
  'device_abc123',
  ['uuid_001', 'uuid_002'],
  callback
)

2.8 getSubRecordId

功能描述

从特定格式的字符串中提取 SubRecordID。

函数签名

getSubRecordId(value: string): number

参数说明

参数 类型 必填 说明
value string 是 输入字符串

返回值

类型 说明
number SubRecordID（提取失败返回 0）

解析规则

字符串长度 格式 提取逻辑
23 12+3+3+5 提取后 5 位
11 3+3+5 提取后 5 位

使用示例

const value1 = '12345678901234567890123'  // 23 位
const subRecordId1 = ThingGyroAndVisualSweeperKit.getInstance().getSubRecordId(value1)
L.i('SweeperDemo', `SubRecordID: ${subRecordId1}`)  // 输出：90123

const value2 = '12345678901'  // 11 位
const subRecordId2 = ThingGyroAndVisualSweeperKit.getInstance().getSubRecordId(value2)
L.i('SweeperDemo', `SubRecordID: ${subRecordId2}`)  // 输出：78901

3. 完整使用流程示例

3.1 标准地图下载流程

import { ThingSweeperKit, IThingResultCallback, IThingSweeperDataListener, SweeperDataBean, IThingByteDataListener } from '@thingsmart/sweepersdk'
import { L } from '@thingsmart/thinglogmodule'
import fs from '@ohos.file.fs'

const TAG = 'SweeperDemo'

class SweeperMapDownloader {
  private sweeperKit = ThingSweeperKit.getInstance()
  private deviceId: string = ''
  
  async downloadMapFlow(deviceId: string) {
    this.deviceId = deviceId
    
    try {
      // 步骤 1: 初始化云存储配置
      const bucket = await this.initCloudConfig()
      L.i(TAG, `配置成功: bucket=${bucket}`)
      
      // 步骤 2: 开启 MQTT 数据通道
      this.startMqttChannel()
      
      // 步骤 3: 等待地图数据推送...（在监听器中处理）
      
    } catch (error) {
      L.e(TAG, `流程失败: ${error}`)
    }
  }
  
  // 初始化云存储配置
  private initCloudConfig(): Promise<string> {
    return new Promise((resolve, reject) => {
      const callback: IThingResultCallback<string> = {
        onSuccess: (bucket?: string) => {
          if (bucket) {
            resolve(bucket)
          } else {
            reject(new Error('bucket is empty'))
          }
        },
        onFailure: (errorCode: string, errorMsg: string) => {
          reject(new Error(`${errorCode}: ${errorMsg}`))
        }
      }
      
      this.sweeperKit.initCloudConfig(this.deviceId, callback)
    })
  }
  
  // 开启 MQTT 数据通道
  private startMqttChannel() {
    const listener: IThingSweeperDataListener = {
      onSweeperDataReceive: (data: SweeperDataBean) => {
        L.i(TAG, `收到地图数据: mapId=${data.mapId}, file=${data.file}`)
        
        // 下载地图文件
        this.downloadMapFile(data.file, data.bucket)
      },
      onSweeperDataRemove: () => {
        L.i(TAG, '地图数据已移除')
      }
    }
    
    this.sweeperKit.startConnectSweeperDataChannel(listener)
    L.i(TAG, 'MQTT 数据通道已开启')
  }
  
  // 下载地图文件
  private downloadMapFile(path: string, bucket: string) {
    const listener: IThingByteDataListener = {
      onSuccess: (data: Uint8Array) => {
        L.i(TAG, `文件下载成功: ${data.length} 字节`)
        
        // 保存到本地
        const savePath = '/data/storage/el2/base/haps/entry/files/map.bin'
        const file = fs.openSync(savePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE)
        fs.writeSync(file.fd, data.buffer)
        fs.closeSync(file)
        
        L.i(TAG, `地图已保存: ${savePath}`)
      },
      onFailure: (errorCode: string, errorMsg: string) => {
        L.e(TAG, `下载失败: ${errorCode} - ${errorMsg}`)
      }
    }
    
    this.sweeperKit.downloadFile(path, bucket, listener)
  }
  
  // 清理资源
  cleanup() {
    this.sweeperKit.stopConnectSweeperDataChannel()
    L.i(TAG, '资源已清理')
  }
}

// 使用
const downloader = new SweeperMapDownloader()
downloader.downloadMapFlow('device_abc123')

// 退出时清理
// downloader.cleanup()

3.2 历史记录管理流程

import { ThingGyroAndVisualSweeperKit, IThingResultCallback, SweeperHistoryBean } from '@thingsmart/sweepersdk'
import { L } from '@thingsmart/thinglogmodule'

const TAG = 'HistoryDemo'

class SweeperHistoryManager {
  private gyroKit = ThingGyroAndVisualSweeperKit.getInstance()
  
  // 获取最近一周的历史记录
  async getRecentHistory(deviceId: string) {
    const now = Date.now()
    const oneWeekAgo = now - 7 * 24 * 60 * 60 * 1000
    
    return new Promise<SweeperHistoryBean>((resolve, reject) => {
      const callback: IThingResultCallback<SweeperHistoryBean> = {
        onSuccess: (result?: SweeperHistoryBean) => {
          if (result) {
            L.i(TAG, `获取到 ${result.total} 条历史记录`)
            resolve(result)
          } else {
            reject(new Error('result is empty'))
          }
        },
        onFailure: (errorCode: string, errorMsg: string) => {
          reject(new Error(`${errorCode}: ${errorMsg}`))
        }
      }
      
      this.gyroKit.getHistoryCleanRecordList(
        deviceId,
        0,            // 第一页
        50,           // 每页 50 条
        oneWeekAgo,
        now,
        callback
      )
    })
  }
  
  // 删除指定的历史记录
  async deleteRecords(deviceId: string, uuids: string[]) {
    return new Promise<boolean>((resolve, reject) => {
      const callback: IThingResultCallback<boolean> = {
        onSuccess: (result?: boolean) => {
          L.i(TAG, '删除成功')
          resolve(result || false)
        },
        onFailure: (errorCode: string, errorMsg: string) => {
          reject(new Error(`${errorCode}: ${errorMsg}`))
        }
      }
      
      this.gyroKit.deleteHistoryCleanRecord(deviceId, uuids, callback)
    })
  }
}

// 使用
const historyManager = new SweeperHistoryManager()

// 获取历史记录
const history = await historyManager.getRecentHistory('device_abc123')
console.log(`总记录数: ${history.total}`)

// 删除前 2 条记录
if (history.records.length >= 2) {
  const uuidsToDelete = history.records.slice(0, 2).map(r => r.id)
  await historyManager.deleteRecords('device_abc123', uuidsToDelete)
}

4. 数据模型参考

4.1 CloudConfigBean

interface CloudConfigBean {
  bucket: string       // OSS Bucket 名称
  region: string       // 区域
  pathConfig: PathConfig  // 路径配置
}

interface PathConfig {
  common: string       // 公共路径前缀
}

4.2 SweeperDataBean

interface SweeperDataBean {
  mapId: number        // 地图 ID
  bucket: string       // OSS Bucket
  file: string         // 文件路径
  region: string       // 区域
  expireTime: number   // 过期时间
}

4.3 SweeperByteDataBean

interface SweeperByteDataBean {
  mapId: number        // 地图 ID
  type: number         // 数据类型
  data: Uint8Array     // 二进制数据
}

4.4 SweeperCleanRecordBean

interface SweeperCleanRecordBean {
  subRecordId: number   // 子记录 ID
  cleanArea: number     // 清扫面积（平方米）
  cleanTime: number     // 清扫时长（秒）
  startTime: number     // 开始时间（时间戳）
  endTime: number       // 结束时间（时间戳）
  data: string          // 路径数据（JSON 字符串）
  startRow: string      // 下次请求的起始位置
}

4.5 SweeperHistoryBean

interface SweeperHistoryBean {
  total: number                 // 总条目数
  records: SweeperCleanRecord[] // 清扫记录列表
}

interface SweeperCleanRecord {
  id: string          // 记录 ID
  startTime: number   // 开始时间
  endTime: number     // 结束时间
  cleanArea: number   // 清扫面积
  cleanTime: number   // 清扫时长
}

4.6 SweeperCurrentPathBean

interface SweeperCurrentPathBean {
  mapPath: string     // 地图文件路径
  routePath: string   // 路线文件路径
}

4.7 SweeperHistory

interface SweeperHistory {
  id: string          // 记录 ID
  startTime: number   // 开始时间
  endTime: number     // 结束时间
  area: number        // 清扫面积
  time: number        // 清扫时长
}
上一篇扫地机 P2P 功能
下一篇智能摄像机 SDK
语言
简体中文
简体中文
English
400-881-8611
7×24小时服务热线
市场合作
marketing@tuya.com
业务合作
service@tuya.com
媒体联络
pr@tuya.com
关注“涂鸦智能”
涂鸦服务尽在掌握
关注“全球智能商业”
第一时间获取物联网资讯
联系我们加入我们TuyaExpoApp 商城TuyaGoTuyaGo服务商查询
法律声明隐私协议加州隐私权利声明服务条款廉正合规安全应急响应中心
©2014-2025 杭州涂鸦信息技术有限公司 版权
浙ICP备2022000504号
浙B2-20210233号
浙公网安备33010602004238号
简体中文
简体中文
English