iot_management

简介

iot_management 是面向 OpenHarmony Small/Mini 系统的统一设备连接管理组件。组件向应用提供统一的 C++ 接口，用于发现设备、建立连接、订阅设备事件、发送控制命令和配置网络，并在内部按扫描结果选择 BLE、Wi-Fi 或 CoAP 链路。

本文面向调用 iot_management C++ 接口的应用开发者，介绍最常用的接入和调用方式。完整接口定义、数据结构和错误处理说明请参见 iot_management API 参考。

当前接口是 OpenHarmony 源码树中的 Inner API，使用时应以本仓库公开头文件及目标产品的实际特性配置为准。

能力概览

能力	主要接口	结果返回方式	构建条件
设备扫描	DeviceManager::StartScanDevice()	DeviceScanCallback 异步回调	对应协议特性已启用
停止扫描	DeviceManager::StopScanDevice()	无公开返回值	同上
设备连接	DeviceManager::ConnectDevice()	DeviceConnectCallback 异步回调	对应协议特性已启用
连接状态订阅	ConnectSession::SubscribeConnectState()	ConnectStateObserver 异步通知	已建立 Session
设备事件订阅	ConnectSession::SubscribeEvent()	EventObserver 异步通知	已建立 Session
命令发送	ConnectSession::SendCommand()	同步返回提交结果，最终响应通过事件订阅上报	已建立 Session
Wi-Fi 配网	DeviceManager::ConfigureNetwork()	BaseCallback 异步回调	iot_management_wifi_support=true 或 iot_management_eth_support=true
会话释放	ConnectSession::Release()	同步返回提交结果	已建立 Session

支持的发现和连接协议由产品构建特性决定：

协议	ScanProtocol	特性开关	说明
Wi-Fi	ScanProtocol::WIFI	iot_management_wifi_support	启用后同时开启 CoAP 相关实现
BLE	ScanProtocol::BLE	iot_management_ble_support	默认启用
CoAP	ScanProtocol::COAP	由 Wi-Fi 或 Ethernet 间接启用	iot_management_coap_support 不是产品直接配置项
全部已启用协议	ScanProtocol::ALL	—	适合扫描；连接时应使用设备扫描结果中的协议

运行架构

应用
 ├─ DeviceManager
 │   ├─ 初始化 / 释放
 │   ├─ 扫描设备
 │   ├─ 连接设备
 │   └─ Wi-Fi 配网（按特性编译）
 │
 └─ ConnectSession
     ├─ 订阅设备数据事件
     ├─ 订阅连接状态
     ├─ 发送设备命令
     └─ 断开并释放会话
              │
              ▼
      iot_management 客户端 / 服务
              │
              ▼
        BLE、Wi-Fi、CoAP 适配层

DeviceManager 管理组件级生命周期；连接成功后，DeviceConnectCallback 返回与目标设备关联的 ConnectSession。应用必须保存 Session、Callback 和 Observer 的 shared_ptr，直到对应异步流程结束或主动取消订阅。

目录结构

iot_management/
├── common/                         # 公共常量、日志和工具
├── core/                           # 设备管理、协议和适配实现
├── interfaces/
│   ├── inner_api/                  # 公共数据类型与 Callback 定义
│   └── inner_kits/native_cpp/      # C++ DeviceManager / ConnectSession 接口
├── services/                       # 客户端、服务端和 IPC 实现
├── test/iot_management_demo/       # 命令行示例
├── docs/                           # API 与产品集成文档
├── BUILD.gn
├── bundle.json
└── iot_management.gni

依赖的 OH 标准接口

iot_management 在 core/adapter/ble 和 core/adapter/wifi 中分别封装了 OpenHarmony 的 BLE 与 Wi-Fi 协议标准接口。

BLE 适配

底层 C 接口全部以 extern "C" 弱符号方式引入，缺失时上层调用会返回 COMMON_FAILED 并记录日志。

