hikvision-isup-client

Hikvision ISUP Client (Pi5 compatible)

C-language Hikvision ISUP5.0 (Ehome) device client for Ubuntu 24.04 and Raspberry Pi 5 (BCM2712 / Cortex-A76 / aarch64 8GB). It registers the device to a platform, encapsulates an H.264 stream into MPEG-PS and pushes it to ZLMediaKit via RTMP, drives record playback (NET_ESTREAM_StartListenPlayBack

• NET_ECMS_StartPlayBack) and ingests alarms (NET_EALARM_StartListen).

Platform (from the device Web-UI screenshot used as the reference config):

• 平台接入方式: ISUP(原Ehome) 协议版本: ISUP5.0
• 服务器地址: 117.131.63.98 端口: 7031
• 设备ID: AX5324540 加密密钥: abc12345

Architecture

main.c  --> platform.c  (CMS init / listen / register / heartbeat / logout)
        --> stream.c    (PS packer: SYS header + PES(0xE0, PTS 90k) -> RTMP)
        --> playback.c  (StartListenPlayBack + NET_ECMS_StartPlayBack state machine)
        --> alarm.c     (NET_EALARM_StartListen + ring-buffer event queue)
        --> config.c    (parse config.ini)
        --> portable.c  (endian / monotonic clock / thread-stack layer)
        --> isup_stub.c (mock SDK for -DISUP_SIM build & self-test)

Directory layout

include/   portable.h common.h config.h platform.h stream.h playback.h alarm.h isup_sdk.h
src/       portable.c config.c platform.c stream.c playback.c alarm.c main.c isup_stub.c
scripts/   setup.sh build_pi5.sh git_sync.sh
systemd/   hikvision-isup.service
config.ini Makefile .gitignore README.md CHANGELOG.md

Build

# 1) Verify on any host (no vendor SDK needed):
make simulate          # builds build/hikvision-isup-client-<arch>-sim
make test              # runs the full self-test (-t)

# 2) Production build (needs vendor SDK):
#    put aarch64 libHCNetSDK.so (+ deps) into ./libs   on the Pi5
make                   # builds ...-<arch>-real

# Raspberry Pi 5 helper:
./scripts/build_pi5.sh

On the Pi5, uname -m returns aarch64; the Makefile auto-detects the arch and names the binary hikvision-isup-client-aarch64-{sim,real}. You can cross-build with make ARCH=aarch64 CC=aarch64-linux-gnu-gcc simulate.

Run

./build/hikvision-isup-client-$(uname -m)-sim -c config.ini -s   # demo w/o SDK
./build/hikvision-isup-client-$(uname -m)-sim -t                 # self-test
./build/hikvision-isup-client-$(uname -m)-real -c config.ini     # production

System service (Pi5)

sudo cp systemd/hikvision-isup.service /etc/systemd/system/
sudo systemctl daemon-reload && sudo systemctl enable --now hikvision-isup

PS -> RTMP push chain (screenshot-style flow)

1. device frame (H.264 Annex-B AU) -> stream_push_frame()
2. build MPEG-PS: pack_system_header (0x000001BA) + PES (0x000001E0, PTS in 90kHz ticks, big-endian written with be_write*)
3. RTMP publish rtmp://<rtmp_host>:1935/live/ch<channel> to ZLMediaKit (real sockets wired in production mode; counted in simulate mode)

API quick reference

Function	Purpose
platform_register()	send ISUP registration (cms_ip:cms_port, device_id, license)
platform_heartbeat()	keepalive, monotonic-clock gated
stream_simulate_loop(ch, n)	push n synthetic frames through the PS packer
playback_start/pause/resume/stop	NET_ECMS_StartPlayBack lifecycle
alarm_ingest(ch, type, desc)	feed an alarm event into the queue
alarm_ack(id)	acknowledge & retire an event

Git auto-sync (Gogs)

After every change run:

./scripts/git_sync.sh          # default branch: main

It commits everything and pushes to https://git.zhonjin.com:40717/steven_roc/hikvision-isup-client. The access token is embedded in the remote URL (override with GOGS_TOKEN=...).

Raspberry Pi 5 notes

• 64-bit Bookworm (aarch64) is the supported image; portable.h avoids all ILP32/long-width assumptions and never casts char* to wider types.
• char is unsigned on ARM AAPCS: every raw byte uses uint8_t explicitly.
• Big buffers live on the heap (not the thread stack) via portable_thread_create.
• 8GB board: MemoryMax=1G in the systemd unit; raise it when adding channels.

Troubleshooting

• cannot dlopen libHCNetSDK.so -> use -s/simulate, or drop the .so in libs/.
• PS stream shows green/garbage on ZLMediaKit -> verify your H.264 AU start codes (00 00 00 01) and that SPS/PPS precede the first IDR (this code emits SPS+IDR on keyframes every fps frames).
• Registration never goes online -> confirm the platform's ISUP listen port and that device_id/license match the platform's whitelist.

Security

• The Gogs token is embedded in scripts/git_sync.sh and the git remote as requested. Rotate by exporting GOGS_TOKEN; keep the repo private. Do not expose 117.131.63.98 / device credentials in public logs (log level in config.ini controls verbosity).