Metadata-Version: 2.4
Name: camera-proto
Version: 0.1.0
Summary: Skyworth/XPAI camera protocol C library with Python ctypes bindings (prebuilt native wheels)
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# camera-proto

创维/晓派摄像头协议 C 库（`camera_proto.c`）的 pip 分发项目。
C 源码在 CI 上按平台编译成动态库，随 wheel 分发，Python 侧通过 ctypes 调用。

## 结构

```
binary-pypi-skeleton/
├── pyproject.toml                    # 包名 camera-proto / 版本 / 打包配置
├── setup.py                          # 强制平台标签（关键，别删）
├── native/
│   ├── camera_proto.c                # C 源码（唯一需要维护的源文件）
│   └── test_dll.py                   # 本机 DLL 冒烟测试
├── src/camera_proto/
│   ├── __init__.py                   # ctypes 绑定：所有 SK_API 函数的 Python 封装
│   └── lib/                          # 编译产物（CI 自动生成，本机已有 win 版）
│       └── camera_proto.dll
└── .github/workflows/release.yml     # 打 tag → 三平台编译 → 上传 PyPI
```

## 日常维护（发布新版本）

```bash
# 1. 改 C 源码或 Python 绑定
# 2. 升版本号：pyproject.toml 里 version = "0.1.1"
# 3. 提交 + 打 tag + 推送
git add -A && git commit -m "release 0.1.1"
git tag v0.1.1 && git push && git push --tags
# CI 自动：Windows(MSVC)/Linux(gcc)/macOS×2(clang) 编译 → 打 4 个 wheel → 上传
```

唯一记得的事：**升版本号**。PyPI 不允许同版本号重复上传。

## 本机（Windows）开发验证

```bash
# 编译（MSYS2 MinGW，已验证 gcc 16.1.0 可用）
cd native
/c/msys64/mingw64/bin/gcc.exe -shared -O2 -static-libgcc \
    -o ../src/camera_proto/lib/camera_proto.dll camera_proto.c -lws2_32

# C 自测（hash/JSON/报警解析全 PASS 才继续）
/c/msys64/mingw64/bin/gcc.exe -O2 -DSK_TEST_MAIN -o selftest.exe camera_proto.c -lws2_32
./selftest.exe

# 打 wheel（已验证产物名带 win_amd64 平台标签）
python -m build

# 模拟用户安装验证
pip install dist/camera_proto-0.1.0-py3-none-win_amd64.whl --force-reinstall
python -c "import camera_proto; print(camera_proto.sk_version())"
```

## Python 用法

```python
import camera_proto as cp

cp.sk_version()                     # '2.0.0'
cp.discovery_search(3.0)            # 局域网发现，返回设备 dict 列表
cp.device_get_info("192.168.1.107")
cp.ptz_set(ip, sn, "admin", password, {"pan": 10, "tilt": 0})
cp.image_set(ip, sn, user, pwd, {...})

# 报警流解析
ap = cp.AlarmParser()
events = ap.feed(rtsp_chunk_bytes)  # [{'topic': 'motion', ...}]
```

## TLS / 云端鉴权：默认启用

所有平台构建均**静态链接 OpenSSL 3.5 LTS**（CI 从官方源码编译，
sha256 强校验），`cloud_auth_request` / `cloud_auth_check` 开箱可用。

- **Windows**：`cacert.pem` 必须与 `camera_proto.dll` 同目录（C 代码按
  DLL 所在目录查找），wheel 的 `lib/` 里已带，安装后自动就位
- **Linux / macOS**：使用系统 CA 证书库，无需额外文件
- 本机 Windows 复现编译（复用 xpai-build-jcp 的 OpenSSL 缓存，只读）：

```bash
DEPS="G:/Share/Project-xpai/7/AgenticCameraControl/xpai-build-jcp/.build/deps/openssl-f9e71f0b414a55661a26"
/c/msys64/mingw64/bin/gcc.exe -shared -static -DSK_ENABLE_OPENSSL -O2 \
  -I"$DEPS/include" -o ../src/camera_proto/lib/camera_proto.dll camera_proto.c \
  "$DEPS/lib64/libssl.a" "$DEPS/lib64/libcrypto.a" \
  -static-libgcc -lws2_32 -lgdi32 -lcrypt32 -ladvapi32 -luser32 -lbcrypt -s
```

- 与 xpai-build-jcp FULL 构建的区别：**不含 `SK_OBFUSCATED` 密钥混淆打包**
  （那是专有流程，且当前仅 Windows 实现）。公开 wheel 里密钥/字符串以
  原文嵌入——如需混淆，后续可在 CI Windows job 里接 pack_sk_secrets.py

## PyPI 发布前置（一次性）

1. pypi.org 注册账号
2. 首次手动上传（本机 `twine upload dist/*`，需 API token）
3. PyPI 项目设置 → Publishing → 绑定 GitHub 仓库 + workflow 文件 `release.yml`
4. 之后永远只需打 tag

## 注意事项

- **平台覆盖**：只打 4 个 wheel（win_amd64 / linux_x86_64 / macos x86_64+arm64），其他平台 pip install 会失败
- **Linux glibc**：CI 在 ubuntu-latest 上编译，要求用户 glibc 较新；老系统兼容需改 manylinux 容器构建
- Windows 版 DLL 静态链 OpenSSL + 系统库，已验证用户机器零额外依赖
- OpenSSL 版本升级：改 release.yml 顶部的 `OPENSSL_VERSION` 和 `OPENSSL_SHA256`（官方发布页有 .sha256 文件）