头文件	接口	说明
ohos_bt_gatt.h	bool IsBleEnabled(void)	检测 BLE 是否可用
ohos_bt_gatt.h	int BleSetScanParameters(int clientId, BleScanParams *param)	设置扫描参数
ohos_bt_gatt.h	int BleStartScanEx(int32_t scannerId, const BleScanConfigs *configs, const BleScanNativeFilter *filter, uint32_t filterSize)	按自定义配置启动扫描
ohos_bt_gatt.h	int BleStopScan(int32_t scannerId)	停止扫描
ohos_bt_gatt.h	int BleRegisterScanCallbacks(BleScanCallbacks *func, int32_t *scannerId)	注册扫描回调并分配 scannerId
ohos_bt_gatt.h	int BleDeregisterScanCallbacks(int32_t scannerId)	反注册扫描回调
ohos_bt_gatt_client.h	int BleGattcRegister(BtUuid appUuid)	注册 GATT Client
ohos_bt_gatt_client.h	int BleGattcUnRegister(int clientId)	注销 GATT Client
ohos_bt_gatt_client.h	int BleGattcConnect(int clientId, BtGattClientCallbacks *func, const BdAddr *bdAddr, bool isAutoConnect, BtTransportType transport)	与对端建立 GATT 连接
ohos_bt_gatt_client.h	int BleGattcDisconnect(int clientId)	断开 GATT 连接
ohos_bt_gatt_client.h	int BleGattcSearchServices(int clientId)	搜索对端 GATT 服务
ohos_bt_gatt_client.h	int BleGattcWriteCharacteristic(int clientId, BtGattCharacteristic characteristic, BtGattWriteType writeType, int len, const char *value)	写特征值
ohos_bt_gatt_client.h	int BleGattcConfigureMtuSize(int clientId, int mtuSize)	配置 MTU 大小
ohos_bt_gatt_client.h	int BleGattcRegisterNotification(int clientId, BtGattCharacteristic characteristic, bool enable)	注册 / 注销特征 Notify 订阅

类型与常量：

头文件	类型 / 常量	说明
ohos_bt_gatt.h	BleScanParams / BleScanConfigs / BleScanCallbacks / OHOS_BLE_SCAN_TYPE_ACTIVE / OHOS_BLE_SCAN_MODE_LOW_LATENCY / OHOS_BLE_SCAN_FILTER_POLICY_ACCEPT_ALL / OHOS_BLE_EVT_LEGACY_SCAN_RSP_TO_ADV_SCAN / OHOS_BLE_EVT_LEGACY_SCAN_RSP_TO_ADV	扫描参数与配置结构、回调结构体、扫描类型 / 模式 / 过滤策略枚举
ohos_bt_gatt_client.h	BtUuid / BdAddr / BtGattCharacteristic / BtGattClientCallbacks / BtGattReadData / BtScanResultData / OHOS_GATT_WRITE_DEFAULT / OHOS_BT_TRANSPORT_TYPE_LE / OHOS_BD_ADDR_LEN	UUID / 地址 / 特征 / 回调 / 读数据 / 扫描结果结构、写入类型枚举、传输类型枚举、地址长度

返回值约定：OHOS_BT_STATUS_SUCCESS 表示成功，OHOS_BT_STATUS_NOT_READY 等错误码会在适配层映射为连接失败或扫描失败。

头文件来源：

• foundation/communication/bluetooth/interfaces/inner_api/include/c_header/ohos_bt_gatt.h
• foundation/communication/bluetooth/interfaces/inner_api/include/c_header/ohos_bt_gatt_client.h

集成要求：产品需使能 Bluetooth 子系统并保证上述符号在进程内可解析。

Wi-Fi 适配

头文件	接口	说明
wifi_device.h	WifiErrorCode Scan(void)	启动一次 Wi-Fi 扫描
wifi_device.h	WifiErrorCode GetScanInfoList(WifiScanInfo *result, unsigned int *size)	获取扫描结果，先传 nullptr 取 AP 总数再取结果数组
wifi_device.h	WifiErrorCode GetLinkedInfo(WifiLinkedInfo *info)	获取当前链接信息
wifi_device.h	WifiErrorCode Disconnect(void)	断开当前链接
wifi_device.h	WifiErrorCode AddDeviceConfig(WifiDeviceConfig *config, int *result)	新增网络配置并返回 networkId
wifi_device.h	WifiErrorCode GetDeviceConfigs(WifiDeviceConfig *result, unsigned int *size)	获取已保存的网络配置
wifi_device.h	WifiErrorCode RemoveDevice(int networkId)	移除指定网络配置
wifi_device.h	WifiErrorCode ConnectTo(int networkId)	连接指定 networkId
wifi_device.h	WifiErrorCode GetIpInfo(IpInfo *info)	获取本地 IP / 子网掩码 / 网关
wifi_event.h	WifiErrorCode RegisterWifiEvent(WifiEvent *event)	注册 Wi-Fi 事件回调
wifi_event.h	WifiErrorCode UnRegisterWifiEvent(WifiEvent *event)	反注册 Wi-Fi 事件回调

类型与常量：

