このリポジトリは、TAKAYA製 RFID リーダライタ UTR-S201/202 シリーズを USBシリアル接続で扱う Python サンプルです。
現在は、通常Inventory確認に加えて、UTR-SUN02-4CH のアンテナ順次Inventory、UTR-SUN02-8CH / USM08 の複数アンテナ順次Inventory確認CLIも含みます。
本サンプルは無保証で提供される確認用コードです。実際の運用環境で利用する場合は、機器設定、通信条件、プロトコル仕様、周辺環境を十分に確認してください。
通常の実機確認は、以下を実行します。
py .\src\utr_usb_sample.pyこの標準入口では、次の流れで動作します。
- USBシリアル接続する。
- ROMバージョンを読み取り、仕様書上の機種を確認する。
- コマンドモードへ切り替える。
- 現在の送信出力設定を読み取る。
- UTR-SUN02-4CH / USM02 の場合、Inventory中だけ送信出力を一時変更するか確認する。
- 変更する場合は、コマンドモード用パラメータだけを書き換える。
- Inventory前の送信出力設定、周波数設定、Inventoryパラメータを表示する。
- 必要に応じて、UTR-SUN02-4CH のアンテナ接続確認とANT別順次Inventoryを実行する。
- Inventoryを実行する。
- 終了時に送信出力を元の値へ復元する。
- 復元後に送信出力設定を読み戻す。
- アンテナ設定を変更した場合は、元のコマンドモード用アンテナ設定へ復元する。
- 結果ファイルを保存し、シリアル接続を閉じる。
UTR-SUN02-8CH / USM08 で、接続OKアンテナを選択順に切り替えてInventoryする場合は、以下を実行します。
py .\src\utr_8ch_sequential_inventory_cli.pyこのCLIでは、次の流れで動作します。
- USBシリアル接続する。
- ROMバージョンを読み取り、UTR-SUN02-8CH / USM08 であることを確認する。
- コマンドモードへ切り替える。
- Inventory前のリーダライタ設定を読み取り表示する。
UHF_GET_INVENTORY_PARAMを読み取り表示する。- 変更前の使用アンテナ番号を読み取り、終了時復元用に保持する。
- 変更前設定を読み取れない場合は、順次Inventoryを開始しない。
- ANT1〜ANT8の接続チェックを実行する。
- 接続OKアンテナだけを候補表示する。
1、1,3、all、qの入力を受け付ける。- 選択した全ANTの使用アンテナ番号設定フレームを事前表示する。
- 最初に1回だけ確認し、選択順に使用アンテナ番号設定を送信する。
- ACKならそのANTでInventoryする。
- NACKまたはACK/NACKなしなら、そのANTをスキップする。
- ANT別に読み取り枚数、Inventory実行回数、スキップ回数を表示する。
- 終了時に、開始前に読み取った使用アンテナ番号へ自動復元する。
- Ctrl+Cや例外時も、可能な範囲でシリアルクローズ前に自動復元を試みる。
- 復元前には、割り込み前のInventory応答が残らないよう受信バッファをクリアする。
- 復元応答としてACK/NACK以外を受信した場合は、残留応答の可能性を考慮して1回だけ再試行する。
- 必要に応じて、8CH順次InventoryサマリをCSV/JSONへ保存する。
- シリアル接続を閉じる。
- USB接続は仮想COMポートとして扱います。
- 通信速度の標準確認値は 115200 bps です。
- 標準入口の送信出力一時変更は、現時点では UTR-SUN02-4CH / USM02 を対象にします。
- 送信出力の変更先は、コマンドモード用パラメータです。
- 送信出力一時変更を確定した場合は、変更送信前に復元計画を保持し、例外時も
finally側で復元を試みます。 - FLASHデータへの書き込みは行いません。
UHF_SET_INVENTORY_PARAMは自動送信しません。- UTR-SUN02-8CH / USM08 の順次Inventory CLIでは、使用アンテナ番号設定をコマンドモード用パラメータへ送信します。FLASHへは保存しません。
- UTR-SUN02-8CH / USM08 では、Inventory対象への一時切替時に ANT1=使用アンテナ番号
00h、ANT2=20h、ANT3=40h、ANT4=60h、ANT5=80h、ANT6=A0h、ANT7=C0h、ANT8=E0hを使います。 - ただし、開始前の変更前設定は外部アンテナ番号が
00h固定とは限りません。終了時は開始前に読み取った内部アンテナ番号・外部アンテナ番号へ自動復元します。 - 異常終了時の自動復元では、受信バッファ内に残ったInventory応答をクリアしてから復元コマンドを送信します。
- 復元コマンドの再試行は、同じ復元フレームを1回だけ送信します。
- UTR-SUN02V-8CH と UTR-SUN02-8CH はROMシリーズ名と機種識別までは扱いますが、UTR-SUN02-8CH用の実送信CLIは USM08 を対象にします。
- 実タグIDを含む
PC+UII/PC+EPCは、GitHub、Issue、PR本文、公開ログへ載せません。 - 実行時に
PC+UIIを画面表示でマスクしますか？でyを選ぶと、画面表示だけPC+UII: 省略にできます。
- USB実機で ROM_VERSION_CHECK、COMMAND_MODE_SET、UHF_GET_INVENTORY_PARAM、UHF_INVENTORY、ブザー制御の応答を確認済みです。
- UTR-SUN02-4CH / USM02 で、送信出力の一時変更と復元を実機確認済みです。
- 標準Inventoryフローで、送信出力 24.0 dBm から 12.0 dBm へ一時変更し、Inventory後に 24.0 dBm へ復元できることを実機確認済みです。
- PR #71 反映後、UTR-SUN02-4CH / USM02、COM6、115200 bpsで通常終了時の送信出力復元を確認済みです。
- pytest は 234 passed を確認済みです。
- Inventory前に送信出力値、キャリア送信時間、キャリア休止時間、キャリアセンス待ち時間、周波数設定を表示できます。
- Inventory応答解析では、タグデータレスポンス、読み取り完了ACK、NACKを扱う補助処理を追加済みです。
- NACK応答時は、通常のタグ未検出とは分けて表示し、NACK用ブザー通知と繰り返しInventory中断に対応済みです。
- UTR-SUN02-4CHでは、UHF_CheckAntennaによるANT0〜ANT3接続確認、コマンドモード用アンテナ設定の読み取り、一時変更、終了時復元に対応済みです。
- UTR-SUN02-4CHでは、
0、1、0,1、all入力による複数アンテナの順次切替Inventoryに対応済みです。 - 通信条件が合わないCOMポートでACK/NACKなしの場合は、Inventory未実行として結果保存せず、シリアル接続を閉じます。
- UTR-SUN02-8CH / USM08では、ANT1〜ANT8の接続チェック、接続OKアンテナの候補表示、
1、1,3、all、q入力による複数アンテナ順次Inventoryに対応済みです。 - UTR-SUN02-8CH / USM08では、ANT1とANT3接続状態で、
all選択による ANT1 -> ANT3 順次Inventoryを実機確認済みです。 - UTR-SUN02-8CH / USM08では、開始前に変更前の使用アンテナ番号を読み取り、通常終了時に変更前設定へ自動復元できることを実機確認済みです。
- 実機確認例では、開始前設定として
ANT3/EXT5、使用アンテナ番号44hを読み取り、終了時にANT3/EXT5 / 44hへ自動復元できています。 - Ctrl+Cや例外時も、可能な範囲で
finally側から変更前設定へ自動復元を試みます。 - Ctrl+C直前のInventory応答が残る場合に備え、復元前に受信バッファをクリアし、必要に応じて同じ復元フレームを1回だけ再送します。
- Ctrl+C時の最終的な復元成功確認は、PR #70 反映後に実機で確認してください。
- Inventory結果保存時、CSV/JSONへ
antenna_number、antenna_label、antenna_descriptionを保存します。 - 8CH順次Inventoryサマリ保存時、CSV/JSONへANT別のInventory実行回数、読み取り枚数、スキップ回数、復元結果を保存します。PC+UII実値は保存しません。
- Inventory未実行時は、結果ファイルを保存しません。
- 既存CSVのヘッダーが旧形式の場合は、
inventory_results_legacy_YYYYMMDD_HHMMSS.csvに退避してから現行ヘッダーで保存します。 - pytest と GitHub Actions による確認運用を行っています。
UTR_USB_Python_CodeX/
├─ src/
│ ├─ utr_usb_sample.py
│ ├─ utr_usb_sample_legacy.py
│ ├─ utr_usb_inventory_with_output_power.py
│ ├─ utr_8ch.py
│ ├─ utr_8ch_single_antenna_inventory_cli.py
│ ├─ utr_8ch_sequential_inventory_cli.py
│ ├─ utr_output_power.py
│ ├─ utr_output_power_change.py
│ ├─ utr_output_power_temporary_change.py
│ ├─ utr_output_power_inventory_integration.py
│ ├─ utr_output_power_readout.py
│ ├─ utr_protocol.py
│ ├─ utr_inventory.py
│ ├─ utr_commands.py
│ ├─ utr_antenna.py
│ ├─ utr_serial_ports.py
│ ├─ utr_privacy.py
│ └─ utr_result_export.py
├─ tests/
├─ docs/
├─ scripts/
├─ requirements.txt
├─ requirements-dev.txt
└─ pytest.ini
| ファイル | 役割 |
|---|---|
src/utr_usb_sample.py |
標準入口。送信出力一時変更つきInventoryフローを起動します。 |
src/utr_usb_sample_legacy.py |
旧サンプル本体。既存関数・定数の互換維持用です。 |
src/utr_usb_inventory_with_output_power.py |
送信出力一時変更つきInventoryフロー本体です。 |
src/utr_8ch.py |
8CH機種判定、ANT番号変換、使用アンテナ番号設定フレーム生成補助関数です。 |
src/utr_8ch_single_antenna_inventory_cli.py |
UTR-SUN02-8CH向けの単一アンテナInventory確認CLIです。 |
src/utr_8ch_sequential_inventory_cli.py |
UTR-SUN02-8CH向けの複数アンテナ順次Inventory確認CLIです。 |
src/utr_output_power.py |
送信出力値の dBm / raw値 / little-endian bytes 変換補助関数です。 |
src/utr_output_power_change.py |
送信出力設定書き込みフレームの計画補助関数です。 |
src/utr_output_power_temporary_change.py |
一時変更用フレームと復元用フレームをセットで作成します。 |
src/utr_output_power_inventory_integration.py |
Inventory前に送信出力一時変更を提案できるか判定します。 |
src/utr_output_power_readout.py |
送信出力読み取りレスポンスからキャリア関連時間を解析します。 |
src/utr_protocol.py |
実機通信なしのプロトコル補助関数です。 |
src/utr_inventory.py |
実機通信なしのInventory解析補助関数です。 |
src/utr_commands.py |
コマンド定義とコマンド生成補助関数です。 |
src/utr_antenna.py |
アンテナ接続確認、アンテナ切替設定、機種プロファイル補助関数です。 |
src/utr_serial_ports.py |
COMポート選択補助関数です。 |
src/utr_privacy.py |
PC+UIIの画面表示・保存時マスク補助関数です。 |
src/utr_result_export.py |
Inventory集計結果のCSV/JSON保存補助関数です。 |
docs/ |
作業計画、確認手順、比較テンプレート、設計資料です。 |
scripts/dev_check.ps1 |
ローカル開発確認スクリプトです。 |
scripts/git_preflight.ps1 |
コミット/PR前の確認スクリプトです。 |
Python仮想環境を使う場合の例です。
py -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
pip install -r requirements-dev.txtpy が使えない環境では、利用可能な Python 実行コマンドに置き換えてください。
py .\src\utr_usb_sample.py実行後、画面の指示に従って以下を入力します。
- COMポート番号またはCOM名。
- ボーレート。未入力なら 115200 bps。
- 送信出力をInventory中だけ一時変更するか。
- 変更する場合は、変更後の送信出力値。
- アンテナ設定表示・接続チェックを実行するか。
- Inventory対象アンテナ。
- ブザー通知の有無。
- PC+UII画面表示マスクの有無。
- Inventory繰り返し回数。
qで終了。
送信出力を一時変更した場合、終了時に元の送信出力へ復元します。PR #71以降は、一時変更を確定した時点で復元計画を保持するため、変更後読み戻しで例外が起きても finally 側で復元を試みます。
実機確認済みの例です。
対象機器: UTR-SUN02-4CH / USM02
COM: COM6
ボーレート: 115200 bps
変更前送信出力: 24.0 dBm
一時変更後送信出力: 12.0 dBm
Inventory実行: 3回
読み取り: 1枚
終了時復元: 24.0 dBm
pytest: 234 passed
py .\src\utr_8ch_sequential_inventory_cli.py実行後、画面の指示に従って以下を入力します。
- COMポート番号またはCOM名。
- ボーレート。未入力なら 115200 bps。
- 変更前の使用アンテナ番号読み取り結果を確認する。
- 接続OKアンテナから、Inventory対象を
1、1,3、all、qで選択する。 - 表示された使用アンテナ番号設定フレームを確認する。
- 順次Inventoryを開始する場合は
yを入力する。 - ブザー通知の有無を選ぶ。
- PC+UII画面表示マスクの有無を選ぶ。
- 選択ANT一巡の繰り返し回数を入力する。
qでInventoryループを終了する。- 終了時に、開始前に読み取った使用アンテナ番号へ自動復元されることを確認する。
- Ctrl+C確認では、Inventory中断後に受信バッファクリアと自動復元再試行が行われることを確認する。
- 必要に応じて、8CH順次InventoryサマリをCSV/JSONへ保存する。
実機確認済みの例です。
接続OK: ANT1, ANT3
選択: all
選択順: ANT1 -> ANT3
Inventory実行回数: 4
合計読み取り枚数: 172 枚
ANT1: 読み取り 8 枚 / Inventory実行 2 回 / スキップ 0 回
ANT3: 読み取り 164 枚 / Inventory実行 2 回 / スキップ 0 回
開始前設定: ANT3/EXT5 / 使用アンテナ番号 44h
最後に使用したANT: ANT3
自動復元完了: ANT3/EXT5 / 使用アンテナ番号 44h
pytestを直接実行する場合:
py -m pytest開発チェックをまとめて実行する場合:
powershell -ExecutionPolicy Bypass -File scripts/dev_check.ps1コミットやPR前の確認を行う場合:
powershell -ExecutionPolicy Bypass -File scripts/git_preflight.ps1git_preflight.ps1 は git diff --check、状態確認、差分表示、直近ログ表示、dev_check をまとめて実行します。
- UHFリーダライタ開発者向け Quick Start
- 送信出力一時変更CLI 実機確認手順
- 送信出力一時変更つきInventory 実機確認手順
- アンテナ選択・順次Inventory確認メモ
- UTR-SUN02-8CH 複数アンテナ順次Inventory確認手順
- UTRRWManager 8CH設定とPython制御の対応メモ
- RSSI検証計画
- UTRRWManager比較テンプレート
- UHF Gen2 NACKエラー対応メモ
- USB実機確認メモ
- UHF Inventory応答解析メモ
USB実機通信を行う前に、UTRRWManagerなどで接続条件と機器状態を事前確認してください。
- COMポートが認識されていることを確認する。
- サンプル実行時のCOMポート選択では、表示された番号または
COM6のようなCOM名を入力できます。 - COMポート選択中に
qを入力すると、接続前に終了できます。 - UTRシリーズのデフォルト通信速度は 115200 bps です。サンプル実行時、ボーレート未入力なら 115200 bps を使用します。
- 19200 bps 設定の機器を使う場合は、ボーレート入力で
19200を明示入力してください。 - 機器設定を確認する。
- UTR機器の電源を確認する。
- アンテナ接続を確認する。
- RFタグを準備する。
- ROMバージョンを確認する。
- 送信出力設定を確認する。
- 送信出力値は
dBm * 10を LSB/MSB の順で解析します。例:F0 00は24.0 dBmです。 - 実機通信は、手順と接続条件を確認したうえで行う。
UHF_SET_INVENTORY_PARAMは自動送信しない。- Inventory結果は
inventory_results.txt、inventory_results.csv、inventory_results.jsonに保存されます。 - Inventoryを1回以上実行した場合は、タグ0枚でも結果を保存します。Inventory自体を実行していない場合は保存しません。
- CSVはExcelでの確認向け、JSONは後続処理やUTRRWManager結果との比較向けです。
- CSV/JSONには、取得できる場合は
antenna_number、antenna_label、antenna_descriptionも保存されます。 - 既存CSVのヘッダーが旧形式の場合は、旧CSVを
inventory_results_legacy_YYYYMMDD_HHMMSS.csvに退避し、新しいinventory_results.csvを現行ヘッダーで作成します。 inventory_results.txt、inventory_results.csv、inventory_results.json、inventory_results_legacy_*.csvはGit管理に入れないでください。- 8CH順次Inventoryサマリは
8ch_sequential_inventory_summary.csvと8ch_sequential_inventory_summary.jsonに保存できます。この2ファイルはGit管理に入れないでください。
標準入口では、Inventory前に送信出力を一時変更するか確認します。
送信出力をInventory中だけ一時変更しますか？ [y/N]: y
送信出力[dBm]: 20
この内容で一時変更してInventoryへ進みますか？ [y/N]: y
送信出力変更時の仕様は以下です。
- 変更対象はコマンドモード用パラメータです。
- FLASHは変更しません。
- 変更前に現在の送信出力値とキャリア関連時間を読み取ります。
- 変更用フレームと復元用フレームを生成します。
- 一時変更を確定した時点で、復元用フレームを保持します。
- 変更後に送信出力設定を読み戻します。
- 変更後読み戻し、Inventory、Ctrl+C、例外のいずれでも、可能な範囲で
finally側から元の送信出力へ復元します。 - Inventory終了時に元の送信出力へ復元します。
- 復元後にも送信出力設定を読み戻します。
実機確認済みの通常終了例です。
変更前: 24.0 dBm
一時変更後: 12.0 dBm
Inventory: 実行あり
復元後: 24.0 dBm
結果ファイルのPC+UII: マスク保存
未確認の項目です。
変更送信後、読み戻し例外が発生した場合のfinally復元
Inventory中にCtrl+Cした場合の送信出力復元
UTR-SUN02-4CHでは、アンテナ設定表示・接続チェックを実行すると、ANT0〜ANT3の接続状態を確認できます。
- ANT0: 内蔵アンテナ
- ANT1〜ANT3: 外付けアンテナ
- Inventory対象アンテナとして
0、1、0,1、allを入力できます。 - 複数アンテナ選択時は、同時使用ではなく、ANT0→ANT1のように順番に切り替えてInventoryします。
- アンテナ切替時もFLASHは変更しません。コマンドモード用パラメータだけを一時変更し、終了時に元の設定へ復元します。
- 8CH機はアンテナ番号体系が異なるため、4CH用の処理をそのまま流用しないでください。
UTR-SUN02-8CH / USM08では、専用CLIでANT1〜ANT8の接続状態を確認し、接続OKアンテナだけを順次Inventory対象にできます。
py .\src\utr_8ch_sequential_inventory_cli.py- UHF_CheckAntennaでは
00h〜07hが ANT1〜ANT8 に対応します。 - Inventory対象への一時切替時は、ANT1=
00h、ANT2=20h、ANT3=40h、ANT4=60h、ANT5=80h、ANT6=A0h、ANT7=C0h、ANT8=E0hを使います。 - 開始前に、変更前の使用アンテナ番号を読み取り、内部アンテナ番号と外部アンテナ番号を保持します。
- 開始前設定は、外部アンテナ番号
00h固定とは限りません。実機確認ではANT3/EXT5、使用アンテナ番号44hの例があります。 - 接続OKアンテナだけを候補表示します。
- Inventory対象アンテナとして
1、1,3、all、qを入力できます。 - 複数アンテナ選択時は、同時使用ではなく、ANT1→ANT3のように順番に切り替えてInventoryします。
- 使用アンテナ番号設定は、コマンドモード用パラメータだけへ送信します。FLASHは変更しません。
- NACKまたはACK/NACKなしの場合、そのANTはスキップします。
- 終了時は、開始前に読み取った使用アンテナ番号へ自動復元します。
- Ctrl+Cや例外時も、可能な範囲でシリアルクローズ前に自動復元を試みます。
- Ctrl+C直前のInventory応答が受信バッファに残る場合があるため、復元前に受信バッファをクリアします。
- 復元応答としてACK/NACK以外を受信した場合、同じ復元フレームを1回だけ再送します。
公開前に、以下の情報が含まれていないことを確認してください。
- 実IP
- 顧客名
- シリアル番号
- 未マスクの実測ログ
- 実測PC/UII または PC/EPC
- 認証情報、APIキー、トークン、パスワード
実機ログが必要な場合は、公開しても問題ないようにマスクした内容だけを使ってください。
共有用の例:
PC+UII: 省略
RSSI: -xx.x dBm
- 送信出力一時変更中のCtrl+C時の復元確認を追加する。
- 変更送信後、読み戻し例外発生時の復元確認方法を検討する。
- ANT別の平均RSSI、最小RSSI、最大RSSI、読み取り成功率を集計する。
- UTRRWManager側ログとPython側ログを比較する。
- NACK/応答なし発生時のANT別エラー集計を強化する。
- Ctrl+Cや応答なしなど、異常終了時の実機確認結果を追加する。
- 実機確認結果を踏まえて、サンプルとドキュメントを継続更新する。
このリポジトリのソースコードは MIT License の下で公開されています。詳細は LICENSE を確認してください。