更新记录

1.0.9（2025-07-03） 下载此版本

1.0.9

1.0.8（2025-05-12） 下载此版本

1.0.8

1.0.7（2025-04-09） 下载此版本

1.0.7

平台兼容性

Uascent-MarsGateSDK 插件文档

版本：1.0.9

目录

• Uascent-MarsGateSDK 插件文档
  • 目录
  • 插件介绍
  • 接入指引
  • 引入插件
  • API 文档
  • 初始化
    • init(config)
  • 设备搜索
    • search(options)
    • onSearchListChange(callback)
    • stopSearch()
  • 设备添加
    • add(info, wifiInfo, callback)
  • 蓝牙设备相关
    • connect(options)
    • control(deviceInfo, data)
    • closeConnect(param)
  • WIFi设备相关
    • connectSocket()
    • disConnectSocket()
    • getSocketStatus()
    • subscribeDevice(list)
    • unSubscribeDevice()
    • onMessageChange(callback)
    • offMessageChange(callback)
    • onSocketStatusChange(callback)
    • offSocketStatusChange(callback)
    • sendControl(deviceInfo, properties)
    • getWifiDeviceStatus(params)
    • getProductModel(productId)
    • resetDevice(params)
    • getUpgradeInfo(params)
    • upgrade(params)
  • 状态码
    • 成功
    • 失败
  • 注意事项

插件介绍

MarsGateUniSDK 是一个用于在小程序中实现蓝牙和 WiFi 设备管理的插件。它提供了设备搜索、添加、连接、控制、OTA等完整功能。

接入指引

引入插件

import MarsGateSDK from '@/uni_modules/Uascent-MarsGateSDK/js_sdk/index.js'

API 文档

初始化

init(config)

初始化插件配置。

参数

返回值

Promise

设备搜索

search(options)

开始搜索设备。

参数

无

返回值

Promise

onSearchListChange(callback)

监听搜索到的设备列表变化。

参数

Function 回调函数，返回设备列表数据：

{
  code: 0,
  data: [], // 设备列表
  message: '成功'
}

设备列表项数据结构

stopSearch()

停止搜索设备。

设备添加

add(info, wifiInfo, callback)

添加设备。

参数

info参数结构

返回值 Promise 成功

  {
    code: 0,
    data: {
      deviceId: 'xxxxxxxxxxxx', // 设备的唯一标识
    },
    message: '成功'
  }

蓝牙设备相关

connect(options)

连接蓝牙设备。

参数

设备信息deviceInfo

设备DP点信息dpInfo

Object 键值对

  {
    switch: 1, // 开关
    level: 2, // 档位(数值)
    timingPowerOff1: 3, // 定时关机(小时)
    angleAutoLROnOff: 4, // 左右旋转/摇头/摆风
    angleAutoUDOnOff: 5, // 上下旋转/摇头/摆风
    anionOnOff: 10, // 负离子功能
    mode: 12, // 风扇工作模式
  }

设备DP点信息protocol 全属性上报的数据协议,从协议数据位的第一字节开始，对应属性key，按顺序组成数组

• 如果在中间有未使用字节，使用void 0 undefined null 表示该字节未使用
• 如果某个字节按位上报，使用数组表示，规则和字节相似，数字下标0表示 bit 0

  ['switch', 'level', void 0, 'timingPowerOff1', ['angleAutoLROnOff', 'angleAutoUDOnOff'] ,'anionOnOff', 'mode']

设备DP点信息onStateChange

回调函数的参数为Object 。

Object 键值对

  onStateChange: (res) => {
    console.log('onStateChange', res)
  }

设备上报数据onReport

回调函数的参数为Object 。

Object 键值对

  onReport: (res) => {
    console.log('onReport', res.data)
  }

control(deviceInfo, data)

控制蓝牙设备。

参数

deviceInfo参数结构

closeConnect(param)

关闭蓝牙连接。

参数

WIFi设备相关

connectSocket()

连接WebSocket。

返回值

Promise

disConnectSocket()

断开WebSocket连接。

返回值

Promise

getSocketStatus()

获取WebSocket连接状态。

返回值

Promise，返回数据结构：

{
  code: 0,
  data: {
    status: 'connecting' // WebSocket连接状态CONNECTING: 'connecting: 连接中 'open': 已连接 'closing': 关闭中 'closed': 已关闭  'error': 连接错误 
  },
  message: '成功'
}

subscribeDevice(list)

订阅设备消息。

参数

Array 设备列表，每项结构：

unSubscribeDevice()

取消订阅设备消息。

参数

无

返回值 Promise

onMessageChange(callback)

监听设备消息变化。

callback参数

{
  'xxxxxxx': { // 设备ID
    data: { // 设备属性键值对

    },
    online_state: 'online', // 设备在线状态 online/offline
    dev_reset: true, // 设备重置
    upgrade: {
      result: 'fail', // 升级结果 success/fail
      error: '文件过大', // 升级错误信息
      progress: 56 // 升级进度 
    }
  }
}

offMessageChange(callback)

取消监听设备消息。

callback参数

onSocketStatusChange(callback)

监听WebSocket连接状态变化。

callback参数

{
  status: 'connecting' // WebSocket连接状态CONNECTING: 'connecting: 连接中 'open': 已连接 'closing': 关闭中 'closed': 已关闭  'error': 连接错误
}

offSocketStatusChange(callback)

取消WebSocket监听连接状态。

sendControl(deviceInfo, properties)

发送控制指令到WiFi设备。

参数

deviceInfo参数结构

返回值

Promise

示例

plugin.sendControl(deviceInfo, {switch: 1}).then(res => {
  console.log(res)
}).catch(err => {
  console.log(err)
})

getWifiDeviceStatus(params)

获取WiFi设备最新状态。

请求参数

返回值

Promise

返回参数

Array 设备列表

getProductModel(productId)

获取产品物模型信息。

参数

返回值

Promise

resetDevice(params)

重置WiFi设备。

请求参数params

返回值

Promise

getUpgradeInfo(params)

查询设备升级信息。

请求参数params

返回值

Promise

返回参数

Array 设备列表

upgrade(params)

升级设备。

请求参数params

返回值

Promise

状态码

成功

  {
    code: 0,
    data: {}, // 成功返回的数据，无数据是不存在该字段
    message: '成功'
  }

失败

  {
    errCode： 1001,
    errMsg： '错误信息'
  }

其余的错误码请参考uni-app官方蓝牙相关接口错误码

注意事项

1. 使用蓝牙功能时需要注意：

   • Android 平台：android6.0+，需要打开蓝牙，打开位置开关，需要授权微信访问位置的权限，部分手机甚至要打开 GPS
   • ios 平台：需要打开系统蓝牙，打开控制中心蓝牙，ios13+需要给微信蓝牙分享的权限

2. WiFi配网注意事项：

   • 配网超时时间为60秒
   • 需要确保设备处于配网模式

3. Socket注意事项：

   • 订阅会自动取消上一次订阅，订阅时请订阅所有需要的设备
   • 订阅后才能收到设备消息

4. 升级注意事项：

   • 升级中和升级完成的设备不要重复调用升级接口
   • 升级中设需要处理设备离线的情况，离线时升级会失败