hawkbit/huaxu/README.md

# Hawkbit DDI Client

轻量级纯 Python OTA 更新代理，零依赖（仅 Python 3 标准库），可在 **Android adb shell** 和 **Linux 主机**上运行。

## 功能

| 功能 | 说明 |
|------|------|
| **轮询** | `GET /{tenant}/controller/v1/{controllerId}` 查询部署任务，自动适配服务端建议的轮询间隔 |
| **断点下载** | HTTP `Range` 请求实现断点续传，临时 `.tmp` 文件保留至下载完成 |
| **SHA256 校验** | 下载完成后自动与部署元数据中的哈希值比对 |
| **状态上报** | 完整状态链：`download` → `downloaded` → `proceeding` → `closed(success/failure)` |
| **设备 SN 检测** | 自动检测序列号：Android `ro.serialno` → DMI `product_serial` → `/etc/machine-id` → hostname |
| **设备属性上报** | 首次连接自动上报设备属性（osType, platform, hwRevision, kernel…），供 Hawkbit target filter 匹配 |
| **认证** | 支持 `GatewayToken` 和 `TargetToken`，也支持从文件读取：`--gateway-token @/etc/hawkbit/gateway.key` |
| **取消/确认** | 处理 `cancelAction`（取消任务）和 `confirmationBase`（headless 自动确认） |

### 设备属性上报

脚本在**首次轮询**时自动调用 `PUT …/configData` 上报以下属性：

| 属性 | 来源 | 示例 |
|------|------|------|
| `osType` | `/system/build.prop` 或 uname | `android` / `linux` |
| `platform` | `platform.machine()` | `aarch64` / `x86_64` |
| `kernel` | `os.uname().release` | `6.17.0-35-generic` |
| `hwRevision` | DMI product_name + product_version | `VMware Virtual Platform` |
| `manufacturer` | DMI sys_vendor 或 Android ro.product.manufacturer | `VMware, Inc.` |
| `hostname` | `socket.gethostname()` | `device-001` |
| `swVersion` | `/etc/hawkbit/current_version`（可选） | `V1.0.0.0` |

**扩展属性**：创建 `/etc/hawkbit/device_attrs.json` 添加自定义属性：

```json
{"dept": "production", "region": "east", "owner": "team-a"}
```

这些属性在 Hawkbit 里就是 target 的 attributes，管理员创建 target filter 时可以直接用：

```
属性 osType=android AND hwRevision=VMware  →  自动分配 V2.0 更新

## 快速开始

```bash
# 网关令牌，每 30 秒轮询
python3 ddi-client.py -u https://hawkbit.example.com -t DEFAULT --gateway-token s3cret -i 30

# 网关令牌从文件读取（生产推荐）
echo "s3cret" > /etc/hawkbit/gateway.key
chmod 600 /etc/hawkbit/gateway.key
python3 ddi-client.py -u https://hawkbit.example.com -t DEFAULT \
    --gateway-token @/etc/hawkbit/gateway.key -i 30

# 目标令牌，单次轮询
python3 ddi-client.py -u http://10.0.0.1:8080 -t DEFAULT --target-token tok --once

# 自定义设备 ID + 自定义属性文件，调试模式
python3 ddi-client.py -u https://hawkbit:8443 -t prod \
    --gateway-token @/etc/hawkbit/gateway.key \
    --controller-id edge-042 -d /data/ota -v
