# endless

**Repository Path**: endless22/endless

## Basic Information

- **Project Name**: endless
- **Description**: IPC开源方案、网络摄像头方案。
- **Primary Language**: C++
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: http://www.endless-sky-tech.com/
- **GVP Project**: No

## Statistics

- **Stars**: 50
- **Forks**: 34
- **Created**: 2022-04-09
- **Last Updated**: 2026-07-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: IPC, 网络摄像头

## README

<div align="center">

# Endless

**面向智能网络摄像机的开源端侧软件栈**

从音视频采集、编码、存储与流媒体，到 Web 管理、行业协议、智能分析和 AI Agent，提供一套可编译、可烧录、可按产品裁剪的 IPC 基础方案。

[![C++17](https://img.shields.io/badge/C%2B%2B-17-00599C?logo=c%2B%2B)](cmake/common.cmake)
[![Vue 3](https://img.shields.io/badge/Vue-3-42b883?logo=vuedotjs)](foundation/web_page)
[![Platform](https://img.shields.io/badge/SoC-Hi3516CV610-0ea5e9)](device/board/3516cv610)
[![License](https://img.shields.io/badge/License-AGPL--3.0--or--later-1f6feb)](LICENSE)

</div>

## 项目定位

Endless 是一套面向 Linux 智能摄像机的嵌入式软件框架。它不只提供一个视频 Demo，而是把量产 IPC 常见的媒体、录像、网络、升级、权限、协议和智能能力组织成可复用组件，并通过产品配置完成型号差异化。

它适合以下场景：

- IPC 厂商快速搭建自有固件、Web 管理端和升级体系；
- 方案商接入 ONVIF、GB28181、RTSP、WHEP/WebRTC 或上层业务平台；
- 开发者新增算法、事件联动、云模型、Agent 工具或设备控制能力；
- 二次开发团队基于统一 HAL 和模块接口适配传感器、板卡与新产品型号。

> 当前开源构建流程仅支持 **HiSilicon 3516CV610**。仓库内已有 `ipc200`、`ipc201`、`ipc220` 三个产品配置；移植其他 SoC 需要同时适配工具链、HAL、板级文件和打包流程。
> 闭源版本支持瑞芯微1126pb，爱芯元智ax615，海思3519dv500，海思3516CV608

### 已有产品配置

| 产品 ID | 硬件组合 | 定位 | 主要差异 |
| --- | --- | --- | --- |
| `ipc200` | 3516CV610 + SC4336P | 4MP 标准款 | 标准主/子码流与通用外设配置 |
| `ipc201` | 3516CV610 + CV4002X | 4MP URI 兼容形态 | 独立传感器、GPIO 与 RTSP URI 配置 |
| `ipc220` | 3516CV610 + SC500AI | 5MP 标准款 | 2880 × 1620 主码流、双路报警输入/输出 |

实际分辨率、帧率、编码、GPIO、IR-CUT 和补光灯能力以对应产品的 `board.yaml` 与 `product.yaml` 为准。

## 核心能力

| 能力域 | 已提供能力 | 主要代码入口 |
| --- | --- | --- |
| 音视频 | H.264/H.265、主/子码流、OSD、抓图、音频输入与语音播放 | `base/media`、`hal/mpp` |
| 流媒体 | RTSP、RTMP、WebRTC/WHEP 直播与录像回放、会话与资源配额 | `foundation/stream_service` |
| 存储录像 | 存储设备管理、计划录像、录像检索、回放、抓图与文件索引 | `base/storage`、`base/record`、`base/file_manager` |
| 智能分析 | 人/车/人脸等内置算法配置、自定义 YOLO 模型、ROI/尺寸过滤和事件联动 | `base/video_analytics`、`hal/ai`、`base/event_manager` |
| 开放协议 | JSON-RPC 2.0、设备发现、ONVIF、GB28181、RTSP/WHEP 接入 | `foundation/protocol`、`base/discovery`、`foundation/onvif`、`foundation/gb28181` |
| AI 与工具 | Qwen/阿里云模型接入、设备 Agent、工具注册中心与 MCP 服务 | `foundation/agent`、`foundation/qwen`、`foundation/aliyun`、`foundation/tools`、`foundation/mcp` |
| 设备管理 | 用户与细粒度权限、网络配置、配置备份、日志、SSH、诊断、看门狗与恢复出厂 | `base/common`、`base/network`、`base/system_service` |
| 固件工程 | 产品配置、RootFS overlay、分区布局、烧录包、升级包与独立升级守护进程 | `vendor`、`device/board`、`scripts/package`、`applications/upgraded` |

云模型、MCP 和行业协议通常还需要在设备端填写服务参数、账号或平台信息；是否启用由产品 `defconfig` 与运行时配置共同决定。

## 功能展示

Web 管理端基于 Vue 3 和 Ant Design Vue，覆盖实时预览、录像回放、摄像头参数、网络协议、事件规则、外设、系统运维、Agent 与 MCP 配置。

> 以下界面采集自一台实际运行设备。为保护现场隐私，采集前已在网络层阻断直播、回放和抓图媒体请求；直播与回放播放器中的场景由图像模型自动生成，页面框架、导航、控件和配置数据来自真实设备。

### 实时直播

![Endless Web 实时直播](docs/assets/readme/web-live-v4.png)

<p align="center"><sub>真实设备 Web 直播页面；播放器内容为隐私保护合成画面。</sub></p>

- 通过 WHEP/WebRTC 在浏览器中低延迟播放设备码流；
- 支持主、子码流快速切换，并以 `HD` / `SD` 标识当前清晰度；
- 支持浏览器抓图、页面全屏和实时码率显示；
- 可订阅设备智能事件，在视频层自动叠加目标类别、置信度和检测框。

### 录像回放

![Endless Web 录像回放](docs/assets/readme/web-playback-v2.png)

<p align="center"><sub>真实设备 Web 录像回放页面；播放器内容为隐私保护合成画面。</sub></p>

- 按日期检索录像，以 24 小时时间轴定位片段，并可切换 24 小时、6 小时和 1 小时视图；
- 区分连续录像、移动侦测、事件录像和手动录像，不同类型在时间轴中分别着色；
- 支持片段列表、前后片段切换、播放/暂停、快退/快进、倍速、音量和全屏控制；
- 通过独立 WHEP 回放会话播放设备端录像，不占用直播会话。

### 算法配置

![Endless Web 算法配置](docs/assets/readme/web-algorithm-v2.png)

<p align="center"><sub>算法实例、置信度、最大检测数量和启用状态集中管理。</sub></p>

- 展示算法类型与用途，例如人脸、人形和车辆检测；
- 支持新增、删除和刷新算法实例；
- 可在线调整置信度阈值、单帧最大检测数量及启用状态；
- 算法输出进入统一目标跟踪与事件管线，供直播叠加、规则判断和报警联动复用。

### 事件管理

事件中心将视频检测、目标跟踪、外部报警输入和设备联动统一为固定事件模型。不同事件类型可以独立启用、设置规则，并复用同一套布防和联动能力。

| 事件分类 | 已提供功能 |
| --- | --- |
| 基础视频检测 | 移动侦测、视频遮挡、虚焦、场景变更 |
| 行为分析 | 越线、区域入侵、物品遗留、物品移除、徘徊、快速移动、人群聚集、非法停车 |
| 热度图分析 | 检测区域、网格行列精度、上报间隔 |
| 人脸分析 | 人脸检测、人脸抓拍，以及算法实际支持的人脸属性 |
| 人数统计 | 全画面人数、区域人数、排队检测 |
| 视频结构化 | 人体、机动车、非机动车检测 |
| 报警输入 | 将板级报警输入转换为事件，并进入统一报警联动流程 |

![Endless Web 事件规则配置](docs/assets/readme/web-event-rules-v2.png)

<p align="center"><sub>行为分析支持多个检测项，以及越线、区域和方向等几何规则。</sub></p>

每条规则可以配置：

- 总开关、规则开关、名称和视频通道；
- 灵敏度、触发/恢复确认帧数、置信度和目标类型过滤；
- 全画面、检测区域、规则线及越线方向；
- 持续时间、上报间隔、人数阈值、热度图网格和人脸属性等事件专用参数；
- 行为分析支持为同一种事件添加多个检测项，分别设置区域、方向与联动策略。

![Endless Web 事件报警联动](docs/assets/readme/web-event-linkage-v2.png)

<p align="center"><sub>布防时间与联动动作直接绑定在事件规则上。</sub></p>

报警联动支持：

- 全天生效或按星期、时间段布防，并设置去抖时间；
- 联动录像与抓图，选择录像通道并设置延迟结束时间；
- 驱动报警输出并设置保持时间；
- 播放指定语音文件，配置音量与播放时长；
- 闪烁白光灯，配置亮灭周期与联动持续时间。

界面会随版本持续演进，请以当前构建结果为准。

## 技术架构

![Endless 分层技术架构](docs/assets/readme/architecture.svg)

架构遵循“产品配置 → 应用编排 → 业务组件 → 基础服务 → HAL → 板级平台”的依赖方向。主进程在 [`applications/endless/main.cpp`](applications/endless/main.cpp) 中按依赖顺序启动和停止模块，各组件通过公共接口、配置管理、事件中心和工具注册中心协作。

### 目录说明

| 目录 | 职责 | 二开建议 |
| --- | --- | --- |
| [`applications`](applications) | 主服务和升级守护进程入口 | 保持入口轻量，只负责生命周期编排 |
| [`base`](base) | 媒体、录像、存储、网络、事件、升级等基础服务 | 放置可被多种协议或产品复用的能力 |
| [`foundation`](foundation) | 流媒体、JSON-RPC、Web、ONVIF、GB28181、Agent/MCP 等业务组件 | 放置接入层、协议层和云服务适配 |
| [`common`](common) | 日志、任务、内存、IPC、配置等通用工具 | 避免引入具体产品或业务语义 |
| [`hal`](hal) | MPP、AI 和外设抽象接口 | 新平台实现应遵守这里的接口契约 |
| [`device/board`](device/board) | 板级 RootFS、内核、启动文件、分区布局与打包 hook | 管理 SoC/板卡共性，不混入客户产品配置 |
| [`vendor`](vendor) | 产品型号、传感器、功能裁剪与 RootFS overlay | 新增产品优先从这里开始 |
| [`scripts/package`](scripts/package) | 通用固件打包引擎 | 扩展新介质、分区策略或升级格式 |
| [`lib`](lib) / [`third_party`](third_party) | 平台预编译库与第三方依赖 | 使用和再分发前确认各自许可证或 SDK 条款 |

## 快速开始

### 1. 准备环境

构建脚本会严格检查 **Ubuntu 24.04**。建议准备以下工具：

```bash
sudo apt update
sudo apt install -y \
  build-essential cmake git jq curl \
  nodejs npm cpio u-boot-tools mtd-utils squashfs-tools
```

- Web 前端要求 Node.js `>= 18`；
- `package` 命令还会使用 `mkenvimage`、`ubinize`、`mksquashfs` 等镜像工具；
- 3516CV610 交叉工具链由 [`cmake/toolchains_manifest.json`](cmake/toolchains_manifest.json) 描述，首次构建会自动下载并校验 SHA-256，默认缓存到 `~/.cache/endless/toolchains`；
- 可用 `ENDLESS_TOOLCHAINS_DIR` 修改缓存根目录，或用 `ENDLESS_TOOLCHAIN_ROOT` 指向已安装工具链。

### 2. 获取源码

```bash
git clone https://gitee.com/endless22/endless.git
cd endless
./build.sh --help
```

如果只想体验设备固件，也可以从 [Releases](https://gitee.com/endless22/endless/releases) 获取已发布镜像。

### 3. 编译与打包

```bash
# 仅编译 C/C++，不构建 Web 前端
./build.sh ipc200 build release

# 编译应用与 Web 前端，不生成固件包
./build.sh ipc200 all release

# 编译应用与 Web 前端，并生成烧录包和升级包
./build.sh ipc200 package release

# 调试版本；也可将 ipc200 换成 ipc201 或 ipc220
./build.sh ipc201 all debug
```

命令格式为：

```text
./build.sh <product> <build|all|package> [debug|release]
```

可通过 `BUILD_JOBS=<并行数>` 控制编译并发。代码格式化使用：

```bash
./build.sh format
```

### 4. 构建产物

产物按产品隔离在 `out/<product>/`：

```text
out/ipc200/
├── bin/                    # endless、upgraded、elsh 等可执行文件
├── web/                    # Web 前端静态资源（all/package）
└── image/
    ├── burn_<date>/        # 烧录镜像与说明（package）
    └── upgrade_<date>/     # Web/设备升级包（package）
```

打包过程还会生成板级烧录说明和分区校验结果；请优先阅读产物目录内随包生成的说明文件。

### 5. 访问设备

烧录并启动设备后，在浏览器打开：

```text
http://<设备 IP>/
```

首次初始化的默认账号为 `admin`，默认密码为 `admin123`。**首次登录后请立即修改密码，不要将默认凭据的设备直接暴露到公网。**

RTSP URI 可能因产品兼容策略而不同，建议从 Web 网络配置页或 `cameras.getStream` 接口获取设备实际地址。

## 二次开发指南

### 新增一个产品型号

同一 SoC/板卡上的新型号通常不需要复制业务代码，可以从已有产品配置派生：

```bash
cp -a vendor/ipc200 vendor/mycam
```

然后至少检查以下文件：

| 文件 | 需要修改的内容 |
| --- | --- |
| `vendor/mycam/config.json` | `product_id`、型号、板卡、传感器、分区与打包参数；简单产品的目录名必须与 `product_id` 一致 |
| `vendor/mycam/defconfig` | 功能开关、内存池等编译期裁剪项 |
| `rootfs/overlay/usr/etc/custom/board.yaml` | 传感器、媒体能力、MMZ、GPIO、IR-CUT、灯光和 pinmux |
| `rootfs/overlay/usr/etc/custom/product.yaml` | 产品身份、语言、码流结构、URI 风格与资源配额 |
| `rootfs/overlay/usr/etc/custom/default` | 首次启动时使用的运行时默认配置 |

修改完成后，`build.sh` 会自动发现合法的 `vendor/*/config.json`：

```bash
./build.sh mycam all debug
./build.sh mycam package release
```

如果更换了仓库中尚未支持的传感器或硬件模块，还需要提供对应驱动、传感器库和 HAL 实现，不能只修改 YAML。

### 裁剪功能

功能定义集中在 [`base/Kconfig`](base/Kconfig)，每个产品通过 `defconfig` 覆盖默认值。例如，资源受限产品可以关闭暂不需要的云能力：

```text
CONFIG_APP_MEM_POOL_SIZE_MB=8
# CONFIG_FEATURE_QWEN is not set
# CONFIG_FEATURE_ALIYUN is not set
# CONFIG_FEATURE_GB28181 is not set
```

配置加载器会校验未知选项，并根据模块依赖自动关闭无法成立的下游功能。修改后建议清理对应的 `build/<product>` 再做完整构建，以排除旧缓存影响。

### 新增业务模块

推荐按以下边界放置代码：

1. 通用设备能力放在 `base/<module>`，协议、云服务或产品交互放在 `foundation/<module>`；
2. 对外接口放入模块 `include/`，实现放入 `src/`，并在对应 `CMakeLists.txt` 注册目标；
3. 在 `applications/endless/main.cpp` 中按依赖关系接入 `Start/Stop`，保证失败回滚和退出顺序清晰；
4. 跨模块状态优先使用配置管理、事件中心或工具注册中心，不直接穿透私有实现；
5. 新增 JSON-RPC 方法时同步完成参数校验、权限检查、错误码和前端 API 封装。

### 移植新板卡或 SoC

新平台移植通常涉及以下工作面：

- `device/board/<board>`：板级配置、RootFS、启动文件、分区布局和打包 hook；
- `cmake/<platform>.cmake`：编译器、sysroot、平台宏和链接规则；
- `hal/*/include`：实现音视频、AI 与外设接口；
- `lib/<platform>/<debug|release>`：若仍采用预编译 HAL，需要提供与接口匹配的静态库；
- `scripts/package`：新增介质、镜像和升级策略；
- `vendor/<product>`：绑定产品、板卡、传感器和功能配置；
- `build.sh`：放开并校验新平台的构建入口。

当前仓库中的部分 HAL、算法和 SoC 相关能力以预编译库形式参与链接。移植新平台前，请先确认所需 SDK、源代码可用性以及二进制再分发条款。

## API 与 Web 开发

设备控制面以 JSON-RPC 2.0 为主，前端本身就是完整的调用示例。常用入口如下：

| 接口 | 用途 |
| --- | --- |
| `ws://<ip>/v1/protocol` | 登录、配置、录像、模型、升级、诊断等 JSON-RPC 方法 |
| `ws://<ip>/v1/events` | 实时事件订阅与推送 |
| `http://<ip>/v1/whep/live` | WHEP 低延迟直播 |
| `http://<ip>/v1/whep/playback` | WHEP 录像回放 |
| `rtsp://<ip>:554/...` | 标准 RTSP 码流，路径以产品配置或查询结果为准 |

完成 `auth.getChallenge` / `auth.login` 后，可携带令牌建立协议连接并发送标准 JSON-RPC 请求：

```js
const socket = new WebSocket(
  `ws://${deviceIp}/v1/protocol?token=${encodeURIComponent(accessToken)}`
)

socket.addEventListener('open', () => {
  socket.send(JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'system.getInfo',
    params: {}
  }))
})
```

可从以下位置继续阅读实现：

- JSON-RPC 方法注册：[`foundation/protocol/src`](foundation/protocol/src)
- WebSocket 服务：[`foundation/restful/src`](foundation/restful/src)
- 浏览器 API 封装：[`foundation/web_page/src/api`](foundation/web_page/src/api)
- 权限校验：[`base/common/include/common_permission.h`](base/common/include/common_permission.h)
- 工具目录与 Agent 调用：[`foundation/tools`](foundation/tools)

前端独立开发：

```bash
cd foundation/web_page
npm install
npm run dev
npm run lint:check
npm run build
```

前端默认连接同源的 `/v1/protocol`。脱离设备运行 Vite 时，需要为该 WebSocket 路径配置本地反向代理或使用可访问的设备后端。

## 开发约定

- C++ 使用 C++17，格式由 [`.clang-format`](.clang-format) 统一；
- 类名使用 `CamelCase`，函数、变量和文件使用 `snake_case`，常量使用大写下划线；
- 提交前至少验证目标产品的 `debug` 或 `release` 构建；涉及 Web 时同时执行 `npm run lint:check` 与 `npm run build`；
- 新增产品、模块、协议或构建参数时，请同步更新 README 和对应配置示例；
- Bug 与功能建议可提交到 [Gitee Issues](https://gitee.com/endless22/endless/issues)。

## 联系方式

- 邮箱：`endless@endless-sky-tech.com`
- 微信公众号：扫描下方二维码关注。

<p align="center">
  <img src="docs/assets/readme/wechat-official-account.jpg" alt="微信公众号二维码" width="258">
</p>

## 许可证

本项目自有代码以 [`AGPL-3.0-or-later`](LICENSE) 提供。你可以在遵守 AGPL 条款的前提下修改、部署和商用；通过网络向用户提供修改后的程序时，请特别留意 AGPL 对应源代码提供义务。

如果需要闭源集成、单独商业授权或技术合作，请联系：`endless@endless-sky-tech.com`。

第三方库、芯片 SDK、预编译 HAL/算法库及模型文件可能适用各自的许可证或分发限制，请在发布二次开发产品前逐项核对。