knb
d2fd6cc1f9
Align raster protocol bytes and print-end sequencing by printer family, add safer status polling/retry behavior, and document the changes with regression coverage to prevent protocol regressions. Made-with: Cursor
127 lines
6.8 KiB
Markdown
127 lines
6.8 KiB
Markdown
# ptouch_label
|
||
|
||
**バージョン 1.0.0**（初回リリース）
|
||
|
||
Brother P-touch シリーズ向けのラベル印刷用 **C コアライブラリ（libptouch）** と、動作確認用 **CLI（`ptouch-print`）** のリポジトリです。
|
||
|
||
対象機種: **PT-P900W**（560 ドットヘッド）、**PT-P750W** / **PT-P710BT**（128 ドットヘッド・USB）。`libptouch_open_usb_vid_pid` に各機種の VID/PID を渡す（P900W 既定は `libptouch_open_usb`）。P750/P710 のラスター仕様は `reference/cv_ptp750w_710bt_jpn_raster_102.pdf`。
|
||
|
||
現状は USB only / 将来 Bluetooth 対応予定。
|
||
|
||
## レイアウト
|
||
|
||
|
||
| パス | 内容 |
|
||
| ----------------------- | --------------------------------------------------------------------------- |
|
||
| `include/libptouch.h` | 公開 API |
|
||
| `src/lib/libptouch_*.c` | ライブラリ本体（core / usb / print / status / png / svg） |
|
||
| `src/cli/main.c` | `ptouch-print` エントリ |
|
||
| `samples/` | 試験用サンプル画像の置き場（PNG/SVG 等） |
|
||
| `ruby/` | Ruby FFI gem（`libptouch`）・コマンド `ptouch-print-png`（PNG のみ）— `ruby/README.md` |
|
||
| `reference/` | 仕様・参考資料（例: ラスター PDF） |
|
||
|
||
|
||
## ビルド
|
||
|
||
依存: **CMake 3.16+**、**libusb-1.0**、**libpng**、**librsvg-2.0**（開発パッケージ例: `libusb-1.0-0-dev`、`libpng-dev`、`librsvg2-dev`）。
|
||
|
||
```bash
|
||
cmake -S . -B build
|
||
cmake --build build
|
||
ctest --test-dir build --output-on-failure
|
||
```
|
||
|
||
成果物（`build/` 以下）:
|
||
|
||
- `libptouch.a` — 静的ライブラリ
|
||
- `libptouch.so` — 共有ライブラリ（Ruby FFI 用）
|
||
- `ptouch-print` — CLI
|
||
|
||
### Ruby gem
|
||
|
||
共有ライブラリをビルドしたうえで、`ruby/` で `bundle install` → `gem build libptouch.gemspec` など（手順は `ruby/README.md`）。
|
||
|
||
## CLI の使い方（雛形）
|
||
|
||
**PNG**（拡張子 `.png` または PNG シグネチャ）の場合は幅・高さは画像から取得します。
|
||
**SVG**（拡張子 `.svg`）の場合は現在装着中テープの印字可能ドット幅に合わせて自動拡大・縮小します（USB 接続が必要）。
|
||
`--trim-right[=DOTS]` で右側空白列を削減できます（DOTS 省略時は左余白ドット、取得失敗時は 0）。
|
||
任意で `-t`（0–255）で二値化しきい値を指定できます。
|
||
|
||
**1bit packed ラスター**（行優先、行あたり `ceil(width/8)` バイト × 行数）の場合は `-f` に加え `-w` / `-H` が必須です。
|
||
|
||
印刷時、`libptouch_print_raster` は内部でラスターを**転置**してから送ります（`-T` / `-M` などのオプションはありません。鏡像のみの変換は行いません）。
|
||
|
||
```bash
|
||
# PNG — 検証のみ（USB 不要）
|
||
./build/ptouch-print -n -f label.png
|
||
./build/ptouch-print -n -f label.png --trim-right
|
||
./build/ptouch-print -n -f label.png --trim-right=20
|
||
|
||
# SVG — 幅を現在テープにフィットさせて検証（USB 必要）
|
||
./build/ptouch-print -n -f label.svg
|
||
|
||
# PNG — しきい値を指定
|
||
./build/ptouch-print -n -f label.png -t 160
|
||
|
||
# 1bit ラスター — 検証のみ
|
||
./build/ptouch-print -n -f sample.raster -w 128 -H 64
|
||
|
||
# プリンタステータス（テープ幅・種類・色・エラービット等、PDF の 32 バイト応答）
|
||
./build/ptouch-print --status
|
||
|
||
# USB 接続時
|
||
./build/ptouch-print -f label.png
|
||
./build/ptouch-print -f label.svg
|
||
./build/ptouch-print -f sample.raster -w 128 -H 64
|
||
|
||
# PT-P750W / PT-P710BT（`lsusb` の PID に合わせる）
|
||
./build/ptouch-print --status -p 0x2062
|
||
./build/ptouch-print -f label.png -p 0x20af
|
||
```
|
||
|
||
`-n`（`--dry-run`）では読み込みと `libptouch_check_raster` まで実行します。
|
||
|
||
## libptouch API（概要）
|
||
|
||
- バージョン — `LIBPTOUCH_VERSION_MAJOR` / `MINOR` / `PATCH` / `LIBPTOUCH_VERSION_STRING`（`libptouch_version.h`、CMake の `project(VERSION …)` と同期）
|
||
- `libptouch_create` / `libptouch_destroy` — コンテキスト
|
||
- `libptouch_open_usb` / `libptouch_open_usb_vid_pid` / `libptouch_close` — USB（libusb・VID/PID）
|
||
- `libptouch_get_status` / `libptouch_status_fprint` — ステータス情報リクエスト（ESC i S）の応答
|
||
- `libptouch_get_current_media_info` — 現在テープ幅(mm)・印字可能幅(dots)・DPI・最小余白(mm)を取得
|
||
- `libptouch_check_raster` — ラスターバッファの検証のみ
|
||
- `libptouch_png_file_to_raster` / `libptouch_free_raster` — PNG を 1bit ラスターに変換（libpng）
|
||
- `libptouch_svg_file_to_raster_fit_current_tape` — SVG を現在テープ幅に合わせて 1bit ラスターへ変換（librsvg + cairo、USB 必須）
|
||
- `libptouch_print_raster` — ラスター印刷（USB・PDF のコマンド列、内部で転置）
|
||
- `libptouch_strerror` / `libptouch_last_error` — エラー情報
|
||
|
||
ラスター形式は `include/libptouch.h` のコメントに合わせてください。
|
||
|
||
## PT-P900W / Linux でのメモ
|
||
|
||
- 接続は **libusb-1.0** のみ。機種ごとに **VID/PID**（`lsusb` 等）を調べ、`libptouch_open_usb_vid_pid` に渡すか、既定の PT-P900W なら `libptouch_open_usb` を使います。PT-P750W は **04f9:2062**、PT-P710BT は **04f9:20af**（`include/libptouch.h` の定数参照）。
|
||
- PT-P750W / PT-P710BT ではラスター幅方向は **180 dpi**（P900W は 360 dpi）。PNG から印刷する場合は解像度に合わせて画像を用意してください。
|
||
- ラスターコマンドの詳細は `**reference/` の PDF** および Brother 公開資料に沿って `src/lib/libptouch_*.c` に実装してください。
|
||
|
||
### Ubuntu で sudo なしで USB を開く（udev）
|
||
|
||
**04f9:2085**（PT-P900W）、**04f9:2062**（PT-P750W）、**04f9:20af**（PT-P710BT）向けルールを `udev/99-ptouch-label-brother.rules` に置いています。
|
||
|
||
```bash
|
||
sudo cp udev/99-ptouch-label-brother.rules /etc/udev/rules.d/
|
||
sudo udevadm control --reload-rules
|
||
sudo udevadm trigger
|
||
sudo usermod -aG plugdev "$USER"
|
||
```
|
||
|
||
**再ログイン**するか、端末で `newgrp plugdev` のあと試すか、USB を**抜き差し**してください。`groups` に `plugdev` が含まれていれば、`./build/ptouch-print --status` などを sudo なしで実行できます。
|
||
|
||
別の Brother 機種（別 PID）のときは、`lsusb` の ID に合わせて同ファイルに行を追加してください。
|
||
|
||
## ライセンス
|
||
|
||
[MIT License](LICENSE)（`LICENSE` ファイルを参照）。
|
||
|
||
## 変更履歴
|
||
|
||
リリース間の変更点は `CHANGELOG.md` を参照してください。 |