ws50529
269 lines
5.9 KiB
Markdown
Executable File
269 lines
5.9 KiB
Markdown
Executable File
# 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。
|
||
|
||
## 專案結構
|
||
|
||
```text
|
||
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 並安裝依賴：
|
||
|
||
```bash
|
||
cd /home/wisetop/diff-eq-analyzer
|
||
python3 -m venv .venv
|
||
.venv/bin/pip install -r requirements.txt
|
||
```
|
||
|
||
安裝前端依賴：
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
建置前端：
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
Vite 會輸出到：
|
||
|
||
```text
|
||
static/build/app.js
|
||
static/build/app.css
|
||
```
|
||
|
||
## 執行
|
||
|
||
本機開發可直接啟動 FastAPI：
|
||
|
||
```bash
|
||
.venv/bin/uvicorn dea_api:app --host 127.0.0.1 --port 8000
|
||
```
|
||
|
||
瀏覽器開啟：
|
||
|
||
```text
|
||
http://localhost:8000/ui/
|
||
```
|
||
|
||
部署在區網主機時可用：
|
||
|
||
```text
|
||
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 寫入命令格式固定為：
|
||
|
||
```text
|
||
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 行，欄位為：
|
||
|
||
```text
|
||
time,value
|
||
```
|
||
|
||
## MCU Serial 設定
|
||
|
||
MCU serial 預設值在 `dea/config.py`，也可用環境變數覆蓋：
|
||
|
||
```bash
|
||
MCU_SERIAL_PORT=/dev/ttyUSB2
|
||
MCU_BAUD_RATE=115200
|
||
MCU_WRITE_TIMEOUT=1.0
|
||
```
|
||
|
||
若使用 systemd，可在 `dea.service` 的 `[Service]` 區塊加入：
|
||
|
||
```ini
|
||
Environment="MCU_SERIAL_PORT=/dev/ttyUSB2"
|
||
Environment="MCU_BAUD_RATE=115200"
|
||
Environment="MCU_WRITE_TIMEOUT=1.0"
|
||
```
|
||
|
||
更新 service 後重新載入：
|
||
|
||
```bash
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl restart dea.service
|
||
```
|
||
|
||
注意：MCU 功能需要 `pyserial>=3.5`，已列在 `requirements.txt`。
|
||
|
||
## systemd
|
||
|
||
查看服務狀態：
|
||
|
||
```bash
|
||
sudo systemctl status dea.service
|
||
```
|
||
|
||
啟動、停止、重啟：
|
||
|
||
```bash
|
||
sudo systemctl start dea.service
|
||
sudo systemctl stop dea.service
|
||
sudo systemctl restart dea.service
|
||
```
|
||
|
||
查看 log：
|
||
|
||
```bash
|
||
sudo journalctl -u dea.service -f
|
||
```
|
||
|
||
若修改 `/etc/systemd/system/dea.service`：
|
||
|
||
```bash
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl restart dea.service
|
||
```
|
||
|
||
## 測試與檢查
|
||
|
||
Python 語法檢查：
|
||
|
||
```bash
|
||
.venv/bin/python -m py_compile dea_api.py tests/test_dea_api.py
|
||
```
|
||
|
||
後端測試使用 Python 內建 `unittest`，不需要安裝或執行 `pytest`：
|
||
|
||
```bash
|
||
.venv/bin/python -m unittest discover -s tests
|
||
```
|
||
|
||
前端建置檢查：
|
||
|
||
```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
|
||
```
|
||
|
||
## 安全與限制
|
||
|
||
- API middleware 只允許 private / loopback IP 存取。
|
||
- 回應會加上 CSP、`Referrer-Policy`、`X-Content-Type-Options: nosniff`、`X-Frame-Options: DENY`。
|
||
- CSP 的 script 來源允許本機與 Plotly CDN：
|
||
|
||
```text
|
||
'self' https://cdn.plot.ly
|
||
```
|
||
|
||
- 係數數量上限為 64。
|
||
- CSV 上限為 32 MB。
|
||
- 頻率、係數、`a[0]` 與 CSV 訊號欄位都有後端驗證。
|
||
|
||
## 常見問題
|
||
|
||
### 頁面沒有更新
|
||
|
||
1. 瀏覽器按 `Ctrl+F5` 強制重新整理。
|
||
2. 確認前端 build 檔存在：
|
||
|
||
```bash
|
||
ls static/build/app.js static/build/app.css
|
||
```
|
||
|
||
3. 重新 build 並重啟服務：
|
||
|
||
```bash
|
||
npm run build
|
||
sudo systemctl restart dea.service
|
||
```
|
||
|
||
### 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
|
||
```
|
||
|
||
### MCU 串口清單是空的
|
||
|
||
1. 確認 USB 裝置已插入。
|
||
2. 確認執行服務的使用者有 serial port 權限。
|
||
3. 檢查預設 port：
|
||
|
||
```bash
|
||
echo $MCU_SERIAL_PORT
|
||
```
|
||
|
||
4. 可在頁面按「刷新」重新讀取 serial ports。
|