FlexRadio API Documentation

📖 Read the FlexRadio API documentation in the Wiki →

This project documents the FlexRadio SmartSDR TCP API — the commands a client program sends over the network to control a FlexRadio. The documentation is published as a browsable wiki, organized into 34 categories (Slice, Radio, Transmit, Antenna, and so on).

If you just want to read the docs, use the wiki link above. The rest of this page is for people who want to suggest improvements or maintain the project.

---

Who this README is for

If you want to…	Go to
Read the API documentation	The Wiki (link above)
Suggest a correction or add an explanation to a command	Suggesting an edit
Publish doc changes to the wiki	Maintainers: publishing the wiki
Update to a new FlexLib version	Maintainers: updating FlexLib

---

Suggesting an edit

The documentation is generated automatically from the FlexRadio source code, so most of it can't be edited directly. But the explanatory notes attached to each command — usage tips, gotchas, clarifications — are hand-written and very welcome.

To suggest a change, open an issue:

• Name the command you're describing (e.g. slice tune) and the category page it's on.
• Describe what should be added or corrected.

A maintainer will write up the note and publish it. You don't need to know how the generator works, edit any files, or open a pull request — just describe the improvement in plain language.

Note: Don't edit the wiki pages directly. The wiki is regenerated automatically and any direct edits will be overwritten. Suggestions made through issues are preserved permanently.

---

How it works (overview)

The documentation is produced by a Python program that reads the FlexLib C# source code and generates one markdown page per command category.

The program (src/build_docs.py) runs a four-stage pipeline:

1. Extract — scan each C# source class for command calls, descriptions, status keys, and enums.
2. Categorize — route each command to a category (by models/categories.json) and write intermediate JSON.
3. Render — merge the intermediate data per category and render markdown pages to docs/, injecting any hand-written supplements.
4. Index — regenerate docs/Command-Index.md.

A separate step (src/publish_wiki.py) transforms docs/ into wiki form and a GitHub Actions workflow pushes it to the wiki.

Full design notes, data schemas, and the supplement heading rules live in impl_docs/system_requirements.md.

---

Repository layout

src/                    Python source for the documentation generator
  build_docs.py           Entry point and pipeline orchestration
  extractor.py            C# source parser
  categorizer.py          Verb-to-category routing and intermediate JSON output
  renderer.py             Intermediate JSON → markdown page renderer
  supplements.py          Supplement file loader
  indexer.py              Command-Index.md generator
  publish_wiki.py         Transforms docs/ into wiki-ready pages

models/
  categories.json         Defines all 34 command categories
  example-api-format.md   Reference template for the markdown output format
  intermediate/           Per-class intermediate JSON files (generated)

supplementary/          Hand-authored supplement notes (committed to git)
docs/                   Generated markdown documentation (committed; do not edit by hand)
example_docs/           Hand-written reference docs (comparison only)
flexlib/                FlexLib C# source tree (gitignored)
impl_docs/
  system_requirements.md  Full requirements and design notes

---

Maintainers: publishing the wiki

For the small group with commit access who regenerate and publish the docs.

Prerequisites: Python 3.10+, and the FlexLib source tree at flexlib/v<version>/FlexLib/.

Adding or editing a command's explanatory note (a "supplement"):

1. Open or create a file in supplementary/ named after the category page (e.g. supplementary/Slice-Commands.md for the Slice page).

2. Add a ### heading whose text exactly matches a command heading on the generated page (the text after ## — no backticks), followed by your note:

   ### slice create
   
   Creates a new receiver slice. The radio returns the index of the
   created slice in the response data field.

3. Regenerate and review:

   python3 src/build_docs.py
   

   If a supplement heading matches no command, the build prints a warning and skips it. For the exact heading rules (how <placeholder> tokens render as ...) and per-parameter overrides, see Supplementary Content in the system requirements.

4. Commit the changed files in supplementary/ and docs/ and push to main.

Publishing to the wiki happens automatically: the Publish Wiki workflow (.github/workflows/publish-wiki.yml) runs on every push to main that touches src/, models/, supplementary/, or docs/, regenerates the pages, and pushes them to the wiki. You can also trigger it manually from the Actions tab. Preview the wiki output locally with python3 src/publish_wiki.py (writes ./wiki/, gitignored).

One-time setup (already done if the wiki is live): initialize the wiki via the Wiki tab, and add a WIKI_TOKEN secret (a PAT with repo scope — the default GITHUB_TOKEN cannot push to wikis). See Wiki Publishing for details.

Adding a new command category: edit models/categories.json (each entry has name, group, output_file, source_classes, tcp_verbs), then re-run build_docs.py.

---

Maintainers: updating FlexLib

For the very small group responsible for moving to a new FlexLib release.

1. Place the new source tree at flexlib/v<version>/FlexLib/.

2. Regenerate, selecting the version (auto-detected if only one is present):

   python3 src/build_docs.py --version <version>
   

3. Review models/intermediate/unmatched.json for any new command verbs that need routing in models/categories.json.

4. Commit the regenerated docs/ and intermediates and push to main — the wiki updates automatically.

See Adding a new FlexLib version in the system requirements for full notes.