Contributing course labs

This guide defines the expected structure for new labs in the Zynq SDR Course. It keeps Russian and English pages aligned and makes every lab reproducible, measurable and useful as an engineering artifact.

Lab design principle

A good lab should answer three questions:

1. What engineering concept is being validated?
2. What model, script, hardware setup or measurement proves it?
3. What result should the learner compare against?

Required lab structure

Every new lab page should contain these sections, in this order and with these headings (the Russian page uses the same order: «Цель», «Зачем это нужно», «Запуск», «Артефакты», «Чего ожидать», «Упражнения», «Что включить в отчёт»):

Section	Purpose
Goal	One clear engineering objective.
Why this lab matters	Short theory and the engineering reason for the task.
Run	The exact command(s), from the repository root.
Artifacts	Generated figures, metrics files or reports, as a text block of paths.
What to expect	Measured numbers and how to read them, including the surprising ones.
Exercises	Changes the learner makes, followed by their answers in a collapsed <details markdown="1"> block. Every numeric answer is obtained by running the lab's script with that change, never estimated.
Report checklist	What the learner must include in the lab report.
RF safety	Required for RF, power, soldering or measurement hardware.

Required artifacts by lab type

Lab type	Minimum artifacts
Theory-only	Markdown page, equations, diagrams, references.
Python DSP	Python script or notebook-friendly script, generated figure, expected numerical result.
MATLAB / Simulink	MATLAB script or model description, reference parameters, exported plots or screenshots.
C++ DSP	Source file, build/run command, test vector or expected output.
Verilog / FPGA	RTL module, testbench, command line simulation path, expected waveform or console result.
RF / SDR hardware	RF path diagram, safety checklist, gain/frequency settings, metadata, fallback synthetic mode.
IQ recording	Manifest file, checksum, format description, reader script and analysis result.

Naming convention

Use stable names so that docs, scripts and figures remain predictable.

docs/en/labs/lab-X-Y-short-name.md
docs/ru/labs/lab-X-Y-short-name.md
blocks/block_XX_topic/labs/lab_X_Y_short_name/
tools/generate_lab_X_Y_figures.py
docs/assets/labXY_result_name.png

For new public figures, prefer docs/assets/ and use lower-case file names with hyphens or underscores.

Page formatting

tests/test_docs_formatting.py checks the rules that MkDocs rendering depends on:

• the H1 reads # Lab X.Y — Title (Russian pages: # Лабораторная X.Y — ...), with an em dash;
• a page under docs/ that includes a snippet with --8<-- has no H1 of its own when the snippet starts with one, otherwise the title is rendered twice;
• every opening code fence names a language (text for diagrams, tables of paths and console output);
• the Russian navigation in mkdocs.yml labels pages in Russian, normally with the page's own H1.

Bilingual rule

For each learner-facing page, keep a Russian and English version. The pages do not need to be literal translations, but they must stay structurally equivalent:

• same lab number;
• same objective;
• same input parameters;
• same expected plots and metrics;
• same safety assumptions;
• same report checklist.

Reproducibility rule

A lab is reproducible when another learner can run it from a clean checkout using documented commands.

At minimum, provide:

python tools/tasks.py install-dev
python tools/tasks.py docs
python tools/tasks.py labs

If the lab requires a special command, document it explicitly:

python path/to/script.py
cmake --build build
ctest --test-dir build -R lab_name
iverilog -g2012 -o build/tb_name path/to/tb.v path/to/dut.v

Figure style

Course figures should follow an IEEE-like style:

• clear axes labels with units;
• readable font sizes;
• no unnecessary decorative effects;
• legends outside the data area when possible;
• deterministic data generation for CI;
• both engineering meaning and visual clarity.

Every generated figure should be connected to a script or reproducibility note.

RF lab requirements

Any lab that touches RF hardware must include:

• RF path diagram;
• attenuation assumption;
• TX/RX gain values;
• center frequency and bandwidth;
• sample rate;
• receiver protection note;
• overload symptoms;
• fallback synthetic-data mode;
• reference to RF safety guide.

IQ dataset requirements

Any lab that uses real IQ data must include:

• dataset manifest;
• file format;
• sample rate;
• center frequency;
• checksum;
• source and hardware setup;
• license or access note;
• reference to IQ dataset manifest guide.

Use the template:

templates/iq_dataset_manifest.template.yml

Review checklist before merging a lab

• The lab has a clear engineering goal.
• RU and EN pages are aligned.
• Commands are copy-pasteable.
• Figures are reproducible or clearly marked as illustrative.
• Expected results are included.
• RF safety notes are present when needed.
• IQ metadata is present when needed.
• The page is linked from mkdocs.yml.
• Block 11 IDs 11.36-11.46 are registered in tools/lab_id_registry.yml.
• The lab does not require large binary files in normal Git history.

Recommended lab report ending

Each lab should end with a concise engineering conclusion:

Conclusion:
- What was implemented or measured?
- Which metric proves correctness?
- What error sources remain?
- What should be changed before hardware deployment?