跳到主要内容
信息

前提导读

局域网设备

更新时间：2026-10-27 19:49:17

当手机与设备处于同一局域网（非公网）时，可以通过局域网搜索发现设备，并与设备建立局域网连接。连接成功后可以进行设备播放（直播、SD卡回放）、获取网关设备下的子设备列表等。

// 导入局域网设备SDK
import { RTCXWlanLinkService, RTCXWlanLinkType } from 'rtcxsdk'

接口定义​

export type WlanLinkCallback =
  (success: boolean, data: Object | undefined, error: BusinessError<void> | undefined) => void

export interface IWlanLinkService {
  /**
   * 开始搜索局域网设备
   *
   * @param callback 响应回调，搜索到多个设备时会多次触发
   */
  startSearchWlanDevice(callback: WlanLinkCallback): void

  /**
   * 停止搜索局域网设备
   */
  stopSearchWlanDevice(): void

  /**
   * 开始局域网设备连接
   *
   * @param req 连接参数对象
   * @param callback 连接结果回调
   */
  startConnect(req: IWlanLinkConnectReq, callback: WlanLinkCallback): void

  /**
   * 断开局域网设备连接
   */
  disconnect(): void

  /**
   * 释放缓存的P2P通道，避免其他手机因P2P通道达到上限而无法连接
   */
  releaseCache(): void

  /**
   * 请求网关的子设备列表
   *
   * @param req 请求参数对象
   * @param callback 子设备列表结果回调
   */
  queryGatewaySubdeviceList(req: IWlanLinkSubdeviceListReq, callback: WlanLinkCallback): void
}

数据结构​

// 局域网设备信息
export interface IWlanLinkDevModel {
  // 设备型号 如：xLeWcoelZbyOePbJludl
  productKey?: string
  // 设备序列号SN 如：TEST20240820002
  deviceName?: string
  // 设备状态。0（未激活）；1（在线）；2（休眠）；3（离线）；8（禁用）
  status?: number
  // 设备属性
  tslProperty?: Record<string, Object>
  // 设备信息
  deviceInfo?: IWlanLinkDevInfo
  // 网络信息
  netInfo?: IWlanLinkNetInfo
  // 设备原始响应数据
  rawData?: Object
}

// 局域网设备基础信息
export interface IWlanLinkDevInfo {
  // 设备型号 如：xLeWcoelZbyOePbJludl
  productKey?: string
  // 设备序列号SN 如：TEST20240820002
  deviceName?: string
  // true：网关设备；false：非网关设备
  isGateway?: boolean
}

// 局域网设备网络信息
export interface IWlanLinkNetInfo {
  // 信令服务协议
  protocol?: string
  // 信令服务IP，搜索时为设备响应报文的来源IP
  sigIp?: string
  // 信令服务端口
  sigPort?: number
}

// 局域网设备连接请求
export interface IWlanLinkConnectReq {
  // 设备信令服务IP，必选
  ip: string
  // 设备信令服务端口，必选
  port: number
  // 设备信令服务协议，必选
  proto: string
  // 鉴权信息，可选
  authenticate?: string
}

// 网关子设备列表请求
export interface IWlanLinkSubdeviceListReq {
  // 网关设备型号
  productKey: string
  // 网关设备序列号SN
  deviceName: string
}

错误码​

export enum EWlanLinkError {
  // 搜索设备超时
  SEARCH_TIMEOUT = -1005
}

搜索设备​

调用 startSearchWlanDevice 后，SDK 会在当前局域网内广播搜索请求。若周围有多台设备响应，回调会多次触发，业务层可将每次回调返回的设备追加到列表展示。

private lanDevices: RTCXWlanLinkType.IWlanLinkDevModel[] = []

startSearch(): void {
  this.lanDevices = []
  RTCXWlanLinkService.startSearchWlanDevice((success: boolean, data: Object | undefined,
    error: BusinessError<void> | undefined) => {
    if (!success) {
      // 30秒内未搜索到任何设备时，error.code 为 RTCXWlanLinkType.EWlanLinkError.SEARCH_TIMEOUT
      showToast(`搜索失败：${error?.code} ${error?.message}`)
      return
    }
    // 回调可能多次触发，追加到列表展示
    this.lanDevices.push(data as RTCXWlanLinkType.IWlanLinkDevModel)
  })
}
备注
  • 搜索通过局域网 UDP 广播完成，设备响应后 SDK 会将响应报文的来源 IP 作为该设备的 netInfo.sigIp 返回。
  • 搜索到第一台设备后不再触发搜索超时，搜索会一直保持，直到调用 stopSearchWlanDevice 或在页面退出时释放。
  • 当前版本仅支持同一局域网内的广播搜索，暂不支持指定 IP 搜索。

停止搜索设备​

不再需要继续搜索时，调用该接口停止搜索并释放 UDP 资源。

RTCXWlanLinkService.stopSearchWlanDevice()

连接设备​

