substation 0.5.1__tar.gz

substation-0.5.1/.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: Publish to PyPI
+
+# Publishes a release whenever a version tag is pushed. Versioning is driven by
+# git tags via setuptools-scm, so `git tag v0.6.0 && git push --tags` is the
+# whole release flow. Uses PyPI Trusted Publishing (OIDC) — no API token is
+# stored. The build runs in isolation and only needs the build backend
+# (setuptools + setuptools-scm), so it never installs the RTL-SDR / HackRF /
+# SoapySDR runtime dependencies. Action versions matter: older majors run on a
+# retired Node runtime and GitHub fails the job (same pattern as Subsequence).
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0  # full history + tags so setuptools-scm can derive the version
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: pipx run build
+      - name: Check metadata
+        run: pipx run twine check dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

substation-0.5.1/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+.vscode/
+.pytest_cache/audio/
+.mypy_cache/
+config.yaml
+*.egg-info/
+audio/
+examples/audio/
+.claude/
+.vs-code/
+CLAUDE.local.md
+AGENT-INSTRUCTIONS.md
+README-AGENTS.md

substation-0.5.1/INSTALL.md

@@ -0,0 +1,269 @@
+# Substation Installation Guide
+
+Platform-specific setup for SDR drivers, system dependencies, and the Python environment. See [README.md](README.md) for usage, configuration, and features.
+
+Tested on:
+- Debian 12 / Ubuntu 24.04 / Raspberry Pi OS (Bookworm)
+- Fedora 43 Server (x86_64)
+
+---
+
+## 1. RTL-SDR Blog V4 Driver
+
+The RTL-SDR Blog V4 requires the rtlsdrblog fork — the standard osmocom drivers are missing required symbols (e.g. `rtlsdr_set_dithering`).
+
+### Debian / Ubuntu / Raspberry Pi OS
+
+```bash
+# Remove any existing RTL-SDR packages to avoid conflicts
+sudo apt purge ^librtlsdr
+sudo rm -rvf /usr/lib/librtlsdr* /usr/include/rtl-sdr* \
+  /usr/local/lib/librtlsdr* /usr/local/include/rtl-sdr* \
+  /usr/local/include/rtl_* /usr/local/bin/rtl_*
+
+# Install build tools
+sudo apt update
+sudo apt install -y libusb-1.0-0-dev git cmake pkg-config build-essential
+
+# Clone and build the RTL-SDR Blog fork
+git clone https://github.com/rtlsdrblog/rtl-sdr-blog.git rtl-sdr
+cd rtl-sdr
+mkdir build && cd build
+cmake ../ -DINSTALL_UDEV_RULES=ON
+make
+sudo make install
+sudo cp ../rtl-sdr.rules /etc/udev/rules.d/
+sudo ldconfig
+
+# Blacklist the default DVB-T driver so it doesn't claim the SDR as a TV tuner
+echo 'blacklist dvb_usb_rtl28xxu' | sudo tee --append /etc/modprobe.d/blacklist-dvb_usb_rtl28xxu.conf
+
+cd ../..
+```
+
+### Fedora
+
+```bash
+# Remove any existing RTL-SDR packages
+sudo dnf remove 'rtl-sdr*' 'librtlsdr*'
+sudo rm -rvf /usr/lib/librtlsdr* /usr/lib64/librtlsdr* \
+  /usr/include/rtl-sdr* /usr/local/lib/librtlsdr* \
+  /usr/local/lib64/librtlsdr* /usr/local/include/rtl-sdr* \
+  /usr/local/include/rtl_* /usr/local/bin/rtl_*
+
+# Install build tools
+sudo dnf group install -y development-tools
+sudo dnf install -y gcc gcc-c++ libusb1-devel git cmake pkgconf
+
+# Clone and build the RTL-SDR Blog fork
+git clone https://github.com/rtlsdrblog/rtl-sdr-blog.git rtl-sdr
+cd rtl-sdr
+mkdir build && cd build
+cmake ../ -DINSTALL_UDEV_RULES=ON
+make
+sudo make install
+sudo cp ../rtl-sdr.rules /etc/udev/rules.d/
+sudo ldconfig
+
+# Blacklist the default DVB-T driver
+echo 'blacklist dvb_usb_rtl28xxu' | sudo tee --append /etc/modprobe.d/blacklist-dvb_usb_rtl28xxu.conf
+
+cd ../..
+```
+
+---
+
+## 2. System Optimisation (USB Buffering)
+
+High sample rates (e.g. HackRF at 20 MHz) require more USB buffer memory than the kernel default.
+
+### Debian / Ubuntu / Raspberry Pi OS
+
+```bash
+# Edit the kernel command line
+sudo nano /boot/firmware/cmdline.txt
+
+# Add the following to the end of the existing (single) line:
+usbcore.usbfs_memory_mb=1000
+
+# Reboot for the change to take effect
+sudo reboot
+```
+
+### Fedora
+
+```bash
+# Add the kernel parameter via grubby (Fedora's preferred method)
+sudo grubby --update-kernel=ALL --args="usbcore.usbfs_memory_mb=1000"
+
+# Reboot for the change to take effect
+sudo reboot
+
+# After reboot, verify the parameter is active
+cat /proc/cmdline | grep usbfs_memory_mb
+```
+
+---
+
+## 3. OS Dependencies
+
+### Debian / Ubuntu / Raspberry Pi OS
+
+```bash
+# Audio and maths libraries
+sudo apt install -y libsndfile1 libsndfile1-dev python3-setuptools python3-dev
+
+# HackRF drivers and utilities
+sudo apt install -y libhackrf-dev hackrf
+```
+
+### Fedora
+
+```bash
+# Audio and maths libraries
+sudo dnf install -y libsndfile libsndfile-devel python3-setuptools python3-devel
+
+# HackRF drivers and utilities
+sudo dnf install -y hackrf hackrf-devel
+```
+
+---
+
+## 4. SoapySDR + AirSpy Support
+
+Required only if using AirSpy R2, AirSpy HF+ Discovery, or other SoapySDR-compatible devices.
+
+### Debian / Ubuntu / Raspberry Pi OS
+
+```bash
+# Install SoapySDR core and Python bindings
+sudo apt install -y soapysdr-tools python3-soapysdr
+
+# Install device-specific SoapySDR modules (install only what you need)
+sudo apt install -y soapysdr-module-airspy      # AirSpy R2
+sudo apt install -y soapysdr-module-airspyhf    # AirSpy HF+ Discovery
+
+# If soapysdr-module-airspyhf is not available in your distro's repos
+# (e.g., Raspberry Pi OS), build from source instead:
+sudo apt install -y libairspyhf-dev libsoapysdr-dev cmake
+git clone https://github.com/pothosware/SoapyAirspyHF.git
+cd SoapyAirspyHF
+mkdir build && cd build
+cmake ..
+make
+sudo make install
+cd ../..
+
+# Verify SoapySDR can see connected devices
+SoapySDRUtil --find
+```
+
+### Fedora
+
+```bash
+# Install SoapySDR core and Python bindings
+sudo dnf install -y SoapySDR SoapySDR-devel python3-SoapySDR
+
+# Install device modules from the Fedora repos
+sudo dnf install -y soapy-rtlsdr        # RTL-SDR via SoapySDR
+sudo dnf install -y soapy-airspyhf      # AirSpy HF+ Discovery
+
+# AirSpy R2 module is not in the Fedora repos — build from source:
+sudo dnf install -y airspyone_host-devel SoapySDR-devel cmake
+git clone https://github.com/pothosware/SoapyAirspy.git
+cd SoapyAirspy
+mkdir build && cd build
+cmake ..
+make
+sudo make install
+cd ../..
+
+# Verify SoapySDR can see connected devices
+SoapySDRUtil --find
+```
+
+---
+
+## 5. Python Environment
+
+The same for all platforms.
+
+```bash
+# If using SoapySDR devices (AirSpy, etc.), the venv MUST inherit system
+# packages so it can access the system-installed python3-soapysdr bindings:
+python3 -m venv --system-site-packages venv
+
+# If you already have an existing venv, enable system packages on it:
+# sed -i 's/include-system-site-packages = false/include-system-site-packages = true/' /path/to/venv/pyvenv.cfg
+
+# If only using RTL-SDR or HackRF (no SoapySDR), a standard venv is fine:
+# python3 -m venv venv
+
+source venv/bin/activate
+```
+
+Then install substation. Most users want one of the first two:
+
+```bash
+# From PyPI (stable release)
+pip install substation
+
+# From GitHub (latest, no release needed)
+pip install git+https://github.com/simonholliday/substation.git
+
+# From a local clone, editable — for development
+pip install -e .
+```
+
+The default configuration ships inside the package, so no clone is needed. After installing, create an editable starter config in your working directory:
+
+```bash
+substation --init          # writes ./config.yaml (the fully-commented defaults)
+```
+
+### Optional extras
+
+```bash
+# OSC event forwarding (for MIDI sequencer, sampler, etc.)
+pip install "substation[osc]"
+```
+
+**Supervisor dashboard** (real-time WebSocket state broadcast) is a separate package installed from GitHub — it is *not* a PyPI extra, because PyPI does not permit direct-URL dependencies:
+
+```bash
+pip install git+https://github.com/simonholliday/supervisor.git
+```
+
+While the supervisor repository is private, this install uses SSH (`git+ssh://git@github.com/...`) and requires a GitHub SSH key on the machine — see [GitHub's SSH setup guide](https://docs.github.com/en/authentication/connecting-to-github-with-ssh). The scanner runs normally with the dashboard disabled if the package isn't present.
+
+After installing supervisor, enable the dashboard in `config.yaml`:
+
+```yaml
+supervisor:
+    enabled: true
+    port: 9004   # default
+```
+
+The scanner logs `Supervisor dashboard server started on ws://0.0.0.0:9004` when it starts. If the extra is not installed, a warning is logged and the scan proceeds without the dashboard.
+
+---
+
+## 6. Verification
+
+```bash
+# List available bands from the default configuration
+substation --list-bands
+
+# Or using the Python module directly
+python3 -m substation --list-bands
+```
+
+---
+
+## Platform-Specific Notes
+
+### Fedora
+
+- **SELinux**: Fedora enables SELinux in enforcing mode by default. If USB devices aren't accessible even after udev rules are in place, check for denials with `sudo ausearch -m avc -ts recent`. Typically the udev rules are sufficient.
+- **Firewalld**: If using OSC event forwarding or other network features, you may need to open ports: `sudo firewall-cmd --add-port=9000/udp --permanent && sudo firewall-cmd --reload`.
+- **lib vs lib64**: Fedora uses `/usr/lib64` for 64-bit libraries. The `ldconfig` step after building RTL-SDR should handle this, but if you get "library not found" errors, check that `/usr/local/lib64` is listed in `/etc/ld.so.conf.d/` and re-run `sudo ldconfig`.