OSS Interfaces

Overview

The Sweeper SDK provides comprehensive device management capabilities for robot vacuums, including core functionalities such as cloud storage configuration, real-time data channels, historical record management, and file downloads.

• SDK:

  • @thingsmart/sweepersdk: The core library of robot vacuums.

• Platform:

  • HarmonyOS (ArkTS)

• Architecture layer:

  • API layer: Publicly exposed interfaces and data models.

Import module

// Core interfaces
import {
  IThingSweeperKit,                 // Core interfaces
  IThingGyroAndVisualSweeperKit,   // Interfaces for gyroscope robot vacuum
  IThingResultCallback,             // General result callback
  IThingSweeperDataListener,        // MQTT data listener
  IThingSweeperByteDataListener,    // MQTT byte data listener
  IThingByteDataListener,           // Byte data listener
  SweeperDataBean,                  // Map data model
  SweeperByteDataBean,              // Byte data model
  SweeperCleanRecordBean,           // Cleaning record model
  SweeperHistoryBean,               // History record model
  SweeperCurrentPathBean,           // Current path model
  CloudConfigBean,                  // Cloud storage configuration model
  SweeperHistory                    // History record model
} from '@thingsmart/sweepersdk'

// Logging library
import { L } from '@thingsmart/thinglogmodule'

// Device SDK
import { TSmartDevice } from '@thingsmart/device'

// HarmonyOS system APIs
import fs from '@ohos.file.fs'

IThingSweeperKit core interfaces

getInstance

Functional description

Gets the singleton instance of the robot vacuum’s core functionality. This provides methods to access the SDK.

Function signature

static getInstance(): IThingSweeperKit

Return value

Type	Description
IThingSweeperKit	The singleton instance of the core interfaces for a robot vacuum.

Example

const sweeperKit = ThingSweeperKit.getInstance()

initCloudConfig

Functional description

Initializes cloud storage configurations. Gets the device’s cloud storage bucket information for subsequent operations such as file downloads.

Function signature

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

Parameters

Parameter	Type	Required	Description
devId	string	Yes	The device ID.
callback	IThingResultCallback	Yes	The callback interface. The bucket name is returned on success.

IThingResultCallback definition

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

Return value

None (results are returned via the callback).

Example

const callback: IThingResultCallback<string> = {
  onSuccess: (bucket?: string) => {
    L.i('SweeperDemo', `Cloud storage was successfully configured: ${bucket}`)
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `Failed to configure cloud storage: ${errorCode} - ${errorMsg}`)
  }
}

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

updateCloudConfig

Functional description

Updates cloud storage configurations. It is functionally identical to initCloudConfig, used to refresh configuration information.

Function signature

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

Parameters

Parameter	Type	Required	Description
devId	string	Yes	The device ID.
callback	IThingResultCallback	Yes	Execute callback

Return value

None (results are returned via the callback).

Example

const callback: IThingResultCallback<string> = {
  onSuccess: (bucket?: string) => {
    L.i('SweeperDemo', `Updated configuration successfully: ${bucket}`)
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `Failed to update configuration: ${errorMsg}`)
  }
}

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

startConnectSweeperDataChannel

Functional description

Enables the robot vacuum’s real-time data channel to listen for map data pushes via the MQTT protocol (URL format).

Function signature

startConnectSweeperDataChannel(
  listener: IThingSweeperDataListener
): void

Parameters

Parameter	Type	Required	Description
listener	IThingSweeperDataListener	Yes	The data listener.

IThingSweeperDataListener definition

interface IThingSweeperDataListener {
  /**
   * Map data receiving callback
   * @param data - Map data (including URLs, buckets, and regions)
   */
  onSweeperDataReceive(data: SweeperDataBean): void

  /**
   * Map data removal callback
   */
  onSweeperDataRemove(): void
}

SweeperDataBean data structure

interface SweeperDataBean {
  mapId: number       // Map ID
  bucket: string      // OSS Bucket
  file: string        // File path
  region: string      // Region
  expireTime: number  // Expiration time
}

Example

const listener: IThingSweeperDataListener = {
  onSweeperDataReceive: (data: SweeperDataBean) => {
    L.i('SweeperDemo', `Map data received: mapId=${data.mapId}, file=${data.file}`)
    // Download maps using data...
  },
  onSweeperDataRemove: () => {
    L.i('SweeperDemo', 'Map data removed')
  }
}

ThingSweeperKit.getInstance().startConnectSweeperDataChannel(listener)

stopConnectSweeperDataChannel

