# CAN_TimeStamp_Tool

**Repository Path**: tom-embedded/can_-time-stamp_-tool

## Basic Information

- **Project Name**: CAN_TimeStamp_Tool
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-19
- **Last Updated**: 2026-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CAN 报文时间戳分析工具

## 简介

CAN 报文时间戳分析工具用于离线分析 CAN 日志文件中指定 ID 报文的周期性，检测时间戳间隔异常（如周期偏差、重复帧、突发异常等），并生成可视化分析报告（包含 HTML 报告和图表）。

## 支持格式

- BLF (.blf) - Vector Binary Logging Format
- ASC (.asc) - Vector ASCII Logging Format
- TRC (.trc) - PEAK TRC Format

## 依赖安装

```bash
pip install python-can matplotlib numpy jinja2
```

## GUI 模式

直接运行程序（不带任何参数）即可启动图形界面：

```bash
python can_timestamp_analyzer.py
```

或双击打包后的 `CAN_TimeStamp_Analyzer.exe` 可执行文件。

## CLI 使用说明

### 基本用法

```bash
python can_timestamp_analyzer.py --file <日志文件> --id <CAN_ID> --period <周期> --threshold <阈值>
```

### 完整参数列表

| 参数 | 简写 | 类型 | 默认值 | 必需 | 说明 |
|------|------|------|--------|------|------|
| `--file` | `-f` | str | - | 是 | 日志文件路径 (支持 .blf, .asc, .trc 格式) |
| `--id` | `-i` | str | - | 否* | CAN ID (十六进制，如 0x123) |
| `--period` | `-p` | float | - | 否* | 期望周期 (ms) |
| `--threshold` | `-t` | float | - | 否* | 超限阈值 (ms) |
| `--config` | `-c` | str | - | 否* | JSON 配置文件路径 (与 --id/--period/--threshold 互斥) |
| `--output` | `-o` | str | 日志文件同目录 | 否 | 输出报告目录 |
| `--deviation-pct` | - | float | 50 | 否 | 周期偏差百分比阈值 |
| `--duplicate-threshold` | - | float | period×0.1 | 否 | 重复帧判定阈值 (ms) |
| `--burst-window` | - | int | 5 | 否 | 突发检测窗口大小 |
| `--burst-count` | - | int | 3 | 否 | 突发检测窗口内最小异常数 |
| `--markers` | `-m` | str | - | 否 | 生成标记文件: full/only/both |
| `--marker-format` | - | str | 与源文件相同 | 否 | 标记文件格式: asc/blf |

> **注意**: `--id`/`--period`/`--threshold` 必须同时提供，或者使用 `--config` 指定配置文件（两者互斥）

### 使用示例

#### 基本分析

分析单个 CAN ID 的周期性：

```bash
python can_timestamp_analyzer.py --file log.blf --id 0x123 --period 2 --threshold 10
```

#### 指定输出目录和高级参数

```bash
python can_timestamp_analyzer.py --file log.blf --id 0x123 --period 2 --threshold 10 --output ./reports --deviation-pct 30
```

#### 使用配置文件批量分析

```bash
python can_timestamp_analyzer.py --file log.blf --config rules.json
```

#### 生成标记文件

`--markers` 参数支持三种模式：

- `full` - 生成完整副本并添加标记（保留原始报文，在异常位置插入标记）
- `only` - 仅生成标记文件（只包含标记报文）
- `both` - 同时生成以上两种文件

```bash
# 生成完整副本+标记
python can_timestamp_analyzer.py --file log.blf --id 0x123 --period 2 --threshold 10 --markers full

# 仅生成标记文件
python can_timestamp_analyzer.py --file log.blf --id 0x123 --period 2 --threshold 10 --markers only

# 同时生成两种文件
python can_timestamp_analyzer.py --file log.blf --id 0x123 --period 2 --threshold 10 --markers both
```

#### 指定标记文件格式

```bash
# 将 BLF 日志的标记文件导出为 ASC 格式
python can_timestamp_analyzer.py --file log.blf --id 0x123 --period 2 --threshold 10 --markers full --marker-format asc
```

### 配置文件格式

配置文件使用 JSON 格式，支持两种写法：

#### 简单格式（兼容旧版）

```json
[
  {"id": "0x123", "period_ms": 2, "threshold_ms": 10},
  {"id": "0x456", "period_ms": 10, "threshold_ms": 50}
]
```

#### 完整格式（包含高级设置）

```json
{
  "rules": [
    {"id": "0x123", "period_ms": 2, "threshold_ms": 10},
    {"id": "0x456", "period_ms": 10, "threshold_ms": 50}
  ],
  "settings": {
    "deviation_pct": 50,
    "duplicate_threshold": null,
    "burst_window": 5,
    "burst_count": 3
  }
}
```

## 打包指令

### 环境准备

```bash
pip install pyinstaller
```

### 打包命令

```bash
python -m PyInstaller can_timestamp_analyzer.spec --noconfirm
```

### 打包说明

- **输出目录**: 打包完成后，可执行文件位于 `dist/CAN_TimeStamp_Analyzer/` 目录下
- **入口文件**: `CAN_TimeStamp_Analyzer.exe`
- **console=False**: 打包配置中设置了 `console=False`，确保双击运行时不会弹出终端窗口（GUI 模式）
- **Hidden Imports**: spec 文件中已配置了 `can`、`matplotlib`、`numpy`、`jinja2`、`tkinter` 等相关模块的 hidden imports

### 注意事项

1. **不要排除 unittest 模块**: `pyparsing` 库依赖 `unittest` 模块，如果在 `excludes` 列表中排除 `unittest`，会导致运行时出现 `ModuleNotFoundError` 错误。spec 文件中已注释掉该排除项。

2. **matplotlib 数据文件**: spec 文件会自动收集 matplotlib 的 mpl-data 目录，确保图表能正常渲染。

3. **打包后体积**: 由于包含了完整的 numpy、matplotlib 等科学计算库，打包后的程序体积较大，这是正常现象。

## 运行测试

```bash
python -m pytest tests/ -v
```