Build Your Own Block
A block is one operation in a MOSAIC pipeline. It receives data from the block connected before it, does some work, and sends a result to the blocks connected after it. In this tutorial you will add a block called Gain that multiplies numbers.
With a gain of 2.5, the input [1, -2, 0] becomes [2.5, -5, 0]. The original input
stays unchanged. MOSAIC already has a Function block that can multiply; we use this
small operation here so you can concentrate on how to add your own code.
Before you begin
You need basic C# knowledge (classes, methods and properties), but no previous experience writing MOSAIC blocks. You also need a source checkout and a working .NET 10 development setup. Follow Getting Started to run the app. If you have never used MOSAIC, first run Your First Pipeline: it shows how to open a configuration, start the Clock and find a plot.
These words will appear throughout the tutorial:
| Word | Meaning here |
|---|---|
| Pipeline | Connected blocks that pass data from one operation to the next. |
| Model | The C# class that performs a block's work. |
| Vector | A list of channel values at one instant, such as [1, -2, 0]. The C# type is Vector<double>. |
| Palette | The searchable list of blocks you can drag into a pipeline. |
| Card | A block's controls and plots in the workbench. |
| JSON configuration | A text file describing which blocks to create, their settings and their connections. |
The repository root is the outer folder containing README.md, Documentation
and MOSAIC. Your block's source files belong inside MOSAIC/MOSAIC/.
All C# and AXAML paths below are relative to that shared application folder. AXAML
is the markup used to lay out Avalonia controls, much like HTML lays out a web page.
You will make three required edits: add the model, register how to create it, and add its palette description. Step 5 runs a complete example and displays the result using an existing card. You can stop there. Steps 6 and 7 add your own controls and plots. The teaching Gain block is not shipped as a registered block; you add it during this tutorial.
1. Understand the pieces
| Edit | File | Why it is needed |
|---|---|---|
| Add the processing model | Models/SignalProcessing/GainBlock.cs |
Defines what happens to incoming numbers. |
| Register construction | Components/Factory/BlockFactory.cs |
Lets MOSAIC create your class when JSON says "Type": "gainblock". |
| Add the palette entry | Components/Factory/BlockCatalog.cs |
Gives the block a name, description and Gain field in the add-block dialog. |
Think of the factory as the list of instructions for creating blocks, and the catalogue as the list shown to users. Adding a class alone does not add it to either list. You will edit each file in order below; no changes to the graph builder are needed.
There are three names to keep track of:
GainBlockis the C# class you create.gainblockis the type key stored in JSON and used by the factory and catalogue.Gainis its palette label. A particular instance can have its own name, such asAmplify.
For example, a block named Amplify with "Type": "gainblock" is one instance of
GainBlock. Its name is how other blocks refer to it in their Inputs lists.
MOSAIC already handles connections, delivery of data and recording. A normal
one-input block inherits those features from BaseBlock; you only write your operation
and its settings. A ViewModel and card are optional and come later.
2. Write the processing model
Download GainBlock.cs and copy it to
Models/SignalProcessing/GainBlock.cs. The code displayed below is included directly
from that file, which is compiled by the documentation tests:
using System;
using System.Collections.Generic;
using System.Threading;
using MathNet.Numerics.LinearAlgebra;
using Microsoft.Extensions.DependencyInjection;
using MOSAIC.Components.Basics;
namespace MOSAIC.Models.SignalProcessing;
/// <summary>Multiplies every element of an incoming vector by a scalar gain.</summary>
/// <remarks>
/// Accepts one Vector<double> input and publishes a new vector of the same length.
/// Params[0] is the gain (default 1.0). Negative and zero gains are allowed.
/// Other payload types are ignored.
/// </remarks>
/// <example>
/// <code language="json">
/// {
/// "Amplify": {
/// "Type": "gainblock",
/// "Inputs": ["Signal"],
/// "Params": [2.5]
/// }
/// }
/// </code>
/// <para>Signal must name an upstream vector-producing block. Params[0] is the gain.</para>
/// </example>
public sealed class GainBlock : BaseBlock
{
#region Settings
private double _gain;
/// <summary>The multiplier currently used by the processing code.</summary>
public double Gain => Volatile.Read(ref _gain);
/// <summary>Applies a finite gain. Zero and negative values are allowed.</summary>
public void SetGain(double gain)
{
if (!double.IsFinite(gain))
throw new ArgumentOutOfRangeException(nameof(gain), "Gain must be finite.");
Volatile.Write(ref _gain, gain);
}
#endregion
#region Construction
public GainBlock(string name, double desiredRate = 0, double gain = 1.0)
: base(name, desiredRate)
{
SetGain(gain);
}
#endregion
#region Processing
protected override void OnReceive(object sender, object value)
{
if (value is not Vector<double> input)
{
ReportError("Gain requires a numeric vector.");
return;
}
ClearError();
// Read once so every channel uses the same gain.
double gain = Gain;
var output = input.Multiply(gain);
Publish(output);
}
#endregion
#region JSON configuration
public static GainBlock ConfigureInput(IServiceProvider sp, JsonModel m)
{
double gain = m.Params is { Count: > 0 }
? JsonModel.GetDouble(m.Params[0], 1.0)
: 1.0;
return ActivatorUtilities.CreateInstance<GainBlock>(
sp, m.Name ?? "Gain", m.DesiredRate ?? 0d, gain);
}
protected override string JsonTypeName => "gainblock";
protected override IReadOnlyList<object>? GetJsonParams()
=> new object[] { Gain };
#endregion
}
The class is grouped into four sections: Settings holds the gain and its validation;
Construction sets its starting value; Processing contains the operation;
JSON configuration loads and saves the settings. The #region markers let you
collapse these sections in your editor; they do not change how the code runs.
Read the example from input to output
Each time data arrives, MOSAIC calls OnReceive(sender, value). sender identifies
the upstream block; value contains the data. Follow these steps in the method:
- Check that
valueis a vector. An unexpected type is rejected without publishing. - Read the current gain once, so all channels use the same setting.
- Create a new vector with
input.Multiply(gain). - Call
Publish(output)to send that result downstream. Recording, when enabled, also receives the published result.
An unexpected payload calls ReportError and publishes nothing. The next valid vector
calls ClearError before processing, which is the current shared diagnostic pattern.
Leave Status to BaseBlock. It updates status and the displayed frequency
automatically from publication activity and the expected rate. You do not need to
set BlockStatus.Normal after processing or BlockStatus.Stumbling when rejecting
an input. In this example an unsupported input simply produces no output. The status
indicator reports runtime activity; it is not a validation result for each value.
The remaining members connect that operation to settings and saved files:
| Member | Why it is in this example |
|---|---|
| Constructor | Receives the instance name, rate and starting gain. |
Gain / SetGain |
Read the setting and apply a new finite value. A finite value excludes NaN and infinity. |
ConfigureInput |
Reads Params[0] from JSON and creates the instance. If no gain is supplied, it uses 1.0. |
JsonTypeName |
Saves the stable key gainblock, so the same type can be loaded again. |
GetJsonParams |
Saves the current gain back into the first parameter position. |
C# lists start at index zero: Params[0] means the first value. The base class
already exports the common fields such as name, input connections and rate.
For a block without settings, you can leave GetJsonParams out entirely.
IServiceProvider supplies application services to constructors that need them.
ActivatorUtilities.CreateInstance combines those services with the explicit values
passed here. Gain has no extra service dependencies; keep this construction pattern
when adapting the example.
Checkpoint: the new file declares GainBlock in MOSAIC.Models.SignalProcessing.
It does not appear in the palette yet; the next two edits make MOSAIC aware of it.
3. Register construction in BlockFactory
In Components/Factory/BlockFactory.cs, find the ResolveRegistration method and its list of type keys. Add this case before
the final _ => throw UnknownBlockType(m) line:
"gainblock" or "mosaic.models.signalprocessing.gainblock"
=> (typeof(GainBlock), () => GainBlock.ConfigureInput(sp, m)),
The existing file imports MOSAIC.Models.SignalProcessing; add that import if it
is absent in your checkout. The factory trims and lowercases incoming type keys.
Keep the exported JsonTypeName supported even if you later change the display name.
The text on the left lists accepted JSON type keys. On the right, typeof(GainBlock)
lets the loader check connections before constructing the block. The function after it
calls your ConfigureInput method when construction is needed. The full class-name alias is optional; the short
gainblock key is the one used throughout this tutorial.
Checkpoint: MOSAIC can now create the block from JSON after rebuilding. The palette entry is the next edit.
4. Add the catalogue description and parameters
In Components/Factory/BlockCatalog.cs, add this entry inside Build(),
alongside the other signal-processing blocks:
new("gainblock", typeof(GainBlock), "Gain", BlockCategory.SignalProcessing,
"Scales every channel of a vector by a gain; preserves channel count.",
[new("Gain", ParamKind.Double, 1.0)]),
The entry says: use the key gainblock, create a GainBlock, show the label Gain
in Signal Processing, and offer one numeric field with a default of 1.0.
The description helps users find and understand it. typeof(GainBlock) refers to
your C# class; the key must match the factory case you just added.
This catalogue entry is also the complete drag-and-drop registration. The palette reads
BlockCatalog.All, and the canvas uses generic handlers for every descriptor. Do not add
a Gain-specific row to palette AXAML or a Gain-specific drag handler to GraphCanvas.
For this example, there is exactly one parameter:
| Index | Dialog label | Kind | Default | Read by | Exported from |
|---|---|---|---|---|---|
| 0 | Gain | Double | 1.0 | ConfigureInput |
Gain |
Keep the dialog field, JSON reader and exporter in the same order. A label in the
dialog does not implement the behavior; SetGain and OnReceive do that work.
Block Catalogue Registration explains every descriptor field, conditional parameters, descriptions, and platform guards.
5. Try the block in a pipeline
Build and start your edited application
Close the running desktop app before rebuilding. Open a terminal at the repository root and enter the solution folder once:
cd MOSAIC
dotnet run --project MOSAIC.Desktop/MOSAIC.Desktop.csproj -f net10.0
dotnet run builds the edited source and starts the application. The generic desktop
target is enough for this hardware-free example. If you already use a platform target
from Getting Started, you can keep using that build/run command.
A build error mentioning GainBlock usually means the file, namespace or registration
needs checking; fix the first error before opening the pipeline.
Load a complete example
Download gain-pipeline.json, or save the
JSON below in a new text file called gain-pipeline.json (not .json.txt).
Open it in MOSAIC with File → Open or the folder button.
It will load only after you have added the model and factory case above.
Clock → Signal → Amplify → Check
your existing Function block
block used to display its output
{
"Clock": { "Type": "clock", "DesiredRate": 100 },
"Signal": {
"Type": "singenerator",
"Inputs": ["Clock"],
"Params": [1, 1.0, 1.0, 0.0, 0.0, 1]
},
"Amplify": {
"Type": "gainblock",
"Inputs": ["Signal"],
"Params": [2.5]
},
"Check": {
"Type": "function",
"Inputs": ["Amplify"],
"Params": ["multiply", 1.0]
}
}
| Block | What this configuration asks it to do |
|---|---|
Clock |
Send 100 ticks per second. |
Signal |
Generate one channel: amplitude 1, frequency 1 Hz, one sample per tick. Its parameters are component count, amplitude, frequency, phase, phase step and scans per packet. |
Amplify |
Apply your gain of 2.5 to each received value. |
Check |
Use the existing Function block to multiply by 1, leaving the result unchanged. Its existing card lets you plot the result. |
The Clock's 100 ticks/s controls sample delivery. The sine's 1 Hz means one full wave cycle per second. These are different settings.
See whether it works
- Open the block controls on the left and press Play on the Clock card.
- Open Signal and show its Scope. Its values should range approximately from -1 to 1.
- Open Check and show its Scope. Its values should range approximately from -2.5 to 2.5, with the same one-second cycle. Compare the axis numbers: automatic scaling can make different amplitudes look equally tall.
- Pause the Clock. Change Amplify's JSON
Paramsto[0], reopen the file and press Play. Check should now show zero. Restore[2.5]afterwards.
Amplify itself shows the class name until you add a custom card. That is expected; its processing works independently of its display. The Check block lets you confirm this before doing any UI programming.
Check the palette too
Pause the Clock, open the right-hand palette and search for Gain. Drag it onto the canvas, choose a different instance name, enter the gain and confirm. Connect Signal's bottom output port to the new block's top input port in build mode. The add-block dialog creates the block; you draw its connections afterwards.
Checkpoint: you have implemented, registered and run your own block. You can stop here and use JSON or the add-block dialog to choose its starting gain. Continue only if you want to adjust that gain from a card while the app is open.
6. Add an optional control card
The card has a slider and an Apply button. It needs a ViewModel, a small class holding the values and commands shown by the controls. The model continues to do the processing. Moving the slider changes a draft value; pressing Apply sends that value to the model. This keeps a partially edited setting from taking effect.
You will add three files and one selector case. Do not put processing code in these files.
Create ViewModels/SignalProcessing/GainViewModel.cs:
Download GainViewModel.cs and copy it to the path above.
using System;
using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;
using MOSAIC.Models.SignalProcessing;
namespace MOSAIC.ViewModels.SignalProcessing;
public sealed partial class GainViewModel : ObservableObject
{
private readonly GainBlock _block;
public GainBlock Block => _block;
[ObservableProperty]
private double _gain;
[ObservableProperty]
private string _message = string.Empty;
public GainViewModel(GainBlock block)
{
_block = block ?? throw new ArgumentNullException(nameof(block));
_gain = _block.Gain;
}
[RelayCommand]
private void Apply()
{
if (!double.IsFinite(Gain))
{
Message = "Enter a finite gain.";
return;
}
Block.SetGain(Gain);
Message = $"Applied gain: {Block.Gain:G}";
}
}
The attributes above generate the bindable Gain and Message properties and
ApplyCommand during compilation. Keep the class partial; do not write the
generated members yourself.
Create Views/Cards/SignalProcessing/GainCardView.axaml:
Download GainCardView.axaml and copy it to the path above.
<cards:PopoutCardBase
xmlns="https://github.com/avaloniaui"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:cards="clr-namespace:MOSAIC.Views.Cards"
xmlns:controls="clr-namespace:MOSAIC.Controls;assembly=MOSAIC"
xmlns:converters="clr-namespace:MOSAIC.Converters;assembly=MOSAIC"
xmlns:vm="clr-namespace:MOSAIC.ViewModels.SignalProcessing"
x:Class="MOSAIC.Views.Cards.SignalProcessing.GainCardView"
x:DataType="vm:GainViewModel">
<cards:PopoutCardBase.Resources>
<converters:StatusToColorConverter x:Key="StatusToColor"/>
</cards:PopoutCardBase.Resources>
<Border Classes="card" MinHeight="220">
<StackPanel Spacing="12">
<Grid ColumnDefinitions="*,Auto">
<StackPanel Grid.Column="0" Spacing="3">
<StackPanel Orientation="Horizontal" Spacing="8">
<TextBlock Classes="cardTitle" Text="{Binding Block.Name}"/>
<Border Background="{StaticResource CategorySignalProcessingBrush}"
CornerRadius="4" Padding="6,2">
<TextBlock Text="GAIN" FontSize="10" FontWeight="Bold"
Foreground="White"/>
</Border>
</StackPanel>
<TextBlock Classes="cardSubtitle" Text="{Binding Block.FrequencyText}"/>
</StackPanel>
<Border Grid.Column="1"
Background="{Binding Block.Status, Converter={StaticResource StatusToColor}}"
CornerRadius="12" Padding="12,5" VerticalAlignment="Center">
<TextBlock Text="{Binding Block.Status}" FontSize="10"
FontWeight="SemiBold" Foreground="White"/>
</Border>
</Grid>
<Border Classes="divider"/>
<Border Classes="cardSection">
<StackPanel Spacing="10">
<TextBlock Classes="sectionLabel" Text="CONFIGURATION"/>
<Grid ColumnDefinitions="Auto,*,Auto" ColumnSpacing="12">
<TextBlock Grid.Column="0" Classes="fieldLabel" Text="Gain:"
VerticalAlignment="Center"/>
<controls:SafeNumericUpDown Grid.Column="1"
Value="{Binding Gain, Mode=TwoWay}"
Minimum="-1000000" Maximum="1000000"
Increment="0.1" FormatString="F3"/>
<Button Grid.Column="2" Content="Apply"
Command="{Binding ApplyCommand}"/>
</Grid>
<TextBlock Text="{Binding Message}" TextWrapping="Wrap"
Foreground="{DynamicResource ThemeTextSecondaryBrush}"/>
</StackPanel>
</Border>
</StackPanel>
</Border>
</cards:PopoutCardBase>
The slider deliberately offers a small editing range; the model and JSON accept any finite gain. Choose controls and limits that match your own block's requirements.
Create Views/Cards/SignalProcessing/GainCardView.axaml.cs:
Download GainCardView.axaml.cs and copy it to the path above.
using MOSAIC.Views.Cards;
namespace MOSAIC.Views.Cards.SignalProcessing;
public partial class GainCardView : PopoutCardBase
{
public GainCardView() => InitializeComponent();
}
{Binding Gain} connects a control to the ViewModel's Gain property. TwoWay
allows the slider to change it. DataContext (assigned next) supplies the ViewModel,
and x:DataType lets the compiler check the binding names.
Follow the existing cards: the AXAML root is cards:PopoutCardBase, and the code-behind
inherits PopoutCardBase. The example also uses the shared card, cardSection, status
converter, category colour, and SafeNumericUpDown patterns used by current cards.
Finally, open Selector/BlockTemplateSelector.cs and add this arm to
BlockTemplateSelector.CreateCard before the fallback:
GainBlock block => new GainCardView
{
DataContext = block.GetOrCreateOwned(() => new GainViewModel(block))
},
Add these imports to the selector if they are not already present:
using MOSAIC.Models.SignalProcessing;
using MOSAIC.ViewModels.SignalProcessing;
using MOSAIC.Views.Cards.SignalProcessing;
Build and run the application again using the command in step 5. Then
open the block, move the slider, and press Apply. Save and reload the pipeline:
GetJsonParams should preserve the applied gain.
The MVVM toolkit generates the Gain and Message properties, their change
notifications, and ApplyCommand from the attributes. Do not add those members
by hand. This example needs no IDisposable implementation because it owns no
subscriptions, timers or visualization resources.
7. Add visualization only when needed
The minimal block above intentionally owns no visualization. If you add one:
- Decide whether the model or ViewModel owns the
BlockVisualization. - Expose it to
VisualizationPanel.Sourcein the card. - Override the model's protected
Visualizationproperty soBaseBlockcan propagate the publish rate automatically. For this one-vector-per-input gain block, that supplies the Scope time base without per-sample rate calls. CallRefreshVisualizationRate()after assigning a visualization later in the lifecycle. - Feed output after
Publish(output). Do not update chart controls directly fromOnReceive. - Dispose the bundle in its owner.
BaseBlock.Disposedoes not dispose an arbitraryVizproperty you added. If you overrideDispose(bool), keep cleanup idempotent and call the base implementation.
Use Visualization Architecture and
Panel Integration for the complete monitor pattern.
The panel handles monitor visibility and pause/resume; no custom UI timer or
manual Scope.Resume() is needed. Models/Templates/TemplateViz.cs shows the same
bundle pattern without gain controls; it is a source template, not a registered palette block.
If your ViewModel subscribes to events or owns timers, implement IDisposable and
unsubscribe or stop them there. The selector uses GetOrCreateOwned to reuse one
ViewModel for each block and dispose it with that block. Closing a pop-out or
regrouping cards does not dispose this shared ViewModel. PipelineSession owns
the blocks and awaits their cleanup on deletion, reload and desktop exit.
8. Verify the whole contract
| Check | Expected result |
|---|---|
Transform [1, -2, 0] with gain 2.5 |
Output [2.5, -5, 0]; input remains unchanged |
| Gain 0, 1, and -1 | Zeros, unchanged values, and sign inversion respectively |
| Unsupported payload, such as a matrix | No output; LastError explains that Gain requires a numeric vector |
Missing Params |
Gain defaults to 1.0 |
| Palette creation | One Double field called Gain, default 1.0 |
| JSON creation | The canonical key and optional full-name alias both construct the block |
| Apply, save, reload | Applied gain survives; unapplied slider changes do not |
| Graph wiring | One input accepted; a second input rejected by the editor |
| Start/stop and remove | No block-owned workers or subscriptions left running |
Add focused automated tests for processing and configuration round-trips when you implement your own block. Check UI behavior in the app as well: successful compilation alone cannot confirm the palette, connection rules, or saved configuration.
The downloadable Gain and RMS models, Gain ViewModel and Gain card are compiled against the current application by the documentation tests, including the card's AXAML bindings. Tests also check that Apply changes the model and that saved JSON keeps the applied value rather than an unconfirmed draft. From the repository root, run:
dotnet test MOSAIC/MOSAIC.Tests/MOSAIC.Tests.csproj --filter FullyQualifiedName~DocumentationWorkflowTests
Then document the block in the human-readable Block Catalogue. This takes two edits, not one:
Create a page
Documentation/docs/blocks/gain.mdwith the fixed structure shown in Block Catalogue Registration: a Type row listing every factory key in backticks, the three required headings, and an[API reference](xref:...)link to the model class.Add a row to the Signal Processing table in
Documentation/docs/block-catalogue.md:| <span id="gain"></span>[Gain](blocks/gain.md) | Scales every channel of a vector by a gain; preserves channel count. |
check_docs.py compares the factory's type keys with the Type rows of all block
pages and fails on any key that appears on only one side: a factory alias with no block
page, or a page listing a key the factory does not accept. The xref line is what lets
the build attach your page to the block's API entry; the check also fails if a block
page lacks it.
Rebuild the documentation using Building the Documentation.
The full build automatically adds your block to the API sidebar and groups its model,
view model and views using the selector and naming conventions. A separate navigation
entry is unnecessary. Use the API association overrides described in that guide only
for unusual class names or helpers that live elsewhere.
Add a class-level XML <example> comment with a <code language="json"> block
containing the block's JSON entry, including Type. This is required, not optional:
check_docs.py fails when a documented model's API page has no JSON configuration
section. Explain parameter positions and
any placeholder input names, device addresses or paths beside it. The documentation
theme places this example in a JSON configuration section beside the model
description during a normal DocFX build. Keep configuration examples on the model;
view and view-model pages describe the UI implementation.
Continue with Batches, features and source blocks for a downloadable, tested RMS feature block, rate declarations, device lifecycle and multiple-input policies.
When you adapt this example
The working steps above are enough for Gain. Read these details when changing its input type, adding settings or owning resources such as a device connection.
What MOSAIC already provides
| Already provided | What you still write |
|---|---|
| One input and no restriction on upstream block class | Override constraints only when your block differs; validate the payload in OnReceive. |
Subscriptions, downstream dispatch and rate inheritance in BaseBlock |
Call Publish(output); declare different rate semantics for windowing, resampling or features. |
| Automatic status and displayed-frequency updates | Validate the input and publish valid results; do not assign Status in this example. |
| JSON export of name, connections, rate and recording path | Export your parameters with GetJsonParams; keep a stable JsonTypeName. |
No parameters by default (GetJsonParams returns null) |
No override is needed for a parameter-free block. |
Recording setup in BlockFactory.Create and logging through Publish |
Use the recording controls or JSON Path; no dumper setup in ConfigureInput. |
| Palette search, add-dialog fields, node movement and connection UI | Supply the catalogue descriptor; no block-specific drag handlers. |
Standard plot controls and pause/resume in VisualizationPanel |
Optionally own, feed and dispose a visualization bundle, then bind the panel. |
For an even smaller example without settings, inspect the shipped
Negate model. GainBlock adds one
parameter to demonstrate configuration and save/reload. Type discovery is not
automatic: the factory case and catalogue entry from steps 3 and 4 are still required.
Processing and shared settings
OnReceive runs on a dispatching thread. Keep processing short and avoid UI work,
blocking network calls, or disk writes here. Other blocks may see the same input
object, so allocate your output and treat published data as immutable: do not reuse
or mutate it after Publish.
Gain is shared between the UI and processing threads. This example uses
Volatile.Read/Write for that one scalar. A block with several related settings
should publish a consistent settings snapshot or protect them together. Keep editable
values in the ViewModel, then validate and apply them in one model method. For example,
Filter.UpdateParameters commits the whole band under the same lock used by processing;
a packet cannot see a new lower cutoff paired with the previous upper cutoff.
[ObservableProperty] provides notifications, not this synchronization.
ConfigureInput constructs the block; GetJsonParams exports its current settings.
They must agree on positions and defaults. The JSON helpers accept the representation
used by loaded JSON as well as supported CLR values, but they can fall back silently
for malformed values. Add strict validation if silently using a default would be wrong
for your block.
Recording is already connected in BlockFactory.Create: it calls InitDumper
and AttachRecording. Publish sends output to the dumper. You do not need
another recording setup or a manual CSV write in this example.
This applies when construction goes through BlockFactory.Create; calling the
constructor or ConfigureInput directly bypasses that factory setup.
Report errors separately from activity
Status describes recent output activity and is updated automatically. For an input or
processing failure, call ReportError("Explain what went wrong and what was skipped.").
The card displays the message separately and the shared logger records it. Call
ClearError() after an explicit reset or recovery when appropriate. Publishing another
value does not erase the error. Leave Status updates to BaseBlock; do not assign it
after processing or add another activity-status property. Use a clearly named message or state property
for a separate concept such as connection state or training progress.
A filter failure skips the affected input; it does not publish raw data as if filtering had succeeded. Intentional bypass remains available through the Filter card's enable switch.
Input constraints are not payload validation
GainBlock inherits MinInputs = 1, MaxInputs = 1 and an empty AllowableBlocks
from BaseBlock, so the example does not repeat those getters.
MinInputs and MaxInputs describe graph connections. An empty
AllowableBlocks accepts any upstream block class; it does not mean any
payload type is valid. The Vector<double> check remains necessary.
BlockConstraints reads these getters on an uninitialised instance. Never depend
on constructor state, hardware, or parameter fields in these getters. For a source,
use a literal MinInputs => 0; for a clock-driven generator, inspect the existing
SinGenerator constraints and lifecycle. See Core Architecture
for scheduling, dispatch, and source blocks.
Common problems
| Symptom | What to check |
|---|---|
| Unknown type when loading or dropping | Factory key matches the catalogue and exported type |
| Loads from JSON but is missing from the palette | Catalogue entry and platform guards |
| Dialog accepts a field but it has no effect | Hint order matches parameter reader and exporter |
| Block receives data but emits nothing | Actual payload type and upstream activity |
| Settings appear to reset after reload | GetJsonParams exports current model state |
| Card is missing | Selector arm, namespaces, and placement before the fallback |
| UI stalls or falls behind | Work in OnReceive, per-sample UI updates, and blocking calls |