Hikvision ISUP Client - Complete C development project
steven_roc
b00ecb8d48
Update git_sync.sh script
|
3 dní pred | |
|---|---|---|
| docs | 3 dní pred | |
| include | 3 dní pred | |
| libs | 3 dní pred | |
| scripts | 3 dní pred | |
| src | 3 dní pred | |
| tests | 3 dní pred | |
| .gitignore | 3 dní pred | |
| Makefile | 3 dní pred | |
| README.md | 3 dní pred | |
| config.ini | 3 dní pred |
README.md
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. 安装依赖
# 运行环境初始化脚本
chmod +x scripts/setup.sh
./scripts/setup.sh
手动安装依赖：
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推流)
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)
# 使用模拟模式编译(无需HCNetSDK，可用于开发和测试)
make simulate
正式编译(需要HCNetSDK)
# 默认编译(需要libs目录中有HCNetSDK库文件)
make
# 指定SDK路径
make HCNETSDK_PATH=/opt/hikvision-sdk
# 清理并重新编译
make cleanbuild
运行程序
# 使用默认配置运行
./hikvision-isup-client
# 指定配置文件
./hikvision-isup-client -c config.ini
# 守护进程模式运行
./hikvision-isup-client -c config.ini -d
# 查看帮助
./hikvision-isup-client -h
# 查看版本
./hikvision-isup-client -v
安装到系统
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)
主要配置项说明：
[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说明
平台注册流程
// 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();
录像回放流程
// 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();
报警接入流程
// 1. 初始化报警模块
alarm_init();
// 2. 启动报警监听
alarm_start_listen("0.0.0.0", 9000,
alarm_data_callback, // 报警数据回调
alarm_process_callback, // 报警处理回调
NULL);
// 3. 清理
alarm_cleanup();
RTMP推流流程
// 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 |
| ... |
封装流程
- 从海康设备接收H.264/H.265原始码流
- 检测SPS/PPS参数集，如有变化则生成PS系统头和PSMAP
- 将NALU数据封装为PES包
- 添加Pack Header
- 填充到PS_PACKET_SIZE(2048字节)
- 添加CRC校验
- 通过RTMP推送到ZLMediaKit
在ZLMediaKit中接收
ZLMediaKit 支持直接接收ISUP/Ehome协议的PS流，配置方法：
# 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代码管理
初始化仓库
# 运行Git同步脚本
chmod +x scripts/git_sync.sh
./scripts/git_sync.sh
手动配置
# 初始化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
日常同步
# 方式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库文件
日志关键字搜索
# 搜索注册相关日志
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
安全说明
- 加密密钥管理：加密密钥等敏感信息不应硬编码在代码中，应通过配置文件或环境变量管理
- 访问控制：生产环境应限制CMS/SMS/Alarm端口的访问来源IP
- 日志安全：日志中可能包含敏感信息，应设置合适的文件权限
- 网络安全：建议在生产环境中使用TLS加密ISUP通信
开发计划
- 平台注册(CMS)模块
- 流媒体管理(SMS)模块
- 录像回放模块
- 报警接入模块
- RTMP推流(ZLMediaKit)
- 模拟测试模式
- 配置文件管理
- 完整文档
- 单元测试框架
- 性能测试
- Docker容器化部署
- Web管理界面
- 多设备管理
- 录像文件管理
许可证
本项目为内部开发项目，仅供学习参考使用。
联系方式
- Git仓库: https://git.zhonjin.com:40717/steven_roc/hikvision-isup-client
- 项目维护: steven_roc