FIrs

Docs/SineArrayGAM.md

@@ -0,0 +1,104 @@
+# SineArrayGAM
+
+`SineArrayGAM` is a helper GAM bundled with the UDPStreamer library. It fills a `float32`
+output array with a continuous sinusoidal waveform, maintaining phase continuity across
+RT cycles. It is intended for testing and demonstrating the UDPStreamer's packed-burst
+signal capability.
+
+> **Library:** The class is compiled into `UDPStreamer.so` alongside the UDPStreamer
+> DataSource. A `SineArrayGAM.so → UDPStreamer.so` symlink is required for MARTe2's
+> auto-loader (created automatically by `Test/MARTeApp/run.sh`).
+
+---
+
+## Configuration
+
+```
++Ch1GAM = {
+    Class        = SineArrayGAM
+    Frequency    = 1000.0       // Signal frequency [Hz]  (default: 1.0)
+    Amplitude    = 1.0          // Peak amplitude           (default: 1.0)
+    Offset       = 0.0          // DC offset                (default: 0.0)
+    Phase        = 0.0          // Initial phase [radians]  (default: 0.0)
+    SamplingRate = 1000000.0    // Sample rate [Hz]         (default: 1000000.0)
+                                //   Must match the SamplingRate declared in the
+                                //   UDPStreamer signal config.
+
+    OutputSignals = {
+        Ch1 = {
+            DataSource       = DDB
+            Type             = float32
+            NumberOfDimensions = 1
+            NumberOfElements = 1000   // N samples per RT cycle
+        }
+    }
+}
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `Frequency` | float64 | 1.0 | Signal frequency in Hz |
+| `Amplitude` | float64 | 1.0 | Peak amplitude (half peak-to-peak) |
+| `Offset` | float64 | 0.0 | DC offset added to every sample |
+| `Phase` | float64 | 0.0 | Phase shift in radians |
+| `SamplingRate` | float64 | 1 000 000.0 | Sample rate in Hz; must be > 0 |
+
+### Output signal
+
+Exactly **one** output signal of type **`float32`** is required. The signal must have
+`NumberOfDimensions = 1` and `NumberOfElements = N` where N ≥ 1.
+
+---
+
+## Waveform formula
+
+Each `Execute()` call fills elements `[0 .. N-1]` using:
+
+```
+v[k] = Amplitude × sin(2π × Frequency × (offset_total + k) / SamplingRate + Phase) + Offset
+```
+
+where `offset_total` is a cumulative sample counter that increments by `N` after each call.
+This guarantees a gapless, phase-continuous waveform across RT cycles.
+
+---
+
+## Bandwidth and fragmentation
+
+For a 1 MSps burst at 10 kHz RT rate with 1000 samples per cycle:
+
+```
+N = SamplingRate / RT_rate = 1 000 000 / 1000 = 1000 samples per cycle
+Wire bytes = 1000 × 4 (float32) = 4000 B per channel per cycle
+At 10 kHz: 4000 × 10 000 = 40 MB/s raw (UDP, before quantization)
+```
+
+Using `QuantizedType = uint16` halves the wire bandwidth to 20 MB/s.
+With `MaxPayloadSize = 1400` the 4 000-byte payload spans 3 UDP datagrams
+(`ceil(4008 / 1383) = 3`).
+
+---
+
+## Example: two-channel quadrature pair
+
+```
++Ch1GAM = {
+    Class = SineArrayGAM
+    Frequency = 1000.0; Amplitude = 1.0; Phase = 0.0; SamplingRate = 10000000.0
+    OutputSignals = {
+        Ch1 = { DataSource = DDB; Type = float32; NumberOfDimensions = 1; NumberOfElements = 1000 }
+    }
+}
+
++Ch2GAM = {
+    Class = SineArrayGAM
+    Frequency = 1000.0; Amplitude = 1.0; Phase = 1.5708; SamplingRate = 10000000.0
+    OutputSignals = {
+        Ch2 = { DataSource = DDB; Type = float32; NumberOfDimensions = 1; NumberOfElements = 1000 }
+    }
+}
+```
+
+This produces two signals 90° out of phase, useful for verifying IQ-style signal chains.