1. 概述

本文档记录 IOT Connect 组件 BLE Only 场景适配沁恒 CH585 芯片的完整过程，涵盖组件架构、BLE 南向接口分析、编译构建配置及开发示例。

CH585 基于青稞 RISC-V3C 内核，内置 BLE 5.4 射频，天然适配 IOTC BLE Only 场景，适用于专业照明、可穿戴设备等低功耗物联网应用。

2. IOTC 组件架构

IoT Connect 组件是专为 OpenHarmony 资源受限 mini 级设备构建的极简、高性能连接控制核心组件。通过抽象底层复杂的网络差异，极大地简化了物联网设备的开发流程，为构建轻量级智能硬件与实现万物互联的广泛接入提供了关键的技术基础支撑。

2.1 组件架构分层

IoT Connect 组件采用分层架构设计，从上到下分为三层：

┌─────────────────────────────────────────────────────────────┐
│                      厂商应用层 (Vendor App)                  │
│  设备信息配置  |  物模型服务  |  控制回调  |  事件监听           │
├─────────────────────────────────────────────────────────────┤
│                      IOTC 组件层 (IoT Connect)                │
│  接口层：部件运行 | BLE Connect | WiFi Connect | 设备管理      │
│  核心功能：部件运行管理 | 配置管理 | 物模型管理 | 设备控制       │
│          消息上报 | 设备发现连接 | 设备配网 | 事件管理          │
├─────────────────────────────────────────────────────────────┤
│                      硬件适配层 (HAL)                         │
│  Bluetooth Lite API  |  WiFi Lite API  |  芯片厂商适配层       │
├─────────────────────────────────────────────────────────────┤
│                      内核层 (LiteOS-M)                        │
│  任务调度  |  内存管理  |  IPC  |  中断管理  |  定时器          │
└─────────────────────────────────────────────────────────────┘
  • 厂商应用层：通过 IOTC 标准化接口（IotcOh* 系列）访问组件服务。
  • IOTC 组件层：封装 BLE 发现、配网、控制等核心业务逻辑。
  • 硬件适配层：通过 OpenHarmony 轻量标准化 API（Bluetooth Lite / WiFi Lite）实现芯片无关移植。
  • 内核层：基于 LiteOS-M 提供系统调度运行底座。

2.2 BLE Only 场景架构

CH585 仅支持 BLE 5.4，无 WiFi 能力，适配 IOTC BLE Only 场景。该场景下组件架构简化为：

┌─────────────────────────────────────────────────────────────┐
│                      厂商应用层                              │
│  设备信息  |  物模型  |  控制回调  |  PIN码认证  |  事件监听     │
├─────────────────────────────────────────────────────────────┤
│                      IOTC 组件层                             │
│  接口层：IotcOhBleEnable | IotcOhBleStartAdv | IotcOhDevInit │
│  核心功能：BLE发现连接 | 设备控制 | 消息上报 | 事件管理         │
├─────────────────────────────────────────────────────────────┤
│                      硬件适配层                              │
│  Bluetooth Lite API → CH585 BLE 驱动适配                     │
├─────────────────────────────────────────────────────────────┤
│                      LiteOS-M 内核                           │
└─────────────────────────────────────────────────────────────┘

2.3 核心功能模块

IOTC 组件核心功能分为 9 个模块，BLE Only 场景下仅启用 BLE 相关模块：

模块功能说明BLE Only 是否启用
部件运行管理组件线程启动/退出控制、运行参数设置、恢复出厂是
配置管理管理设备信息、WiFi 配置参数是（仅设备信息）
物模型管理维护物模型服务、控制指令合法性检查、透传执行信息是
设备发现连接BLE 广播发现、PIN 码认证、SPEKE 密钥协商是
设备配网BLE 辅助 WiFi 配网否（无 WiFi）
设备注册WiFi 连接后通过 CoAP 与云端注册登录否（无 WiFi）
设备控制BLE 直连控制、云端远程控制是（仅 BLE 直连）
消息上报向云端/控制设备上报状态和事件是（仅 BLE 通道）
事件管理模块间解耦通信、定时任务、心跳保活、超时重传是

3. IOTC 组件目录结构

IOTC 组件源码位于 foundation/communication/iot_connect 目录，各模块分目录管理：