Functional description

Stops the real-time data channel and cancels MQTT listening.

Function signature

stopConnectSweeperDataChannel(): void

Example

ThingSweeperKit.getInstance().stopConnectSweeperDataChannel()
L.i('SweeperDemo', 'MQTT data channel is closed')

startConnectSweeperByteDataChannel

Functional description

Enables the byte data channel to listen for binary map data (byte array format) pushed via the MQTT protocol.

Function signature

startConnectSweeperByteDataChannel(
  listener: IThingSweeperByteDataListener
): void

Parameters

Parameter	Type	Required	Description
listener	IThingSweeperByteDataListener	Yes	The byte data listener.

IThingSweeperByteDataListener definition

interface IThingSweeperByteDataListener {
  /**
   * Callback for receiving byte data.
   * @param data - Byte data (contains binary map data)
   */
  onSweeperByteDataReceive(data: SweeperByteDataBean): void

  /**
   * Callback for removing byte data.
   */
  onSweeperByteDataRemove(): void
}

SweeperByteDataBean data structure

interface SweeperByteDataBean {
  mapId: number           // Map ID
  type: number            // Data type
  data: Uint8Array        // Binary data
}

Example

const listener: IThingSweeperByteDataListener = {
  onSweeperByteDataReceive: (data: SweeperByteDataBean) => {
    L.i('SweeperDemo', `Received byte data: mapId=${data.mapId}, size=${data.data.length}`)
    // Directly process binary data...
  },
  onSweeperByteDataRemove: () => {
    L.i('SweeperDemo', 'Byte data has been removed')
  }
}

ThingSweeperKit.getInstance().startConnectSweeperByteDataChannel(listener)

stopConnectSweeperByteDataChannel

Functional description

Stops the byte data channel and cancels MQTT listening.

Function signature

stopConnectSweeperByteDataChannel(): void

Example

ThingSweeperKit.getInstance().stopConnectSweeperByteDataChannel()
L.i('SweeperDemo', 'Byte data channel is closed')

getSweeperByteData

Functional description

Downloads byte data files from OSS.

Function signature

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

Parameters

Parameter	Type	Required	Description
bucket	string	Yes	The OSS bucket name. It can be obtained from initCloudConfig.
path	string	Yes	The file path, that is, relative path on OSS.
listener	IThingByteDataListener	Yes	The byte data listener.

IThingByteDataListener definition

interface IThingByteDataListener {
  /**
   * Callback for successful download
   * @param bytes - The byte data of the file
   */
  onSuccess(bytes: Uint8Array): void

  /**
   * Callback for failed download
   * @param code - The error code
   * @param errorMsg - The error message
   */
  onFailure(code: number, errorMsg: string): void
}

Return value

None (results are returned via the callback).

Example

const listener: IThingByteDataListener = {
  onSuccess: (bytes: Uint8Array) => {
    L.i('SweeperDemo', `File downloaded successfully: ${bytes.length} bytes`)

    // Save to local file
    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', `File saved to: ${savePath}`)
  },
  onFailure: (code: number, errorMsg: string) => {
    L.e('SweeperDemo', `Failed to download the file: ${code} - ${errorMsg}`)
  }
}

ThingSweeperKit.getInstance().getSweeperByteData(
  'bucket-name',           // Bucket name
  'maps/layout/lay.bin',  // File path
  listener
)

getCloudFileUrl

Functional description

Get the URL of the specified file in the cloud.

Function signature

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

Parameters

Parameter	Type	Required	Description
bucket	string	Yes	The OSS bucket name.
path	string	Yes	The path of the file.

Return value

Type	Description
string	The URL of the file.

Example

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

getSweeperHistoryData

Functional description

Gets the history records of the robot vacuum (single map, no time range).

Function signature

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

Parameters

Parameter	Type	Required	Description
devId	string	Yes	The device ID.
limit	number	Yes	The number of entries per page.
offset	number	Yes	The number of the entry starting from which entries are returned.
callback	IThingResultCallback	Yes	Execute callback

Return value

None (results are returned via the callback).

Example

const callback: IThingResultCallback<SweeperHistory> = {
  onSuccess: (result?: SweeperHistory) => {
    if (result) {
      L.i('SweeperDemo', `Obtained history records successfully`)
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `Failed to obtain history records: ${errorMsg}`)
  }
}

ThingSweeperKit.getInstance().getSweeperHistoryData(
  'device_abc123',
  20,   // 20 items on each page
  0,    // Page 1
  callback
)

