# Hikvision ISUP Client

海康威视 ISUP(Ehome) 协议 C 语言客户端/平台服务端完整开发项目

## 项目概述

本项目是一个基于海康威视 ISUP(Ehome) 协议的完整 C 语言开发框架，实现了以下核心功能：

- **平台注册**：设备通过 ISUP 协议向 CMS 注册服务器注册上线
- **PS 流推送**：接收海康设备视频流并通过 RTMP 推送到 ZLMediaKit 流媒体服务器
- **录像回放**：支持通过 NET_ESTREAM_StartListenPlayBack + NET_ECMS_StartPlayBack 实现录像回放
- **报警接入**：通过 NET_EALARM_StartListen 接收和处理设备报警事件
- **模拟测试**：内置模拟图片/视频流生成功能，方便开发测试

### 技术栈

| 组件 | 技术选型 | 说明 |
|------|----------|------|
| 编程语言 | C11 | 高性能、底层控制 |
| 操作系统 | Ubuntu 24.04 LTS | 稳定服务器系统 |
| 海康SDK | HCNetSDK (ISUP/Ehome) | 设备注册/流媒体/报警 |
| 流媒体 | ZLMediaKit | RTMP/RTSP/HLS 流媒体服务器 |
| 构建系统 | Make | 简单可靠的构建工具 |
| 版本控制 | Git + Gogs | 自托管代码管理 |

### 系统架构

```
┌─────────────┐     ISUP/TCP     ┌──────────────────┐
│  海康设备    │ ◄──────────────► │  ISUP Client     │
│  (摄像头/NVR) │   注册/流/报警    │  (本程序)        │
└─────────────┘                  └────────┬─────────┘
                                          │ RTMP/PS流
                                          ▼
                                   ┌──────────────┐
                                   │ ZLMediaKit   │
                                   │ (流媒体服务器) │
                                   └──────┬───────┘
                                          │
                    ┌─────────────────────┼─────────────────────┐
                    ▼                     ▼                     ▼
              ┌──────────┐        ┌──────────┐        ┌──────────┐
              │ RTMP     │        │ HLS      │        │ RTSP     │
              │ 客户端    │        │ 直播     │        │ 拉流     │
              └──────────┘        └──────────┘        └──────────┘
```

## 目录结构

```
hikvision-isup-client/
├── README.md              # 项目说明文档
├── Makefile               # 构建配置文件
├── config.ini             # 运行配置文件
├── .gitignore             # Git忽略规则
├── include/               # 头文件目录
│   ├── common.h           # 公共定义与常量
│   ├── config.h           # 配置管理
│   ├── platform.h         # 平台注册管理
│   ├── stream.h           # 视频流管理
│   ├── playback.h         # 录像回放管理
│   └── alarm.h            # 报警管理
├── src/                   # 源代码目录
│   ├── main.c             # 主程序入口
│   ├── platform.c         # 平台注册实现
│   ├── stream.c           # 流媒体管理实现
│   ├── playback.c         # 录像回放实现
│   ├── alarm.c            # 报警管理实现
│   ├── config.c           # 配置管理实现
│   └── utils.c            # 工具函数实现
├── libs/                  # 第三方库目录
├── scripts/               # 辅助脚本
│   ├── setup.sh           # 环境初始化脚本
│   ├── deploy.sh          # 部署脚本
│   └── git_sync.sh        # Git同步脚本
├── docs/                  # 文档目录
├── tests/                 # 测试目录
└── logs/                  # 日志目录(运行时生成)
```

## 环境准备

### 1. 系统要求

- 操作系统：Ubuntu 24.04 LTS (推荐) 或 CentOS 7+
- 编译器：GCC 9.0+
- 内存：最低 512MB，推荐 2GB+
- 磁盘：最低 1GB 可用空间

### 2. 安装依赖

```bash
# 运行环境初始化脚本
chmod +x scripts/setup.sh
./scripts/setup.sh
```

手动安装依赖：

```bash
sudo apt-get update
sudo apt-get install -y build-essential gcc g++ make cmake git pkg-config libssl-dev \
    ffmpeg libavcodec-dev libavformat-dev libavutil-dev libswscale-dev valgrind cppcheck
```

### 3. 安装 ZLMediaKit (可选，用于RTMP推流)

```bash
git clone --depth 1 https://gitee.com/xia-chu/ZLMediaKit
cd ZLMediaKit
git submodule update --init
mkdir build && cd build
cmake ..
make -j4
sudo make install
```

### 4. 部署 HCNetSDK

从海康威视官网下载 HCNetSDK 包，将 Linux 64位版本的文件复制到 `libs/` 目录：

```
libs/
├── libhcnetsdk.so        # 主SDK库
├── libHCCommon.so        # 公共库
├── libHCWindowsComm.so   # 通信库
├── libPlayCtrl.so        # 播放库
├── libHCNetSDK.so        # 备用SDK库
└── ...                   # 其他依赖库
```