foundation/communication/iot_connect/
├── adapter/                   # 适配层代码（OS/BLE/WiFi）
│   └── ble/                   # BLE 适配层（CH585 适配入口）
├── core/                      # 核心代码
│   ├── ble/                   # BLE 发现配网代码
│   ├── wifi/                  # WiFi 发现配网及端云连接代码
│   ├── device/                # 设备控制及注册信息管理代码
│   └── infrastructure/        # 核心基础设施代码（安全/日志/事件等）
├── interfaces/                # 对外接口代码
│   └ kits/common/            # 通用接口定义（错误码/事件/配置等）
│   └ kits/oh_connect/        # OpenHarmony 对接接口
├── sdk/                       # 解决方案业务入口代码
├── test/                      # 测试代码
├── tools/                     # 工具代码
└── docs/                      # 文档目录

4. BLE 南向接口

IOTC 组件通过 OpenHarmony 轻量级 Bluetooth 子系统标准接口（Bluetooth Lite API）访问底层 BLE 硬件。芯片厂商需在适配层实现这些接口，对接芯片 BLE 驱动。

CH585 BLE Only 场景需适配以下 17 个 BLE 接口：

4.1 协议栈管理

函数原型核心功能说明
int InitBtStack(void)初始化蓝牙协议栈
int EnableBtStack(void)使能蓝牙协议栈
int DisableBtStack(void)去使能蓝牙协议栈
int SetDeviceName(const char *name, unsigned int len)设置蓝牙设备名称
int ReadBtMacAddr(unsigned char *mac, unsigned int len)读取蓝牙 MAC 地址

4.2 GATT 服务

函数原型核心功能说明
int BleGattsRegisterCallbacks(BtGattServerCallbacks *func)注册 GATT 服务器回调
int BleGattRegisterCallbacks(BtGattCallbacks *func)注册 GATT 客户端回调
int BleGattsStartServiceEx(int *srvcHandle, BleGattService *srvcInfo)启动 GATT 服务
int BleGattsDeleteService(int serverId, int srvcHandle)删除 GATT 服务
int BleGattsUnRegister(int serverId)注销 GATT 服务器
int BleGattsSendIndication(int serverId, GattsSendIndParam *param)发送 Indication 通知

4.3 广播与连接

函数原型核心功能说明
int BleStartAdvEx(int *advId, const StartAdvRawData rawData, BleAdvParams advParam)启动 BLE 广播
int BleStopAdv(int advId)停止 BLE 广播
int BleGattsDisconnect(int serverId, BdAddr bdAddr, int connId)断开 GATT 连接

4.4 安全认证

函数原型核心功能说明
int BleSetSecurityAuthReq(BleAuthReqMode mode)蓝牙安全认证设置
int BleGattSecurityRsp(BdAddr bdAddr, bool accept)安全响应

4.5 设备信息

函数原型核心功能说明
int BleGattsSetEncryption(BdAddr bdAddr, BleSecAct secAct)设置连接加密类型

轻量级 Bluetooth 系统接口详细使用说明参见：https://gitcode.com/ohos-oneconnect/communication_bluetooth

5. IOTC 对外接口

IOTC 组件向厂商应用暴露标准化接口，BLE Only 场景下主要使用以下接口：

5.1 部件运行

函数原型核心功能说明
int32_t IotcOhMain(void)部件业务入口，调用后拉起自身任务线程，大部分预配置类接口不再可用
int32_t IotcOhReset(void)部件复位，重置所有组件业务的运行状态，仅在部件运行时有效
int32_t IotcOhStop(void)停止部件的运行，仅在部件运行时有效
int32_t IotcOhRestore(void)通知所有业务恢复出厂，仅在部件运行时有效
int32_t IotcOhSetOption(int32_t option, ...)配置部件运行时的参数，option 为待配置的参数类型

5.2 BLE Connect

函数原型核心功能说明
int32_t IotcOhBleEnable(void)使能 BLE 发现、连接、控制的能力，应在 iot connect 运行前调用
int32_t IotcOhBleDisable(void)关闭 BLE 发现、连接、控制的能力，用于释放资源
int32_t IotcOhBleStartAdv(uint32_t ms)启动 BLE 广播发现，ms 为广播时长（单位 ms）
int32_t IotcOhBleStopAdv(void)停止 BLE 广播
int32_t IotcOhBleSendCustomSecData(const uint8_t *data, uint32_t len)通过 customSecData 服务通道发送数据
int32_t IotcOhBleSendIndicateData(const char *svcUuid, const char *charUuid, const uint8_t *value, uint32_t valueLen)发送 BLE Indicate 数据
int32_t IotcOhBleRelease(void)BLE 资源释放，在 iot connect 运行时调用