getSweeperHistoryDataWithTimeRange

Functional description

Gets the history records of the robot vacuum (single map, with time range).

Function signature

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

Parameters

Parameter	Type	Required	Description
devId	string	Yes	The device ID.
limit	number	Yes	The number of entries per page.
offset	number	Yes	The number of the entry starting from which entries are returned.
startTime	number	Yes	The start timestamp.
endTime	number	Yes	The end timestamp.
callback	IThingResultCallback	Yes	Execute callback

Return value

None (results are returned via the callback).

Example

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

const callback: IThingResultCallback<SweeperHistory> = {
  onSuccess: (result?: SweeperHistory) => {
    if (result) {
      L.i('SweeperDemo', `Obtained history records successfully`)
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `Failed to obtain history records: ${errorMsg}`)
  }
}

ThingSweeperKit.getInstance().getSweeperHistoryDataWithTimeRange(
  'device_abc123',
  20,          // 20 items on each page
  0,           // Page 1
  oneWeekAgo,  // One week ago
  now,         // Now
  callback
)

getSweeperMultiMapHistoryData

Functional description

Gets the multi-map history records of the robot vacuum (no time range).

Function signature

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

Parameters

Parameter	Type	Required	Description
devId	string	Yes	The device ID.
limit	number	Yes	The number of entries per page.
offset	number	Yes	The number of the entry starting from which entries are returned.
callback	IThingResultCallback	Yes	Execute callback

Return value

None (results are returned via the callback).

Example

const callback: IThingResultCallback<SweeperHistory> = {
  onSuccess: (result?: SweeperHistory) => {
    if (result) {
      L.i('SweeperDemo', `Obtained history records of multiple maps successfully`)
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `Failed to obtain history records: ${errorMsg}`)
  }
}

ThingSweeperKit.getInstance().getSweeperMultiMapHistoryData(
  'device_abc123',
  20,   // 20 items on each page
  0,    // Page 1
  callback
)

getSweeperMultiMapHistoryDataWithTimeRange

Functional description

Gets the multi-map history records of the robot vacuum (with time range).

Function signature

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

Parameters

Parameter	Type	Required	Description
devId	string	Yes	The device ID.
limit	number	Yes	The number of entries per page.
offset	number	Yes	The number of the entry starting from which entries are returned.
startTime	number	Yes	The start timestamp.
endTime	number	Yes	The end timestamp.
callback	IThingResultCallback	Yes	Execute callback

Return value

None (results are returned via the callback).

Example

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

const callback: IThingResultCallback<SweeperHistory> = {
  onSuccess: (result?: SweeperHistory) => {
    if (result) {
      L.i('SweeperDemo', `Obtained history records of multiple maps successfully`)
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `Failed to obtain history records: ${errorMsg}`)
  }
}

ThingSweeperKit.getInstance().getSweeperMultiMapHistoryDataWithTimeRange(
  'device_abc123',
  20,          // 20 items on each page
  0,           // Page 1
  oneWeekAgo,  // One week ago
  now,         // Now
  callback
)

deleteSweeperHistoryData

Functional description

Deletes the cleaning history of the robot vacuum.

Function signature

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

Parameters

Parameter	Type	Required	Description
devId	string	Yes	The device ID.
fileIdList	string[]	Yes	The list of IDs for the files to be deleted.
callback	IThingResultCallback	Yes	The callback interface (returns the deletion result).

Return value

None (results are returned via the callback).

Example

const callback: IThingResultCallback<boolean> = {
  onSuccess: (result?: boolean) => {
    if (result) {
      L.i('SweeperDemo', 'Deleted history successfully')
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `Failed to delete: ${errorMsg}`)
  }
}

ThingSweeperKit.getInstance().deleteSweeperHistoryData(
  'device_abc123',
  ['file_001', 'file_002'],  // The ID of the file to be deleted
  callback
)

getSweeperCurrentPath

Functional description

Gets the current path information of the robot vacuum, including the map path and route path.

Function signature

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

Parameters

Parameter	Type	Required	Description
devId	string	Yes	The device ID.
bucket	string | undefined	No	(Optional) The OSS bucket name. The passed-in value takes precedence. Otherwise, the cached value is used.
callback	IThingResultCallback	Yes	Execute callback

SweeperCurrentPathBean data structure

interface SweeperCurrentPathBean {
  mapPath: string     // Map file path
  routePath: string   // Route file path
}

Return value

None (results are returned via the callback).

Example

