# ood-device-sdk

**Repository Path**: akoles/ood-device-sdk

## Basic Information

- **Project Name**: ood-device-sdk
- **Description**: 常见监控设备SDK接口工具，目前主要对接海康、大华，后续对接更多
- **Primary Language**: Java
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 21
- **Forks**: 11
- **Created**: 2024-01-09
- **Last Updated**: 2026-07-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ood-device-sdk

## 项目简介

OOD设备SDK是一个基于Java的设备接入SDK，支持多种厂家的监控设备和人脸识别设备。该项目旨在简化常见监控设备SDK的集成工作，解决厂家SDK中的版本兼容性问题，提供统一的接口来对接海康、大华等主流设备。

**注意**：这是一个个人项目，设备接入功能仍在完善中，可能会存在兼容性问题。

## 功能特性

### 海康设备支持 (device-hik)
- **人脸机设备**：卡片管理、人脸管理、打卡记录查询、抓拍图片、开门控制
- **监控设备**：视频录制、人脸识别（简易版，开发中）、FFmpeg视频转码
- **可视对讲室内机**：通知公告下发

### 大华设备支持 (device-dh)
- **人脸机设备**：卡片管理、人脸管理、打卡记录查询、抓拍图片、开门控制

### 虹软人脸识别 (device-face)
- 基于ArcSoft Face SDK 3.0.0.0的人脸识别功能

## 项目结构

```
ood-device-sdk/
├── pom.xml                          # 父POM配置
├── device-core/                     # 核心模块
│   └── src/main/java/com/ood/device/core/
│       └── (公共接口和基础实现)
├── device-dh/                       # 大华设备SDK模块
│   └── src/main/java/com/ood/device/dh/
│       ├── core/                    # 大华设备核心实现
│       └── lib/                     # 大华SDK原生库封装
├── device-hik/                      # 海康设备SDK模块
│   └── src/main/java/com/ood/device/hik/
│       ├── core/                    # 海康设备核心实现
│       └── lib/                     # 海康SDK原生库封装
└── device-face/                     # 虹软人脸识别模块
    └── src/main/java/com/ood/device/face/
        └── core/                    # 虹软人脸识别核心实现
```

## 技术栈

- **Java 8**：目标Java版本
- **Maven**：构建工具，多模块项目管理
- **Lombok 1.18.30**：减少样板代码
- **Hutool 5.8.25**：Java工具类库
- **JNA-platform 5.13.0**：Java Native Access，用于JNI/native库集成
- **JUnit 4.13.2**：单元测试框架
- **ArcSoft Face SDK 3.0.0.0**：虹软人脸识别SDK

## 快速开始

### 环境要求
- Java 8 或更高版本
- Maven 3.x
- 支持的操作系统：Windows 64位、Linux 64位

### 安装

1. 克隆项目代码
```bash
git clone https://gitee.com/akoles/ood-device-sdk.git
cd ood-device-sdk
```

2. 编译项目
```bash
mvn clean install
```

### 海康SDK使用

1. 初始化SDK
```java
import com.ood.device.hik.core.HikDeviceFactory;

HikDeviceFactory.init("海康设备IP", 37777, "用户名", "密码");
```

2. 登录设备
```java
IHikDevice device = HikDeviceFactory.login("设备序列号");
```

3. 使用设备功能
```java
// 抓拍图片
device.captureImage();

// 获取打卡记录
List<AttendanceRecord> records = device.getAttendanceRecords(startDate, endDate);

// 开门控制
device.openDoor();
```

### 大华SDK使用

1. 初始化SDK
```java
import com.ood.device.dh.core.DhAccessDeviceClient;

DhAccessDeviceClient.init("大华设备IP", 37777, "用户名", "密码");
```

2. 登录设备
```java
DhAccessDeviceClient client = DhAccessDeviceClient.login("设备序列号");
```

3. 使用设备功能
```java
// 抓拍图片
client.captureImage();

// 获取打卡记录
List<AttendanceRecord> records = client.getAttendanceRecords(startDate, endDate);

// 开门控制
client.openDoor();
```

## 模块说明

### device-core
核心模块，包含所有设备共用的接口定义和基础实现。其他模块都依赖此核心模块。

### device-hik
海康设备SDK模块，包含：
- 海康人脸机设备接入
- 海康监控设备接入
- 海康可视对讲室内机接入
- 海康SDK原生库封装

### device-dh
大华设备SDK模块，包含：
- 大华人脸机设备接入
- 大华SDK原生库封装

### device-face
虹软人脸识别模块，基于ArcSoft Face SDK，提供人脸识别、人脸检测等功能。

## 依赖管理

### 模块依赖关系
```
device-hik
    ├── device-core
    └── device-face (test scope)

device-dh
    └── device-core

device-face
    ├── device-core
    └── arcsoft-sdk-face
```

### 版本管理
所有模块继承父POM的版本配置，避免版本冲突。

## 注意事项

1. **SDK版本兼容性**：已解决海康、大华SDK中的JNA版本统一和兼容性问题
2. **初始化顺序**：使用前必须先调用init初始化SDK，再调用login登录设备
3. **线程安全**：SDK初始化和登录操作需要在线程安全的环境下进行
4. **资源释放**：使用完毕后需要正确释放SDK资源

## 开发指南

### 添加新的设备支持

1. 创建新的Maven模块（如device-hikvision）
2. 在父POM中添加模块引用
3. 创建包结构：com.ood.device.{module-name}
4. 实现核心接口：com.ood.device.core.IDeviceClient
5. 封装原生SDK库
6. 编写单元测试

### 代码规范

- 使用Lombok减少样板代码
- 遵循统一的包命名规范
- 编写完整的单元测试
- 注释关键代码逻辑

## 测试

项目使用JUnit 4进行单元测试，测试文件位于各模块的`src/test/java`目录下。

```bash
# 运行所有测试
mvn test

# 运行特定模块测试
mvn test -pl device-hik
```

## 常见问题

### Q: 如何解决JNA版本冲突？
A: 项目已统一使用JNA-platform 5.13.0版本，确保所有模块使用相同版本。

### Q: 支持哪些操作系统？
A: 目前支持Windows 64位和Linux 64位系统。

### Q: 如何获取设备序列号？
A: 设备序列号通常可以在设备管理软件或设备Web界面中找到。

### Q: SDK初始化失败怎么办？
A: 检查网络连接、设备IP配置、用户名密码是否正确。

## 贡献指南

欢迎提交Issue和Pull Request！

1. Fork本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交Pull Request

## 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

## 联系方式

如有问题或建议，请联系：hurrington_z@foxmail.com

## 致谢

感谢以下开源项目：
- [Lombok](https://projectlombok.org/)
- [Hutool](https://hutool.cn/)
- [JNA](https://github.com/java-native-access/jna)
- [ArcSoft Face SDK](https://www.arcsoft.com.cn/)