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 組合（支援 δ/r 參數微調）、Q 格式位元數與 fixed-point 整數係數。
- 透過瀏覽器 Web Serial API 直接將 fixed-point 係數命令送到 MCU（需透過 HTTPS 連線）。
- 上傳 CSV 時域資料，套用目前差分方程並繪製輸入/輸出波形。
- 匯出包含濾波輸出欄位的 CSV。
- 支援深色模式 (Dark Mode) 與響應式 UI。

## 專案結構

```text
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/                 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
npm run build
```

## HTTPS 設定

為了支援 Web Serial API（瀏覽器直接存取本機連接埠），後端必須透過 HTTPS 連線提供服務。

1. **產生自簽憑證**：
   ```bash
   bash certs/generate_cert.sh
   ```
   這會在 `certs/` 目錄下產生 `key.pem` 與 `cert.pem`。

2. **信任憑證**：
   由於是自簽憑證，瀏覽器會顯示安全性警告。請在「進階」中選擇「繼續前往」或將其加入信任清單。

## 執行

### 手動啟動 (HTTPS)

```bash
.venv/bin/uvicorn dea_api:app --host 0.0.0.0 --port 8000 --ssl-keyfile certs/key.pem --ssl-certfile certs/cert.pem
```

瀏覽器開啟：`https://<server-ip>:8000/ui/` 或本機 `https://localhost:8000/ui/`

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

### 使用 systemd

1. 檢查 `dea.service` 中的路徑是否正確（需確認 `ExecStart` 已加上 `--ssl-keyfile` 等參數）。
2. 啟用並啟動服務：
   ```bash
   sudo cp dea.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable dea.service
   sudo systemctl start dea.service
   ```

查看狀態與 Log：
```bash
sudo systemctl status dea.service
sudo journalctl -u dea.service -f
```

## MCU 連接埠 (Web Serial)

本工具優先使用瀏覽器的 Web Serial API 直接與 MCU 通訊，無需伺服器端具備 serial 權限。

- **連線**：點擊 UI 上的「選擇連接埠並連線」，在瀏覽器彈出視窗中選擇正確的 MCU 裝置。
- **寫值**：點擊「寫值到 MCU」，系統會將目前定點數係數格式化為 `bodeplot=b0,b1,b2,a1,a2` 並送出。
- **限制**：需使用 Chrome 或 Edge 瀏覽器，且必須透過 HTTPS (或 localhost) 連線。

## 後端 MCU Serial 設定 (備用)

若無法使用 Web Serial，後端仍保留透過伺服器端實體連線寫入的 API。預設值在 `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"
```

## 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
```

## a1/a2 微調 (δ/r 參數)

針對二階濾波器 (2P1Z/2P2Z)，UI 提供了進階的步階微調功能：

- **δ (Delta)**：控制極點的頻率/阻尼平衡點。
- **r**：控制極點的半徑/頻寬。
- 公式：`a1 = -a0 - r + δ`，`a2 = r + δ` (定點數模式) 或 `a1 = -1 - r + δ`，`a2 = r + δ` (浮點數模式)。
- 支援透過 Shift + 滑鼠滾輪或觸控拖曳進行高精度微調。

## CSV 上傳

限制與行為：

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

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

```text
time,value
```

## 測試與檢查

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。
- 係數數量上限為 64。
- CSV 上限為 32 MB。
- 頻率、係數、`a[0]` 與 CSV 訊號欄位都有後端驗證。

## 常見問題

### 為什麼無法連線連接埠？
1. 確認是否使用 HTTPS 連線。
2. 確認瀏覽器是否支援 Web Serial API (推薦使用 Chrome/Edge)。
3. 檢查 USB 傳輸線是否連接正確。

### 頁面沒有更新
1. 瀏覽器按 `Ctrl+F5` 強制重新整理。
2. 執行 `npm run build` 重新建置前端。
3. 執行 `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
```