5.3 设备管理

函数原型核心功能说明
int32_t IotcOhDevInit(void)配置设备信息，注册设备服务/控制回调，应在 iot connect 运行前调用
int32_t IotcOhDevDeinit(void)释放调用 IotcOhDevInit 时申请的资源
int32_t IotcOhDevReportCharState(const IotcCharState state[], uint32_t num)上报设备的服务信息，应在服务信息变化时调用

6. 编译构建配置

6.1 IOTC 组件声明

在 build/lite/components/communication.json 中声明 iot_connect 组件：

{
    "component": "iot_connect",
    "description": "iot_connect component",
    "optional": "true",
    "dirs": [
        "foundation/communication/iot_connect"
    ],
    "targets": [
        "//foundation/communication/iot_connect:iotc_static"
    ],
    "adapted_kernel": [ "liteos_m" ],
    "deps": {
        "components": [ "hilog_lite" ],
        "third_party": [ "bounds_checking_function" ]
    }
}

6.2 厂商工具链

编译 liteos_m 轻量系统需要使用沁恒提供的编译工具链：

  1. 进入官网 https://mounriver.com/download%EF%BC%8C%E9%80%89%E6%8B%A9 "Linux" -> "工具链和调试器"，下载 MRS_Toolchain_Linux_X64_V240.tar.xz。
  2. 下载完成后解压到编译的 Linux 设备目录中，将 Toolchain/RISC-V Embedded GCC12 重命名为 WCH-RISCV-GCC12。
  3. 在配置 device/board/wch/ch585_r0/liteos_m/config.gni 文件时，需修改 board_toolchain_path = ""，将工具链路径配置到解压的目录中，例如：
board_toolchain_path = "/home/wch/OpenHarmony/Toolchain/WCH-RISCV-GCC12/bin"

6.3 获取小型系统底座

repo init -u git@gitcode.com:ohos-oneconnect/manifest.git -b OpenHarmony-5.1.0-Release -m nearlink.xml -g ohos:mini --no-repo-verify
repo sync -c
repo forall -c 'git lfs pull'
bash build/prebuilts_download.sh   # 如执行不成功，可加上 sudo 权限

6.4 预编译

首次编译 OpenHarmony 源码需要执行预编译命令下载预编译工具链：

bash build/prebuilts_download.sh

6.5 编译前步骤

# 1. 切换到 nearlink 目录，执行 copy.sh（使 nearlink 仓目录下的 openharmony 目录覆盖到代码根目录）
cd foundation/communication/nearlink/
bash copy.sh

# 2. 切回代码根目录
cd ../../../

# 3. 选择产品并编译（当前为共建模式，已调整 patch 方式为 copy 方式，无需 patch）
hb set .             # 选择 hi3863 产品，如 nearlink_dk3863e
hb build -f

6.6 iot_connect 组件编译集成

  1. 在 foundation/communication/ 下拉取 iot_connect 组件代码，并重命名为 iot_connect：
git clone https://gitcode.com/openharmony/communication_iot_connect.git
  1. 修改 foundation/communication/iot_connect/iotc.gni 中第 38 行。
  2. 修改 foundation/communication/iot_connect/adapter/adapter.gni 中原第 58 行与原 124 行。

6.7 修改 third_party

  1. 修改 third_party/mbedtls/mbedtls.gni，将 mbedtls_porting_path = 的内容设置为 ""。
  2. 修改 third_party/mbedtls/port/config/config_liteos_m.h，将 MBEDTLS_NO_DEFAULT_ENTROPY_SOURCES 这个宏打开。

6.8 替换设备仓

将 CH585 设备仓代码替换到 OH 6.1-Release 源码根目录中：

源目录目标目录
vendor/wchvendor 目录
Vendor/ohemuvendor 目录
device/board/wchdevice/board 目录
device/soc/wchdevice/soc 目录
device/qemu/device 目录

6.9 替换轻量级内核

将 kernel/liteos_m 的 liteos_m 文件夹替换为与沁恒适配的 liteos_m。

7. 开发示例

