ws50529
423 lines
13 KiB
Markdown
423 lines
13 KiB
Markdown
# Difference Equation Analyzer
|
||
|
||
Difference Equation Analyzer 是用來設計、檢視與驗證離散時間濾波器的工具。它同時支援浮點係數、fixed-point 係數、時域 CSV 驗證，以及透過 Web Serial 將係數寫入 MCU。
|
||
|
||
Backend 使用 FastAPI、NumPy、SciPy 與 Pandas；Frontend 使用 Vue 3、Vite、Tailwind CSS 與 Plotly。
|
||
|
||
## Features
|
||
|
||
- 設計 Lowpass、Highpass、Bandpass、Notch、1P1Z、2P1Z、2P2Z、PID、SOGI 濾波器。
|
||
- 比較 Ideal Float 與 Fixed-Point 的 Bode 頻率響應。
|
||
- 支援多個 cascade stages 的頻率響應與時域模擬，並可個別啟用或 bypass。
|
||
- 手動微調 b/a 係數、a1/a2、δ/r、Q-format 位元數與 fixed-point 整數係數。
|
||
- 上傳 CSV 時域資料，繪製輸入、Ideal Float 輸出與 Mimic Integer 輸出。
|
||
- 匯出包含理想浮點與定點整數模擬輸出的 CSV；cascade workflow 可匯出乾淨的 4 欄 CSV。
|
||
- 使用瀏覽器 Web Serial API 將 fixed-point 係數寫入 MCU。
|
||
- 時域圖表支援 zoom 後以 `start_idx` / `end_idx` 向後端重取可視區間資料，保留 IIR 完整歷史狀態。
|
||
- 支援 Dark Mode 與響應式 UI。
|
||
|
||
## Quick Start
|
||
|
||
```bash
|
||
cd /home/wisetop/diff-eq-analyzer
|
||
python3 -m venv .venv
|
||
.venv/bin/pip install -r requirements.txt
|
||
npm install
|
||
npm run build
|
||
bash certs/generate_cert.sh
|
||
.venv/bin/uvicorn dea_api:app --host 0.0.0.0 --port 8000 --ssl-keyfile certs/key.pem --ssl-certfile certs/cert.pem
|
||
```
|
||
|
||
開啟：
|
||
|
||
```text
|
||
https://192.168.2.58:8000/ui/
|
||
```
|
||
|
||
本專案固定從 FastAPI 提供的 HTTPS UI 使用。不要用 Vite dev server URL 測試 CSV 或 MCU 功能，否則 `/api/...` 可能會回 `Not Found`。
|
||
|
||
自簽憑證會讓瀏覽器顯示安全性警告，第一次開啟時需手動信任或選擇繼續前往。
|
||
|
||
## Project Layout
|
||
|
||
```text
|
||
dea_api.py FastAPI 入口與 HTTP route
|
||
dea/ 後端核心模組
|
||
bode.py 頻率響應計算
|
||
config.py 限制值與伺服器端 serial 設定
|
||
csv_processing.py CSV 快取、驗證、單濾波器/cascade 濾波與匯出
|
||
filter_design.py 濾波器設計
|
||
mcu.py MCU serial port 列表與命令寫入
|
||
schemas.py Pydantic request schema
|
||
security.py LAN 存取限制與安全標頭
|
||
validation.py 係數、頻率與有限值驗證
|
||
src/ Vue 3 前端原始碼
|
||
certs/ HTTPS 自簽憑證與產生腳本
|
||
static/build/ Vite production build 輸出
|
||
tests/ unittest 測試
|
||
dea.service systemd service 範例
|
||
chirp_signal.csv CSV 上傳測試範例
|
||
```
|
||
|
||
## Architecture
|
||
|
||
| Layer | Responsibility |
|
||
| --- | --- |
|
||
| FastAPI | 提供 API、serve `/ui/`、套用 LAN 存取限制與安全標頭 |
|
||
| `dea/` | 濾波器設計、單濾波器/cascade Bode plot、CSV 處理、fixed-point simulation、驗證 |
|
||
| Vue UI | 管理係數、Q-format、CSV workflow、Plotly 圖表與 Web Serial 狀態 |
|
||
| Vite build | 將 `src/` 打包到 `static/build/`，由 FastAPI 在 production 提供 |
|
||
|
||
CSV workflow：
|
||
|
||
1. 前端選擇 CSV。
|
||
2. 前端只讀取檔案前段內容建立欄位與 preview，避免為了 preview 把大型 CSV 全部載入瀏覽器記憶體。
|
||
3. 前端呼叫 `POST /api/csv/upload`，後端將檔案暫存並回傳 `file_id`。
|
||
4. 上傳完成前，filter 按鈕會保持 disabled，避免尚未取得 `file_id` 就送出處理。
|
||
5. 後續 `POST /api/filter` 與 `POST /api/filter/download` 使用 `file_id`，避免反覆傳大檔。
|
||
|
||
CSV 預設暫存在：
|
||
|
||
```text
|
||
/tmp/diff-eq-analyzer-csv/
|
||
```
|
||
|
||
可用環境變數覆寫：
|
||
|
||
```bash
|
||
DEA_TEMP_CSV_DIR=/path/to/csv-cache
|
||
```
|
||
|
||
暫存 CSV 預設保留 24 小時。可用環境變數調整，設為 `0` 可停用清理：
|
||
|
||
```bash
|
||
DEA_TEMP_CSV_TTL_SECONDS=86400
|
||
```
|
||
|
||
## Usage
|
||
|
||
### Filter Design
|
||
|
||
在左側控制面板選擇濾波器類型並調整參數。系統會更新 b/a 係數，並繪製 Ideal Float 與 Fixed-Point 的頻率響應。
|
||
|
||
支援濾波器：
|
||
|
||
```text
|
||
Lowpass, Highpass, Bandpass, Notch,
|
||
1P1Z, 2P1Z, 2P2Z,
|
||
PID, SOGI-Alpha, SOGI-Beta
|
||
```
|
||
|
||
### a1/a2 Fine Tuning
|
||
|
||
針對二階濾波器，UI 支援 δ/r 參數化微調。
|
||
|
||
| Mode | Formula |
|
||
| --- | --- |
|
||
| Float | `a1 = -1 - r`, `a2 = r + δ` |
|
||
| Fixed | `a1 = -a0 - r`, `a2 = r + δ` |
|
||
|
||
反推關係：
|
||
|
||
| Mode | δ | r |
|
||
| --- | --- | --- |
|
||
| Float | `a1 + a2 + 1` | `-1 - a1` |
|
||
| Fixed | `a1 + a2 + a0` | `-a0 - a1` |
|
||
|
||
桌機可用 Shift + 滑鼠滾輪微調；觸控裝置可按住數值面板上下拖曳。
|
||
|
||
|
||
### Cascade Stages
|
||
|
||
UI 以 cascade stage accordion 管理多段濾波器。每個 stage 顯示序號、濾波器型態、Active/Bypass 狀態、係數摘要與 Q-format 摘要；可用上移/下移調整串接順序。
|
||
|
||
完整的濾波器設計、浮點係數、fixed-point 係數與 MCU 寫值控制只會出現在目前選取的 active stage accordion 內。同時間只有一個 active stage 承載完整 editor，避免多份表單同時修改同一組全域 active-stage state。展開非 active stage 時，UI 會先切換該 stage 為 active stage。
|
||
|
||
送出 Bode 或 CSV 時，前端會先同步目前 active stage，再把所有 stages 依畫面順序打包送到後端。單一 stage 時仍等同 legacy 單濾波器 workflow。
|
||
|
||
後端相容兩種路徑：
|
||
|
||
| Mode | API Behavior |
|
||
| --- | --- |
|
||
| Legacy single filter | `/api/bode`、`/api/bode/compare`、`/api/filter` 仍接受原本的 `b/a/b_int/a_int` 參數 |
|
||
| Cascade | `/api/bode/compare_cascade` 接受 stages；`/api/filter` 與 `/api/filter/download` 可接受 `stages` form payload |
|
||
|
||
Cascade 設計刻意不直接 merge `origin/cascadedfilters` 的整包檔案，而是在 `main` 上重作功能，避免帶入大型 CSV、暫存檔、log、舊文件與 build noise。
|
||
|
||
### Fixed-Point Time Simulation
|
||
|
||
時域分析同時計算兩條路徑：
|
||
|
||
| Path | Description |
|
||
| --- | --- |
|
||
| Ideal Float | 使用 SciPy `signal.lfilter()` 作為理想浮點參考 |
|
||
| Mimic Integer | 將輸入與係數量化為整數，模擬 MCU / DSP fixed-point 差分方程 |
|
||
|
||
Q-format 參數：
|
||
|
||
| Parameter | Meaning |
|
||
| --- | --- |
|
||
| `shift_in` | 輸入訊號量化位元數 |
|
||
| `shift_out` | 輸出訊號量化位元數 |
|
||
| `shift_b` | 前饋 b 係數量化位元數 |
|
||
| `shift_a` | 回授 a 係數量化位元數 |
|
||
| `use_round` | 右移時使用 Floor (SRA) 或 Round (+0.5) |
|
||
|
||
整數模擬採高精度狀態變數架構：前饋項保留在 `Q_in+b` 精度，回授項除以 `A0` 對齊，再於最終輸出依 `Q_out` 縮放。
|
||
|
||
|
||
### Time-Domain LOD Zoom
|
||
|
||
時域圖表使用 Plotly zoom / pan 時，前端會把目前可視時間範圍換算成 sample index，透過 `/api/filter` 傳送 `start_idx` 與 `end_idx`。後端仍先用完整訊號計算 IIR 輸出，保留濾波器歷史狀態正確性，再只切出可視區間並 downsample 回傳，避免 zoom in 後只能看到粗略的全域降採樣資料。
|
||
|
||
時間軸單位會在首次完整載入時鎖定為 `s`、`ms` 或 `μs`，避免 zoom 後重新換單位造成 Plotly `uirevision` 座標錯位。前端也使用 `isRedrawingTimePlot` 避免 `Plotly.react()` 觸發 relayout callback 造成重繪迴圈。
|
||
|
||
### CSV Workflow
|
||
|
||
限制與行為：
|
||
|
||
| Item | Value |
|
||
| --- | --- |
|
||
| 檔案大小上限 | 300 MB |
|
||
| 時域運算列數上限 | 1,200,000 rows |
|
||
| 圖表點數上限 | 5000 points |
|
||
| 格式要求 | 必須有標題列與至少一筆資料 |
|
||
|
||
若第一欄像 `time`、`t`、`sec`、`x`、`index`，前端會預設選第二欄作為訊號欄位。
|
||
|
||
首頁會自動嘗試載入 `.scratch/examples/preset_signals.csv` 作為 preset waveform；若檔案不存在，UI 仍可正常手動上傳 CSV。preset 路徑可用環境變數覆寫：
|
||
|
||
```bash
|
||
DEA_PRESET_CSV_PATH=/path/to/preset_signals.csv
|
||
```
|
||
|
||
範例 CSV 不再放在 Git 追蹤路徑。大型範例請放在本機 ignored 目錄：
|
||
|
||
```text
|
||
.scratch/examples/
|
||
```
|
||
|
||
常用範例欄位格式：
|
||
|
||
```text
|
||
time,value
|
||
```
|
||
|
||
可從歷史 commit 匯出範例到本機 ignored 路徑使用：
|
||
|
||
```bash
|
||
mkdir -p .scratch/examples
|
||
git show 075f20d:chirp_signal.csv > .scratch/examples/chirp_signal.csv
|
||
git show 0140b049:chirp_signal_small_s.csv > .scratch/examples/chirp_signal_small_s.csv
|
||
git show 0140b049:step_signal.csv > .scratch/examples/step_signal.csv
|
||
git show 8caa8918:static/preset_signals.csv > .scratch/examples/preset_signals.csv
|
||
```
|
||
|
||
`.scratch/` 已被 `.gitignore` 忽略，適合放大型 CSV、手動測試資料與暫存分析檔。
|
||
|
||
|
||
### CSV Export
|
||
|
||
`/api/filter/download` 預設保留 legacy 行為：輸出原始 CSV 欄位，並新增 `[欄位]_filtered_ideal` 與 `[欄位]_filtered_fixed`。
|
||
|
||
若前端傳送 `compact=true`，後端會輸出專供分析用的 4 欄 CSV：
|
||
|
||
| Column | Meaning |
|
||
| --- | --- |
|
||
| `Time (s)` | 由 sample index 與前端傳入的 `fs` 計算 |
|
||
| 原輸入欄位 | 選定訊號欄位原始值 |
|
||
| `[欄位]_filtered_ideal` | Ideal Float 輸出 |
|
||
| `[欄位]_filtered_fixed` | Mimic Integer / fixed-point 輸出 |
|
||
|
||
### MCU Web Serial
|
||
|
||
Web Serial 是主要 MCU 寫入方式，伺服器不需要 serial 權限。
|
||
|
||
| Action | Description |
|
||
| --- | --- |
|
||
| 連線 | 點擊「選擇連接埠並連線」，在瀏覽器彈窗選擇 MCU |
|
||
| 寫值 | 點擊「寫值到 MCU」 |
|
||
| 限制 | Chrome / Edge，且必須透過 HTTPS 或 localhost |
|
||
|
||
寫入命令格式：
|
||
|
||
```text
|
||
bodeplot=b0,b1,b2,a1,a2
|
||
```
|
||
|
||
## API
|
||
|
||
| Method | Endpoint | Purpose |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/design` | 依濾波器參數產生 b/a 係數 |
|
||
| `POST` | `/api/bode` | 計算單組 b/a 頻率響應 |
|
||
| `POST` | `/api/bode/compare` | 比較單一濾波器 Ideal Float 與 Fixed-Point 頻率響應 |
|
||
| `POST` | `/api/bode/compare_cascade` | 比較 cascade stages 的 Ideal Float 與 Fixed-Point 頻率響應 |
|
||
| `GET` | `/api/csv/preset` | 讀取本機 ignored preset CSV metadata，供首頁自動載入 |
|
||
| `POST` | `/api/csv/upload` | 上傳 CSV 並回傳 `file_id` |
|
||
| `POST` | `/api/filter` | 使用 `file_id` 回傳單濾波器或 cascade 時域圖表資料；可傳 `start_idx/end_idx` 做 LOD zoom |
|
||
| `POST` | `/api/filter/download` | 使用 `file_id` 匯出結果 CSV；可傳 `compact=true` 匯出 4 欄 CSV |
|
||
| `GET` | `/api/mcu/ports` | 列出伺服器端 serial ports |
|
||
| `POST` | `/api/mcu/write` | 後端模式寫入 MCU 命令 |
|
||
|
||
## Development
|
||
|
||
### Frontend
|
||
|
||
```bash
|
||
npm install
|
||
npm run test:frontend
|
||
npm run build
|
||
```
|
||
|
||
開發模式：
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
CSV 與 API 流程保留 `dev-v2` 的兩段式設計：先 upload 取得 `file_id`，再用 `file_id` filter 或 download。`vite.config.js` 仍保留 `main` 的 HTTPS deployment 設定，不在 Vite 內設定 `/api` proxy。因此 `npm run dev` 只適合檢查前端畫面；CSV upload、filter API、MCU API 請固定使用：
|
||
|
||
```text
|
||
https://192.168.2.58:8000/ui/
|
||
```
|
||
|
||
### Backend
|
||
|
||
```bash
|
||
.venv/bin/pip install -r requirements.txt
|
||
.venv/bin/uvicorn dea_api:app --host 0.0.0.0 --port 8000 --ssl-keyfile certs/key.pem --ssl-certfile certs/cert.pem
|
||
```
|
||
|
||
### HTTPS Certificate
|
||
|
||
```bash
|
||
bash certs/generate_cert.sh
|
||
```
|
||
|
||
會在 `certs/` 產生：
|
||
|
||
```text
|
||
cert.pem
|
||
key.pem
|
||
```
|
||
|
||
### systemd
|
||
|
||
```bash
|
||
sudo cp dea.service /etc/systemd/system/
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable dea.service
|
||
sudo systemctl start dea.service
|
||
```
|
||
|
||
查看狀態：
|
||
|
||
```bash
|
||
sudo systemctl status dea.service
|
||
sudo journalctl -u dea.service -f
|
||
```
|
||
|
||
### Backend Serial Fallback
|
||
|
||
若無法使用 Web Serial，可改用後端 serial API。環境變數：
|
||
|
||
```bash
|
||
MCU_SERIAL_PORT=/dev/ttyUSB2
|
||
MCU_BAUD_RATE=115200
|
||
MCU_WRITE_TIMEOUT=1.0
|
||
```
|
||
|
||
systemd 可在 `[Service]` 加入：
|
||
|
||
```ini
|
||
Environment="MCU_SERIAL_PORT=/dev/ttyUSB2"
|
||
Environment="MCU_BAUD_RATE=115200"
|
||
Environment="MCU_WRITE_TIMEOUT=1.0"
|
||
```
|
||
|
||
## Testing
|
||
|
||
Python syntax check：
|
||
|
||
```bash
|
||
.venv/bin/python -m py_compile dea_api.py tests/test_dea_api.py
|
||
```
|
||
|
||
Backend tests 使用 Python 內建 `unittest`：
|
||
|
||
```bash
|
||
.venv/bin/python -m unittest discover -s tests
|
||
```
|
||
|
||
Frontend build check：
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
建議完整驗證：
|
||
|
||
```bash
|
||
.venv/bin/pip install -r requirements.txt
|
||
.venv/bin/python -m unittest discover -s tests
|
||
npm run build
|
||
sudo systemctl restart dea.service
|
||
```
|
||
|
||
## Security And Limits
|
||
|
||
| Item | Value |
|
||
| --- | --- |
|
||
| Network access | 只允許 private / loopback IP |
|
||
| CSV size | 300 MB |
|
||
| Time-domain rows | 1,200,000 rows |
|
||
| Plot points | 5000 points |
|
||
| Coefficients | 最多 64 個 |
|
||
|
||
HTTP responses 會加上 CSP、`Referrer-Policy`、`X-Content-Type-Options: nosniff`、`X-Frame-Options: DENY`。
|
||
|
||
## Troubleshooting
|
||
|
||
### CSV 上傳顯示 `Not Found`
|
||
|
||
請確認目前網址是：
|
||
|
||
```text
|
||
https://192.168.2.58:8000/ui/
|
||
```
|
||
|
||
如果從 `http://localhost:5173` 或其他 Vite dev server URL 開啟，`/api/csv/upload` 會送到前端 dev server，而不是 FastAPI，因此會回 `Not Found`。
|
||
|
||
### 無法連線 MCU
|
||
|
||
1. 確認使用 `https://192.168.2.58:8000/ui/`。
|
||
2. 確認瀏覽器支援 Web Serial API。
|
||
3. 使用 Chrome 或 Edge。
|
||
4. 檢查 USB 線與 MCU 裝置狀態。
|
||
|
||
### 頁面沒有更新
|
||
|
||
1. 執行 `npm run build`。
|
||
2. 重啟服務：`sudo systemctl restart dea.service`。
|
||
3. 瀏覽器按 `Ctrl+F5` 強制重新整理。
|
||
|
||
### systemd 顯示 `status=203/EXEC`
|
||
|
||
通常是 `.venv` 或 `uvicorn` 路徑不正確。可重建 venv：
|
||
|
||
```bash
|
||
rm -rf .venv
|
||
python3 -m venv .venv
|
||
.venv/bin/pip install -r requirements.txt
|
||
sudo systemctl restart dea.service
|
||
```
|
||
|
||
### 找不到 pytest
|
||
|
||
本專案不使用 pytest。請改用：
|
||
|
||
```bash
|
||
.venv/bin/python -m unittest discover -s tests
|
||
```
|