const callback: IThingResultCallback<SweeperCurrentPathBean> = {
  onSuccess: (result?: SweeperCurrentPathBean) => {
    if (result) {
      L.i('SweeperDemo', `Map path: ${result.mapPath}`)
      L.i('SweeperDemo', `Route path: ${result.routePath}`)
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `Failed to get the path: ${errorMsg}`)
  }
}

// Method 1: Use a cached bucket
ThingSweeperKit.getInstance().getSweeperCurrentPath(
  'device_abc123',
  undefined,
  callback
)

// Method 2: Specify bucket
ThingSweeperKit.getInstance().getSweeperCurrentPath(
  'device_abc123',
  'custom-bucket-name',
  callback
)

sweeperFileNameUpdateWithDevId

Functional description

Renames a map file for multi-layer map scenarios.

Function signature

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

Parameters

Parameter	Type	Required	Description
devId	string	Yes	The device ID.
id	number	Yes	The ID of the specified multi-layer map.
name	string	Yes	The new name.
callback	IThingResultCallback	Yes	The callback interface (returns the rename result).

Return value

None (results are returned via the callback).

Example

const callback: IThingResultCallback<boolean> = {
  onSuccess: (result?: boolean) => {
    if (result) {
      L.i('SweeperDemo', 'Renamed the map successfully')
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `Failed to rename: ${errorMsg}`)
  }
}

ThingSweeperKit.getInstance().sweeperFileNameUpdateWithDevId(
  'device_abc123',
  1,               // Map ID
  'Living Room',   // New name
  callback
)

IThingGyroAndVisualSweeperKit - interfaces for gyroscope robot vacuum

getInstance

Functional description

Gets the singleton instance of the gyroscope robot vacuum functionality.

Function signature

static getInstance(): IThingGyroAndVisualSweeperKit

Return value

Type	Description
IThingGyroAndVisualSweeperKit	The interface instance (singleton) of the gyroscope robot vacuum.

Example

const gyroSweeperKit = ThingGyroAndVisualSweeperKit.getInstance()

queryLatestCleanRecord

Functional description

Queries the latest cleaning record (for stream service 1.0/v2).

Function signature

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

Parameters

Parameter	Type	Required	Description
devId	string	Yes	The device ID.
start	string	Yes	The start position. Pass an empty string for the first request. For subsequent requests, pass the startRow from the previous response.
size	number	Yes	The maximum number of entries returned per call.
callback	IThingResultCallback	Yes	Execute callback

SweeperCleanRecordBean data structure

interface SweeperCleanRecordBean {
  subRecordId: number     // Sub-record ID
  cleanArea: number       // Cleaning area
  cleanTime: number       // Cleaning duration
  startTime: number       // Start time
  endTime: number         // End time
  data: string            // Path data
  startRow: string        // Start position for the next request
}

Return value

None (results are returned via the callback).

Example

const callback: IThingResultCallback<SweeperCleanRecordBean> = {
  onSuccess: (result?: SweeperCleanRecordBean) => {
    if (result) {
      L.i('SweeperDemo', `Cleaning area: ${result.cleanArea}m²`)
      L.i('SweeperDemo', `Cleaning duration: ${result.cleanTime}s`)
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `Query failed: ${errorMsg}`)
  }
}

ThingGyroAndVisualSweeperKit.getInstance().queryLatestCleanRecord(
  'device_abc123',
  '',      // First request
  100,     // Maximum of 100 requests per time
  callback
)

queryLatestCleanRecordV2

Functional description

Queries the latest cleaning record (for stream service 2.0/v3).

Function signature

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

Parameters

The same as queryLatestCleanRecord.

Return value

None (results are returned via the callback).

Example

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

getHistoryCleanRecordList

Functional description

Queries historical cleaning task data.

Function signature

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

Parameters

Parameter	Type	Required	Description
devId	string	Yes	The device ID.
offset	number	Yes	The number of the entry starting from which entries are returned.
limit	number	Yes	The number of entries returned per page.
startTime	number	Yes	The start time (timestamp) for the query.
endTime	number	Yes	The end time (timestamp) for the query.
callback	IThingResultCallback	Yes	Execute callback

SweeperHistoryBean data structure

interface SweeperHistoryBean {
  total: number                 // Total number of entries
  records: SweeperCleanRecord[] // The list of cleaning tasks
}

interface SweeperCleanRecord {
  id: string          // Record ID
  startTime: number   // Start time
  endTime: number     // End time
  cleanArea: number   // Cleaning area
  cleanTime: number   // Cleaning duration
}

Return value

None (results are returned via the callback).

