PySDR: a free textbook on software-defined radio with the code alongside

A textbook built around code

PySDR is a guide to software-defined radio and radio frequency signal processing using Python code examples, and it is a free online textbook, live at pysdr.org. The description in the readme is precise about what that means: a gentle introduction to wireless communications and SDR using an abundance of diagrams, animations, and code examples, from FFTs to filters to digital modulation to receiving and transmitting from SDRs in Python.

The word gentle is doing the work, and it is a deliberate positioning. Most signal processing textbooks assume a reader who already knows the mathematics and needs the implementation. This one starts from the point where somebody has a radio and a plot and does not yet know what the plot is telling them.

The scope, though, is not small. The chapters run from the fast Fourier transform through filtering and digital modulation to actually receiving and transmitting, and the topics the repository carries name the hardware it assumes: a Pluto radio, an RTL-SDR, and a USRP, alongside the general ones of communications, digital signal processing, and wireless.

What is in the repository is the source of the book rather than the book: the body text and the Python scripts that generate the figures. So every diagram in the text is produced by a script in the same tree, and the animation is the output of a program rather than an asset somebody recorded.

That arrangement has an obvious benefit and an obvious cost. The benefit is that a figure cannot drift out of step with the code around it, because regenerating the figures regenerates them from the current code. The cost is that the book is a build, not a set of files, and building it needs a toolchain.

The contribution arrangement is unusually generous and worth quoting, because it says something about the project's assumptions. For questions, comments, or suggestions you can file an issue; to propose a change to the textbook, such as a fix or an improvement, you can open a pull request; and those who submit valuable feedback or fixes are permanently added to the acknowledgments section. And for people who are not comfortable with git but have changes to suggest, there is an email address, with a name and a domain attached to it.

Building the book, and why the build is not in the page host

The building section explains that the site is built and deployed automatically on every push to the master branch, by a GitHub action that uploads the built site to Cloudflare Pages with the deployment tool, and it names the reason the build has to happen in the action rather than in the page host's own build system.

The reason is a list of three system packages: a TeX distribution, a document converter, and a spell checking library. The pages host does not have them, and the book needs them because the figures are drawn with a TeX package and the text is spell checked against a word list.

That is a small architectural decision with a large consequence, and it is worth naming as a pattern: the book is built in CI and the output is uploaded, rather than the source being uploaded and built by the host. The build needs more than the host offers, so the build moves to where the tools can be installed.

The manual deployment path is a single command run from the repository root, with the settings coming from a configuration file in the same directory. So the same build can be reproduced by hand, which is the escape hatch every automated pipeline needs.

For testing changes locally, the readme gives the two platform recipes. On Ubuntu and Debian it says to look at the workflow file and run the same apt and pip installs that the action does, and then to build each language with its own make target.

make html
make html-fr
make html-nl
make html-ukraine
make html-zh
make html-ja

The output lands in a build directory, where the index page for the English site is the main one. And then there is a note that on one machine the local bin directory had to be added to the path, which is the kind of detail that saves somebody an afternoon.

The Windows recipe is spelled out as numbered steps, starting with a Python version from the Microsoft Store, with the note that a range of versions will do if one is already installed. Then the dependencies, then a single build command for the English version only, run through the module interface to the Sphinx command so that it works on Windows.

The first run takes a while, because the LaTeX packages have to be downloaded. And then there is a step that is easy to miss and would otherwise waste an hour: to test the JavaScript parts you have to serve the built directory over a local HTTP server, because opening the files directly produces cross-origin errors.

Six languages, one source, and the notebooks

The repository layout is where the shape of the project becomes clearest, and the language directories are the first thing to notice.

There is a content directory for the English text, and beside it five more: one for French, one for Japanese, one for Dutch, one for Ukrainian, and one for Chinese. Each has its own index file at the top level of the repository, and each is built by its own make target, as the local build instructions show.

The significance is in how the translation is produced. The make file carries a comment that says the internationalisation builder cannot share the environment and the doctrees with the others, which is the Sphinx way of saying that the translated builds have to be run separately from the main one rather than as a side effect of it. And the site is published on every push, so all six languages go out together with the same commit.

The Ukrainian and Chinese directories are the ones to note. A textbook on radio signal processing, written by an author whose own name and email are given, in a language that the surrounding technical literature barely covers, is a different proposition from the same book in English. The readme lists the languages and the site publishes them, and the make file confirms that the Ukrainian and Chinese builds are first class rather than afterthoughts.

Then there is the in-browser notebook system, which is the newest thing in the repository and the one with the most interesting plumbing.

The make file lists the scripts in the figure generating directory that are turned into browser notebooks, and there are nine of them, with names that match the chapters: time difference of arrival, the full synchronisation example, the RDS demonstration, the frequency domain, digital modulation in Python, the NTSC and PAL bandwidth example, a minimal filter example, the detection chapter, and pulse shaping.

The comments explain the mechanism in detail. The scripts carry cell markers, and a conversion tool reads those markers to turn a plain Python script into a notebook, and an export step produces a web assembly build of the notebook that runs entirely in the browser. The converted notebook only ever exists in the build directory and never in the repository, and every notebook exports into the same folder so that they share one copy of the frontend, which is identical across notebooks.

That last point is a small piece of engineering that a lot of projects get wrong. If each notebook shipped its own copy of the runtime, a reader who opened ten of them would download the runtime ten times, and a change to the runtime would have to be applied ten times. One shared copy, built once, is both smaller and consistent.

So a reader of the book can, for most of the computational chapters, read the text and then run the code in the browser without installing Python at all.

The figures, and how they are drawn