```

## 命令行参数

```
-u, --base-url           Hawkbit 服务端地址（必填）
-t, --tenant             租户名称，如 DEFAULT（必填）
--gateway-token          Gateway 安全令牌
--target-token           Target 安全令牌
--controller-id          控制器 ID，默认自动检测设备序列号
-d, --download-dir       下载目录，默认 /tmp/hawkbit
-i, --polling-interval   轮询间隔（秒），默认 60，可被服务端覆盖
--no-verify              跳过 SHA256 校验
--no-resume              禁用断点续传
--no-ssl-verify          禁用 TLS 证书验证（不安全）
--once                   仅轮询一次后退出
-v, --verbose            调试级日志
-h, --help               帮助信息
```

## DDI API 流程

```
  ┌─────────┐     ① GET /{tenant}/controller/v1/{controllerId}     ┌──────────┐
  │         │ ────────────────────────────────────────────────────→ │          │
  │  设备   │     ←──── HAL links (deploymentBase / cancel / …)     │ Hawkbit  │
  │         │                                                       │  Server  │
  │         │     ② GET …/deploymentBase/{actionId}                 │          │
  │         │ ────────────────────────────────────────────────────→ │          │
  │         │     ←──── chunks[].artifacts[] (filename, SHA256,     │          │
  │         │            download URL)                              │          │
  │         │                                                       │          │
  │         │     ③ GET …/softwaremodules/{id}/artifacts/{file}     │          │
  │         │ ────────────────────────────────────────────────────→ │          │
  │         │     ←──── 二进制流（支持 Range 断点续传）                 │          │
  │         │                                                       │          │
  │         │     ④ POST …/deploymentBase/{actionId}/feedback       │          │
  │         │ ───── {execution, result, details} ────────────────→  │          │
  │         │     ←──── 200 OK                                      │          │
  └─────────┘                                                       └──────────┘
```

### 状态上报 JSON 格式

```json
{
    "timestamp": 1750000000000,
    "status": {
        "execution": "download",
        "result": {
            "finished": "none"
        },
        "details": ["Starting download"]
    }
}
```

| execution 值 | 含义 | result.finished |
|-------------|------|-----------------|
| `download` | 开始下载 | `none` |
| `downloaded` | 下载完成 | `none` |
| `proceeding` | 安装中 | `none` |
| `closed` | 最终状态 | `success` / `failure` |
| `canceled` | 已取消 | `none` |
| `rejected` | 已拒绝 | `none` |

## 认证配置

### Target Token（推荐，每设备独立令牌）

在 Hawkbit Management API 中为目标设置 security token：

```bash
curl -u admin:admin -X PUT \
  -H "Content-Type: application/json" \
  "http://<hawkbit>:9090/rest/v1/targets/<controllerId>" \
  -d '{"securityToken": "my-device-token"}'
```

启用租户级 TargetToken 认证：

```bash
curl -u admin:admin -X PUT \
  -H "Content-Type: application/json" \
  "http://<hawkbit>:9090/rest/v1/system/configs/authentication.targettoken.enabled" \
  -d '{"value": true}'
```

### Gateway Token（所有设备共享同一令牌）

```bash
# 设置 token key
curl -u admin:admin -X PUT \
  -H "Content-Type: application/json" \
  "http://<hawkbit>:9090/rest/v1/system/configs/authentication.gatewaytoken.key" \
  -d '{"value": "my-gateway-key"}'

# 启用
curl -u admin:admin -X PUT \
  -H "Content-Type: application/json" \
  "http://<hawkbit>:9090/rest/v1/system/configs/authentication.gatewaytoken.enabled" \
  -d '{"value": true}'
```

## 设备 SN 检测优先级

| 优先级 | 来源 | 适用平台 |
|--------|------|---------|
| 1 | `getprop ro.serialno` | Android |
| 2 | `/sys/class/dmi/id/product_serial` | Linux (x86) |
| 3 | `/sys/devices/virtual/dmi/id/product_serial` | Linux (ARM / 嵌入式) |
| 4 | `/etc/machine-id` | systemd Linux |
| 5 | `socket.gethostname()` | 通用回退 |

## 安装钩子

下载完成后，脚本调用 `_install(files, handling)` 方法执行实际安装。**默认实现仅做文件存在性检查，生产环境必须覆盖此方法**。

### 方式一：子类继承

```python
from ddi_client import HawkbitDDIClient

class MyClient(HawkbitDDIClient):
    def _install(self, files, handling):
        import subprocess
        for f in files:
            subprocess.run(["unzip", "-o", f, "-d", "/data/ota"], check=True)
        return True
```

### 方式二：Monkey-Patch

```python
client = HawkbitDDIClient(...)
client._install = lambda files, h: do_my_install(files)
```

## 兼容性

- Python ≥ 3.7
- Android (adb shell, 需安装 Python)
- Linux (x86_64 / aarch64 / armv7l)
- macOS
- Hawkbit DDI API v1

## 文件结构

```
ddi-client.py          # 脚本本体（单文件，可直接部署）
```

无其他依赖文件。