Block Development Tools

Block development tools are loaded dynamically via enable_block_dev_mode(). They provide code generation, validation, protocol analysis, signal analysis, and OOT module export.

Note

These tools register 5 MCP prompt resources for guiding code generation. Read them via prompts://block-generation/sync-block, prompts://block-generation/grc-yaml, etc.

Mode Control

get_block_dev_mode

Check whether block development mode is enabled.

Returns: BlockDevModeStatus with enabled, tools_registered

enable_block_dev_mode

Enable block development tools. Registers ~15 tools and 5 prompt resources.

Returns: BlockDevModeStatus with list of registered tools

disable_block_dev_mode

Disable block development tools, removing them from the tool list.

Returns: BlockDevModeStatus

---

Block Generation

generate_sync_block

Generate a gr.sync_block from a natural language description. The 1:1 input-to-output ratio makes this the most common block type.

Parameter	Type	Required	Description
name	string	Yes	Block name (e.g., "configurable_gain")
description	string	Yes	Natural language description of block behavior
input_signature	list	Yes	Input port specs: [{"dtype": "float", "vlen": 1}]
output_signature	list	Yes	Output port specs
parameters	list	No	Constructor params: [{"name": "gain", "dtype": "float", "default": 1.0}]
work_logic	string	No	Description of the work function logic

Returns: GeneratedBlockCode with source_code, is_valid, validation_errors

generate_basic_block

Generate a gr.basic_block with custom forecast() and general_work(). Use this when input/output rates differ in non-trivial ways.

Parameter	Type	Required	Description
name	string	Yes	Block name
description	string	Yes	Block behavior description
input_signature	list	Yes	Input port specs
output_signature	list	Yes	Output port specs
parameters	list	No	Constructor parameters
forecast_logic	string	No	How to predict input requirements
work_logic	string	No	Processing logic description

Returns: GeneratedBlockCode

generate_interp_block

Generate an interpolation block (gr.interp_block) that produces more output samples than input samples.

Parameter	Type	Required	Description
name	string	Yes	Block name
description	string	Yes	Block behavior description
interpolation	int	Yes	Interpolation factor
input_signature	list	Yes	Input port specs
output_signature	list	Yes	Output port specs
parameters	list	No	Constructor parameters

Returns: GeneratedBlockCode

generate_decim_block

Generate a decimation block (gr.decim_block) that produces fewer output samples than input samples.

Parameter	Type	Required	Description
name	string	Yes	Block name
description	string	Yes	Block behavior description
decimation	int	Yes	Decimation factor
input_signature	list	Yes	Input port specs
output_signature	list	Yes	Output port specs
parameters	list	No	Constructor parameters

Returns: GeneratedBlockCode

---

Validation

validate_block_code

Validate generated block code without execution. Checks syntax (ast.parse), required imports, class hierarchy, work() method signature, and I/O signature consistency.

Parameter	Type	Required	Description
source_code	string	Yes	Python source code to validate

Returns: ValidationResult with is_valid, errors, warnings

parse_block_prompt

Parse a natural language description into a structured block specification. Useful for multi-step workflows where you want to review the spec before generating code.

Parameter	Type	Required	Description
prompt	string	Yes	Natural language block description

Returns: Structured block specification with inferred name, I/O, parameters

---

Block Testing

test_block_in_docker

Test a generated block in an isolated Docker container. Creates a test harness flowgraph with vector_source → block → vector_sink, runs it, and collects output.

Parameter	Type	Required	Description
source_code	string	Yes	Block source code
test_input	list	No	Input samples (e.g., [1.0, 2.0, 3.0])
parameters	dict	No	Constructor args (e.g., {"gain": 2.0})
timeout	int	No	Max execution time in seconds (default: 30)

Returns: DockerTestResult with success, output_data, errors, duration

Caution

Requires Docker. The gnuradio-runtime base image must be built first.

---

Protocol Analysis

parse_protocol_spec

Parse a protocol description (natural language or structured) into a ProtocolModel. Identifies modulation scheme, framing, encoding, and relevant parameters.

Parameter	Type	Required	Description
spec	string	Yes	Protocol description or specification

Returns: ProtocolModel with modulation, framing, encoding details

generate_decoder_chain

Generate a complete multi-block decoder pipeline from a protocol specification. Selects existing GNU Radio blocks where possible, generates custom blocks for gaps.

Parameter	Type	Required	Description
protocol	string	Yes	Protocol name or specification
sample_rate	float	No	Target sample rate
center_freq	float	No	Center frequency

Returns: DecoderPipelineModel with blocks, connections, and required OOT modules

get_missing_oot_modules

Identify which OOT modules are needed for a protocol but aren’t installed. Cross-references the protocol’s block requirements against the OOT catalog.

Parameter	Type	Required	Description
protocol	string	Yes	Protocol name

Returns: List of missing module names with install instructions

---

Signal Analysis

analyze_iq_file

Analyze a captured IQ file to determine signal characteristics. Performs FFT analysis, estimates bandwidth, detects signal presence, and estimates modulation parameters.

Parameter	Type	Required	Description
file_path	string	Yes	Path to IQ capture file
sample_rate	float	Yes	Sample rate of the capture
dtype	string	No	Data type (default: "complex64")

Returns: Analysis results including bandwidth, center frequency offset, SNR estimate

---

OOT Export

generate_grc_yaml

Generate a GRC block definition (.block.yml) file for a block. This is required for blocks to appear in GNU Radio Companion’s graphical editor.

Parameter	Type	Required	Description
source_code	string	Yes	Block Python source code
block_name	string	Yes	Block name
module_name	string	No	Module prefix (default: "custom")
inputs	list	No	Input port specs
outputs	list	No	Output port specs
parameters	list	No	Block parameters with types and defaults
category	string	No	GRC palette category

Returns: GrcYamlResult with yaml_content, filename, block_id, notes

Tip

The generated YAML includes flags: [ python ], parameter dtype mapping (Python float → GRC real), setter method detection for callbacks, and asserts from parameter min/max values.

generate_oot_skeleton

Generate a gr_modtool-compatible Out-of-Tree module skeleton with CMakeLists.txt, Python package structure, and grc/ directory.

Parameter	Type	Required	Description
module_name	string	Yes	Module name (e.g., "custom", not "gr-custom")
output_dir	string	Yes	Where to create the module directory
author	string	No	Module author name

Returns: OOTSkeletonResult with success, module_name, path

export_block_to_oot

Export a generated block into a full OOT module structure. Creates the Python source file, GRC YAML block definition, and updates __init__.py. Creates the OOT skeleton if it doesn’t exist.

Parameter	Type	Required	Description
source_code	string	Yes	Block source code
block_name	string	Yes	Block name
module_name	string	Yes	Target OOT module name
output_dir	string	Yes	OOT module root directory

Returns: ExportResult with success, file paths created

export_from_flowgraph

Export an embedded Python block from the current flowgraph into an OOT module. Extracts the block’s source code and metadata, then calls export_block_to_oot.

Parameter	Type	Required	Description
block_id	string	Yes	Block ID in the flowgraph (e.g., "epy_block_0")
module_name	string	Yes	Target OOT module name
output_dir	string	Yes	OOT module root directory

Returns: ExportResult