Example

const callback: IThingResultCallback<SweeperHistoryBean> = {
  onSuccess: (result?: SweeperHistoryBean) => {
    if (result) {
      L.i('SweeperDemo', `Total records: ${result.total}`)
      result.records.forEach(record => {
        L.i('SweeperDemo', `Record: ${record.id}, area: ${record.cleanArea}m²`)
      })
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `Query failed: ${errorMsg}`)
  }
}

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

ThingGyroAndVisualSweeperKit.getInstance().getHistoryCleanRecordList(
  'device_abc123',
  0,            // Page 1
  20,           // 20 items on each page
  oneWeekAgo,   // One week ago
  now,          // Now
  callback
)

getCleanRecordDetail

Functional description

Queries the details of cleaning tasks (for stream service 1.0/v2).

Function signature

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

Parameters

Parameter	Type	Required	Description
devId	string	Yes	The device ID.
subRecordId	number	Yes	The ID of the cleaning task you want to query.
start	string	Yes	The start position.
size	number	Yes	The maximum number of entries returned per call.
callback	IThingResultCallback	Yes	Execute callback

Return value

None (results are returned via the callback).

Example

const callback: IThingResultCallback<SweeperCleanRecordBean> = {
  onSuccess: (result?: SweeperCleanRecordBean) => {
    if (result) {
      L.i('SweeperDemo', `Cleaning details: area=${result.cleanArea}m², duration=${result.cleanTime}s`)
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `Failed to query details: ${errorMsg}`)
  }
}

ThingGyroAndVisualSweeperKit.getInstance().getCleanRecordDetail(
  'device_abc123',
  12345,   // Sub-record ID
  '',      // First request
  100,
  callback
)

getCleanRecordDetailV2

Functional description

Queries the details of cleaning tasks (for stream service 2.0/v3).

Function signature

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

Parameters

Parameter	Type	Required	Description
devId	string	Yes	The device ID.
subRecordId	number	Yes	The ID of the cleaning task.
start	string	Yes	The start position.
size	number	Yes	The maximum number of entries returned per call.
mapId	number	Yes	The sub-map ID.
datatype	number	Yes	The map type.
callback	IThingResultCallback	Yes	Execute callback

Return value

None (results are returned via the callback).

Example

ThingGyroAndVisualSweeperKit.getInstance().getCleanRecordDetailV2(
  'device_abc123',
  12345,  // Sub-record ID
  '',     // First request
  100,
  1,      // Map ID
  0,      // Data type
  callback
)

deleteHistoryCleanRecord

Functional description

Deletes historical cleaning tasks.

Function signature

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

Parameters

Parameter	Type	Required	Description
devId	string	Yes	The device ID.
uuids	string[]	Yes	The unique ID (list of UUIDs) for each cleaning task.
callback	IThingResultCallback	Yes	The callback interface (returns the deletion result).

Return value

None (results are returned via the callback).

Example

const callback: IThingResultCallback<boolean> = {
  onSuccess: (result?: boolean) => {
    if (result) {
      L.i('SweeperDemo', 'Deleted successfully')
    }
  },
  onFailure: (errorCode: string, errorMsg: string) => {
    L.e('SweeperDemo', `Failed to delete: ${errorMsg}`)
  }
}

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

getSubRecordId

Functional description

Extracts SubRecordID from a string with a specific format.

Function signature

getSubRecordId(value: string): number

Parameters

Parameter	Type	Required	Description
value	string	Yes	The input string.

Return value

Type	Description
number	SubRecordID. 0 is returned on extraction failure.

Parsing rules

String length	Format	Extraction logic
23	12+3+3+5	Extract the last 5 digits
11	3+3+5	Extract the last 5 digits

Example

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

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

Complete usage flow

