Skip to main content

SerenGanglion

Seren's reflexes on the M5Stack LLM module.

A ganglion is a cluster of nerve cells outside the brain that runs reflexes without asking it, and a wake word is a reflex. This one lives on the LLM module inside a StackChan: a StackFlow unit beside M5's own, on the module's own Linux. It does the module's work there, and the robot's core hears only what it needs. It sits in the Seren family beside Sinew, Meninges, Soma and Psycheion.

What's in it (today)

Early. The pieces under the unit are built and tested; the unit itself is not.

  • seren-ganglion check: what this module is, read-only. Its Python and C library, the versions it carries, StackFlow's sockets and who may connect to them, how M5 starts its units, and whether a microSD card shows up. Every part answers on its own, so one that can't run says why and the rest still report. It writes nothing and opens no socket.
  • The StackFlow wire (seren_ganglion.wire): the framing M5's units use between themselves, read from M5's own C++ (pzmq.hpp, StackFlow.cpp), standard library only.
  • The sys client (seren_ganglion.sys_client): registering with StackFlow's sys unit and calling any unit over ZeroMQ. It's the one part that needs pyzmq.
  • The .deb, built on every release: one file with everything inside, for a module with no network.

Install

On a module

Download seren-ganglion_<version>_arm64.deb from the releases and check it against that release's SHA256SUMS. Get it onto the module however you have to hand (below), then:

dpkg -i seren-ganglion_<version>_arm64.deb
seren-ganglion check

The module needs no pip, no venv and no network. Everything is under /opt/seren/ganglion/, and dpkg -r seren-ganglion takes it all away again.

For working on it

pip install seren-ganglion

That gives you the Python package on a desktop, for development and tests. To fetch the wheels for a module by hand: Ganglion and Sinew are pure Python, but pyzmq has to be fetched for the module's platform. It comes as one file, pyzmq-26.4.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl, with ZeroMQ's library inside:

pip download seren-ganglion seren-sinew --no-deps -d ganglion-wheels
pip download pyzmq --only-binary=:all: --platform manylinux2014_aarch64 --python-version 3.10 --no-deps -d ganglion-wheels

--no-deps because Sinew's declared dependencies (starlette and its family) are never imported here. On the module a wheel is a zip, and python3 -m zipfile -e <wheel> <folder> needs nothing that isn't already there.

Where it runs

The LLM module (AX630C) is its own computer inside the StackChan: Ubuntu 22.04 (arm64), kernel 4.19, about 1 GB of RAM, 32 GB of eMMC, M5's StackFlow units, and no network of its own. It talks to the CoreS3 over one UART, as JSON lines at up to 1.5 Mbaud. What's known about the module, and how it was found, is in SerenSoma's firmware/docs/appendages.md, under "The LLM module as ears".

A package, not a distro. Forking M5's image would mean their Windows-only reflash, with the module out of the stack, for every mistake, and owning a kernel 4.19 BSP with closed NPU blobs through every M5 update. Everything we want lives above the kernel, so it's one .deb beside M5's packages.

Python 3.10 is the floor because it's the module's. Raise it and the module falls off.

What it will do

It joins StackFlow as the unit ganglion, so the core reaches it as ganglion.<n> through the same locked route it uses for M5's units: one more name on that route's allow list. bashexec, push, upgrade and rmmode stay off the robot's API.

  • Listening, wired inside the module. Wake word, VAD and Whisper chained on the module. The core gets one finished event, heard, with its text and timing. Only text crosses the UART.
  • Face sounds. It plays the MP3s the core forwards. M5's audio.play takes wav, mp3 or pcm, not Opus, so Psycheion's Face Studio makes the MP3s; at most about 64 KB a line.
  • The three LEDs, its health, its versions.
  • Its own upkeep: updating M5's StackFlow as a script anyone can run, telnet on port 23 switched off at install, and a refusal to run on a StackFlow older than the one tested.

Its shapes live in Sinew, beside the robot's, with the same contract test, so the two ends can't drift. Sinew's body shapes import with the standard library alone from 5.10 on, and tests/test_sinew_on_the_module.py holds us to it: it fails on 5.9, which imports starlette at its front door.

It can be Python. StackFlow units talk ZeroMQ over socket files, and the protocol doesn't care what a unit is written in (Psycheion read pzmq.hpp and StackFlow.cpp, 20 Nov; checked the same night):

  • Each unit answers requests on a REP socket at ipc:///tmp/rpc.<unit>. A call is two frames, the action then its data, and the answer is one frame.
  • Two values travel as one string: a byte giving the first one's length, the first, then the second.
  • A unit joins by calling sys's register_unit with its name. The answer is nested: its work id number, paired with a second pair of its output URL and its inference URL.

The mic light is the core's, never the ganglion's

Psycheion, 20 Nov; Chad: "yes yes yes". A unit that crashes or hangs could leave a mic open and never say so, which is the hidden microphone again. So:

  1. The ganglion opens a mic only when the core tells it to. Never on its own, and never by itself after a restart.
  2. The core doesn't take its word for it. Every few seconds it asks sys.lstask. If anything that captures audio is running (ours, or M5's audio, kws, vad, asr or whisper), the light is on.
  3. No answer counts as listening. A module that stops replying keeps the light on until it answers.

The ganglion's own "mic open" event is still wanted, for the face's listening look, because it's fast. It never decides the light.

Connections: however the person brings it

Chad, 20 Nov: the module has a microSD slot and a USB-C port, and the Ethernet board "doesn't really go on for the real stuff". So nothing assumes a network.

  • Talking to the robot is always the UART, through the core. It's the one link every StackChan with a module has. The ganglion listens on no network port.

  • Getting the .deb and models on takes whichever of these is to hand:

    Way How
    microSD Copy it onto the card
    USB-C adb push from a computer
    Ethernet, if someone has it Download it on the module
    The UART Later, through Soma (below). About ten seconds for the .deb