头文件	类型 / 常量	说明
wifi_event.h	WifiEvent{ OnWifiScanStateChanged, OnWifiConnectionChanged, OnDeviceConfigChange }	事件回调结构体，三个回调字段
wifi_error_code.h	WifiErrorCode / WIFI_SUCCESS / ERROR_WIFI_BUSY / ERROR_WIFI_INVALID_ARGS	错误码枚举与典型常量
wifi_scan_info.h	WifiScanInfo	单个 AP 的扫描结果
wifi_linked_info.h	WifiLinkedInfo	当前链接信息结构
wifi_device_config.h	WifiDeviceConfig / IpInfo / ConfigChange / WifiConnState / WifiSecurityType / WIFI_MAX_CONFIG_SIZE / WIFI_CONFIG_INVALID	网络配置、IP 配置、配置变更事件枚举、链接状态枚举、安全类型枚举与边界常量

头文件来源：

• foundation/communication/wifi_lite/interfaces/wifiservice/wifi_device.h
• foundation/communication/wifi_lite/interfaces/wifiservice/wifi_event.h
• foundation/communication/wifi_lite/interfaces/wifiservice/wifi_error_code.h
• foundation/communication/wifi_lite/interfaces/wifiservice/wifi_scan_info.h
• foundation/communication/wifi_lite/interfaces/wifiservice/wifi_linked_info.h
• foundation/communication/wifi_lite/interfaces/wifiservice/wifi_device_config.h

集成要求：产品需使能 Wi-Fi 协议服务并保证上述符号在进程内可解析。

使用前提

1. 产品已集成 iot_management 组件和常驻服务。
2. 产品已启用业务所需的 BLE、Wi-Fi 或 Ethernet 特性。
3. 对应驱动、协议服务和板级适配已正常启动。
4. 调用进程具备访问 iotc_management 服务的 IPC 权限。

应用侧至少包含：

#include "iotc_device_manager.h"

GN 目标依赖：

deps = [
  "//foundation/communication/iot_management/interfaces/inner_kits/native_cpp:iotc_management_api",
]

接口位于命名空间：

OHOS::IotcManagement

快速开始

1. 实现回调和 Observer

#include "iotc_device_manager.h"

#include <memory>
#include <string>
#include <utility>
#include <vector>

using namespace OHOS::IotcManagement;

class ScanCallback final : public DeviceScanCallback {
public:
    void OnDeviceDiscovered(const std::vector<DeviceInfo>& devices) override
    {
        // 保存需要连接的 DeviceInfo；连接时使用其 udid 和 scannedProtocol。
    }

    void OnDeviceDiscoveryFinished() override
    {
        // 本轮扫描结束。
    }

    void OnFailure(int32_t errorCode, const std::string& msg) override
    {
        // 处理扫描失败。
    }
};

class EventCallback final : public EventObserver {
public:
    void OnEvent(const std::string& eventName, const std::string& data) override
    {
        // 处理设备数据、命令最终响应和协议事件。
    }
};

class StateCallback final : public ConnectStateObserver {
public:
    void OnConnectStateChanged(ConnectState state) override
    {
        // 处理 CONNECTED / DISCONNECTED。
    }
};

连接回调需要保存 Session。下面仅展示对象关系，实际项目应使用与自身线程模型匹配的同步方式保护共享状态。

std::shared_ptr<ConnectSession> g_session;
std::shared_ptr<EventCallback> g_eventObserver;
std::shared_ptr<StateCallback> g_stateObserver;

class ConnectCallback final : public DeviceConnectCallback {
public:
    void OnDeviceConnect(std::shared_ptr<ConnectSession> session) override
    {
        g_session = std::move(session);

        g_eventObserver = std::make_shared<EventCallback>();
        g_stateObserver = std::make_shared<StateCallback>();
        g_session->SubscribeEvent(g_eventObserver);
        g_session->SubscribeConnectState(g_stateObserver);
    }

    void OnFailure(int32_t errorCode, const std::string& msg) override
    {
        // 处理连接失败。
    }
};

2. 初始化并扫描

DeviceManager manager;
manager.InitDevice();

auto scanCallback = std::make_shared<ScanCallback>();
ScanRequest scanRequest;
scanRequest.duration = 8000;
scanRequest.scanType = ScanProtocol::ALL;
manager.StartScanDevice(scanRequest, scanCallback);

扫描结果通过 OnDeviceDiscovered() 异步返回。扫描结束后不再需要扫描时，可调用：

manager.StopScanDevice();

3. 连接扫描到的设备

DeviceInfo selectedDevice = /* 从扫描结果中选择 */;

ConnectRequest connectRequest;
connectRequest.udid = selectedDevice.udid;
connectRequest.connectType = selectedDevice.scannedProtocol;
connectRequest.pinCode = "01234567"; // 按目标设备实际鉴权信息填写

