GrumpyTanker/fluke-3540-analyzer

GitHub: GrumpyTanker/fluke-3540-analyzer

Fluke 3540 FC 三相电能记录仪会话文件的开源解析、事件检测与可视化工具，提供浏览器端 Web 应用和 Python CLI，作为 Fluke Energy Analyze Plus 的跨平台替代方案。

Stars: 0 | Forks: 0

# fluke-3540-analyzer **针对 Fluke 3540 FC 三相电能质量记录仪会话的开源解析器、事件检测器和图表生成器。** 支持 Windows、Linux 和 macOS。在浏览器中运行——无需上传，无需安装。 🌐 **在线 Web 应用：** [grumpytanker.github.io/fluke-3540-analyzer](https://grumpytanker.github.io/fluke-3540-analyzer/) ## 为什么会有这个项目 Fluke 3540 FC 是一款出色的小型三相电能记录仪，但读取其会话文件（包含 `trend.bin` 的 `.fel` 档案）的唯一官方途径是 **Fluke Energy Analyze Plus**——仅限 Windows、闭源，且导出功能有限。它没有 Linux/macOS 客户端，没有用于批量分析的 CLI，也没有跨大量会话编写报告脚本的理想方法。本项目为您提供： - **文档化的二进制格式**，适用于 3540 FC 的 `trend.bin` 文件——参见 [`docs/FILE_FORMAT.md`](docs/FILE_FORMAT.md) - **一个在浏览器中运行的 Web 应用**。拖放一个 `trend.bin`，即可获取图表、选择事件并导出 CSV / XLSX / PNG。不上传任何数据——所有解析均通过 JavaScript 在客户端完成。 - **一个 Python CLI**，用于编写脚本、批量作业以及生成出版级质量的 gnuplot 输出。只需 `pip install -e .` 即可开始。 - **自动事件检测**——停电、电压暂降、电压暂升、电流峰值、频率偏差、NEMA 不平衡尖峰、突发负载阶跃。 - **CT 反接校正**——`--reverse-cts` 标志可处理反向安装的 iFlex 探头（极其常见的错误）。参见 [`docs/CT_REVERSAL.md`](docs/CT_REVERSAL.md)。 - **主动/待机负载状态分离**——对于双峰负载（例如，在重负载主动消耗和轻负载待机之间切换的整流器），系统会根据电流对每条记录进行分类，分别报告这两种状态，突出显示主动状态下的功率因数，并以三种方式校正会话能量。参见 [`docs/LOAD_STATES.md`](docs/LOAD_STATES.md)。 ## Web 应用——无需安装访问 **[grumpytanker.github.io/fluke-3540-analyzer](https://grumpytanker.github.io/fluke-3540-analyzer/)**，并将您的 `trend.bin`（或整个解压后的 `ES.NNN/` 会话文件夹，这样也能读取 `ES.NNN-config.json` 中的资产名称）拖放到页面上。浏览器会在 Web Worker 中本地解析文件，运行事件检测 + 洞察分析，并显示： - 摘要面板（记录数、时间范围、资产） - **Insights (洞察)** 部分，包含带有严重性颜色标记的卡片，解释了发现的问题及相应对策（参见 [`docs/INSIGHTS.md`](docs/INSIGHTS.md)） - 事件表格，包含严重性、受影响相位、搜索/过滤、可排序列以及一键缩放功能 - 平静基线窗口的快照列表 - **range select (区间选择)** 小地图——通过拖拽刷选来限定所有图表范围，并导出到特定时间窗口 - 带有异常带、拖拽框选缩放、滚轮缩放、Shift+拖拽平移功能的图表 - 图表选择器（电压 / 电流 / 功率 / 功率因数 / 频率 / THD） - 单图表下载为 PNG 或 CSV - 完整工作簿 (XLSX)、独立 HTML 报告、**PDF 报告**，以及“下载所有内容 (.zip)”压缩包 - IndexedDB 缓存：再次拖放同一文件 → 第二次将跳过解析步骤 - 键盘快捷键（按 `?` 查看）和页脚处的深色模式切换开关 **数据绝不会离开您的设备。** 您可以在 DevTools → Network 中自行验证：页面加载后没有任何对外请求。Insights 引擎基于本地规则运行——不涉及云端 LLM，也不需要 API key。 ## Python CLI——用于编写脚本及生成出版级图表 ``` # 从 PyPI (v0.2.0+) pip install fluke-3540-analyzer # 或者从源码进行开发 git clone https://github.com/GrumpyTanker/fluke-3540-analyzer cd fluke-3540-analyzer pip install -e "python/[dev]" ``` 您需要安装 [gnuplot](http://www.gnuplot.info/) 才能渲染图表（`apt install gnuplot` / `brew install gnuplot` / `choco install gnuplot`）。CLI 会依次通过 `$GNUPLOT`、`$PATH` 以及 `C:\Program Files\gnuplot\bin\gnuplot.exe` 自动发现它。 ``` # auto: parse + detect + render everything fluke-analyze path/to/ES.NNN -o output/ --reverse-cts # interactive: walk through event picker fluke-analyze path/to/ES.NNN -o output/ --interactive # parse only — write CSV + events.json + summary.txt, no charts fluke-analyze path/to/ES.NNN -o output/ --parse-only # plot only — reuse existing CSV + events.json, just (re-)render charts fluke-analyze path/to/ES.NNN -o output/ --plot-only --plot voltage,current # time-window slice + chart subset fluke-analyze path/to/ES.NNN -o output/ \ --from "2024-01-13T22:50:00" --to "2024-01-13T22:55:00" \ --events 0,3,5 --plot power,current --pre 60 --post 120 ``` ### CLI 标志参考 | 标志 | 默认值 | 说明 | |---|---|---| | `SESSION_DIR` | 必填 | 指向 `ES.NNN/` 会话目录的路径 | | `-o`, `--output` | `_out/` | 输出目录 | | `--auto` | (默认) | 解析 + 检测 + 渲染所有内容 | | `--interactive` | | 提示选择要渲染的事件/物理量 | | `--parse-only` | | 仅写出 CSV + events.json + summary.txt | | `--plot-only` | | 复用现有的 CSV/events.json，仅渲染图表 | | `--from ISO_TIME` | | 将事件扫描和缩放范围限制为 ≥ 此时间 | | `--to ISO_TIME` | | 将事件扫描和缩放范围限制为 ≤ 此时间 | | `--pre SECS` | `30` | 事件前缩放填充时间 | | `--post SECS` | `60` | 事件后缩放填充时间 | | `--events IDS` | all | 要渲染的事件 ID，以逗号分隔 | | `--plot QTYS` | `voltage,current,power,thd,pf,frequency` | 要绘制图表的物理量 | | `--snapshots N` | `3` | 要选取的平静快照数量 | | `--reverse-cts [PHASES]` | off | 对 P/Q/PF/DPF/Wh/VARh 取反。直接使用该标志 = 所有相位；传入 `a` 或 `a,c` 以选择特定相位（总计项随之改变）。参见 `docs/CT_REVERSAL.md` | | `--every K` | `1` | 将每第 K 条记录写入 CSV | | `--max-csv-rows N` | off | 针对长达一周的会话，将完整 CSV 的行数限制在约 N 行；步幅会自动调大并记录降采样操作。1分钟 CSV + 分析保持全分辨率。 | | `--anchor-start ISO_TIME` | off | 固定真实的挂钟**开始时间**，以校正错误的仪表 RTC（平移所有时间戳）。与 `--anchor-end` 互斥。 | | `--anchor-end ISO_TIME` | off | 固定真实的挂钟**结束时间**（例如已知的停机时间）。 | | `--split-by PERIOD` | off | 划分为不同时间档（`hour`\|`day`\|`week`，如 `30m`/`6h`/`2d` 的时间段，或用于命名班次窗口的 `shifts`）。输出完整的按档分类报告（`/`）+ `buckets_summary.csv` 汇总。 | | `--shifts SPEC` | `day=06:00-18:00,night=18:00-06:00` | 与 `--split-by shifts` 配合使用：命名窗口 `name=HH:MM-HH:MM,...`。`end<=start` 表示跨过午夜。在 `--tz` 下进行评估。输出 `shift_comparison.csv`/`.json` 及每次班次的报告。参见 [`docs/SHIFTS.md`](docs/SHIFTS.md)。 | | `--shifts-file FILE` | off | JSON 格式的班次表（`{"shifts":[{"name","start","end"}]}`）；作为 `--shifts` 的替代方案。 | | `--mark "ISO=LABEL"` | | 添加事件标记（可重复使用）；在 `markers.json` 中与最接近的事件进行交叉引用。 | | `--marks FILE.csv` | | 从 CSV（`time,label`）加载标记。 | | `--tod-profile [HH:MM-HH:MM]` | off | 昼夜（每日）曲线——所有日期中每个区间的平均值/最小值/最大值包络线。直接使用该标志 = 24 小时。生成 `time_of_day_profile.csv` + 一个 XLSX 工作表。 | | `--tod-bin MINS` | `1` | 昼夜区间宽度（以分钟为单位）。 | | `--demand-window SECS` | `900` | 滚动峰值需求窗口。报告峰值需求及其出现的窗口（`demand.json` + XLSX）。参见 [`docs/DEMAND.md`](docs/DEMAND.md)。 | | `--tz ZONE` | UTC | 以本地 + UTC 时间为指定的 IANA 时区（例如 `America/Chicago`）渲染报告时间戳。默认仅限 UTC。 | | `--auto-reverse-cts` | off | 自动检测 CT 反接安装并自动应用 `--reverse-cts`，并给出醒目通知。基于主导的**大电流（主动）**状态做出决定——对双峰负载十分稳健。参见 `docs/CT_REVERSAL.md`。 | | `--standby-threshold-a A` | `50` | 当单相平均电流（A）大于或等于此值时，记录为**主动**负载（否则为待机）。驱动主动/待机状态分离（`load_states.csv`/`.json`）、能量校正（三个数值）以及基于幅值加权的 CT 反接判定。参见 [`docs/LOAD_STATES.md`](docs/LOAD_STATES.md)。 | | `--load-states` | auto | 强制生成主动/待机负载状态报告（默认生成；该标志用于显式启用）。 | | `--rules-file FILE` | off | 以资产名称为键的 JSON/TOML `EventRules` 覆盖配置。参见 [`docs/RULES_FILE.md`](docs/RULES_FILE.md)。 | | `--no-stats` | | 跳过整个会话的统计信息（`stats.json`/`stats.csv` + XLSX 工作表）。 | | `--format` | `png` | `png` 或 `svg` | | `--no-xlsx` | | 跳过 XLSX 工作簿 | | `--no-html` | | 跳过独立的 HTML 报告（默认会生成 `report.html`） | | `--pdf` | | 同时写入 `report.pdf`（需要 `pip install fluke-3540-analyzer[pdf]`） | | `--no-overview` | | 跳过 2x2 概览多图 | | `--nominal-ln-v V` | auto | 覆盖标称的 L-N 电压（否则将自动推断） | | `--json` | | 向 stdout 输出单个 JSON 数据块（无图表，无日志）。包含 `insights` 数组。 | ### 输出布局（`--auto`） ``` output/ ├── session.csv # one row per record, ~75K rows for a 20h session ├── session_1min.csv # downsampled to 1 row/min ├── events.json # detected events ├── snapshots.json # quiet baseline windows ├── summary.txt # asset + energy + per-event lines ├── report.xlsx # multi-sheet workbook with native Excel charts └── charts/ ├── overview.png ├── full_.png ├── event___.png └── snapshot__.png ``` `--plot-only` 会复用之前 `--parse-only` 运行产生的 `session.csv`、`session_1min.csv` 和 `events.json`——这在无需重新解析 55 MB 二进制数据的情况下迭代图表样式时非常有用。 ### 多会话比较 ``` fluke-analyze compare SESSION1 SESSION2 [...] -o OUT --labels "before,after" ``` 在同一坐标轴上叠加多个会话中选定的物理量（按相对会话开始时间进行对齐），并输出并排对比的 `compare_summary.csv`。参见 [`docs/COMPARE.md`](docs/COMPARE.md)。 ### 多会话拼接 ``` fluke-analyze stitch ES.001 ES.002 [...] -o OUT ``` 将同一资产的连续采集片段拼接成一条连续、具备间隔感知的时间线（突破记录仪 7 天的记录上限），并在 `stitch.json` 中包含各来源的溯源信息，然后对拼接后的时间序列进行常规分析。参见 [`docs/STITCHING.md`](docs/STITCHING.md)。 ## 电能质量标准与按资产规则 - **IEEE 519 / IEEE 1159 / SARFI**——每次运行都会计算电压 THD 合规性及 SARFI 暂降指标（`pq_standards.json`）。参见 [`docs/PQ_STANDARDS.md`](docs/PQ_STANDARDS.md)。 - **按资产设定的阈值**——通过 `--rules-file` 以 JSON/TOML 格式按资产键名覆盖 `EventRules`。参见 [`docs/RULES_FILE.md`](docs/RULES_FILE.md)。 ## 事件检测自动检测的事件类型（完整规则与说明见 [`docs/EVENT_RULES.md`](docs/EVENT_RULES.md)）： | 类型 | 检测内容 | 默认阈值 | |---|---|---| | `outage` | 所有相位的 L-N 电压崩溃 | 每个相位 < 50 V | | `dip` | 任意相位的电压下降（不包括停电） | < 标称值的 90 % | | `swell` | 任意相位的电压上升 | > 称值的 110 % | | `high_current` | 单相电流峰值 | > 平均值 + 2σ | | `freq_excursion` | 工频偏差 | 偏离 60 Hz > 0.5 Hz | | `imbalance_spike` | NEMA 电压不平衡 | > 2.5 % | | `power_step` | P_total 突然出现 1 秒内的变化 | > 会话平均 \|P\| 的 50 % | 直接使用 API 时，所有阈值均可通过 `EventRules` 数据类进行调整。 ## 文件格式 Fluke 3540 FC 将会话保存为 `.fel` 档案，其中包含： - `trend.bin`——744 字节的记录，每秒一条，包含 180 个 float32 测量值（电压、电流、各相及总的 P/Q/S、基波和 RMS、PF/DPF、Wh/VAh/VARh、谐波、频率、滚动需求量） - `trend-meta.bin`——会话元数据 - `session-meta.bin`——会话 ID、时间戳 - `configuration.bin`——仪器配置快照 - `ES.NNN-config.json`——资产名称、团队、仪器固件标准的记录布局和字段映射位于 [`spec/field_map.json`](spec/field_map.json)——Python 和 JavaScript 解析器均从此处加载，以确保两者保持同步。头部布局、FILETIME 转换以及每个字段的置信度级别均在 [`docs/FILE_FORMAT.md`](docs/FILE_FORMAT.md) 中有详细记录。 ## 隐私 Web 应用利用 Web Worker **完全在您的浏览器中进行解析**。没有后端，没有上传接口，也没有任何遥测或分析。您可以通过打开 DevTools → Network 并确认页面加载后没有对外请求来验证这一点。页面一旦缓存即可完全离线运行——第三方库（uPlot, SheetJS, JSZip, Pico CSS）均从同源提供，不依赖 CDN。 ## 架构 ``` fluke-3540-analyzer/ ├── spec/field_map.json ← canonical binary layout + field map ├── python/src/fluke_3540/ │ ├── parser.py ← loads spec, decodes trend.bin │ ├── events.py ← detection rules │ ├── snapshots.py ← quiet-window picker │ ├── cli.py ← fluke-analyze entry point │ └── plots/ ← gnuplot + openpyxl ├── web/ │ ├── parser.js ← JS port; loads same spec │ ├── events.js, snapshots.js │ ├── plots.js ← uPlot wrappers │ ├── xlsx_export.js ← SheetJS workbook │ ├── bundle_export.js ← JSZip "download everything" │ ├── parser_worker.js ← Web Worker │ ├── app.js / index.html / style.css │ └── vendor/ ← uPlot, SheetJS, JSZip, Pico (vendored) └── .github/workflows/ ├── ci.yml ← pytest + node --test on PR/push └── pages.yml ← deploy web/ to grumpytanker.github.io ``` 一项跨语言对等测试（`web/tests/parity.test.js`）使用两套实现分别解析同一个 `python/tests/fixtures/synthetic_trend.bin` 测试夹具，并断言每个单元格的数据在字节级别完全相等。CI 会在每次 PR 时运行这两套测试套件。 ## 许可证 MIT——参见 [LICENSE](LICENSE)。可在商业或个人项目中自由使用。 ## 关键词 Fluke 3540 FC、Fluke 3540、Fluke energy analyze plus 替代品、Fluke 3540 Linux、Fluke 3540 macOS、三相电能记录仪、电能质量分析仪、.fel 文件格式、trend.bin 解析器、Fluke FC 开源、电能质量监测、电气事件检测、电压暂降检测、电压暂升检测、停电检测、NEMA 不平衡、电流互感器反接、iFlex 探头方向、谐波畸变、THD、kWh 导出、三相负载曲线、工业能源监测、电动汽车充电桩监测。

标签：Python, 数据可视化, 数据解析, 无后门, 电力分析, 逆向工具