# zaiohController_openharmony_sdk

**Repository Path**: zaihong/zaiohController_openharmony_sdk

## Basic Information

- **Project Name**: zaiohController_openharmony_sdk
- **Description**: 在鸿控制器CT1x系列OpenHarmony移动端开发sdk
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-02
- **Last Updated**: 2026-06-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 在鸿控制器 OpenHarmony SDK

![Version](https://img.shields.io/badge/version-V2.0.0-blue)
![Platform](https://img.shields.io/badge/platform-OpenHarmony%20%7C%20HarmonyOS-green)
![API](https://img.shields.io/badge/API-15+-orange)
![License](https://img.shields.io/badge/license-Proprietary-lightgrey)

## 1. 简介

**在鸿控制器 OpenHarmony SDK** 是由湖南开鸿智谷数字产业发展有限公司提供的一站式物联网开发工具包。本 SDK 旨在帮助开发者快速构建基于 OpenHarmony/HarmonyOS 平台的智能控制应用，实现与在鸿控制器的高效通信与管理。

通过集成此 SDK，开发者可轻松实现以下核心能力：
- ☁️ **云端交互**：HTTP/HTTPS 通信，完成认证鉴权与配置获取。
- 📶 **蓝牙通信**：BLE 设备扫描、连接、鉴权及数据收发。
- 📱 **近场通信**：支持 NFC 碰一碰快速连接设备。
- ⚙️ **设备管理**：机电设备配置、场景联动、状态监控及远程控制。

## 2. 环境要求

在开始开发前，请确保你的开发环境满足以下最低要求：

| 组件 | 要求版本 | 说明 |
| :--- | :--- | :--- |
| **操作系统** | Windows 10/11 (64 位) 或 macOS 13+ | 建议专业版 |
| **开发工具** | DevEco Studio | 建议 Release 版 |
| **SDK API** | OpenHarmony API 15+ / HarmonyOS 5.0.3(15)+ | 必须匹配 |
| **Node.js** | v18.20.1 | 构建环境依赖 |
| **ohpm** | 5.0+ | 包管理工具 |

## 3. 快速开始

### 3.1 获取 SDK
从仓库获取以下核心文件：
- `ZaiOHOSControllerSDK_vx.x.x_release.har`([sdk目录下](./sdk)) (核心库)
- `openvalley-zaiohos-controller-example` (示例工程)
- 相关开发指南文档

### 3.2 集成 SDK
1. 将 `.har` 文件复制到主项目的 `libs` 目录下（若无则创建）。
2. 在主工程 `oh-package.json5` 的 `dependencies` 中添加依赖：
   ```json5
   "dependencies": {
     "@openvalley/communication": "file:./libs/ZaiOHOSControllerSDK_vx.x.x_release_xxxxxxxxxx.har"
   }
   ```
3. 点击 IDE 右上角 **Sync Now** 同步依赖。

### 3.3 权限配置
在 `module.json5` 中声明以下权限（部分需运行时申请）：
```json5
"requestPermissions": [
  { "name": "ohos.permission.INTERNET" },
  { "name": "ohos.permission.GET_NETWORK_INFO" },
  { "name": "ohos.permission.ACCESS_BLUETOOTH" },
  { "name": "ohos.permission.USE_BLUETOOTH" },
  { "name": "ohos.permission.DISCOVER_BLUETOOTH" },
  { "name": "ohos.permission.NFC_TAG" }
]
```
*注意：NFC 功能还需在 Ability 的 `skills` 中配置 `ohos.nfc.tag.action.TAG_FOUND` action。*

### 3.4 初始化与释放
在 `EntryAbility.ts` 中管理 SDK 生命周期：
```typescript
export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // 初始化 SDK
    ControllerSdk.getInstance().init(this.context);
  }
  onDestroy(): void {
    // 释放 SDK 资源
    ControllerSdk.getInstance().release();
  }
}
```

## 4. 核心功能流程

### 4.1 云端认证 (HTTP)
1. **登录**：使用租户 ID、用户名、密码登录获取 Token。
2. **获取产品列表**：选择目标产品。
3. **获取配置证明 (Sign)**：用于后续蓝牙鉴权。
   > 提示：SDK 支持 `loginAndGetSign` 一步完成登录与配置获取。

### 4.2 蓝牙连接 (BLE)
1. **扫描**：调用 `startScan` 发现附近控制器。
2. **连接**：调用 `connectBle(address)` 建立连接。
3. **鉴权**：连接成功后立即调用 `authentication`。
4. **通信**：鉴权通过后，使用 `write` 发送物模型请求。
   > 注意：通信前需确保已查询本机 ID (`localId`) 且协议版本匹配。

### 4.3 NFC 碰一碰
1. 注册 `NfcListener`。
2. 监听 `TAG_FOUND` 动作，解析 NFC 信息获取蓝牙 MAC 地址。
3. 实现BLE 连接流程。

## 5. 文档索引

| 文档名称 | 版本 | 描述 |
| :--- | :--- | :--- |
| [快速开发指南](./docs/在鸿控制器OpenHarmony%20SDK快速开发指南.md) | V2.0.0 | 集成、初始化、API 调用示例 |
| [环境搭建指南](./docs/在鸿控制器OpenHarmony%20SDK环境搭建指南.md) | V2.0.0 | 开发环境配置、验证、Q&A |
| [协议通讯接口及物模型文档](./docs/在鸿控制器OpenHarmony%20SDK协议通讯接口及物模型文档.md) | V1.4.13 | 详细接口定义、物模型结构、错误码 |

## 6. 技术支持

如遇文档未覆盖的问题，请提供以下信息联系技术支持：
- 系统环境 (OS, DevEco 版本，API 版本)
- 复现步骤与错误日志
- 影响范围

> **版权所有** ©湖南开鸿智谷数字产业发展有限公司 2025-2026，保留一切权利。
>
> 非经本公司书面许可，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传播。
>
> **注意**：
> 您购买的产品、服务或特性等应受本公司商业合同和条款的约束，本文档中描述的全部或部分产品、服务或特性可能不在您的购买或使用范围之内。除非合同另有约定，本公司对本文档内容不做任何明示或默示的声明或保证。由于产品版本升级或其他原因，本文档内容会不定期进行更新。除非另有约定，本文档仅作为使用指导，本文档中的所有陈述、信息和建议不构成任何明示或暗示的担保。