# zaiohController_android_sdk

**Repository Path**: zaihong/zaiohController_android_sdk

## Basic Information

- **Project Name**: zaiohController_android_sdk
- **Description**: 在鸿控制器CT1x系列Android移动端开发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-04-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 在鸿控制器 Android SDK

![version](https://img.shields.io/badge/version-V1.4.13-blue)
![platform](https://img.shields.io/badge/platform-Android-green)
![API](https://img.shields.io/badge/API-26+-orange)
![license](https://img.shields.io/badge/license-Proprietary-lightgrey)

## 1. 简介

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

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

此外也可参考我们自研的在鸿控制器APP，同样是基于该SDK开发，可参考[在鸿控制器APP使用文档](./app/在鸿控制器APP使用文档.md)

## 2. 环境要求

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

| 组件 | 要求版本 | 说明 |
| --- | --- | --- |
| 操作系统 | Windows 10/11 (64 位) 或 macOS 13+ | 建议专业版 |
| 开发工具 | Android Studio | 建议最新稳定版 |
| JDK | OpenJDK 17.0.10 | Android Studio 默认集成 |
| Android SDK | API 级别 ≥ 26 (Android 8.0+) | 必须匹配 |
| Gradle | 8.0+ | Android Studio 默认集成 |

## 3. 快速开始

### 3.1 获取 SDK

从仓库获取以下核心文件：
- `ZaiOHOSControllerSDK_Vx.x.x_release_xxxxxxxxxx.aar` (核心库)
- `bcprov-jdk15to18-173.jar` (加密依赖)
- `openvalley-zaiohos-controller-example` (示例工程)
- 相关开发指南文档

### 3.2 集成 SDK

1. 将 `.aar` 和 `.jar` 文件复制到主项目的 `libs` 目录下（若无则创建）。
2. 在主工程 `build.gradle` 的 `dependencies` 中添加依赖：

```groovy
dependencies {
    implementation fileTree(includes: ['*.aar', '*.jar'], dir: 'libs')
}
```

3. 点击 IDE 右上角 **Sync Now** 同步依赖。

### 3.3 权限配置

在 `AndroidManifest.xml` 中声明以下权限（部分需运行时申请）：

```xml
<!-- 网络权限 -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- 蓝牙权限 (Android 12+ 需额外申请运行时权限) -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

<!-- NFC 权限 -->
<uses-permission android:name="android.permission.NFC" />
<uses-feature android:name="android.hardware.nfc" android:required="true" />
```

> **注意**：Android 12 及以上版本需要在代码中动态申请蓝牙相关运行时权限。NFC 功能还需在 Activity 的 `intent-filter` 中配置相关 action。

### 3.4 初始化与释放

在 `Application` 类中管理 SDK 生命周期：

```java
public class App extends Application {
    @Override 
    public void onCreate() { 
        super.onCreate(); 
        // 初始化 SDK
        ControllerSdk.getInstance().init(this); 
    }
    
    @Override 
    public void onTerminate() { 
        super.onTerminate(); 
        // 释放 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_DISCOVERED` 等动作，解析 NFC 信息获取蓝牙 MAC 地址。
3. 实现 BLE 连接流程。
> **注意**：需在 Activity 的 `onStart` 注册监听，`onStop` 注销监听，并在 `onNewIntent` 中处理数据。

## 5. 文档索引

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

## 6. 技术支持

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

---

**版权所有 ©湖南开鸿智谷数字产业发展有限公司 2024，保留一切权利。**

非经本公司书面许可，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传播。

> **注意**：
> 您购买的产品、服务或特性等应受本公司商业合同和条款的约束，本文档中描述的全部或部分产品、服务或特性可能不在您的购买或使用范围之内。除非合同另有约定，本公司对本文档内容不做任何明示或默示的声明或保证。由于产品版本升级或其他原因，本文档内容会不定期进行更新。除非另有约定，本文档仅作为使用指导，本文档中的所有陈述、信息和建议不构成任何明示或暗示的担保。

---