A textbook on signal processing is mostly figures, and the way this one produces them explains a good deal about its character.

The extensions list in the make file names what the build uses: the maths extension, the auto section label extension, a package for drawing with TeX, and a package for diagrams. The TeX drawing package gets a path to the images directory and a set of libraries for positioning, shapes, arrows, and a library of snake-shaped connectors.

That last detail is worth pausing on. A library of curved connectors is a small thing that tells you the figures are drawn programmatically with layout rules, not hand-placed. When a curve is routed automatically between two nodes, the diagram stays readable when the text changes, and when a label becomes two lines instead of one, the arrow still points at the right place.

The text also mentions animations. The figure generating scripts produce animated images, and the readme's note on the PDF export explains the consequence: it is not fully working yet because of the animated images, and they all need to be removed for it not to error out.

That is an honest and rather instructive failure. A book that contains animations cannot easily be typeset as a PDF, because a PDF is a page format and an animation is a sequence, and the standard answer is to fall back to a static frame. The readme names the problem and the fix, which is removing the animations, and the PDF build instructions follow the usual pattern with a document builder and a make target.

The dependencies list is worth reading too, because it shows how much of the toolchain is about the figures rather than the text. There is an image library, a diagram tool, the maths extension, a spelling extension with its own word list in the repository, and a serialising HTML extension. The word list file is a nice touch: a technical book about signal processing has a large vocabulary of terms that a general spell checker will not know, and shipping the list is the way to keep the spell check useful rather than turning it off.

And the extras are the small conveniences: a configuration file for the site, templates, static assets, an image directory, a scripts directory for generating the figures, a set of presentation files, a small script for serving the site, and a script for scraping the funding page.

Funding, and the licence that constrains reuse

Two practical things in the readme are worth their own attention, because both are decisions the reader has to live with.

The first is funding. The author asks for support through a Patreon page or a one-time donation through PayPal, and the repository contains a script that scrapes the funding platform's API, with a comment in the requirements file explaining that it exists to hit that API. There is also a donation page configuration in the site configuration file.

For a free textbook that is a normal arrangement. What is less usual is having the funding list on the site as a data source rather than as a hand-maintained page, which means the number of supporters on the site is always current.

The second is the licence, and it is the one detail that a reader should not skip.

The work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 Unported licence, with the badge in the readme and the statement in full at the end. Three terms, and each of them has a consequence.

Attribution means you have to credit the author. Share alike means a derivative has to carry the same licence. And non-commercial means the work cannot be used for commercial purposes.

That last term is the one that catches people. A textbook on a technical subject that you want to use as the basis of a paid course, or to include in a commercial training programme, or to reprint for a company, is outside what this licence permits, and that is a decision the author has made explicitly rather than an oversight.

The contrast with the software ecosystem is instructive, because a book whose figures are generated by scripts in the same repository is a repository with two quite different licences in play. The scripts are in the repository, under the repository's own terms, and the text and the figures are under a Creative Commons licence with a non-commercial clause. That split is common in documentation and textbooks, and it is worth checking both halves when you plan to reuse anything.

The acknowledgments section is the other place where the licence and the contribution policy meet, because the readme promises that people who submit valuable feedback are permanently added to it. For a book that is written by one person and improved by many, that promise is part of the deal.

What the author wants to write next

The last section of the readme is a list of ideas for future chapters, and it is more informative than most roadmaps because it shows where the author thinks the book is incomplete.

Equalization is first, and the reason given is that it would be the last step needed to finish the end to end communications link. That tells you the book's structure: it has been building a complete link from one end to the other, and the receiver and the transmitter work, but the channel is not yet being undone properly.

The second is OFDM, with a specific and technical description of what the chapter would do: simulate OFDM and the cyclic prefix, and show through Python how it turns frequency selective fading into flat fading. That is a precise, teachable claim, and it is the kind of thing a chapter title in a signal processing book should be.

The third is about real-time SDR applications with a graphical interface in Python, using a Qt binding and a plotting library, or even matplotlib with updating. The alternative of just matplotlib is mentioned because it is the pragmatic choice and the chapter would probably show both.

The fourth is code that lets a Pluto or an RTL-SDR act as an FM receiver, with sound output. That is a chapter about a complete, tangible device, and it is the one a reader with cheap hardware would want most.

The fifth is an end-to-end example showing how to detect the start of a packet, and the note ties it back to the RDS chapter, which the repository listing shows exists as a notebook. So the author is looking to close a gap in a chapter that is already written.

The last item is an introduction to radar, which is the one that reaches beyond communications. It is the natural next frontier for a book that has taken a reader from a spectrum plot to a working receiver, and it is a subject with the same mix of theory and instrumentation.

There is also a mention in the readme of the author by name, with an email address, and of the site, and of the promise that the book covers everything from FFTs to filters to digital modulation to receiving and transmitting. The list of future chapters is a good summary of the ambition: the book is not trying to be a complete reference on a subject, it is trying to be a complete path through it, and the chapters left are the ones that finish the path.

Editorial conclusion

PySDR fits a student or engineer who wants to understand what a spectrum plot means before reaching for a radio, and who learns by running code rather than by reading derivations. It does not fit a commercial training programme that needs a permissive licence, because the non-commercial share alike terms are explicit, and it does not fit somebody who wants a reference manual for a particular device. Verify first which radio hardware the examples assume, since the chapters are written against specific dongles, that you can run the Python examples as well as read them, since the point of the book is that the figures are produced by the code next to them, and that the translation you read is current, since the build publishes all six languages from the same sources on every push.

Frequently asked questions

Official sources

1. 777arc/PySDR on GitHub
2. Issues
3. Project website
4. README
5. Releases