Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions .github/workflows/cli-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,7 @@ name: CLI tests

# Build ("compile") and test the Python command-line tool across Linux,
# Windows, and macOS Apple Silicon (macos-14, running natively on arm64). The
# tests use a fake sonpy shim, so they do not require CED's proprietary
# binaries.
# tests use a fake sonpy shim, so they do not require CED's sonpy binaries.

on:
push:
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/matlab-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ name: MATLAB tests
# matbox-style CI (mirroring VH-Lab/NDR-matlab) for the +sonpipe MATLAB
# wrappers. Runs the matlab.unittest suite across Linux, Windows, and macOS
# Apple Silicon (macos-14). The MATLAB tests drive a fake sonpipe CLI
# (Python + numpy), so CED's proprietary sonpy binaries are not required.
# (Python + numpy), so CED's sonpy binaries are not required.
#
# Licensing: matlab-actions provides MathWorks licensing for free on PUBLIC
# repositories, so no token or secret is needed. (If this repo is kept private,
Expand Down
28 changes: 16 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# sonpipe

A lightweight command-line **bridge** for reading Cambridge Electronic Design
(CED) Spike2 data files. `sonpipe` extracts data from proprietary Spike2 files
with CED's [`sonpy`](https://pypi.org/project/sonpy/) library and streams it as
(CED) Spike2 data files. `sonpipe` extracts data from Spike2 files with CED's
[`sonpy`](https://pypi.org/project/sonpy/) library (GPLv3) and streams it as
**raw binary bytes** to standard output, so a host environment such as MATLAB
can ingest it in chunks — quickly, predictably, and cross-platform.

Expand All @@ -24,11 +24,12 @@ functions that call the CLI for you.
system call. It never shares MATLAB's memory space, so there are no version
locks, environment conflicts, or interpreter crashes inside your workspace.

2. **Licensing via pip.** CED's `sonpy` is proprietary. sonpipe does **not**
bundle or redistribute it; instead `pip install sonpipe` declares `sonpy` as
a dependency, so pip fetches the official, authorized CED binaries directly.
(On Apple Silicon, CED's current wheel is x86_64-only — see the Apple Silicon
note under Installation.)
2. **Licensing via pip.** CED's `sonpy` is licensed under the GPL v3. sonpipe
does **not** vendor it; instead `pip install sonpipe` declares `sonpy` as a
dependency, so pip fetches the official build from PyPI. Keeping it a runtime
dependency (rather than bundling) leaves sonpipe's own MIT distribution free
of GPL copyleft. (On Apple Silicon, CED's current wheel is x86_64-only — see
the Apple Silicon note under Installation.)

3. **No text-parsing overhead.** Waveforms and event times are written as raw
little-endian binary, not JSON/CSV text. MATLAB captures the byte stream and
Expand Down Expand Up @@ -100,9 +101,12 @@ sonpipe --version
This also installs `sonpy` (from CED, via PyPI) and `numpy`. For an isolated,
PATH-managed command you can alternatively use `pipx install sonpipe`.

> **Note on the CED license.** `sonpy` is proprietary CED software. It is
> fetched by pip at install time and is intentionally not included in this
> repository.
> **Note on the `sonpy` license.** `sonpy` is CED software licensed under the
> **GPL v3** and distributed by CED as prebuilt binaries (the underlying SON64
> C source is not published). It is fetched by pip at install time and is
> intentionally not bundled in this repository, so sonpipe's own MIT
> distribution stays free of GPL copyleft. GPL places no restrictions on *use*
> (reading your own files); obligations attach only to redistribution.

---

Expand Down Expand Up @@ -309,5 +313,5 @@ sonpipe/
## License

sonpipe is released under the MIT License (see `LICENSE`). It depends on, but
does not include, CED's proprietary `sonpy` library, which carries its own
license.
does not include, CED's `sonpy` library, which is licensed separately under the
GPL v3.
2 changes: 1 addition & 1 deletion matlab/+sonpipe/Contents.m
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
%
% The +sonpipe package reads Cambridge Electronic Design (CED) Spike2 data
% files by calling the standalone "sonpipe" command-line tool, which in turn
% uses CED's proprietary sonpy library. Python runs in its own isolated
% uses CED's sonpy library (GPLv3). Python runs in its own isolated
% process; nothing is loaded into the MATLAB interpreter, so there are no
% version locks or interpreter crashes.
%
Expand Down
10 changes: 5 additions & 5 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -19,11 +19,11 @@ classifiers = [
"Topic :: Scientific/Engineering",
]

# NOTE: sonpy is a proprietary Cambridge Electronic Design (CED) package.
# We declare it as a dependency so that `pip install sonpipe` legally and
# automatically fetches the official, authorized sonpy binaries from PyPI/CED.
# We deliberately do NOT vendor or redistribute sonpy in this repository, in
# order to comply with CED's license.
# NOTE: sonpy is Cambridge Electronic Design (CED)'s GPLv3-licensed Python
# interface to the SON64 library. We declare it as a runtime dependency so that
# `pip install sonpipe` fetches the official build from PyPI. We deliberately do
# NOT vendor it in this repository -- keeping sonpipe's own MIT distribution
# free of GPL copyleft, and letting users obtain sonpy directly from CED/PyPI.
dependencies = [
"numpy>=1.17",
"sonpy>=1.7",
Expand Down
18 changes: 9 additions & 9 deletions src/sonpipe/__init__.py
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
"""sonpipe - a CLI bridge for reading CED Spike2 .smrx / .smr files via sonpy.

sonpipe extracts data from proprietary 64-bit ``.smrx`` (and legacy 32-bit
``.smr``) files produced by the Cambridge Electronic Design (CED) Spike2
acquisition system and streams it, as raw binary bytes, to standard output.
This lets a host environment such as MATLAB drive data ingestion in chunks and
reinterpret the byte stream directly (e.g. with ``typecast``) without any
text-parsing overhead.
sonpipe extracts data from 64-bit ``.smrx`` (and legacy 32-bit ``.smr``) files
produced by the Cambridge Electronic Design (CED) Spike2 acquisition system and
streams it, as raw binary bytes, to standard output. This lets a host
environment such as MATLAB drive data ingestion in chunks and reinterpret the
byte stream directly (e.g. with ``typecast``) without any text-parsing overhead.

The proprietary reader, :mod:`sonpy`, is provided by CED and is fetched
automatically by ``pip install sonpipe``. It is intentionally *not* vendored
in this repository, to comply with CED's license.
The reader, :mod:`sonpy`, is CED's GPLv3-licensed interface to the SON64
library and is fetched automatically by ``pip install sonpipe``. It is
intentionally *not* vendored in this repository, so sonpipe's own MIT
distribution stays free of GPL copyleft.

The command-line tools mirror the reading functions found in the NDR-matlab
``ndr.format.ced`` package:
Expand Down
6 changes: 3 additions & 3 deletions src/sonpipe/sonfile.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

* the rest of sonpipe deals in plain integers, numpy arrays and dicts, and
* tests can inject a fake ``sonpy`` implementation (see ``tests/fakesonpy.py``)
and run on machines where the proprietary CED binaries are not available.
and run on machines where CED's sonpy binaries are not available.

Channel numbering
-----------------
Expand Down Expand Up @@ -55,7 +55,7 @@ def _resolve_son_module(root, importer):
def load_sonpy():
"""Import and return the sonpy module that exposes ``SonFile``.

``sonpy`` is a proprietary CED package and is not vendored with sonpipe.
``sonpy`` is CED's GPLv3-licensed package and is not vendored with sonpipe.
"""
import importlib

Expand All @@ -66,7 +66,7 @@ def load_sonpy():
"The 'sonpy' package (Cambridge Electronic Design) is required but "
"could not be imported.\n"
"Install it with: pip install sonpy\n"
"sonpy is proprietary CED software and is fetched from PyPI on "
"sonpy is CED's GPLv3-licensed software, fetched from PyPI on "
"install; it is intentionally not bundled with sonpipe.\n"
f"(import error: {exc})"
)
Expand Down
2 changes: 1 addition & 1 deletion test/+sonpipe/+unittest/TestCase.m
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
%
% Points sonpipe.executable at a fake sonpipe CLI (fakecli.py) that runs the
% real sonpipe Python code against a synthetic in-memory file, so the MATLAB
% wrappers can be tested end-to-end without CED's proprietary sonpy binaries.
% wrappers can be tested end-to-end without CED's sonpy binaries.
%
% Tests are skipped (filtered) if a working Python 3 with numpy is not found.

Expand Down
2 changes: 1 addition & 1 deletion test/+sonpipe/+unittest/fakecli.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"""A stand-in for the ``sonpipe`` command-line tool, for MATLAB unit tests.

It runs the *real* sonpipe CLI code, but injects the test fake sonpy module in
place of CED's proprietary ``sonpy``. That way the MATLAB ``+sonpipe`` wrappers
place of CED's ``sonpy``. That way the MATLAB ``+sonpipe`` wrappers
can be exercised end-to-end (argument construction, JSON decoding, binary
typecast, channel dispatch, time-vector math) on any machine, without the CED
binaries and without a Python/MATLAB in-process bridge.
Expand Down
6 changes: 3 additions & 3 deletions tests/fakesonpy.py
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
"""A minimal fake of the CED ``sonpy.lib`` module for testing.

It reproduces the parts of the ``sonpy`` API that :class:`sonpipe.SmrxFile`
relies on, so the package can be exercised on machines without CED's
proprietary binaries. It is *not* a real SON file reader -- it serves synthetic
in-memory data whose shape matches what real sonpy returns.
relies on, so the package can be exercised on machines without CED's sonpy
binaries. It is *not* a real SON file reader -- it serves synthetic in-memory
data whose shape matches what real sonpy returns.

The channel layout of the default fake file (mirrors a small Spike2 file):

Expand Down
2 changes: 1 addition & 1 deletion tests/test_integration.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

They run when BOTH of the following hold:

* the ``sonpy`` package (proprietary CED) is importable, and
* the ``sonpy`` package (CED, GPLv3) is importable, and
* a real Spike2 file is available -- by default the repository's
``example/spike2data.smrx``, or whatever ``SONPIPE_TEST_FILE`` points at.

Expand Down
Loading