tcad-bodeplot/README.md

Difference Equation Analyzer

Difference Equation Analyzer 是一個用來設計、檢視與驗證離散時間濾波器的工具。後端使用 FastAPI、NumPy、SciPy 與 Pandas；前端使用 Vue 3、Vite、Tailwind CSS 與 Plotly。

主要功能：

• 設計 Lowpass、Highpass、Bandpass、Notch、1P1Z、2P1Z、2P2Z、PID、SOGI 濾波器。
• 比較浮點係數與 fixed-point 係數的頻率響應。
• 手動微調 b/a 係數、a1/a2 組合、Q 格式位元數與 fixed-point 整數係數。
• 上傳 CSV 時域資料，套用目前差分方程並繪製輸入/輸出波形。
• 匯出包含濾波輸出欄位的 CSV。
• 透過 USB serial 將 fixed-point 係數命令送到 MCU。

專案結構

dea_api.py              FastAPI 入口與 HTTP route
dea/                    後端核心模組
  bode.py               頻率響應計算
  config.py             限制值與 MCU 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 前端原始碼
static/                 FastAPI 對外提供的靜態 UI
static/build/           Vite build 輸出
tests/                  unittest 測試
dea.service             systemd service 範例
chirp_signal.csv        CSV 上傳測試範例

安裝

在目標主機上建立 Python venv 並安裝依賴：

cd /home/wisetop/diff-eq-analyzer
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

安裝前端依賴：

npm install

建置前端：

npm run build

Vite 會輸出到：

static/build/app.js
static/build/app.css

執行

本機開發可直接啟動 FastAPI：

.venv/bin/uvicorn dea_api:app --host 127.0.0.1 --port 8000

瀏覽器開啟：

http://localhost:8000/ui/

部署在區網主機時可用：

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

根路徑 / 會自動導向 /ui/。

API

目前主要 API：

• POST /api/design：依濾波器參數產生 b/a 係數。
• POST /api/bode：計算單組 b/a 係數的頻率響應。
• POST /api/bode/compare：一次計算浮點與 fixed-point 兩組頻率響應。
• POST /api/filter：上傳 CSV 並回傳圖表用的濾波結果。
• POST /api/filter/download：上傳 CSV 並下載包含 <欄位>_filtered 的結果 CSV。
• GET /api/mcu/ports：列出可用 serial ports。
• POST /api/mcu/write：送出 MCU 命令。

MCU 寫入命令格式固定為：

bodeplot=b0,b1,b2,a1,a2

前端會使用目前 fixed-point 係數自動組出此命令。

CSV 上傳

限制與行為：

• CSV 檔案大小上限為 32 MB。
• CSV 必須有標題列與至少一筆資料。
• 可選擇要濾波的訊號欄位；若第一欄像 time、t、sec、x、index，前端會預設選第二欄。
• 圖表回應最多回傳 5000 點，避免大型 CSV 讓前端過重。
• 下載 CSV 會保留完整資料，不套用圖表降採樣。

專案根目錄的 chirp_signal.csv 是上傳測試範例，約 19 MB、500001 行，欄位為：

time,value

MCU Serial 設定

MCU serial 預設值在 dea/config.py，也可用環境變數覆蓋：

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

若使用 systemd，可在 dea.service 的 [Service] 區塊加入：

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

更新 service 後重新載入：

sudo systemctl daemon-reload
sudo systemctl restart dea.service

注意：MCU 功能需要 pyserial>=3.5，已列在 requirements.txt。

systemd

查看服務狀態：

sudo systemctl status dea.service

啟動、停止、重啟：

sudo systemctl start dea.service
sudo systemctl stop dea.service
sudo systemctl restart dea.service

查看 log：

sudo journalctl -u dea.service -f

若修改 /etc/systemd/system/dea.service：

sudo systemctl daemon-reload
sudo systemctl restart dea.service

測試與檢查

Python 語法檢查：

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

後端測試使用 Python 內建 unittest，不需要安裝或執行 pytest：

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

前端建置檢查：

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

安全與限制

• API middleware 只允許 private / loopback IP 存取。
• 回應會加上 CSP、Referrer-Policy、X-Content-Type-Options: nosniff、X-Frame-Options: DENY。
• CSP 的 script 來源允許本機與 Plotly CDN：

'self' https://cdn.plot.ly

• 係數數量上限為 64。
• CSV 上限為 32 MB。
• 頻率、係數、a[0] 與 CSV 訊號欄位都有後端驗證。

常見問題

頁面沒有更新

1. 瀏覽器按 Ctrl+F5 強制重新整理。
2. 確認前端 build 檔存在：

ls static/build/app.js static/build/app.css

3. 重新 build 並重啟服務：

npm run build
sudo systemctl restart dea.service

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

MCU COM Port清單是空的

1. 確認 USB 裝置已插入。
2. 確認執行服務的使用者有 serial port 權限。
3. 檢查預設 port：

echo $MCU_SERIAL_PORT

4. 可在頁面按「更新」重新讀取 serial ports。