open_pub/Uni-Lab-OS
1
0
Fork 0
mirror of https://github.com/dptech-corp/Uni-Lab-OS.git synced 2026-02-04 05:15:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

增强新威电池测试系统 OSS 上传功能 / Enhanced Neware Battery Test System OSS Upload (#196)

Browse Source 
* feat: neware-oss-upload-enhancement

* feat(neware): enhance OSS upload with metadata and workflow handles
This commit is contained in:
Xie Qiming
2025-12-23 18:41:15 +08:00
committed by GitHub
parent 5fec753fb9
commit 2ffeb49acb
5 changed files with 3199 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

560
unilabos/devices/neware_battery_test_system/OSS_UPLOAD_README_CN.md Normal file
View File

@@ -0,0 +1,560 @@
# 新威电池测试系统 - OSS 上传功能说明
## 功能概述
本次更新为新威电池测试系统添加了**阿里云 OSS 文件上传功能**，采用统一的 API 方式，允许将测试数据备份文件上传到云端存储。
## 版本更新说明
### ⚠️ 重大变更（2025-12-17）
本次更新将 OSS 上传方式从 **`oss2` 库** 改为 **统一 API 方式**，实现与团队其他系统的统一。
**主要变化**：
- ✅ 用 `requests` 库
- ✅ 通过统一 API 获取预签名 URL 进行上传
- ✅ 简化环境变量配置（仅需要 JWT Token）
- ✅ 返回文件访问 URL
## 主要改动
### 1. OSS 上传工具函数重构（第30-200行）
#### 新增函数
- **`get_upload_token(base_url, auth_token, scene, filename)`**
从统一 API 获取文件上传的预签名 URL
- **`upload_file_with_presigned_url(upload_info, file_path)`**
使用预签名 URL 上传文件到 OSS
#### 更新的函数
- **`upload_file_to_oss(local_file_path, oss_object_name)`**
上传单个文件到阿里云 OSS（使用统一 API 方式）
- 返回值变更：成功时返回文件访问 URL，失败时返回 `False`
- **`upload_files_to_oss(file_paths, oss_prefix)`**
批量上传文件列表
- `oss_prefix` 参数保留但暂不使用（接口兼容性）
- **`upload_directory_to_oss(local_dir, oss_prefix)`**
上传整个目录
- 简化实现，直接使用文件名上传
### 2. 环境变量配置简化
#### 新方式（推荐）
```bash
# ✅ 必需
UNI_LAB_AUTH_TOKEN # API Key 格式: "Api xxxxxx"
# ✅ 可选（有默认值）
UNI_LAB_BASE_URL (默认: https://uni-lab.test.bohrium.com)
UNI_LAB_UPLOAD_SCENE (默认: job，其他值会被改成 default)
```
### 3. 初始化方法（保持不变）
`__init__` 方法中的 OSS 相关配置参数：
```python
# OSS 上传配置
self.oss_upload_enabled = False # 默认不启用 OSS 上传
self.oss_prefix = "neware_backup" # OSS 对象路径前缀
self._last_backup_dir = None # 记录最近一次的 backup_dir
```
**默认行为**：OSS 上传功能默认关闭（`oss_upload_enabled=False`），不影响现有系统。
### 4. upload_backup_to_oss 方法（保持不变）
```python
def upload_backup_to_oss(
self,
backup_dir: str = None,
file_pattern: str = "*",
oss_prefix: str = None
) -> dict
```
## 使用说明
### 前置条件
#### 1. 安装依赖
```bash
# requests 库（通常已安装）
pip install requests
```
#### 2. 配置环境变量
根据您使用的终端类型配置环境变量：
##### PowerShell（推荐）
```powershell
# 必需：设置认证 Token（API Key 格式）
$env:UNI_LAB_AUTH_TOKEN = "Api xxxx"
# 可选：自定义服务器地址（默认为 test 环境）
$env:UNI_LAB_BASE_URL = "https://uni-lab.test.bohrium.com"
# 可选：自定义上传场景（默认为 job）
$env:UNI_LAB_UPLOAD_SCENE = "job"
# 验证是否设置成功
echo $env:UNI_LAB_AUTH_TOKEN
```
##### CMD / 命令提示符
```cmd
REM 必需：设置认证 Token（API Key 格式）
set UNI_LAB_AUTH_TOKEN=Api xxxx
REM 可选：自定义配置
set UNI_LAB_BASE_URL=https://uni-lab.test.bohrium.com
set UNI_LAB_UPLOAD_SCENE=job
REM 验证是否设置成功
echo %UNI_LAB_AUTH_TOKEN%
```
##### Linux/Mac
```bash
# 必需：设置认证 Token（API Key 格式）
export UNI_LAB_AUTH_TOKEN="Api xxxx"
# 可选：自定义配置
export UNI_LAB_BASE_URL="https://uni-lab.test.bohrium.com"
export UNI_LAB_UPLOAD_SCENE="job"
# 验证是否设置成功
echo $UNI_LAB_AUTH_TOKEN
```
#### 3. 获取认证 Token
> **重要**：从 Uni-Lab 主页 → 账号安全 中获取 API Key。
**获取步骤**：
1. 登录 Uni-Lab 系统
2. 进入主页 → 账号安全
3. 复制 API Key
Token 格式示例：
```
Api 48ccxx336fba44f39e1e37db93xxxxx
```
> **提示**：
> - 如果 Token 已经包含 `Api ` 前缀，直接使用
> - 如果没有前缀，代码会自动添加 `Api ` 前缀
> - 旧版 `Bearer` JWT Token 格式仍然兼容
#### 4. 持久化配置（可选）
**临时配置**：上述命令设置的环境变量只在当前终端会话中有效。
**持久化方式 1：PowerShell 配置文件**
```powershell
# 编辑 PowerShell 配置文件
notepad $PROFILE
# 在打开的文件中添加：
$env:UNI_LAB_AUTH_TOKEN = "Api 你的API_Key"
```
**持久化方式 2：Windows 系统环境变量**
- 右键"此电脑" → "属性" → "高级系统设置" → "环境变量"
- 添加用户变量或系统变量：
- 变量名：`UNI_LAB_AUTH_TOKEN`
- 变量值：`Api 你的API_Key`
### 使用流程
#### 步骤 1：启用 OSS 上传功能
**推荐方式：在 `device.json` 中配置**
编辑设备配置文件 `unilabos/devices/neware_battery_test_system/device.json`，在 `config` 中添加：
```json
{
"nodes": [
{
"id": "NEWARE_BATTERY_TEST_SYSTEM",
"config": {
"ip": "127.0.0.1",
"port": 502,
"machine_id": 1,
"oss_upload_enabled": true,
"oss_prefix": "neware_backup/2025-12"
}
}
]
}
```
**参数说明**：
- `oss_upload_enabled`: 设置为 `true` 启用 OSS 上传
- `oss_prefix`: OSS 文件路径前缀，建议按日期或项目组织（暂时未使用，保留接口兼容性）
**其他方式：通过初始化参数**
```python
device = NewareBatteryTestSystem(
ip="127.0.0.1",
port=502,
oss_upload_enabled=True, # 启用 OSS 上传
oss_prefix="neware_backup/2025-12" # 可选：自定义路径前缀
)
```
**配置完成后，重启 ROS 节点使配置生效。**
#### 步骤 2：提交测试任务
使用 `submit_from_csv` 提交测试任务：
```python
result = device.submit_from_csv(
csv_path="test_data.csv",
output_dir="D:/neware_output"
)
```
此时会创建以下目录结构：
```
D:/neware_output/
├── xml_dir/ # XML 配置文件
└── backup_dir/ # 测试数据备份（由新威设备生成）
```
#### 步骤 3：等待测试完成
等待新威设备完成测试，备份文件会生成到 `backup_dir` 中。
#### 步骤 4：上传备份文件到 OSS
**方法 A：使用默认设置（推荐）**
```python
# 自动使用最近一次的 backup_dir，上传所有文件
result = device.upload_backup_to_oss()
```
**方法 B：指定备份目录**
```python
# 手动指定备份目录
result = device.upload_backup_to_oss(
backup_dir="D:/neware_output/backup_dir"
)
```
**方法 C：筛选特定文件**
```python
# 仅上传 CSV 文件
result = device.upload_backup_to_oss(
backup_dir="D:/neware_output/backup_dir",
file_pattern="*.csv"
)
# 仅上传特定电池编号的文件
result = device.upload_backup_to_oss(
file_pattern="Battery_A001_*.nda"
)
```
### 返回结果示例
**成功上传所有文件**：
```python
{
"return_info": "全部上传成功: 15/15 个文件",
"success": True,
"uploaded_count": 15,
"total_count": 15,
"failed_files": [],
"uploaded_files": [
{
"filename": "Battery_A001.ndax",
"url": "https://uni-lab-test.oss-cn-zhangjiakou.aliyuncs.com/job/abc123.../Battery_A001.ndax"
},
{
"filename": "Battery_A002.ndax",
"url": "https://uni-lab-test.oss-cn-zhangjiakou.aliyuncs.com/job/abc123.../Battery_A002.ndax"
}
# ... 其他 13 个文件
]
}
```
**部分上传成功**：
```python
{
"return_info": "部分上传成功: 12/15 个文件，失败 3 个",
"success": True,
"uploaded_count": 12,
"total_count": 15,
"failed_files": ["Battery_A003.csv", "Battery_A007.csv", "test.log"],
"uploaded_files": [
{
"filename": "Battery_A001.ndax",
"url": "https://uni-lab-test.oss-cn-zhangjiakou.aliyuncs.com/job/abc123.../Battery_A001.ndax"
},
{
"filename": "Battery_A002.ndax",
"url": "https://uni-lab-test.oss-cn-zhangjiakou.aliyuncs.com/job/abc123.../Battery_A002.ndax"
}
# ... 其他 10 个成功上传的文件
]
}
```
> **说明**：`uploaded_files` 字段包含所有成功上传文件的详细信息：
> - `filename`: 文件名（不含路径）
> - `url`: 文件在 OSS 上的完整访问 URL
## 错误处理
### OSS 上传未启用
如果 `oss_upload_enabled=False`，调用 `upload_backup_to_oss` 会返回：
```python
{
"return_info": "OSS 上传未启用 (oss_upload_enabled=False)，跳过上传。备份目录: ...",
"success": False,
"uploaded_count": 0,
"total_count": 0,
"failed_files": []
}
```
**解决方法**：设置 `device.oss_upload_enabled = True`
### 环境变量未配置
如果缺少 `UNI_LAB_AUTH_TOKEN`，会返回：
```python
{
"return_info": "OSS 环境变量配置错误: 请设置环境变量: UNI_LAB_AUTH_TOKEN",
"success": False,
...
}
```
**解决方法**：按照前置条件配置环境变量
### 备份目录不存在
如果指定的备份目录不存在，会返回：
```python
{
"return_info": "备份目录不存在: D:/neware_output/backup_dir",
"success": False,
...
}
```
**解决方法**：检查目录路径是否正确，或等待测试生成备份文件
### API 认证失败
如果 Token 无效或过期，会返回：
```python
{
"return_info": "获取凭证失败: 认证失败",
"success": False,
...
}
```
**解决方法**：检查 Token 是否正确，或联系开发团队获取新 Token
## 技术细节
### OSS 上传流程（新方式）
```mermaid
flowchart TD
A[开始上传] --> B[验证配置和环境变量]
B --> C[扫描备份目录]
C --> D[筛选符合 pattern 的文件]
D --> E[遍历每个文件]
E --> F[调用 API 获取预签名 URL]
F --> G{获取成功?}
G -->|是| H[使用预签名 URL 上传文件]
G -->|否| I[记录失败]
H --> J{上传成功?}
J -->|是| K[记录成功 + 文件 URL]
J -->|否| I
I --> L{还有文件?}
K --> L
L -->|是| E
L -->|否| M[返回统计结果]
```
### 上传 API 流程
1. **获取预签名 URL**
- 请求：`GET /api/v1/applications/token?scene={scene}&filename={filename}`
- 认证：`Authorization: Bearer {token}`
- 响应：`{code: 0, data: {url: "预签名URL", path: "文件路径"}}`
2. **上传文件**
- 请求：`PUT {预签名URL}`
- 内容：文件二进制数据
- 响应：HTTP 200 表示成功
3. **生成访问 URL**
- 格式：`https://{OSS_PUBLIC_HOST}/{path}`
- 示例：`https://uni-lab-test.oss-cn-zhangjiakou.aliyuncs.com/job/20251217/battery_data.csv`
### 日志记录
所有上传操作都会通过 ROS 日志系统记录：
- `INFO` 级别：上传进度和成功信息
- `WARNING` 级别：空目录、未启用等警告
- `ERROR` 级别：上传失败、配置错误
## 注意事项
1. **上传时机**：`backup_dir` 中的文件是在新威设备执行测试过程中实时生成的，请确保测试已完成再上传。
2. **文件命名**：上传到 OSS 的文件会保留原始文件名，路径由统一 API 分配。
3. **网络要求**：上传需要稳定的网络连接到阿里云 OSS 服务。
4. **Token 有效期**：JWT Token 有过期时间，过期后需要重新获取。
5. **成本考虑**：OSS 存储和流量会产生费用，请根据需要合理设置文件筛选规则。
6. **并发上传**：当前实现为串行上传，大量文件上传可能需要较长时间。
7. **文件大小限制**：请注意单个文件大小是否有上传限制（由统一 API 控制）。
## 兼容性
- ✅ **向后兼容**：默认 `oss_upload_enabled=False`，不影响现有系统
- ✅ **可选功能**：仅在需要时启用
- ✅ **独立操作**：上传失败不会影响测试任务的提交和执行
- ⚠️ **环境变量变更**：需要更新环境变量配置（从 OSS AK/SK 改为 JWT Token）
## 迁移指南
如果您之前使用 `oss2` 库方式，请按以下步骤迁移：
### 1. 卸载旧依赖（可选）
```bash
pip uninstall oss2
```
### 2. 删除旧环境变量
```powershell
# PowerShell
Remove-Item Env:\OSS_ACCESS_KEY_ID
Remove-Item Env:\OSS_ACCESS_KEY_SECRET
Remove-Item Env:\OSS_BUCKET_NAME
Remove-Item Env:\OSS_ENDPOINT
```
### 3. 设置新环境变量
```powershell
# PowerShell
$env:UNI_LAB_AUTH_TOKEN = "Bearer 你的token..."
```
### 4. 测试上传功能
```python
# 验证上传是否正常工作
result = device.upload_backup_to_oss(backup_dir="测试目录")
print(result)
```
## 常见问题
**Q: 为什么要从 `oss2` 改为统一 API？**
A: 为了与团队其他系统保持一致，简化配置，并统一认证方式。
**Q: Token 在哪里获取？**
A: 请联系开发团队获取有效的 JWT Token。
**Q: Token 过期了怎么办？**
A: 重新获取新的 Token 并更新环境变量 `UNI_LAB_AUTH_TOKEN`。
**Q: 可以自定义上传路径吗？**
A: 当前版本路径由统一 API 自动分配，`oss_prefix` 参数暂不使用（保留接口兼容性）。
**Q: 为什么不在 `submit_from_csv` 中自动上传？**
A: 因为备份文件在测试进行中逐步生成，方法返回时可能文件尚未完全生成，因此提供独立的上传方法更灵活。
**Q: 上传后如何访问文件？**
A: 上传成功后会返回文件访问 URL，格式为 `https://uni-lab-test.oss-cn-zhangjiakou.aliyuncs.com/{path}`
**Q: 如何删除已上传的文件？**
A: 需要通过 OSS 控制台或 API 操作，本功能仅负责上传。
## 验证上传结果
### 方法1：通过阿里云控制台查看
1. 登录 [阿里云 OSS 控制台](https://oss.console.aliyun.com/)
2. 点击左侧 **Bucket列表**
3. 选择 `uni-lab-test` Bucket
4. 点击 **文件管理**
5. 查看上传的文件列表
### 方法2：使用返回的文件 URL
上传成功后，`upload_file_to_oss()` 会返回文件访问 URL：
```python
url = upload_file_to_oss("local_file.csv")
print(f"文件访问 URL: {url}")
# 输出示例：https://uni-lab-test.oss-cn-zhangjiakou.aliyuncs.com/job/20251217/local_file.csv
```
> **注意**：OSS 文件默认为私有访问，直接访问 URL 可能需要签名认证。
### 方法3：使用 ossutil 命令行工具
安装 [ossutil](https://help.aliyun.com/document_detail/120075.html) 后：
```bash
# 列出文件
ossutil ls oss://uni-lab-test/job/
# 下载文件到本地
ossutil cp oss://uni-lab-test/job/20251217/文件名 ./本地路径
# 生成签名URL（有效期1小时）
ossutil sign oss://uni-lab-test/job/20251217/文件名 --timeout 3600
```
## 更新日志
- **2025-12-17**: v2.0（重大更新）
- ⚠️ 从 `oss2` 库改为统一 API 方式
- 简化环境变量配置（仅需 JWT Token）
- 新增 `get_upload_token()` 和 `upload_file_with_presigned_url()` 函数
- `upload_file_to_oss()` 返回值改为文件访问 URL
- 更新文档和迁移指南
- **2025-12-15**: v1.1
- 添加初始化参数 `oss_upload_enabled` 和 `oss_prefix`
- 支持在 `device.json` 中配置 OSS 上传
- 更新使用说明，添加验证方法
- **2025-12-13**: v1.0 初始版本
- 添加 OSS 上传工具函数（基于 `oss2` 库）
- 创建 `upload_backup_to_oss` 动作方法
- 支持文件筛选和自定义 OSS 路径
## 参考资料
- [Uni-Lab 统一文件上传 API 文档](https://uni-lab.test.bohrium.com/api/docs)（如有）
- [阿里云 OSS 控制台](https://oss.console.aliyun.com/)
- [ossutil 工具文档](https://help.aliyun.com/document_detail/120075.html)

574
unilabos/devices/neware_battery_test_system/OSS_UPLOAD_README_EN.md Normal file
View File

@@ -0,0 +1,574 @@
# Neware Battery Test System - OSS Upload Feature
## Overview
This update adds **Aliyun OSS file upload functionality** to the Neware Battery Test System using a unified API approach, allowing test data backup files to be uploaded to cloud storage.
## Version Updates
### ⚠️ Breaking Changes (2025-12-17)
This update changes the OSS upload method from **`oss2` library** to **unified API approach** to align with other team systems.
**Main Changes**:
- ✅ Use `requests` library
- ✅ Upload via presigned URLs obtained through unified API
- ✅ Simplified environment variable configuration (only API Key required)
- ✅ Returns file access URLs
## Main Changes
### 1. OSS Upload Functions Refactored (Lines 30-200)
#### New Functions
- **`get_upload_token(base_url, auth_token, scene, filename)`**
Obtain presigned URL for file upload from unified API
- **`upload_file_with_presigned_url(upload_info, file_path)`**
Upload file to OSS using presigned URL
#### Updated Functions
- **`upload_file_to_oss(local_file_path, oss_object_name)`**
Upload single file to Aliyun OSS (using unified API approach)
- Return value changed: returns file access URL on success, `False` on failure
- **`upload_files_to_oss(file_paths, oss_prefix)`**
Batch upload file list
- `oss_prefix` parameter retained but not used (interface compatibility)
- **`upload_directory_to_oss(local_dir, oss_prefix)`**
Upload entire directory
- Simplified implementation, uploads using filenames directly
### 2. Simplified Environment Variable Configuration
#### Old Method (Deprecated)
```bash
# ❌ No longer used
OSS_ACCESS_KEY_ID
OSS_ACCESS_KEY_SECRET
OSS_BUCKET_NAME
OSS_ENDPOINT
```
#### New Method (Recommended)
```bash
# ✅ Required
UNI_LAB_AUTH_TOKEN # API Key format: "Api xxxxxx"
# ✅ Optional (with defaults)
UNI_LAB_BASE_URL (default: https://uni-lab.test.bohrium.com)
UNI_LAB_UPLOAD_SCENE (default: job, other values will be changed to default)
```
### 3. Initialization Method (Unchanged)
OSS-related configuration parameters in `__init__` method:
```python
# OSS upload configuration
self.oss_upload_enabled = False # OSS upload disabled by default
self.oss_prefix = "neware_backup" # OSS object path prefix
self._last_backup_dir = None # Record last backup_dir
```
**Default Behavior**: OSS upload is disabled by default (`oss_upload_enabled=False`), does not affect existing systems.
### 4. upload_backup_to_oss Method (Unchanged)
```python
def upload_backup_to_oss(
self,
backup_dir: str = None,
file_pattern: str = "*",
oss_prefix: str = None
) -> dict
```
## Usage Guide
### Prerequisites
#### 1. Install Dependencies
```bash
# requests library (usually pre-installed)
pip install requests
```
> **Note**: No longer need to install `oss2` library
#### 2. Configure Environment Variables
Configure environment variables based on your terminal type:
##### PowerShell (Recommended)
```powershell
# Required: Set authentication Token (API Key format)
$env:UNI_LAB_AUTH_TOKEN = "Api xxxx"
# Optional: Custom server URL (defaults to test environment)
$env:UNI_LAB_BASE_URL = "https://uni-lab.test.bohrium.com"
# Optional: Custom upload scene (defaults to job)
$env:UNI_LAB_UPLOAD_SCENE = "job"
# Verify if set successfully
echo $env:UNI_LAB_AUTH_TOKEN
```
##### CMD / Command Prompt
```cmd
REM Required: Set authentication Token (API Key format)
set UNI_LAB_AUTH_TOKEN=Api xxxx
REM Optional: Custom configuration
set UNI_LAB_BASE_URL=https://uni-lab.test.bohrium.com
set UNI_LAB_UPLOAD_SCENE=job
REM Verify if set successfully
echo %UNI_LAB_AUTH_TOKEN%
```
##### Linux/Mac
```bash
# Required: Set authentication Token (API Key format)
export UNI_LAB_AUTH_TOKEN="Api xxxx"
# Optional: Custom configuration
export UNI_LAB_BASE_URL="https://uni-lab.test.bohrium.com"
export UNI_LAB_UPLOAD_SCENE="job"
# Verify if set successfully
echo $UNI_LAB_AUTH_TOKEN
```
#### 3. Obtain Authentication Token
> **Important**: Obtain API Key from Uni-Lab Homepage → Account Security.
**Steps to Obtain**:
1. Login to Uni-Lab system
2. Go to Homepage → Account Security
3. Copy your API Key
Token format example:
```
Api 48ccxx336fba44f39e1e37db93xxxxx
```
> **Tips**:
> - If Token already includes `Api ` prefix, use directly
> - If no prefix, code will automatically add `Api ` prefix
> - Old `Bearer` JWT Token format is still compatible
#### 4. Persistent Configuration (Optional)
**Temporary Configuration**: Environment variables set with the above commands are only valid for the current terminal session.
**Persistence Method 1: PowerShell Profile**
```powershell
# Edit PowerShell profile
notepad $PROFILE
# Add to the opened file:
$env:UNI_LAB_AUTH_TOKEN = "Api your_API_Key"
```
**Persistence Method 2: Windows System Environment Variables**
- Right-click "This PC" → "Properties" → "Advanced system settings" → "Environment Variables"
- Add user or system variable:
- Variable name: `UNI_LAB_AUTH_TOKEN`
- Variable value: `Api your_API_Key`
### Usage Workflow
#### Step 1: Enable OSS Upload Feature
**Recommended: Configure in `device.json`**
Edit device configuration file `unilabos/devices/neware_battery_test_system/device.json`, add to `config`:
```json
{
"nodes": [
{
"id": "NEWARE_BATTERY_TEST_SYSTEM",
"config": {
"ip": "127.0.0.1",
"port": 502,
"machine_id": 1,
"oss_upload_enabled": true,
"oss_prefix": "neware_backup/2025-12"
}
}
]
}
```
**Parameter Description**:
- `oss_upload_enabled`: Set to `true` to enable OSS upload
- `oss_prefix`: OSS file path prefix, recommended to organize by date or project (currently unused, retained for interface compatibility)
**Alternative: Via Initialization Parameters**
```python
device = NewareBatteryTestSystem(
ip="127.0.0.1",
port=502,
oss_upload_enabled=True, # Enable OSS upload
oss_prefix="neware_backup/2025-12" # Optional: custom path prefix
)
```
**After configuration, restart the ROS node for changes to take effect.**
#### Step 2: Submit Test Tasks
Use `submit_from_csv` to submit test tasks:
```python
result = device.submit_from_csv(
csv_path="test_data.csv",
output_dir="D:/neware_output"
)
```
This creates the following directory structure:
```
D:/neware_output/
├── xml_dir/ # XML configuration files
└── backup_dir/ # Test data backup (generated by Neware device)
```
#### Step 3: Wait for Test Completion
Wait for the Neware device to complete testing. Backup files will be generated in the `backup_dir`.
#### Step 4: Upload Backup Files to OSS
**Method A: Use Default Settings (Recommended)**
```python
# Automatically uses the last backup_dir, uploads all files
result = device.upload_backup_to_oss()
```
**Method B: Specify Backup Directory**
```python
# Manually specify backup directory
result = device.upload_backup_to_oss(
backup_dir="D:/neware_output/backup_dir"
)
```
**Method C: Filter Specific Files**
```python
# Upload only CSV files
result = device.upload_backup_to_oss(
backup_dir="D:/neware_output/backup_dir",
file_pattern="*.csv"
)
# Upload files for specific battery IDs
result = device.upload_backup_to_oss(
file_pattern="Battery_A001_*.nda"
)
```
### Return Result Examples
**All Files Uploaded Successfully**:
```python
{
"return_info": "All uploads successful: 15/15 files",
"success": True,
"uploaded_count": 15,
"total_count": 15,
"failed_files": [],
"uploaded_files": [
{
"filename": "Battery_A001.ndax",
"url": "https://uni-lab-test.oss-cn-zhangjiakou.aliyuncs.com/job/abc123.../Battery_A001.ndax"
},
{
"filename": "Battery_A002.ndax",
"url": "https://uni-lab-test.oss-cn-zhangjiakou.aliyuncs.com/job/abc123.../Battery_A002.ndax"
}
# ... other 13 files
]
}
```
**Partial Upload Success**:
```python
{
"return_info": "Partial upload success: 12/15 files, 3 failed",
"success": True,
"uploaded_count": 12,
"total_count": 15,
"failed_files": ["Battery_A003.csv", "Battery_A007.csv", "test.log"],
"uploaded_files": [
{
"filename": "Battery_A001.ndax",
"url": "https://uni-lab-test.oss-cn-zhangjiakou.aliyuncs.com/job/abc123.../Battery_A001.ndax"
},
{
"filename": "Battery_A002.ndax",
"url": "https://uni-lab-test.oss-cn-zhangjiakou.aliyuncs.com/job/abc123.../Battery_A002.ndax"
}
# ... other 10 successfully uploaded files
]
}
```
> **Note**: The `uploaded_files` field contains detailed information for all successfully uploaded files:
> - `filename`: Filename (without path)
> - `url`: Complete OSS access URL for the file
## Error Handling
### OSS Upload Not Enabled
If `oss_upload_enabled=False`, calling `upload_backup_to_oss` returns:
```python
{
"return_info": "OSS upload not enabled (oss_upload_enabled=False), skipping upload. Backup directory: ...",
"success": False,
"uploaded_count": 0,
"total_count": 0,
"failed_files": []
}
```
**Solution**: Set `device.oss_upload_enabled = True`
### Environment Variables Not Configured
If `UNI_LAB_AUTH_TOKEN` is missing, returns:
```python
{
"return_info": "OSS environment variable configuration error: Please set environment variable: UNI_LAB_AUTH_TOKEN",
"success": False,
...
}
```
**Solution**: Configure environment variables as per prerequisites
### Backup Directory Does Not Exist
If specified backup directory doesn't exist, returns:
```python
{
"return_info": "Backup directory does not exist: D:/neware_output/backup_dir",
"success": False,
...
}
```
**Solution**: Check if directory path is correct, or wait for test to generate backup files
### API Authentication Failed
If Token is invalid or expired, returns:
```python
{
"return_info": "Failed to get credentials: Authentication failed",
"success": False,
...
}
```
**Solution**: Check if Token is correct, or contact development team for new Token
## Technical Details
### OSS Upload Process (New Method)
```mermaid
flowchart TD
A[Start Upload] --> B[Verify Configuration and Environment Variables]
B --> C[Scan Backup Directory]
C --> D[Filter Files Matching Pattern]
D --> E[Iterate Each File]
E --> F[Call API to Get Presigned URL]
F --> G{Success?}
G -->|Yes| H[Upload File Using Presigned URL]
G -->|No| I[Record Failure]
H --> J{Upload Success?}
J -->|Yes| K[Record Success + File URL]
J -->|No| I
I --> L{More Files?}
K --> L
L -->|Yes| E
L -->|No| M[Return Statistics]
```
### Upload API Flow
1. **Get Presigned URL**
- Request: `GET /api/v1/lab/storage/token?scene={scene}&filename={filename}&path={path}`
- Authentication: `Authorization: Api {api_key}` or `Authorization: Bearer {token}`
- Response: `{code: 0, data: {url: "presigned_url", path: "file_path"}}`
2. **Upload File**
- Request: `PUT {presigned_url}`
- Content: File binary data
- Response: HTTP 200 indicates success
3. **Generate Access URL**
- Format: `https://{OSS_PUBLIC_HOST}/{path}`
- Example: `https://uni-lab-test.oss-cn-zhangjiakou.aliyuncs.com/job/20251217/battery_data.csv`
### Logging
All upload operations are logged through ROS logging system:
- `INFO` level: Upload progress and success information
- `WARNING` level: Empty directory, not enabled warnings
- `ERROR` level: Upload failures, configuration errors
## Important Notes
1. **Upload Timing**: Files in `backup_dir` are generated in real-time during test execution. Ensure testing is complete before uploading.
2. **File Naming**: Files uploaded to OSS retain original filenames. Paths are assigned by unified API.
3. **Network Requirements**: Upload requires stable network connection to Aliyun OSS service.
4. **Token Expiration**: JWT Tokens have expiration time. Need to obtain new token after expiration.
5. **Cost Considerations**: OSS storage and traffic incur costs. Set file filtering rules appropriately.
6. **Concurrent Upload**: Current implementation uses serial upload. Large number of files may take considerable time.
7. **File Size Limits**: Note single file size upload limits (controlled by unified API).
## Compatibility
- ✅ **Backward Compatible**: Default `oss_upload_enabled=False`, does not affect existing systems
- ✅ **Optional Feature**: Enable only when needed
- ✅ **Independent Operation**: Upload failures do not affect test task submission and execution
- ⚠️ **Environment Variable Changes**: Need to update environment variable configuration (from OSS AK/SK to API Key)
## Migration Guide
If you previously used the `oss2` library method, follow these steps to migrate:
### 1. Uninstall Old Dependencies (Optional)
```bash
pip uninstall oss2
```
### 2. Remove Old Environment Variables
```powershell
# PowerShell
Remove-Item Env:\OSS_ACCESS_KEY_ID
Remove-Item Env:\OSS_ACCESS_KEY_SECRET
Remove-Item Env:\OSS_BUCKET_NAME
Remove-Item Env:\OSS_ENDPOINT
```
### 3. Set New Environment Variables
```powershell
# PowerShell
$env:UNI_LAB_AUTH_TOKEN = "Api your_API_Key"
```
### 4. Test Upload Functionality
```python
# Verify upload works correctly
result = device.upload_backup_to_oss(backup_dir="test_directory")
print(result)
```
## FAQ
**Q: Why change from `oss2` to unified API?**
A: To maintain consistency with other team systems, simplify configuration, and unify authentication methods.
**Q: Where to get the Token?**
A: Obtain API Key from Uni-Lab Homepage → Account Security.
**Q: What if Token expires?**
A: Obtain a new API Key and update the `UNI_LAB_AUTH_TOKEN` environment variable.
**Q: Can I customize upload paths?**
A: Current version has paths automatically assigned by unified API. `oss_prefix` parameter is currently unused (retained for interface compatibility).
**Q: Why not auto-upload in `submit_from_csv`?**
A: Because backup files are generated progressively during testing, they may not be fully generated when the method returns. A separate upload method provides more flexibility.
**Q: How to access files after upload?**
A: Upload success returns file access URL in format `https://uni-lab-test.oss-cn-zhangjiakou.aliyuncs.com/{path}`
**Q: How to delete uploaded files?**
A: Need to operate through OSS console or API. This feature only handles uploads.
## Verifying Upload Results
### Method 1: Via Aliyun Console
1. Login to [Aliyun OSS Console](https://oss.console.aliyun.com/)
2. Click **Bucket List** on the left
3. Select the `uni-lab-test` Bucket
4. Click **File Management**
5. View uploaded file list
### Method 2: Using Returned File URL
After successful upload, `upload_file_to_oss()` returns file access URL:
```python
url = upload_file_to_oss("local_file.csv")
print(f"File access URL: {url}")
# Example output: https://uni-lab-test.oss-cn-zhangjiakou.aliyuncs.com/job/20251217/local_file.csv
```
> **Note**: OSS files are private by default, direct URL access may require signature authentication.
### Method 3: Using ossutil CLI Tool
After installing [ossutil](https://help.aliyun.com/document_detail/120075.html):
```bash
# List files
ossutil ls oss://uni-lab-test/job/
# Download file to local
ossutil cp oss://uni-lab-test/job/20251217/filename ./local_path
# Generate signed URL (valid for 1 hour)
ossutil sign oss://uni-lab-test/job/20251217/filename --timeout 3600
```
## Changelog
- **2025-12-17**: v2.0 (Major Update)
- ⚠️ Changed from `oss2` library to unified API approach
- Simplified environment variable configuration (only API Key required)
- Added `get_upload_token()` and `upload_file_with_presigned_url()` functions
- `upload_file_to_oss()` return value changed to file access URL
- Updated documentation and migration guide
- Token format: Support both `Api Key` and `Bearer JWT`
- API endpoint: `/api/v1/lab/storage/token`
- Scene parameter: Fixed to `job` (other values changed to `default`)
- **2025-12-15**: v1.1
- Added initialization parameters `oss_upload_enabled` and `oss_prefix`
- Support OSS upload configuration in `device.json`
- Updated usage guide, added verification methods
- **2025-12-13**: v1.0 Initial Version
- Added OSS upload utility functions (based on `oss2` library)
- Created `upload_backup_to_oss` action method
- Support file filtering and custom OSS paths
## References
- [Uni-Lab Unified File Upload API Documentation](https://uni-lab.test.bohrium.com/api/docs) (if available)
- [Aliyun OSS Console](https://oss.console.aliyun.com/)
- [ossutil Tool Documentation](https://help.aliyun.com/document_detail/120075.html)

35
unilabos/devices/neware_battery_test_system/device.json Normal file
View File

@@ -0,0 +1,35 @@
{
"nodes": [
{
"id": "NEWARE_BATTERY_TEST_SYSTEM",
"name": "Neware Battery Test System",
"parent": null,
"type": "device",
"class": "neware_battery_test_system",
"position": {
"x": 620.0,
"y": 200.0,
"z": 0
},
"config": {
"ip": "127.0.0.1",
"port": 502,
"machine_id": 1,
"devtype": "27",
"timeout": 20,
"size_x": 500.0,
"size_y": 500.0,
"size_z": 2000.0,
"oss_upload_enabled": true,
"oss_prefix": "neware_backup/2025-12"
},
"data": {
"功能说明": "新威电池测试系统，提供720通道监控和CSV批量提交功能",
"监控功能": "支持720个通道的实时状态监控、2盘电池物料管理、状态导出等",
"提交功能": "通过submit_from_csv action从CSV文件批量提交测试任务。CSV必须包含: Battery_Code, Pole_Weight, 集流体质量, 活性物质含量, 克容量mah/g, 电池体系, 设备号, 排号, 通道号"
},
"children": []
}
],
"links": []
}

1838
unilabos/devices/neware_battery_test_system/neware_battery_test_system.py Normal file
View File

File diff suppressed because it is too large Load Diff

258
unilabos/registry/devices/neware_battery_test_system.yaml
View File

@@ -1,73 +1,40 @@
neware_battery_test_system:
category:
- neware_battery_test_system
- neware
- battery_test
class:
action_value_mappings:
auto-post_init:
debug_resource_names:
feedback: {}
goal: {}
goal_default:
ros_node: null
goal_default: {}
handles: {}
placeholder_keys: {}
result: {}
result:
return_info: return_info
success: success
schema:
description: ''
description: 调试方法：显示所有资源的实际名称
properties:
feedback: {}
goal:
properties: {}
required: []
type: object
result:
properties:
ros_node:
return_info:
description: 资源调试信息
type: string
success:
description: 是否成功
type: boolean
required:
- ros_node
- return_info
- success
type: object
result: {}
required:
- goal
title: post_init参数
type: object
type: UniLabJsonCommand
auto-print_status_summary:
feedback: {}
goal: {}
goal_default: {}
handles: {}
placeholder_keys: {}
result: {}
schema:
description: ''
properties:
feedback: {}
goal:
properties: {}
required: []
type: object
result: {}
required:
- goal
title: print_status_summary参数
type: object
type: UniLabJsonCommand
auto-test_connection:
feedback: {}
goal: {}
goal_default: {}
handles: {}
placeholder_keys: {}
result: {}
schema:
description: ''
properties:
feedback: {}
goal:
properties: {}
required: []
type: object
result: {}
required:
- goal
title: test_connection参数
type: object
type: UniLabJsonCommand
export_status_json:
@@ -145,29 +112,32 @@ neware_battery_test_system:
goal:
plate_num: plate_num
goal_default:
plate_num: 1
plate_num: null
handles: {}
result:
plate_data: plate_data
return_info: return_info
success: success
schema:
description: 获取指定盘(1或2)的电池状态信息
description: 获取指定盘或所有盘的状态信息
properties:
feedback: {}
goal:
properties:
plate_num:
description: 盘号 (1 或 2)
description: 盘号 (1 或 2)，如果为null则返回所有盘的状态
maximum: 2
minimum: 1
type: integer
required:
- plate_num
required: []
type: object
result:
properties:
plate_data:
description: 盘状态数据（单盘或所有盘）
type: object
return_info:
description: 盘状态信息JSON格式
description: 操作结果信息
type: string
success:
description: 查询是否成功
@@ -175,6 +145,7 @@ neware_battery_test_system:
required:
- return_info
- success
- plate_data
type: object
required:
- goal
@@ -219,7 +190,9 @@ neware_battery_test_system:
goal_default:
string: ''
handles: {}
result: {}
result:
return_info: return_info
success: success
schema:
description: ''
properties:
@@ -252,6 +225,56 @@ neware_battery_test_system:
title: StrSingleInput
type: object
type: StrSingleInput
submit_from_csv:
feedback: {}
goal:
csv_path: string
output_dir: string
goal_default:
csv_path: ''
output_dir: .
handles: {}
result:
return_info: return_info
submitted_count: submitted_count
success: success
schema:
description: 从CSV文件批量提交Neware测试任务
properties:
feedback: {}
goal:
properties:
csv_path:
description: 输入CSV文件的绝对路径
type: string
output_dir:
description: 输出目录（用于存储XML和备份文件），默认当前目录
type: string
required:
- csv_path
type: object
result:
properties:
return_info:
description: 执行结果详细信息
type: string
submitted_count:
description: 成功提交的任务数量
type: integer
success:
description: 是否成功
type: boolean
total_count:
description: CSV文件中的总行数
type: integer
required:
- return_info
- success
type: object
required:
- goal
type: object
type: UniLabJsonCommand
test_connection_action:
feedback: {}
goal: {}
@@ -284,30 +307,135 @@ neware_battery_test_system:
- goal
type: object
type: UniLabJsonCommand
module: unilabos.devices.battery.neware_battery_test_system:NewareBatteryTestSystem
upload_backup_to_oss:
feedback: {}
goal:
backup_dir: backup_dir
file_pattern: file_pattern
oss_prefix: oss_prefix
goal_default:
backup_dir: null
file_pattern: '*'
oss_prefix: null
handles:
output:
- data_key: uploaded_files
data_source: executor
data_type: array
handler_key: uploaded_files
io_type: sink
label: Uploaded Files (with standard flow info)
result:
failed_files: failed_files
return_info: return_info
success: success
total_count: total_count
uploaded_count: uploaded_count
schema:
description: 上传备份文件到阿里云OSS
properties:
feedback: {}
goal:
properties:
backup_dir:
description: 备份目录路径（默认使用最近一次submit_from_csv的backup_dir）
type: string
file_pattern:
default: '*'
description: 文件通配符模式，例如 *.csv 或 Battery_*.nda
type: string
oss_prefix:
description: OSS对象路径前缀（默认使用self.oss_prefix）
type: string
required: []
type: object
result:
properties:
failed_files:
description: 上传失败的文件名列表
items:
type: string
type: array
return_info:
description: 上传操作结果信息
type: string
success:
description: 上传是否成功
type: boolean
total_count:
description: 总文件数
type: integer
uploaded_count:
description: 成功上传的文件数
type: integer
uploaded_files:
description: 成功上传的文件详情列表
items:
properties:
Battery_Code:
description: 电池编码
type: string
Electrolyte_Code:
description: 电解液编码
type: string
filename:
description: 文件名
type: string
url:
description: OSS下载链接
type: string
required:
- filename
- url
- Battery_Code
- Electrolyte_Code
type: object
type: array
required:
- return_info
- success
- uploaded_count
- total_count
- failed_files
- uploaded_files
type: object
required:
- goal
type: object
type: UniLabJsonCommand
module: unilabos.devices.neware_battery_test_system.neware_battery_test_system:NewareBatteryTestSystem
status_types:
channel_status: dict
connection_info: dict
device_summary: dict
plate_status: dict
status: str
total_channels: int
type: python
config_info: []
description: 新威电池测试系统驱动，支持720个通道的电池测试状态监控和数据导出。通过TCP通信实现远程控制，包含完整的物料管理系统，支持2盘电池的状态映射和监控。
description: 新威电池测试系统驱动，提供720个通道的电池测试状态监控、物料管理和CSV批量提交功能。支持TCP通信实现远程控制，包含完整的物料管理系统（2盘电池状态映射），以及从CSV文件批量提交测试任务的能力。
handles: []
icon: ''
init_param_schema:
config:
properties:
devtype:
default: '27'
type: string
ip:
default: 127.0.0.1
type: string
machine_id:
default: 1
type: integer
oss_prefix:
default: neware_backup
description: OSS对象路径前缀
type: string
oss_upload_enabled:
default: false
description: 是否启用OSS上传功能
type: boolean
port:
default: 502
type: integer
size_x:
default: 500.0
@@ -319,6 +447,7 @@ neware_battery_test_system:
default: 2000.0
type: number
timeout:
default: 20
type: integer
required: []
type: object
@@ -330,8 +459,6 @@ neware_battery_test_system:
type: object
device_summary:
type: object
plate_status:
type: object
status:
type: string
total_channels:
@@ -341,7 +468,6 @@ neware_battery_test_system:
- channel_status
- connection_info
- total_channels
- plate_status
- device_summary
type: object
version: 1.0.0