auto connectCallback = std::make_shared<ConnectCallback>();
manager.ConnectDevice(connectRequest, connectCallback);

连接是异步操作。只有 DeviceConnectCallback::OnDeviceConnect() 被调用后，应用才获得可用的 ConnectSession。

4. 发送命令并接收最终结果

应先通过 SubscribeEvent() 注册事件订阅，再发送命令：

const std::string body =
    R"([{"sid":"switch","data":{"on":1}}])";

int32_t ret = g_session->SendCommand("customSecData", body);
if (ret != 0) {
    // 命令未成功提交，不应等待设备响应。
}

SendCommand() 返回的 int32_t 只表示命令是否成功提交到管理服务，不表示目标设备已经执行成功。设备的最终响应由 EventObserver::OnEvent() 异步上报，应用应根据 eventName 和业务协议解析 data。

5. 取消订阅并释放

if (g_session != nullptr) {
    g_session->UnsubscribeEvent(g_eventObserver);
    g_session->UnsubscribeConnectState(g_stateObserver);
    (void)g_session->Release();
}

g_eventObserver.reset();
g_stateObserver.reset();
g_session.reset();

manager.ReleaseDevice();

推荐生命周期：

InitDevice
    ↓
StartScanDevice
    ↓
ConnectDevice
    ↓
SubscribeEvent / SubscribeConnectState
    ↓
SendCommand
    ↓
UnsubscribeEvent / UnsubscribeConnectState
    ↓
ConnectSession::Release
    ↓
DeviceManager::ReleaseDevice

不传 Observer 调用 UnsubscribeEvent() 或 UnsubscribeConnectState() 时，会取消该 Session 对应类型的全部本地订阅。

GN 特性配置

组件特性定义在 iot_management.gni：

配置项	默认值	作用
iot_management_ble_support	true	编译 BLE 扫描、连接和控制能力
iot_management_wifi_support	false	编译 Wi-Fi 及相关配网能力
iot_management_eth_support	false	编译 Ethernet 相关能力
iot_management_kv_support	true	启用真实 KV Backend；关闭时使用 stub
iot_management_kv_backend	按内核选择	posix 或 utils_file
iot_management_kv_root_dir	/storage/data/iot_management	POSIX Backend 的数据根目录

CoAP 支持由下式决定：

iot_management_coap_support =
    iot_management_wifi_support || iot_management_eth_support

产品 config.json 示例：

{
  "component": "iot_management",
  "features": [
    "iot_management_ble_support = true",
    "iot_management_wifi_support = true",
    "iot_management_eth_support = false",
    "iot_management_kv_support = true",
    "iot_management_kv_backend = \"posix\"",
    "iot_management_kv_root_dir = \"/storage/data/iot_management\""
  ]
}

KV Backend

• posix：直接使用 POSIX 文件系统，默认用于 Linux 和 LiteOS-A。
• utils_file：使用系统 UtilsFile* / file HAL，默认用于 LiteOS-M。
• iot_management_kv_support=false：仅编译 KV stub，持久化接口返回“不支持”。

产品显式配置优先于内核默认值。两种真实 Backend 的物理存储格式不同，量产后切换前应制定数据迁移或清理方案。

服务、Demo 与产品集成

组件构建目标：

//foundation/communication/iot_management:iotc_management_lite

应用接口目标：

//foundation/communication/iot_management/interfaces/inner_kits/native_cpp:iotc_management_api

命令行 Demo：

//foundation/communication/iot_management/test/iot_management_demo:iot_management_demo

Demo 的集成和运行方式参见 iot_management Demo。服务权限、开机启动和产品配置请按对应产品集成指南处理，不应只复制本文片段。

使用注意事项

• InitDevice() 和 ReleaseDevice() 的返回类型为 void；初始化失败由组件日志体现。
• StartScanDevice()、ConnectDevice() 和 ConfigureNetwork() 要求传入非空 Callback。
• 扫描、连接、配网和事件通知均包含异步过程；Callback 或 Observer 中不要执行长时间阻塞操作。
• 当前接口未承诺 Callback 的固定执行线程。访问跨线程共享数据时，应用应自行同步。
• Session 与目标设备及连接协议绑定，不要用一个 Session 操作其他设备。
• 连接时优先使用扫描结果中的 DeviceInfo::scannedProtocol，不要无条件使用 ScanProtocol::ALL。
• Release() 成功后 Session 的 UDID 会被清空，不应继续发送命令。
• 不要把 SendCommand() 的返回值当作设备业务执行结果。

相关文档

• iot_management API 参考
• iot_management Demo