tcad-bodeplot/README.md

# 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

```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://localhost:8000/ui/
```

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

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

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

## Project Layout

```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/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 預設暫存在：

```text
/tmp/diff-eq-analyzer-csv/
```

可用環境變數覆寫：

```bash
DEA_TEMP_CSV_DIR=/path/to/csv-cache
```

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

### 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`，前端會預設選第二欄作為訊號欄位。

範例檔案：

```text
chirp_signal.csv
```

欄位：

```text
time,value
```

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

```bash
npm install
npm run build
```

開發模式：

```bash
npm run dev
```

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

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

### 無法連線 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：

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