Who it runs as

Psycheion, 21 Nov: the ganglion parses whatever the core sends, so a parsing bug as root is a root bug, on the box we locked bashexec away from. M5's units run as root, and their sockets may admit only root. Connecting to a unix socket needs write permission on its file, which check reports.

  • If the sockets let a group write, the .deb makes a ganglion system user in that group, and the unit runs as it.

  • If they're root-only, it runs as root, boxed by systemd, and this section says so until it's fixed:

    NoNewPrivileges=yes
    CapabilityBoundingSet=
    ProtectSystem=strict
    ReadWritePaths=/var/lib/seren-ganglion /tmp
    ProtectHome=yes
    PrivateNetwork=yes
    RestrictAddressFamilies=AF_UNIX
    

    That means no capabilities, a read-only system apart from its own state and the sockets, and no network at all. Path-based unix sockets still work across a private network namespace, so StackFlow is reachable and nothing else is. PrivateTmp stays off, because the sockets live in /tmp. These need checking against the module's systemd before they're trusted.

  • We don't change M5's units to loosen their sockets. A drop-in that changed how their root processes create files would reach well past ours.

No systemd unit ships yet. It waits for the unit to exist, and for check's answers on a real module. A service that can only fail is worse than none.

Later: Soma installs it for you

Soma already fetches firmware from GitHub releases and checks checksums before staging it. It could fetch this .deb the same way and send it to the module through the core. Psycheion, 21 Nov: installing a .deb is dpkg -i as root, so while that install mode is on, whoever holds the robot's token has root on the module. A checksum on the NUC proves the right file left the NUC, not who's sending it now. So, before anyone builds the convenient version:

  • The switch is hands on the robot, not the token: for example, holding the head for five seconds in the first two minutes after a boot. Soma's page says "touch the robot to allow the install".
  • It closes after one install or ten minutes, whichever comes first.
  • It takes one file to one fixed path and runs one fixed command, dpkg -i on that path. The core builds the command itself; nothing the caller sends ends up in it. It never takes shell lines.

Releasing

The family's shape (.github/workflows/release.yml):

  1. Every push: the tests, on Python 3.10 to 3.14. The first set is the leanest, Sinew and pytest only, as close to the module as a runner gets; [dev] adds pyzmq for the socket tests.
  2. A vX.Y.Z tag on main: setuptools_scm takes the version from the tag, so the wheel and the .deb always carry the same number.
  3. The wheel and sdist are built, then the .deb by tools/build_deb.py. That's pure Python, so it builds the same on a desktop as in CI, with no dpkg needed. Everything inside is pure Python or an already-built wheel, so there's nothing to compile for ARM. It carries the wheel just built, the newest Sinew the pyproject allows, and pyzmq for the module, and records each with its checksum in /opt/seren/ganglion/BUNDLED. File times come from the tagged commit, so a rebuild is byte-identical.
  4. The GitHub release gets the wheel, the sdist, the .deb and SHA256SUMS. PyPI gets the wheel and sdist, by trusted publishing, so no token is stored.

A dev version like 0.2.0.dev3 becomes 0.2.0~dev3 in the .deb, so dpkg sorts it before 0.2.0.

Layout

Where What
seren_ganglion/check.py seren-ganglion check, read-only
seren_ganglion/wire.py StackFlow's framing. Standard library only
seren_ganglion/sys_client.py RPC to sys or any unit over ZeroMQ
tools/build_deb.py The .deb, from wheels
Sinew, seren_sinew.ganglion (to come) The shapes the ganglion and the core exchange
SerenSoma The core's half: forwarding to ganglion, the lstask check behind the mic light, the allow list

Tests

cd SerenGanglion
pip install -e ".[test]"
python -m pytest

The socket tests run against a fake sys on tcp, because Windows has no ipc sockets. The .deb is read back the way dpkg reads it, and a real one was checked with dpkg-deb on 21 Nov.

What's coming

  1. check on a real module: who the unit runs as, and how M5 starts theirs.
  2. The unit: registering with sys, serving setup, work and exit, then listening.
  3. A systemd unit and the install scripts in the .deb, including telnet off.
  4. Its shapes in Sinew, and the core's half in Soma.

AGPL-3.0-or-later.

Metadata

Release files for seren-ganglion 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for seren-ganglion 0.3.0
File Size Uploaded Provenance Actions
seren_ganglion-0.3.0.tar.gz 24.0 kB With provenance Details for seren_ganglion-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for seren-ganglion 0.3.0
File Interpreter ABI Platform Actions
seren_ganglion-0.3.0-py3-none-any.whl Python 3 none any Details for seren_ganglion-0.3.0-py3-none-any.whl

Total release size: 36.8 kB

Release files / seren_ganglion-0.3.0.tar.gz

Download URL seren_ganglion-0.3.0.tar.gz
Size 24.0 kB
Tags Source
SHA-256 checksum
How to use checksums
d7e3296fd3bd7f24feab4d33281be21f33c5d1bcf9ab21c7c59178082c0c76e9
BLAKE2b-256 checksum
How to use checksums
21c703ffe761ace45209a7b52d5bdfd424a53a2aea1767b20cad4e2b549a64b3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / seren_ganglion-0.3.0-py3-none-any.whl

Download URL seren_ganglion-0.3.0-py3-none-any.whl
Size 12.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9c3155f9b1126963454f4452c056bfd4b478a684d58ef8849ea35048dcf2d878
BLAKE2b-256 checksum
How to use checksums
2ccb176f32765d090dea89a30f6ec65a3a6b8f7d8262641bd548667036fb6312
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for seren-ganglion 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for seren_ganglion-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page