RedPitaya ビットストリーム設定仕様書

概要

このドキュメントは、RedPitaya アイスレーダシステムで使用するビットストリーム設定とデータフォーマットの仕様を定義します。

設計思想

1 ビットストリーム 1 設定: 各ビットストリームタイプごとに独立した JSON 設定ファイル
ヘッダレス設計: データファイルにはヘッダを含めず、設定ファイルがデータフォーマットを定義

対応するビットストリームをロードし、設定ファイルを読みこむ。

ビットストリームはパラメータを可変にすると挙動が不安定になることもあるため、ユースケースを絞ってビットストリームを用意する。

自分でビットストリームを用意した場合は、同名の設定ファイルを作って保存する。

システム構成

observe -b {bitstream_id} -c {count}
    ↓
{bitstream_id}.bit.bin ロード
{bitstream_id}.json 読み込み
    ↓
設定に基づいてデータを取得
    ↓
識別子付きファイル名でデータ保存

プリセットのビットストリームタイプ

250-12-raw-32: SIGNALLab250-12、32 回生データ
125-14-raw-8: STEMLab125-14、8 回生データ
250-12-sum-128-20: SIGNALLab250-12、128 回積算、データ幅 20bit
125-14-sum-64-20: STEMLab125-14、64 回積算、データ幅 20bit

ファイル構成

ビットストリームとその設定ファイルは規定の場所に配置する。

redpitaya/
├── observe.c
├── bitstreams/
│   ├── 250-12-raw-32.bit.bin    # ビットストリームファイル
│   ├── 250-12-raw-32.json       # 設定ファイル
│   └── ...
└── Makefile

ビットストリーム: redpitaya/bitstreams/{bitstream_id}.bit.bin
設定ファイル: redpitaya/bitstreams/{bitstream_id}.json
ペア管理: 同名のファイルが必ずペアで存在

作成済みビットストリームのダウンロード

作成済みのビットストリームについてはダウンロードすることが可能。

ダウンロードスクリプト

# 個別ダウンロード
./scripts/download_bitstream.sh {bitstream_id}

# プリセット全体ダウンロード
./scripts/download_bitstream.sh preset

使用例

# 250-12-raw-32 のみダウンロード
./scripts/download_bitstream.sh 250-12-raw-32

# 現在定義されているプリセット全体をダウンロード
./scripts/download_bitstream.sh preset

ダウンロード元

S3 バケット: iceradar-redpitaya-fpga-proto-bitstreams
リージョン: ap-northeast-1
ファイル名: {bitstream_id}.bit.bin, {bitstream_id}.json

設定ファイル仕様

各ビットストリームには対応する JSON 設定ファイルが必要です。

250-12-raw-32.json の例:

{
  "device_type": "250-12",
  "sampling_freq_hz": 250000000,
  "adc_bits": 12,
  "bitstream_path": "/root/rp-fpga-project/bitstreams/250-12-raw-32.bit.bin",
  "fpga_type": "raw",
  "voltage_scale_v": 20,
  "trigger_source": "TRIG_SRC_EXT",
  "cycle_count": 32,
  "output_file_count": 32,
  "data_mask": "0xFFF",
  "data_width_bytes": 2,
  "data_bits": 12,
  "data_points": 8191,
  "data_start_after_trigger": 1
}

プロパティ詳細

デバイス情報

device_type: デバイス識別子
"250-12": SIGNALLab250-12（250MHz, 12bit ADC）
"125-14": STEMLab125-14（125MHz, 14bit ADC）
sampling_freq_hz: サンプリング周波数（Hz 単位）
250-12: 250,000,000 Hz
125-14: 125,000,000 Hz
adc_bits: ADC 量子化ビット数
RedPitaya ハードウェアの物理的な ADC ビット数
250-12: 12bit、125-14: 14bit

FPGA ビットストリーム設定

bitstream_path: ビットストリームファイルの絶対パス
/root/rp-fpga-project/bitstreams/{bitstream_id}.bit.bin形式
observe.c がこのパスからビットストリームを読み込む
fpga_type: FPGA 内データ処理方式
"raw": 生データ保存（BRAM 使用）
"sum": 積算処理（S/N 比向上）
"fft": FFT 処理（周波数解析、将来実装予定）

計測設定

voltage_scale_v: 電圧スケール（V 単位）
データ解析時の電圧変換に使用
典型値: 1V（低ゲイン）、20V（高ゲイン）
trigger_source: トリガ信号ソース
"TRIG_SRC_EXT": 外部トリガ（推奨）
"TRIG_SRC_CHB": チャンネル B トリガ
"TRIG_SRC_CHA": チャンネル A トリガ

データ構造情報

cycle_count: FPGA 処理サイクル数
生データ: BRAM 容量で決まる保存サイクル数
積算: 積算回数（S/N 比向上に直結）
output_file_count: 出力ファイル数
生データ: cycle_count と同値（サイクルごとに 1 ファイル）
積算: 1（全サイクル積算した 1 ファイル）
data_mask: データ抽出用ビットマスク（16 進文字列）
生データ: ADC ビット数に対応（12bit="0xFFF", 14bit="0x7FFF"）
積算: 拡張ビット数に対応（20bit="0xFFFFF"）
data_width_bytes: 1 データポイントのバイト数
生データ: 2 バイト（ADC の 14bit 以下を 16bit で格納）
積算: 4 バイト（20bit 以上のデータを 32bit で格納）
data_bits: 実際の有効データビット数
生データ: ADC ビット数（adc_bits と同値）
積算: 拡張ビット数（積算により増加、典型値 20bit）
data_points: 1 サイクルあたりのデータポイント数
典型値: 8191 ポイント（RedPitaya のバッファサイズ制約）
data_start_after_trigger: トリガ後のデータ開始位置
典型値: 1（トリガ直後から記録開始）