设备播放、SD卡查询前需要先建立局域网连接，建议搜索到设备后提前连接。连接参数直接使用搜索返回的 netInfo。

const netInfo = device.netInfo
if (netInfo?.sigIp && netInfo.sigPort && netInfo.protocol) {
  RTCXWlanLinkService.startConnect({
    ip: netInfo.sigIp,
    port: netInfo.sigPort,
    proto: netInfo.protocol
  }, (success: boolean, _data: Object | undefined,
    error: BusinessError<void> | undefined) => {
    if (success) {
      // 连接成功，可以进行播放、SD卡查询等操作
    } else {
      showToast(`连接失败：${error?.code} ${error?.message}`)
    }
  })
}
备注
  • 该接口只用于连接网关主设备或普通设备，不能对网关子设备调用；子设备通过网关的局域网连接访问。
  • 若设备开启了连接鉴权，需要在请求中携带 authenticate。
  • 如需限制连接等待时间，业务层可自行增加超时控制。

断开连接设备​

不再需要连接设备时（如退出局域网设备页面），需要断开设备连接。

RTCXWlanLinkService.disconnect()

释放缓存​

退出局域网流程时，需要释放缓存的 P2P 通道，避免因占用 P2P 资源导致其他手机无法连接播放。

RTCXWlanLinkService.releaseCache()

建议在页面退出时按顺序完成停止搜索、断开连接和释放缓存：

aboutToDisappear(): void {
  RTCXWlanLinkService.stopSearchWlanDevice()
  RTCXWlanLinkService.disconnect()
  RTCXWlanLinkService.releaseCache()
}

网关子设备列表​

当搜索到的设备是网关设备（deviceInfo.isGateway === true）时，连接成功后可以获取该网关下的子设备列表，非网关设备不需要调用此接口。

RTCXWlanLinkService.queryGatewaySubdeviceList({
  productKey: gateway.productKey!,
  deviceName: gateway.deviceName!
}, (success: boolean, data: Object | undefined,
  error: BusinessError<void> | undefined) => {
  if (!success) {
    showToast(`获取网关子设备失败：${error?.code} ${error?.message}`)
    return
  }
  const subDevices = Array.isArray(data)
    ? data as RTCXWlanLinkType.IWlanLinkDevModel[]
    : []
  // 展示子设备列表
})
备注
  • 回调成功时，data 为 IWlanLinkDevModel[]。
  • 查询子设备前需要先连接网关设备。
  • 查询成功后 SDK 会记录子设备与网关的映射关系，后续子设备的播放、SD卡查询等操作会通过网关的局域网通道访问，不需要单独连接子设备。

设备播放​

局域网设备播放接口与通用版基本相同，请先阅读【通用版-音视频播放】。区别在于构建 IPlayInfo 时需要设置 deviceType = 2，iotId 为 productKey 与 deviceName 拼接。

  • 直播
// device 为搜索或网关子设备列表返回的 IWlanLinkDevModel
const playInfo: RTCXMediaType.IPlayInfo = {
  iotId: `${device.productKey}${device.deviceName}`,
  productKey: device.productKey!,
  deviceName: device.deviceName!,
  lensId: 0,
  streamType: 0,
  deviceType: 2 // 局域网设备
}
this.playInfo = playInfo
this.playerController = new RTCXMediaControl.PlayerController(playInfo, this.playerListener)
this.playerController.start()

播放窗口仍使用 RTCXPlayerView，将 playInfo 和 playerController 传入即可。

  • SD卡回放
const playbackInfo: RTCXMediaType.IPlaybackInfo = {
  startTime: startTime,
  endTime: endTime,
  playbackType: RTCXMediaType.PlaybackTypeEnum.SDCardRecord
}
this.playerController?.seekToTime(playbackInfo)

SD卡存储录像​

局域网设备的 SD 卡数据获取与通用版基本相同，请先阅读【通用版-存储卡】。区别在于构建请求对象时需要设置 deviceType = 2，即使用局域网 AP 信令查询。

const req: RTCXPlaybackTypes.SDCardRecordQueryReq = {
  productKey: device.productKey!,
  deviceName: device.deviceName!,
  beginTime: startTime,
  endTime: endTime,
  pageSize: 100,
  deviceType: 2 // 局域网设备
}

try {
  const rsp = await RTCXSDCardPlayback.recordTimeQuery(req)
  this.recordList = rsp.recordFileList
} catch (e) {
  showToast(`获取数据失败：${e}`)
}

recordFileQuery（按文件查询）和 eventTimeQuery（事件查询）的请求对象同样需要设置 deviceType = 2。

当前版本说明​

  • 搜索仅支持同一局域网内的 UDP 广播，暂不支持指定 IP 搜索。
  • 局域网设备的物模型（如 PTZ）操作当前版本仍走云端信令通道，纯局域网环境下暂不支持。
  • 按月录制统计查询暂未适配局域网信令通道，需要设备同时在线于云端。