更新记录

2.2.4（2026-04-10） 下载此版本

2.2.4

2.2.3（2026-04-01） 下载此版本

2.2.3

2.2.2（2026-03-18） 下载此版本

2.2.2

平台兼容性

uni-app(4.73)

uni-app x(4.73)

Uascent-MarsGateSDK 插件文档

版本：2.2.4

目录

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

插件介绍

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

接入指引

引入插件

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，logCallback)

添加设备。

参数

info参数结构

wifiInfo参数结构

callback参数结构

logCallback参数结构

返回值 Promise 成功

  {
    code: 0,
    data: {
      deviceId: 'xxxxxxxxxxxx', // 设备的唯一标识
      bindState: 1, // WiFi设备绑定状态 0: 添加中  1: 成功 2：失败
      deviceName: 'xxxxxxxxxxxx', // WiFi设备名称
      productId: 'xxxxxxxxxxxx', // WiFi产品ID
      productName: 'xxxxxxxxxxxx', // WiFi产品名称
      productBrand: 'xxxxxxxxxxxx', // WiFi产品品牌
      productModel: 'xxxxxxxxxxxx', // WiFi产品型号
      productUrl: 'xxxxxxxxxxxx', // WiFi产品图标
      isAddNetwork: true, // 是否支持添加网络
      isSupportWiFiList: true, // 是否支持通过设备获取2.4G WiFi列表
      isSupport4G: true, // 是否支持通过4G网络
    },
    message: '成功'
  }

data数据结构

WiFi设备添加网络

addNetwork(info, wifiInfo, callback, logCallback)

添加设备网络。

参数

info参数结构

wifiInfo参数结构

callback参数结构

logCallback参数结构

返回值

Promise

蓝牙相关

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']

设备蓝牙状态变化回调onStateChange

回调函数的参数为Object 。

Object 键值对

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

设备上报数据onReport

回调函数的参数为Object 。

Object 键值对

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

control(deviceInfo, data)

通过蓝牙控制设备。

参数

deviceInfo参数结构

searchWifi(deviceInfo)

通过蓝牙通知WiFi设备搜索附近WiFi，支持该方法的WiFi设备会在connect方法中onReport回调中返回WiFi列表，列表是分批上报，收到数据根据自身需求进行处理，WiFi列表为wifiList，每个WiFi项格式为：

{
  wifiList: [
    {
      ssid: 'WiFi名称',
      bssid: 'WiFi BSSID',
      rssi: -60
    },
    {
      ssid: 'WiFi名称',
      bssid: 'WiFi BSSID',
      rssi: -80
    }
  ]
}

参数

deviceInfo参数结构

stopSearchWifi(deviceInfo)

通过蓝牙通知WiFi设备停止搜索WiFi。

参数

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)
})

sendQuery(deviceInfo, properties)

发送查询指令到WiFi设备。

参数

deviceInfo参数结构

返回值

Promise

示例

plugin.sendQuery(deviceInfo).then(res => {
  console.log(res)
}).catch(err => {
  console.log(err)
})

getWifiDeviceStatus(params)

获取WiFi设备最新状态。

请求参数

返回值

Promise

返回参数

Array 设备列表

resetDevice(params)

重置WiFi设备。

请求参数params

返回值

Promise

getUpgradeInfo(params)

查询设备升级信息。

请求参数params

返回值

Promise

返回参数

Array 设备列表

upgrade(params)

升级设备。

请求参数params

返回值

Promise

设备通用

getProductModel(productId)

获取产品物模型信息。

参数

返回值

Promise

返回参数

data 说明

properties 说明

valueType 说明

Expands 说明

getDeviceId(prams)

通过MAC地址和产品ID获取设备ID。

参数

返回值

Promise

成功

  {
    code: 0,
    data: {
      deviceId: 'xxxxxxxxxxxx', // 设备的唯一标识
      productId: 'xxxxxxxxxxxx', // 产品ID
      mac: 'xxxxxxxxxxxx', // MAC地址
    },
    message: '成功'
  }

状态码

成功

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

失败

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

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

注意事项

1. 使用蓝牙功能时需要注意：
   • Android 平台：android6.0+，需要打开蓝牙，打开位置开关，需要授权微信访问位置的权限，部分手机甚至要打开 GPS
   • ios 平台：需要打开系统蓝牙，打开控制中心蓝牙，ios13+需要给微信蓝牙分享的权限
2. WiFi配网注意事项：
   • 需要确保设备处于配网模式
   • 配网过程中，部分设备会在回调中上报错误信息，但设备还会继续尝试配网，直到成功或超时，可根据业务需求处理
3. Socket注意事项：
   • 订阅会自动取消上一次订阅，订阅时请订阅所有需要的设备
   • 订阅后才能收到设备消息
4. 升级注意事项：
   • 升级中和升级完成的设备不要重复调用升级接口
   • 升级中设需要处理设备离线的情况，离线时升级会失败'
5. 通过设备获取周围WiFi列表
   • 在设备支持的情况下，需要先连接设备蓝牙（调用connect），才能获取周围WiFi列表（调用searchWifi）
   • 获取WiFi列表后，添加设备时，不需要断开蓝牙，直接调用添加设备（add）或者添加网络（addNetwork）即可