Skip to content

README_ja.md

Latest commit

 

History

History
281 lines (205 loc) · 7.46 KB

README_ja.md

File metadata and controls

281 lines (205 loc) · 7.46 KB

RSPdx-R2 Python Control Plan

このリポジトリは、SDRplay RSPdx-R2 ハードウェアを Python から扱うための ctypes ベースのラッパと、AI-CW-Decoder 連携用のIQ exportを管理します。

参照

前提

  • 対象ハードウェアは SDRplay RSPdx-R2。
  • SDRplay API は 3.15 以上が必要。
  • SDRplay API とネイティブ共有ライブラリはインストール済みであること。
  • Python 側は ctypes で SDRplay API を呼び出す。
  • 初期対象は RSPdx-R2 1台、単一チューナ運用。

Architecture

RSPdx-R2 hardware
↓
SDRplay API 3.15
↓
rspdx_r2 ctypes wrapper
↓
capture_iq()
iter_iq_chunks()
↓
capture.json / capture.npy / capture.raw / SigMF
↓
AI-CW-Decoder

現在の機能

  • device discovery
  • configure()
  • capture_iq()
  • realtime iter_iq_chunks()
  • npy export
  • raw export
  • metadata export
  • SigMF metadata export
  • inspect_capture.py
  • analyze_capture.py

インストール

前提: SDRplay API は別途インストールしてください。

macOS downloads:

https://www.sdrplay.com/downloads/

このPython wrapperはeditable modeでインストールできます。

pip install -e .

このプロジェクトは以下を再配布しません。

  • SDRplay API binaries
  • SDRplay API headers
  • SDK packages
  • installers

SDRplay API Dependency

このプロジェクトは SDRplay API を外部runtime dependencyとして使用します。

  • Python ctypes wrapper projectです。
  • SDRplay API runtime が必要です。
  • SDRplay hardware が必要です。
  • SDRplay API は別途インストールしてください。

Official SDRplay website:

https://www.sdrplay.com/

Downloads:

https://www.sdrplay.com/downloads/

API Documentation:

https://www.sdrplay.com/docs/

dependency relationship:

RSPdx-R2 hardware
↓
SDRplay API runtime
↓
rspdx_r2 Python wrapper
↓
capture / realtime streaming / export

このリポジトリには、オリジナルのPython codeのみを含めます。

以下は再配布しません。

  • SDRplay API binaries
  • SDRplay API headers
  • SDRplay SDK packages
  • SDRplay installers
  • SDRplay trademarks

利用者は SDRplay API を SDRplay Ltd から直接入手してください。

macOS導入例:

  1. SDRplay API を以下からインストールします。

    https://www.sdrplay.com/downloads/

  2. インストール内容を確認します。

    find /Library/SDRplayAPI \
  -iname "*license*" \
  -o -iname "*readme*"

  3. API runtime を確認します。

    python examples/api_version.py

  4. ハードウェア検出を確認します。

    python examples/list_devices.py

CLI例

python examples/api_version.py
python examples/list_devices.py
python examples/capture_iq.py --center-hz 100000000 --sample-rate 2000000 --duration-sec 1 --out capture.npy

安全なデフォルト

  • OS設定変更は行わない。
  • サービスの開始・停止・再起動は行わない。
  • 生成コードやexampleで sudo を使わない。
  • Bias-T はデフォルト無効。
  • HDR は明示指定がない限り無効。
  • 通常終了、例外、Ctrl-C のいずれでもAPIリソースを解放する。
  • SDRplay callback内では重い処理をせず、queue/ring bufferへ渡すだけにする。

AI-CW-Decoder Export Format

examples/capture_iq.py は RSPdx-R2 のIQ captureを次のファイル群として保存します。

  • capture.npy: NumPy complex64 IQ samples。
  • capture.raw: signed 16-bit の interleaved IQ raw data。
  • capture.json: capture metadata とファイル参照。

capture.json が読み込み入口です。AI-CW-Decoder側は capture.json を受け取り、 metadataを検証してから参照先のIQデータを読み込みます。

AI-CW-Decoder側は、export_format に complex64_npy が含まれ、npy_path が 存在する場合は npy_path を優先して読みます。npy_path がない場合のみ raw_path から復元します。

Metadata Schema

必須キー:

  • schema_version: "rspdx-r2-capture-v1"。
  • source: "rspdx-r2"。
  • export_format: export形式のリスト。例: ["complex64_npy", "interleaved_int16_iq"]。
  • center_hz: RF center frequency in Hz。
  • sample_rate_hz: sample rate in Hz。
  • duration_sec: requested capture duration in seconds。
  • antenna: selected antenna。通常 "A", "B", "C"。
  • sample_count: complex IQ sample数。
  • dtype: .npy exportの期待dtype。
  • npy_path: .npy export path、または null。
  • raw_path: .raw export path、または null。
  • raw_format: 現在は "interleaved_int16_iq"。
  • iq_order: 現在は "I,Q"。
  • created_by: producer identifier。

相対パスの npy_path / raw_path は、capture.json の親ディレクトリ基準で解決します。

Format Details

complex64_npy:

  • np.load(path) で読む。
  • dtype は complex64。
  • shape は (sample_count,)。

interleaved_int16_iq:

  • np.fromfile(path, dtype=np.int16) で読む。
  • 配列順は I0,Q0,I1,Q1,...。
  • 要素数は sample_count * 2。
  • complex64 復元:
    • real = raw[0::2]
    • imag = raw[1::2]

AI-CW-Decoder Integration

AI-CW-Decoder側は capture.json を標準の入口として読みます。

AI-CW-Decoder利用者も SDRplay API を別途インストールしてください。この リポジトリはSDRplay SDKをvendorしません。保存済みIQ exportの連携入口は capture.json です。

推奨順序:

  1. capture.json を読む。
  2. "complex64_npy" が export_format に含まれる場合は npy_path を使う。
  3. それ以外の場合は raw_path からIQを復元する。
  4. 次を検証する:
    • schema_version
    • source
    • sample_count
    • raw_format
    • iq_order
  5. 得られたIQ ndarray をdecoderへ渡す。

Realtime API Example

AI-CW-Decoder のrealtime integrationでは、保存済みファイルではなく iter_iq_chunks() を利用できます。

with RspDxR2Device() as dev:
    dev.open()
    dev.select_rspdx_r2()
    dev.configure(config)

    for chunk in dev.iter_iq_chunks(
        duration_sec=3,
        chunk_samples=8192,
    ):
        process(chunk)

ライセンス注意事項

  • このリポジトリ内のコードは MIT License の対象です。
  • SDRplay SDK/API は別のproprietary dependencyです。
  • ユーザーは SDRplay API を SDRplay Ltd から別途インストールする必要があります。
  • このリポジトリには、オリジナルのPython wrapper codeのみを含めます。
  • SDRplay API binaries, libraries, headers, installers, SDK packages, trademarks は SDRplay Ltd に帰属し、このリポジトリでは再配布しません。

公開前セルフチェック

生成captureファイルがignoreされることを確認します。

git check-ignore -v \
capture.raw \
capture.sigmf-meta \
capture.json

proprietaryなSDRplay artifactがtrackされていないことを確認します。

git ls-files | grep -Ei \
"sdrplay|\.dylib$|\.so$|sdk|installer|header"

期待結果: SDRplay API binary, header, SDK archive, installer file が このリポジトリにtrackされていないこと。