跳到主要内容

局域网设备接入

更新时间：2025-07-22 18:35:15
信息

前提导读

此章节内容仅针对局域网设备接入进行说明。

接入前提：设备已完成了设备IoTSDK和StreamSDK的接入，具体流程可以参考普通IPC接入流程: IoTSDK接入 和 StreamSDK接入

概述​

在特定的应用场景中，设备可能运行于局域网环境，并因此无法直接访问外网。此外，设备还可能具备开启接入点（AP）热点的功能，允许手机客户端通过连接该热点来对设备进行配置和操作。

针对这两种情况，理解本章节的内容将至关重要，本章节详细说明了如何在这种网络环境下有效管理和操作设备。

相关接口​

IoTSDK初始化之后默认工作在广域网模式，如果需要工作在局域网AP模式，需要调用如下接口进行切换：


/** 
 * @brief 切换SDK工作的网络模式，局域网(AP热点)模式或者广域网模式
 * @param mode : 网络模式，枚举值，XS_IOT_NET_LAN 或者 XS_IOT_NET_INTERNET
 * @param param: mode = XS_IOT_NET_LAN时有效，表示局域网内本地监听的端口，0表示使用SDK内部默认端口（9821）
 * @note  如果未设置，默认工作在广域网模式
*/
xs_int32 xs_iot_switch_net_mode(xs_iotNetWorkMode_en mode, xs_int32 lanListernPort);

调用流程​

启动过程：如果设备需要工作在局域网或AP模式，sdk初始化之后，连接服务器之前，直接设置工作的网络模式为局域网模式（如未设置，默认会连接广域网服务器）：

示例代码：

{
xs_iot_init(&cbFun, &initParam);
xs_iot_switch_net_mode(XS_IOT_NET_LAN, 0);	//0表示使用sdk内部默认端口
xs_iot_open(XS_IOT_DEV_TYPE_MASTER, &devAuth.devInfo);
xs_iot_connect(devAuth.devId);
...
}

运行过程中，如果切换工作模式，直接调用xs_iot_switch_net_mode 接口切换即可，SDK内部会重新启动信令连接

切换为广域网模式：

xs_iot_switch_net_mode(XS_IOT_NET_INTERNET, 0);

切换为局域网模式：

xs_iot_switch_net_mode(XS_IOT_NET_LAN, 0)

工作原理​

局域网AP模式工作原理：

  1. IoT 信令服务器启动 设备 SDK 内部会启动一个 IoT Server 信令服务器，并监听特定的信令服务端口。此服务器实现了与云端信令服务器相同的通信协议，从而支持设备端和手机端之间的信令交互。
  2. UDP 广播监听与响应 设备 SDK 同时会在指定的 UDP 广播端口上进行监听，等待手机客户端发送的广播包以搜索局域网内的设备（该功能由 APP SDK 实现）。当设备 SDK 收到广播请求后，它将返回设备的基本信息以及正在监听的信令服务器端口，以便手机客户端能够连接到相应的信令服务器。

注意事项：

  1. 设备仅支持单一模式运行 设备在任意时刻只能工作在一种模式下。一旦启用了局域网 AP 模式，设备将不再连接外网服务器，所有通信将仅限于本地网络。
  2. 局域网模式下的 SDK 使用方式与广域网一致 在局域网模式下，接入者调用 SDK 接口的方式与广域网模式完全相同，由于设备连接的是本地信令服务器，因此仍能接收到设备在线/离线状态变化、物模型更新等相关功能的回调消息。
  3. 切换模式需确保 AP 热点启动成功 若设备采用 AP 热点方式提供局域网接入能力，应在设备成功启动 AP 热点之后，再调用相关接口切换至局域网工作模式。否则，可能导致本地监听端口初始化失败，影响功能正常使用。