以下为 CH585 场景下 IOTC 组件的完整开发示例，实现一个 BLE 灯控设备。

7.1 设备信息配置

#include "iotc_oh_device.h"
#include "iotc_oh_ble.h"
#include "iotc_prof_def.h"

// 设备信息（需与云平台注册信息一致）
static const IotcDeviceInfo DEV_INFO = {
    .sn = "CH585001",
    .prodId = "00007",
    .subProdId = "",
    .model = "CH585_BLE",
    .devTypeId = "1007",
    .devTypeName = "CH585Light",
    .manuId = "104",
    .manuName = "WCH",
    .devName = "CH585Light",
    .fwv = "1.0.0",
    .hwv = "1.0.0",
    .swv = "1.0.0",
    .protType = IOTC_PROT_TYPE_BLE,   // BLE 单模
};

static const char *PIN_CODE = "01234567";

7.2 物模型服务与控制回调

// 定义开关服务
static const IotcServiceInfo SVC_INFO[] = {
    {"switch", "switch"},    // 开关服务
};

static bool g_switch = false;  // 灯状态

// 控制指令接收（APP 下发）
int32_t SwitchPutCharState(const IotcServiceInfo *svc,
                           const char *data, uint32_t len)
{
    cJSON *json = cJSON_Parse(data);
    if (json == NULL) { return -1; }
    cJSON *item = cJSON_GetObjectItem(json, "on");
    if (item == NULL || !cJSON_IsNumber(item)) {
        cJSON_Delete(json);
        return -1;
    }
    g_switch = (cJSON_GetNumberValue(item) == 1);
    IoTGpioSetOutputVal(LED_GPIO, g_switch ? 1 : 0);
    cJSON_Delete(json);
    return 0;
}

// 状态查询（APP 查询）
int32_t SwitchGetCharState(const IotcServiceInfo *svc,
                           char **data, uint32_t *len)
{
    cJSON *json = cJSON_CreateObject();
    cJSON_AddNumberToObject(json, "on", g_switch ? 1 : 0);
    *data = cJSON_PrintUnformatted(json);
    *len = strlen(*data);
    cJSON_Delete(json);
    return 0;
}

// 全量状态上报
int32_t ReportAll(void)
{
    char *jsonStr = NULL;
    uint32_t jsonLen = 0;
    SwitchGetCharState(&SVC_INFO[0], &jsonStr, &jsonLen);
    IotcCharState states[1] = {0};
    states[0].svcId = "switch";
    states[0].data = jsonStr;
    states[0].len = jsonLen;
    int32_t ret = IotcOhDevReportCharState(states, 1);
    cJSON_free(jsonStr);
    return ret;
}

7.3 认证回调

// PIN码获取（配网鉴权）
int32_t GetPincode(uint8_t *buf, uint32_t bufLen)
{
    if (buf == NULL || bufLen < IOTC_PINCODE_LEN) { return -1; }
    (void)memcpy_s(buf, bufLen, PIN_CODE, IOTC_PINCODE_LEN);
    return 0;
}

// 内存释放回调
void DataFree(void *ptr)
{
    if (ptr != NULL) { cJSON_free((char *)ptr); }
}

7.4 组件启动入口

int32_t IotcOhDemoEntry(void)
{
    int32_t ret;

    // 1. 初始化设备管理模块（必须首先调用）
    ret = IotcOhDevInit();
    if (ret != 0) { return ret; }

    // 2. 使能 BLE 模块
    ret = IotcOhBleEnable();
    if (ret != 0) { return ret; }

    // 3. 注册控制回调
    SET_OH_SDK_OPTION(ret, IOTC_OH_OPTION_DEVICE_PUT_CHAR_STATE_CALLBACK,
                       PutCharState);
    SET_OH_SDK_OPTION(ret, IOTC_OH_OPTION_DEVICE_GET_CHAR_STATE_CALLBACK,
                       GetCharState);
    SET_OH_SDK_OPTION(ret, IOTC_OH_OPTION_DEVICE_REPORT_ALL_CALLBACK,
                       ReportAll);
    SET_OH_SDK_OPTION(ret, IOTC_OH_OPTION_DEVICE_GET_PINCODE_CALLBACK,
                       GetPincode);
    SET_OH_SDK_OPTION(ret, IOTC_OH_OPTION_DEVICE_DATA_FREE_CALLBACK,
                       DataFree);

    // 4. 配置设备和服务信息
    SET_OH_SDK_OPTION(ret, IOTC_OH_OPTION_DEVICE_DEV_INFO, &DEV_INFO);
    SET_OH_SDK_OPTION(ret, IOTC_OH_OPTION_DEVICE_SVC_INFO, SVC_INFO, 1);

    // 5. 配置 BLE 广播参数
    SET_OH_SDK_OPTION(ret, IOTC_OH_OPTION_BLE_START_UP_ADV_TIMEOUT,
                       (1000 * 60 * 1000));

    // 6. 注册事件监听
    SET_OH_SDK_OPTION(ret, IOTC_OH_OPTION_SDK_CONFIG_PATH,
                       "/data/app/iotc");
    SET_OH_SDK_OPTION(ret, IOTC_OH_OPTION_SDK_REG_EVENT_LISTENER,
                       DemoEventListener);

    // 7. 启动组件
    ret = IotcOhMain();
    return ret;
}

