`orbitforge waveform generate`

Synopsis


orbitforge waveform generate --standard <STD> --iq <PATH> [OPTIONS]

Description

Produces a standards-conformant modulated waveform and writes it as complex IQ samples. Use it to feed a receiver under test, to verify a demodulator against a known-good signal, or to build a reference capture that a Doppler profile can later be applied to.

Three standards are supported, and each takes a different set of options because they are genuinely different signals.

`--standard`	Standard	Typical use
`ccsds-tm`	CCSDS TM sync and channel coding, 131.0-B	Spacecraft telemetry downlink
`ccsds-tc`	CCSDS TC BCH and CLTU, 231.0-B	Spacecraft telecommand uplink
`dvbs2`	DVB-S2 PLFRAMEs, EN 302 307-1	Broadband and broadcast downlink

Options

Common.
Parameter	Type	Unit	Default	Required	Description
`--standard`	enum	n/a	—	Yes	`ccsds-tm`, `ccsds-tc`, or `dvbs2`.
`--iq`	path	n/a	—	Yes	Output IQ file path.
`--sps`	integer	samples/symbol	`4`	No	Samples per symbol. Sets oversampling of the pulse-shaped output.
`--roll-off`	float	n/a	`0.35`	No	Root-raised-cosine roll-off factor.
`--sample-rate-hz`	float	Hz	`32000`	No	Sample rate recorded in the SigMF metadata. Descriptive, not resampling.
`--seed`	integer	n/a	—	No	Seed for the random payload bits, so a capture is reproducible.

DVB-S2 only.
Parameter	Type	Unit	Default	Required	Description
`--modcod`	string	n/a	`qpsk-1/2`	No	MODCOD name, for example `qpsk-1/2` or `8psk-3/4`.
`--frame-size`	enum	n/a	`short`	No	`normal` for the 64,800-bit FECFRAME, `short` for 16,200 bits.
`--pilots`	flag	n/a	—	No	Insert pilot blocks, which aid carrier recovery at the cost of capacity.

CCSDS TM only.
Parameter	Type	Unit	Default	Required	Description
`--frames`	integer	count	`1`	No	Number of TM transfer frames.
`--rs-interleave`	integer	n/a	`1`	No	Reed-Solomon interleave depth, 1 to 5. Deeper interleaving spreads burst errors across codewords.
`--conv`	flag	n/a	—	No	Concatenate the K=7 convolutional code.
`--modulation`	enum	n/a	`qpsk`	No	`bpsk` or `qpsk`. TC is always BPSK.

CCSDS TC only.
Parameter	Type	Unit	Default	Required	Description
`--frame-bytes`	integer	bytes	`56`	No	TC frame length, zero-padded to 7-byte blocks.

Worked example

Two DVB-S2 frames at QPSK rate 1/2:


orbitforge waveform generate \
  --standard dvbs2 \
  --modcod qpsk-1/2 \
  --frames 2 \
  --iq iq.bin


Wrote 65680 samples (cf32_le) -> iq.bin

The file is 525,440 bytes: 65,680 samples at 8 bytes each, since cf32_le is a pair of little-endian 32-bit floats per sample.

Output format

Property	Value
Format	`cf32_le`, interleaved complex 32-bit float, little endian
Bytes per sample	8
Ordering	I, Q, I, Q
Metadata	SigMF, recording the sample rate and format

cf32_le is the common interchange format for software-defined radio tooling, so the output loads directly into GNU Radio, SigMF-aware analysis tools, and most laboratory receivers.

--sample-rate-hz is recorded in metadata and does not resample the signal. The actual sample rate is determined by your symbol rate and --sps. Set it to describe the rate you intend to play the capture out at, so downstream tools interpret the timing correctly.

Samples per symbol and roll-off

--sps 4 produces four samples per symbol, which is enough to represent a root-raised-cosine pulse without aliasing and is the usual default for simulation. Higher values give a smoother waveform and a proportionally larger file; the sample count scales linearly.

--roll-off 0.35 is the classic DVB-S2 value. Lower roll-off uses less bandwidth and produces a signal with higher peak-to-average ratio, which stresses the amplifier. It is a real trade, not a cosmetic setting.

Reproducibility

--seed fixes the random payload bits. The same seed produces a byte-identical capture, which is what makes a regression test possible: generate, run the receiver, and compare against a stored expectation.

Change the seed to test against different payload content, which matters because some framing failures only appear on particular bit patterns.

Adding impairments

The generated capture is clean by construction. Real testing needs impairments, applied as separate steps:

Impairment	Applied by
Pass Doppler	`waveform doppler-apply`
Noise, and the resulting error rate	`waveform ber`
Decoder threshold in noise	`waveform thresholds`

Keeping generation and impairment separate means the same reference capture can be reused across many test conditions, and a failure can be attributed to the impairment rather than to the signal.

orbitforge waveform generate