## 编译与运行

### 开发模式(无需实际SDK)

```bash
# 使用模拟模式编译(无需HCNetSDK，可用于开发和测试)
make simulate
```

### 正式编译(需要HCNetSDK)

```bash
# 默认编译(需要libs目录中有HCNetSDK库文件)
make

# 指定SDK路径
make HCNETSDK_PATH=/opt/hikvision-sdk

# 清理并重新编译
make cleanbuild
```

### 运行程序

```bash
# 使用默认配置运行
./hikvision-isup-client

# 指定配置文件
./hikvision-isup-client -c config.ini

# 守护进程模式运行
./hikvision-isup-client -c config.ini -d

# 查看帮助
./hikvision-isup-client -h

# 查看版本
./hikvision-isup-client -v
```

### 安装到系统

```bash
sudo make install
sudo ./scripts/deploy.sh
sudo systemctl enable hikvision-isup-client
sudo systemctl start hikvision-isup-client
```

## 配置说明

### 设备端配置(海康设备Web页面)

按照以下路径配置海康设备：

```
系统 > 高级配置 > 网络 > 平台接入 > ISUP(原Ehome)
```

配置参数如下(与项目 config.ini 对应)：

| 配置项 | 值 | 说明 |
|--------|-----|------|
| 平台接入方式 | ISUP(原Ehome) | 选择ISUP协议 |
| 启用 | 勾选 | 启用平台接入 |
| 服务器地址 | 117.131.63.98 | 本程序服务器IP |
| 端口 | 7031 | CMS注册端口 |
| 设备ID | AX5324540 | 设备序列号 |
| 注册状态 | 在线 | 确认注册成功 |
| 协议版本 | ISUP5.0 | 协议版本 |
| 加密密钥 | abc12345 | 加密密钥 |

### 程序配置(config.ini)

主要配置项说明：

```ini
[CMS]
cms_server_ip=117.131.63.98     # CMS服务器IP(本机IP)
cms_server_port=7031            # CMS监听端口
device_id=AX5324540             # 设备ID
protocol_version=ISUP5.0        # 协议版本
encrypt_key=abc12345            # 加密密钥

[RTMP]
rtmp_server=127.0.0.1           # ZLMediaKit服务器地址
rtmp_port=1935                  # RTMP端口
rtmp_app_name=live              # 应用名称
rtmp_stream_key=camera1         # 流名称
```

## 核心API说明

### 平台注册流程

```c
// 1. 初始化CMS库
platform_cms_init();

// 2. 启动CMS监听(接收设备注册)
platform_cms_start_listen("0.0.0.0", 7031, device_register_callback, NULL);

// 3. 设备注册(主动向CMS注册)
int user_id = platform_device_register("117.131.63.98", 7031,
    "AX5324540", "ISUP5.0", "abc12345", NULL);

// 4. 设置自动重连
platform_set_auto_reconnect(user_id, 1, 5);

// 5. 清理
platform_cms_cleanup();
```

### 录像回放流程

```c
// 1. 初始化回放模块
playback_init();

// 2. 开启SMS回放监听
stream_start_playback_listen("0.0.0.0", 7660, NULL, NULL);

// 3. 启动回放
PlaybackSession* session = playback_start(
    "AX5324540",           // 设备ID
    1,                     // 通道号
    start_time,            // 开始时间
    end_time,              // 结束时间
    1,                     // 速度(1=正常)
    playback_data_cb,      // 数据回调
    playback_status_cb,    // 状态回调
    NULL                   // 用户数据
);

// 4. 停止回放
playback_stop(session);

// 5. 清理
playback_cleanup();
```

### 报警接入流程

```c
// 1. 初始化报警模块
alarm_init();

// 2. 启动报警监听
alarm_start_listen("0.0.0.0", 9000,
    alarm_data_callback,    // 报警数据回调
    alarm_process_callback, // 报警处理回调
    NULL);

// 3. 清理
alarm_cleanup();
```

### RTMP推流流程

```c
// 1. 创建流会话
StreamSession* session = stream_create_session(
    "AX5324540", STREAM_TYPE_MAIN, CODEC_TYPE_H264,
    1920, 1080, 25, 4096000
);

// 2. 开始推流到ZLMediaKit
stream_start_push(session, "rtmp://127.0.0.1:1935/live/camera1",
    rtmp_push_callback, NULL);

// 3. 发送视频帧
StreamFrame frame = { .data = frame_data, .data_size = frame_size, ... };
stream_send_frame(session, &frame);

// 4. 停止推流
stream_stop_push(session);

// 5. 销毁会话
stream_destroy_session(session);
```

## PS流封装说明

