Metadata-Version: 2.4
Name: pypamc_104
Version: 0.4.0
Summary: Python driver for PAMC-104 Piezo Assist Motor Controller
License-Expression: MIT
Project-URL: Homepage, https://github.com/mechano-transformer/pypamc-104
Project-URL: PyPI, https://pypi.org/project/pypamc-104/
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pyserial>=3.5
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# pypamc_104

[![PyPI](https://img.shields.io/pypi/v/pypamc-104)](https://pypi.org/project/pypamc-104/)
[![Python](https://img.shields.io/pypi/pyversions/pypamc-104)](https://pypi.org/project/pypamc-104/)

PAMC-104 ピエゾアシストモーターコントローラ用 Python ライブラリ

## インストール

```bash
pip install pypamc_104
```

開発版（ローカルインストール）：

```bash
cd pypamc-104
pip install -e .
```

## 必要環境

- Python 3.9+
- pyserial

## 開発環境のセットアップ

### 1. リポジトリをクローン

```bash
git clone https://github.com/mechano-transformer/pypamc-104.git
cd pypamc-104
```

### 2. 仮想環境（venv）を作成・有効化

**Windows:**

```bash
python -m venv .venv
.venv\Scripts\activate
```

**macOS / Linux:**

```bash
python3 -m venv .venv
source .venv/bin/activate
```

### 3. 開発用依存パッケージと共にインストール

```bash
pip install -e ".[dev]"
```

これで `pypamc104` 本体 + `pytest` がインストールされます。

### 4. ユニットテストの実行

```bash
pytest
```

詳細出力で実行する場合：

```bash
pytest -v
```

特定のテストクラスだけ実行する場合：

```bash
pytest tests/test_controller.py::TestRotation -v
```

### 5. 仮想環境の終了

```bash
deactivate
```

## クイックスタート

```python
from pypamc104 import PAMC104

# コントローラに接続（ポートは自動検出）
with PAMC104() as ctrl:
    # 通信確認
    ctrl.check_connection()

    # ファームウェアバージョン確認
    print(ctrl.get_firmware_info())

    # CH1を正回転（1500Hz, 10パルス）
    ctrl.rotate_forward(channel=1, frequency=1500, pulses=10)

    # CH2を逆回転（連続駆動）
    ctrl.rotate_reverse(channel=2, frequency=300)

    # 停止
    ctrl.stop()
```

## 使い方

### 接続

ポート名を省略すると、USBのVID/PID（FTDI FT230X: `0403:6015`）が一致する
シリアルポートを自動検出します。ポート名の明示指定も可能です。

```python
from pypamc104 import PAMC104, find_port

# context manager（推奨）。ポート自動検出
with PAMC104() as ctrl:
    ...

# ポート名を明示指定（自動検出をスキップ）
with PAMC104("COM3") as ctrl:
    ...

# 手動で接続管理
ctrl = PAMC104()
ctrl.open()
print(ctrl.port)  # 実際に使用中のポート（例: "COM3", "/dev/ttyUSB0"）
# ... 操作 ...
ctrl.close()

# 検出だけ行うことも可能（見つからない/複数候補の場合は ConnectionError）
port = find_port()
```

### 通信確認

```python
with PAMC104("COM3") as ctrl:
    # CON コマンドで通信状態を確認
    if ctrl.check_connection():
        print("通信OK")
```

### ファームウェアバージョン確認

```python
with PAMC104("COM3") as ctrl:
    info = ctrl.get_firmware_info()
    print(info)  # e.g. "PAMC-104 Ver:0.8.0(115200bps)"
```

### チャンネル / 軸（CH1〜CH4 = A〜D）の指定方法

PAMC-104 は最大4軸を制御できます。各メソッドの **`channel`** 引数には、
**数字 `1`〜`4`** でも **軸文字 `"A"`〜`"D"`**（大文字・小文字どちらも可）でも指定できます。
両者は次のように対応します。

| 数字 | 軸文字 | 軸 |
|---|---|---|
| `1` | `"A"` | CH1 |
| `2` | `"B"` | CH2 |
| `3` | `"C"` | CH3 |
| `4` | `"D"` | CH4 |

PAMC-104 の駆動コマンド（`NR`/`RR`）では軸表記はコマンド末尾の `A`〜`D` です。
数字で指定してもライブラリが自動変換するため、利用者はどちらの書き方をしても同じ結果になります。

| コマンド系統 | 軸表記 | 例（CH1 / CH2） |
|---|---|---|
| 回転駆動（`NR`/`RR`） | 末尾に `A`〜`D` | `NR05000100`**`A`** / …**`B`** |

```python
with PAMC104("COM3") as ctrl:
    # 数字でも軸文字でも同じ（どちらも CH2 を 500Hz で正回転）
    ctrl.rotate_forward(channel=2, frequency=500, pulses=100)
    ctrl.rotate_forward(channel="B", frequency=500, pulses=100)

    # 小文字も可
    ctrl.rotate_reverse(channel="c", frequency=300)
```

### モーター駆動（正回転 / 逆回転）

```python
with PAMC104("COM3") as ctrl:
    # 正回転: CH1, 1500Hz, 10パルス
    ctrl.rotate_forward(channel=1, frequency=1500, pulses=10)

    # 逆回転: CH2, 500Hz, 連続駆動（pulses=0）
    ctrl.rotate_reverse(channel=2, frequency=500)

    # 小数点周波数（ファームウェア0.8.0以降）
    ctrl.rotate_forward(channel=1, frequency=100.5, pulses=10)

    # 拡張パルス（最大999999パルス、ファームウェア0.8.0以降）
    ctrl.rotate_forward(channel=1, frequency=800, pulses=100000)

    # 停止（駆動パルス数が返る）
    result = ctrl.stop()
    print(result)  # e.g. "FIN" or "FIN1456"

    # パルス数だけ取得
    count = ctrl.get_stop_pulse_count()
```

### 生コマンド送信

```python
with PAMC104("COM3") as ctrl:
    response = ctrl.send_raw("CON")
    print(response)
```

## コマンド一覧

| メソッド | コマンド | 説明 |
|---|---|---|
| `check_connection()` | `CON` | 通信確認 |
| `get_firmware_info()` | `INF` | ファームウェアバージョン確認 |
| `rotate_forward()` | `NRnnnnyyyyz` | 正回転駆動 |
| `rotate_reverse()` | `RRnnnnyyyyz` | 逆回転駆動 |
| `stop()` | `S` | 駆動停止 |

### 駆動コマンドのフォーマット

| フォーマット | 説明 | 対応FW |
|---|---|---|
| `NR/RR` + `nnnn` + `yyyy` + `z` | 標準（整数周波数、4桁パルス） | 全バージョン |
| `NR/RR` + `nnnn.n` + `yyyy` + `z` | 小数点周波数（0.1Hz単位） | 0.8.0+ |
| `NR/RR` + `nnnn` + `Xyyyyyy` + `z` | 拡張パルス（6桁） | 0.8.0+ |

### パラメータ

| パラメータ | 範囲 | 説明 |
|---|---|---|
| 周波数（整数） | 1〜1500 Hz | 4桁ゼロ埋め |
| 周波数（小数） | 0.1〜1500.0 Hz | ○○○○.○形式 (FW 0.8.0+) |
| パルス数（標準） | 0000〜9999 | 0000 = 連続駆動 |
| パルス数（拡張） | X000000〜X999999 | X + 6桁 (FW 0.8.0+) |
| チャンネル | 1〜4 または A〜D | 数字でも軸文字でも指定可（A:CH1, B:CH2, C:CH3, D:CH4） |

### レスポンスメッセージ

| メッセージ | 意味 |
|---|---|
| `OK` | コマンドを正常に受けた |
| `FIN` | 駆動終了 |
| `FIN△△△△` | 連続駆動停止時の実移動パルス数 |
| `ERROR` | コマンド入力間違い |
| `BUSY` | 駆動中 |

## 通信仕様

| 項目 | 値 |
|---|---|
| ボーレート | 115200 bps |
| データビット | 8 bit |
| パリティ | None |
| ストップビット | 1 bit |
| フロー制御 | None |
| デリミタ | CR + LF |

## PAMC-204 との違い

PAMC-104 は PAMC-204 と比較してシンプルな構成です：

- **アドレスシステムなし**: コマンドに `Exx` プレフィックスを付けません
- **位置制御なし**: 絶対位置移動（PA）、相対位置移動（PR）等はありません
- **CON コマンド**: PAMC-104 固有の通信確認コマンドがあります
- **出力電圧制御なし**: DAC コマンドはありません

## ライセンス

MIT
