refactor signalhound, add tests, add docs, increment to v1.8.0

Author: Kyle A Logue

README.md

@@ -32,6 +32,7 @@ sample_rate = meta.sample_rate  # get sample rate
 # read other formats containing RF time series as SigMF
 meta = sigmf.fromfile("recording.wav")   # WAV
 meta = sigmf.fromfile("recording.cdif")  # BLUE / Platinum
+meta = sigmf.fromfile("recording.xml")   # Signal Hound Spike
 ```
 
 ### Docs

docs/requirements.txt

@@ -1,3 +1,2 @@
-# pinned 2025-01-15
-sphinx==8.1.3
-sphinx-rtd-theme==3.0.2
+sphinx>=8.0
+sphinx-rtd-theme>=3.0

docs/source/converters.rst

@@ -12,6 +12,7 @@ Conversion is available for:
 
 * **BLUE files** - MIDAS Blue and Platinum BLUE RF recordings (usually ``.cdif``)
 * **WAV files** - Audio recordings (``.wav``)
+* **Signal Hound Spike files** - Signal Hound zero-span recordings (``.xml`` + ``.iq``)
 
 All converters return a :class:`~sigmf.SigMFFile` object with converted metadata.
 
@@ -29,6 +30,7 @@ formats and reads without writing any output files:
     # auto-detect and create NCD for any supported format
     meta = sigmf.fromfile("recording.cdif")  # BLUE file
     meta = sigmf.fromfile("recording.wav")   # WAV file
+    meta = sigmf.fromfile("recording.xml")   # Signal Hound Spike file
     meta = sigmf.fromfile("recording.sigmf")  # SigMF archive
 
     all_samples = meta.read_samples()
@@ -44,13 +46,17 @@ For programmatic access, use the individual converter functions directly:
 
     from sigmf.convert.wav import wav_to_sigmf
     from sigmf.convert.blue import blue_to_sigmf
+    from sigmf.convert.signalhound import signalhound_to_sigmf
 
     # convert WAV to SigMF archive
     _ = wav_to_sigmf(wav_path="recording.wav", out_path="recording", create_archive=True)
 
     # convert BLUE to SigMF pair and return metadata for new files
     meta = blue_to_sigmf(blue_path="recording.cdif", out_path="recording")
 
+    # convert Signal Hound Spike to SigMF pair
+    meta = signalhound_to_sigmf(signalhound_path="recording.xml", out_path="recording")
+
 
 Command Line Usage
 ~~~~~~~~~~~~~~~~~~
@@ -65,8 +71,9 @@ Converters are accessed through a unified command-line interface that automatica
     # examples
     sigmf_convert recording.cdif recording.sigmf
     sigmf_convert recording.wav recording.sigmf
+    sigmf_convert recording.xml recording.sigmf
 
-The converter uses magic byte detection to automatically identify BLUE and WAV file formats.
+The converter uses magic byte detection to automatically identify BLUE, WAV, and Signal Hound Spike file formats.
 No need to remember format-specific commands!
 
 
@@ -168,4 +175,38 @@ Examples
 
     # access standard SigMF data & metadata
     all_samples = meta.read_samples()
-    sample_rate_hz = meta.sample_rate
+    sample_rate_hz = meta.sample_rate
+
+
+Signal Hound Spike Converter
+-----------------------------
+
+The Signal Hound Spike converter handles recordings from Signal Hound devices.
+These recordings consist of two files: an XML metadata file (``.xml``) and a binary IQ data file (``.iq``).
+The converter extracts metadata from the XML file and references the IQ data file, storing Signal Hound-specific
+fields in the ``spike:`` namespace extension.
+
+.. autofunction:: sigmf.convert.signalhound.signalhound_to_sigmf
+
+Examples
+~~~~~~~~
+
+.. code-block:: python
+
+    from sigmf.convert.signalhound import signalhound_to_sigmf
+
+    # standard conversion (provide path to XML file)
+    meta = signalhound_to_sigmf(signalhound_path="recording.xml", out_path="recording")
+
+    # create NCD automatically (metadata-only, references original .iq file)
+    meta = signalhound_to_sigmf(signalhound_path="recording.xml")
+
+    # access standard SigMF data & metadata
+    all_samples = meta.read_samples()
+    sample_rate = meta.sample_rate
+    center_freq = meta.get_captures()[0]["core:frequency"]
+
+    # access Signal Hound-specific metadata in spike: namespace
+    reference_level = meta.get_global_field("spike:reference_level")
+    if_bandwidth = meta.get_global_field("spike:if_bandwidth")
+    decimation = meta.get_global_field("spike:decimation")

docs/source/developers.rst

@@ -60,6 +60,7 @@ To build the docs and host locally:
 .. code-block:: console
 
    $ cd docs
+   $ pip install -r requirements.txt
    $ make clean
    $ make html
    $ python3 -m http.server --directory build/html/

sigmf/__init__.py

@@ -5,7 +5,7 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 
 # version of this python module
-__version__ = "1.7.0"
+__version__ = "1.8.0"
 # matching version of the SigMF specification
 __specification__ = "1.2.6"
 

sigmf/convert/__main__.py

@@ -98,7 +98,6 @@ def main() -> None:
         # BLUE file
         _ = blue_to_sigmf(blue_path=input_path, out_path=output_path, create_archive=args.archive, create_ncd=args.ncd)
 
-    ## TODO: Determine proper way to integrate Signal Hound files. 
     elif magic_bytes == b"<?xm": # <?xml version="1.0" encoding="UTF-8"?> <SignalHoundIQFile Version="1.0">
        # Signal Hound Spike 1.0 file
         # Of the 66 Byte string move 43 bytes in to skip the XML declaration
@@ -109,12 +108,12 @@ def main() -> None:
         else:
           raise SigMFConversionError(
             f"Unsupported XML file format. Expanded Magic bytes: {expanded_magic_bytes}. "
-            f"Supported formats for conversion are WAV, BLUE/Platinum and Signal Hound Spike."
+            f"Supported formats for conversion are WAV, BLUE/Platinum, and Signal Hound Spike."
         )
     else:
         raise SigMFConversionError(
             f"Unsupported file format. Magic bytes: {magic_bytes}. "
-            f"Supported formats for conversion are WAV, BLUE/Platinum and Signal Hound Spike."
+            f"Supported formats for conversion are WAV, BLUE/Platinum, and Signal Hound Spike."
         )
 
 

sigmf/convert/blue.py

@@ -25,7 +25,6 @@
 import numpy as np
 from packaging.version import InvalidVersion, Version
 
-from .. import __version__ as toolversion
 from ..error import SigMFConversionError
 from ..sigmffile import SigMFFile, fromfile, get_sigmf_filenames
 from ..utils import SIGMF_DATETIME_ISO8601_FMT