本项目实现了H.264/H.265原始码流到MPEG-2 PS(Program Stream)的封装：

### PS流结构

```
| Pack Header (4-11 bytes) |
| Program Stream Map       |
| PES Packet               |
|  - PES Header            |
|  - PES Payload (NALU)    |
| ...                       |
| Pack Header              |
| ...                       |
```

### 封装流程

1. 从海康设备接收H.264/H.265原始码流
2. 检测SPS/PPS参数集，如有变化则生成PS系统头和PSMAP
3. 将NALU数据封装为PES包
4. 添加Pack Header
5. 填充到PS_PACKET_SIZE(2048字节)
6. 添加CRC校验
7. 通过RTMP推送到ZLMediaKit

### 在ZLMediaKit中接收

ZLMediaKit 支持直接接收ISUP/Ehome协议的PS流，配置方法：

```ini
# config.ini
[rtmp]
port=1935

# ZLMediaKit会自动将RTMP流转换为多种协议输出
# RTMP: rtmp://server:1935/live/camera1
# HLS:  http://server:8080/live/camera1.m3u8
# RTSP: rtsp://server:554/live/camera1
```

## Git代码管理

### 初始化仓库

```bash
# 运行Git同步脚本
chmod +x scripts/git_sync.sh
./scripts/git_sync.sh
```

### 手动配置

```bash
# 初始化git仓库
git init
git branch -M main

# 添加远程仓库(使用Access Token)
git remote add origin "https://steven_roc:1942ce3d6478f7a572fee3dd4891e49f6c416aad@git.zhonjin.com:40717/steven_roc/hikvision-isup-client.git"

# 添加所有文件
git add -A

# 提交
git commit -m "Initial commit: Hikvision ISUP Client project"

# 推送
git push -u origin main
```

### 日常同步

```bash
# 方式1: 使用脚本
./scripts/git_sync.sh

# 方式2: 手动
git add -A
git commit -m "描述本次更新内容"
git push
```

## 日志说明

程序运行日志输出到 `logs/isup_client.log` 文件和控制台。

日志级别：

| 级别 | 说明 |
|------|------|
| DEBUG | 调试信息，详细的内部状态 |
| INFO | 一般信息，关键流程节点 |
| WARN | 警告信息，非致命问题 |
| ERROR | 错误信息，功能异常 |
| FATAL | 致命错误，程序无法继续 |

修改日志级别：编辑 `config.ini` 中的 `log_level` 参数。

## 故障排查

### 常见问题

**1. 设备注册失败**

- 检查海康设备Web页面配置是否正确(服务器地址、端口、设备ID)
- 确认防火墙允许7031端口通信
- 检查加密密钥是否一致
- 查看程序日志中的错误信息

**2. 视频流无法接收**

- 确认设备已注册上线
- 检查SMS端口(默认7660)是否可访问
- 检查HCNetSDK库文件是否正确部署
- 查看日志中的流相关错误信息

**3. RTMP推流失败**

- 确认ZLMediaKit服务正在运行
- 检查rtmp_server和rtmp_port配置
- 使用 `rtmp://server:1935/live/camera1` 测试拉流
- 查看ZLMediaKit日志

**4. 编译错误**

- 运行 `make simulate` 跳过SDK依赖进行开发
- 确认GCC版本 >= 9.0
- 检查 `libs/` 目录中的SDK库文件

### 日志关键字搜索

```bash
# 搜索注册相关日志
grep -i "register\|login\|cms" logs/isup_client.log

# 搜索流相关日志
grep -i "stream\|rtmp\|push" logs/isup_client.log

# 搜索报警相关日志
grep -i "alarm" logs/isup_client.log

# 搜索错误日志
grep -i "error\|fail" logs/isup_client.log
```

## 安全说明

1. **加密密钥管理**：加密密钥等敏感信息不应硬编码在代码中，应通过配置文件或环境变量管理
2. **访问控制**：生产环境应限制CMS/SMS/Alarm端口的访问来源IP
3. **日志安全**：日志中可能包含敏感信息，应设置合适的文件权限
4. **网络安全**：建议在生产环境中使用TLS加密ISUP通信

## 开发计划

- [x] 平台注册(CMS)模块
- [x] 流媒体管理(SMS)模块
- [x] 录像回放模块
- [x] 报警接入模块
- [x] RTMP推流(ZLMediaKit)
- [x] 模拟测试模式
- [x] 配置文件管理
- [x] 完整文档
- [ ] 单元测试框架
- [ ] 性能测试
- [ ] Docker容器化部署
- [ ] Web管理界面
- [ ] 多设备管理
- [ ] 录像文件管理

## 许可证

本项目为内部开发项目，仅供学习参考使用。

## 联系方式

- Git仓库: https://git.zhonjin.com:40717/steven_roc/hikvision-isup-client
- 项目维护: steven_roc