Standard map download process

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 {
      // Step 1: Initialize cloud storage configuration
      const bucket = await this.initCloudConfig()
      L.i(TAG, `Configuration successful: bucket=${bucket}`)

      // Step 2: Start MQTT data channel
      this.startMqttChannel()

      // Step 3: Wait for map data push... (handled in the listener)

    } catch (error) {
      L.e(TAG, `Process failed: ${error}`)
    }
  }

  // Initialize cloud storage configuration
  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)
    })
  }

  // Start MQTT data channel
  private startMqttChannel() {
    const listener: IThingSweeperDataListener = {
      onSweeperDataReceive: (data: SweeperDataBean) => {
        L.i(TAG, `Received map data: mapId=${data.mapId}, file=${data.file}`)

        // Download map file
        this.downloadMapFile(data.file, data.bucket)
      },
      onSweeperDataRemove: () => {
        L.i(TAG, 'Map data removed')
      }
    }

    this.sweeperKit.startConnectSweeperDataChannel(listener)
    L.i(TAG, 'MQTT data channel is started')
  }

  // Download map file
  private downloadMapFile(path: string, bucket: string) {
    const listener: IThingByteDataListener = {
      onSuccess: (data: Uint8Array) => {
        L.i(TAG, `File downloaded successfully: ${data.length} bytes`)

        // Save to local
        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, `Map saved: ${savePath}`)
      },
      onFailure: (errorCode: string, errorMsg: string) => {
        L.e(TAG, `Download failed: ${errorCode} - ${errorMsg}`)
      }
    }

    this.sweeperKit.downloadFile(path, bucket, listener)
  }

  // Clean up resources
  cleanup() {
    this.sweeperKit.stopConnectSweeperDataChannel()
    L.i(TAG, 'Resources have been cleaned up')
  }
}

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

// Clean up on exit
// downloader.cleanup()

History record management process

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

const TAG = 'HistoryDemo'

class SweeperHistoryManager {
  private gyroKit = ThingGyroAndVisualSweeperKit.getInstance()

  // Get the history of the past week
  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, `Obtained ${result.total} records`)
            resolve(result)
          } else {
            reject(new Error('result is empty'))
          }
        },
        onFailure: (errorCode: string, errorMsg: string) => {
          reject(new Error(`${errorCode}: ${errorMsg}`))
        }
      }

      this.gyroKit.getHistoryCleanRecordList(
        deviceId,
        0,            // Page 1
        50,           // 50 items on each page
        oneWeekAgo,
        now,
        callback
      )
    })
  }

  // Delete specified history
  async deleteRecords(deviceId: string, uuids: string[]) {
    return new Promise<boolean>((resolve, reject) => {
      const callback: IThingResultCallback<boolean> = {
        onSuccess: (result?: boolean) => {
          L.i(TAG, 'Deleted successfully')
          resolve(result || false)
        },
        onFailure: (errorCode: string, errorMsg: string) => {
          reject(new Error(`${errorCode}: ${errorMsg}`))
        }
      }

      this.gyroKit.deleteHistoryCleanRecord(deviceId, uuids, callback)
    })
  }
}

// Use
const historyManager = new SweeperHistoryManager()

// Get history records
const history = await historyManager.getRecentHistory('device_abc123')
console.log(`Total records: ${history.total}`)

// Delete the first 2 records
if (history.records.length >= 2) {
  const uuidsToDelete = history.records.slice(0, 2).map(r => r.id)
  await historyManager.deleteRecords('device_abc123', uuidsToDelete)
}

Data model reference

CloudConfigBean

interface CloudConfigBean {
  bucket: string       // OSS bucket name
  region: string       // Region
  pathConfig: PathConfig  // Path configuration
}

interface PathConfig {
  common: string       // Common path prefix
}

SweeperDataBean

interface SweeperDataBean {
  mapId: number        // Map ID
  bucket: string       // OSS bucket
  file: string         // File path
  region: string       // Region
  expireTime: number   // Expiration time
}

SweeperByteDataBean

interface SweeperByteDataBean {
  mapId: number        // Map ID
  type: number         // Data type
  data: Uint8Array     // Binary data
}

SweeperCleanRecordBean

interface SweeperCleanRecordBean {
  subRecordId: number   // Sub-record ID
  cleanArea: number     // Cleaning area (square meter)
  cleanTime: number     // Cleaning duration (in seconds)
  startTime: number     // Start time (timestamp)
  endTime: number       // End time (timestamp)
  data: string          // Path data (JSON string)
  startRow: string      // Start position for the next request
}

SweeperHistoryBean

interface SweeperHistoryBean {
  total: number                 // Total number of entries
  records: SweeperCleanRecord[] // The list of cleaning tasks
}

interface SweeperCleanRecord {
  id: string          // Record ID
  startTime: number   // Start time
  endTime: number     // End time
  cleanArea: number   // Cleaning area
  cleanTime: number   // Cleaning duration
}

SweeperCurrentPathBean

interface SweeperCurrentPathBean {
  mapPath: string     // Map file path
  routePath: string   // Route file path
}

SweeperHistory

interface SweeperHistory {
  id: string          // Record ID
  startTime: number   // Start time
  endTime: number     // End time
  area: number        // Cleaning area
  time: number        // Cleaning duration
}