7.5 事件监听处理

void DemoEventListener(int32_t event)
{
    switch (event) {
        case IOTC_CORE_COMM_EVENT_MAIN_INITIALIZED:
            // 组件初始化完成，开始业务
            break;
        case IOTC_CORE_BLE_EVENT_GATT_DISCONNECT:
            // 连接断开，重启广播等待重连
            IotcOhBleStartAdv(0);
            break;
        default:
            break;
    }
}

8. 总结

本文档从组件架构、BLE 南向接口、编译构建配置到开发示例，完整梳理了 IOT Connect 组件 BLE Only 场景适配沁恒 CH585 芯片的全过程。

核心要点：

  • 架构分层清晰：厂商应用层 → IOTC 组件层 → 硬件适配层 → LiteOS-M 内核，通过 Bluetooth Lite API 实现芯片无关移植。
  • BLE Only 裁剪：9 个核心模块中，设备配网、设备注册因无 WiFi 能力而禁用，其余走 BLE 直连通道。
  • 17 个南向接口：芯片厂商需在适配层实现协议栈管理、GATT 服务、广播连接、安全认证、设备信息五类接口。
  • 开发范式统一：通过 IotcOhDevInit → IotcOhBleEnable → SET_OH_SDK_OPTION（注册回调）→ IotcOhMain 的标准流程完成组件集成。
Logo
欢迎加入Laval社区

社区规范：仅讨论OpenHarmony相关问题。

更多推荐

一次地图文字颜色异常排查：RGB565 和 ARGB8888 不能混为一谈

在适配轻量地图渲染时，我遇到过一类很有迷惑性的现象：路名文字有时接近黑色，有时偏红，重新进入页面后颜色还可能变化。第一反应通常是字体绘制或屏幕像素格式有问题，但沿渲染链继续检查后，真正的异常出现在更早的颜色数据边界。 这次排查最重要的收获，是要把“缓冲区像素格式”和“画笔颜色格式”分开理解。 两种格式描述的不是同一件事 RGB565 描述的是像素缓冲区布局。一个像素占 16 位，红色 5 位、绿色

avatar Laval社区

给轻量地图组件补充异步任务投递：从网络回调安全返回地图线程

在完善轻量地图组件的异步网络能力时，我遇到的核心问题并不是“怎样发出一个异步请求”，而是请求完成以后，怎样安全地把结果交还给地图引擎。 网络回调可能运行在协议栈线程，地图状态却通常要求在固定任务线程中串行修改。如果直接从网络线程进入地图引擎，短期内可能看不出问题，但在并发请求、页面退出或重复回调时，很容易出现数据竞争和生命周期错误。 地图线程在框架中的作用 轻量地图内部会同时维护视图状态、瓦片缓存

avatar Laval社区

给 OpenHarmony 轻量地图组件补充离线能力：一次公共接口演进实践

在参与 OpenHarmony 轻量地图组件共建时，我尝试为地图模块补充离线资源管理能力。最初看起来，这项工作只是增加查询、下载、暂停和删除接口，但真正开始梳理后，我发现难点并不在函数数量，而在于如何让新能力自然地进入原有框架，同时不破坏已有实现。 这次修改让我对轻量地图组件的分层、代理线程和公共接口兼容有了更具体的认识。 从现有调用链开始轻量地图组件并不是应用直接调用某个地图 SDK，而是通过一

avatar Laval社区