wisetop/tcad-bodeplot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
345b4a789a7b7fd0bc0a490c1c3b1e9ce891114e
tcad-bodeplot/README.md
T

8.3 KiB
Raw Blame History

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 頻率響應。
  • 手動微調 b/a 係數、a1/a2、δ/r、Q-format 位元數與 fixed-point 整數係數。
  • 上傳 CSV 時域資料，繪製輸入、Ideal Float 輸出與 Mimic Integer 輸出。
  • 匯出包含理想浮點與定點整數模擬輸出的 CSV。
  • 使用瀏覽器 Web Serial API 將 fixed-point 係數寫入 MCU。
  • 支援 Dark Mode 與響應式 UI。

Quick Start

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

開啟：

https://localhost:8000/ui/

若從其他主機連線，改用：

https://<server-ip>:8000/ui/

自簽憑證會讓瀏覽器顯示安全性警告，需手動信任或選擇繼續前往。

Project Layout

dea_api.py              FastAPI 入口與 HTTP route
dea/                    後端核心模組
  bode.py               頻率響應計算
  config.py             限制值與伺服器端 serial 設定
  csv_processing.py     CSV 快取、驗證、濾波與匯出
  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/ 濾波器設計、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. 前端呼叫 POST /api/csv/upload，後端將檔案暫存並回傳 file_id。
  3. 後續 POST /api/filter 與 POST /api/filter/download 使用 file_id，避免反覆傳大檔。

CSV 預設暫存在：

/tmp/diff-eq-analyzer-csv/

可用環境變數覆寫：

DEA_TEMP_CSV_DIR=/path/to/csv-cache

Usage

Filter Design

在左側控制面板選擇濾波器類型並調整參數。系統會更新 b/a 係數，並繪製 Ideal Float 與 Fixed-Point 的頻率響應。

支援濾波器：

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 + 滑鼠滾輪微調；觸控裝置可按住數值面板上下拖曳。

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 縮放。

CSV Workflow

限制與行為：

Item Value
檔案大小上限 300 MB
時域運算列數上限 1,200,000 rows
圖表點數上限 5000 points
格式要求 必須有標題列與至少一筆資料

若第一欄像 time、t、sec、x、index，前端會預設選第二欄作為訊號欄位。

範例檔案：

chirp_signal.csv

欄位：

time,value

MCU Web Serial

Web Serial 是主要 MCU 寫入方式，伺服器不需要 serial 權限。

Action Description
連線 點擊「選擇連接埠並連線」，在瀏覽器彈窗選擇 MCU
寫值 點擊「寫值到 MCU」
限制 Chrome / Edge，且必須透過 HTTPS 或 localhost

寫入命令格式：

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/csv/upload 上傳 CSV 並回傳 file_id
POST /api/filter 使用 file_id 回傳時域圖表資料
POST /api/filter/download 使用 file_id 匯出結果 CSV
GET /api/mcu/ports 列出伺服器端 serial ports
POST /api/mcu/write 後端模式寫入 MCU 命令

Development

Frontend

npm install
npm run build

開發模式：

npm run dev

目前 vite.config.js 保留 main 設定，不在 Vite 內設定 /api proxy。

Backend

.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 certs/generate_cert.sh

會在 certs/ 產生：

cert.pem
key.pem

systemd

sudo cp dea.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable dea.service
sudo systemctl start dea.service

查看狀態：

sudo systemctl status dea.service
sudo journalctl -u dea.service -f

Backend Serial Fallback

若無法使用 Web Serial，可改用後端 serial API。環境變數：

MCU_SERIAL_PORT=/dev/ttyUSB2
MCU_BAUD_RATE=115200
MCU_WRITE_TIMEOUT=1.0

systemd 可在 [Service] 加入：

Environment="MCU_SERIAL_PORT=/dev/ttyUSB2"
Environment="MCU_BAUD_RATE=115200"
Environment="MCU_WRITE_TIMEOUT=1.0"

Testing

Python syntax check：

.venv/bin/python -m py_compile dea_api.py tests/test_dea_api.py

Backend tests 使用 Python 內建 unittest：

.venv/bin/python -m unittest discover -s tests

Frontend build check：

npm run build

建議完整驗證：

.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

無法連線 MCU

  1. 確認使用 HTTPS 或 localhost。
  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：

rm -rf .venv
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
sudo systemctl restart dea.service

找不到 pytest

本專案不使用 pytest。請改用：

.venv/bin/python -m unittest discover -s tests
Reference in New Issue View Git Blame Copy Permalink