pieeg-server 0.1.0__tar.gz

pieeg_server-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 PiEEG Community
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pieeg_server-0.1.0/PKG-INFO

@@ -0,0 +1,288 @@
+Metadata-Version: 2.4
+Name: pieeg-server
+Version: 0.1.0
+Summary: One-command local streaming server for PiEEG-16 (16-channel EEG shield for Raspberry Pi)
+Author: PiEEG Community
+License: MIT License
+        
+        Copyright (c) 2025 PiEEG Community
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/yelabb/PiEEG-16-server
+Project-URL: Documentation, https://pieeg.com/docs/docs/pieeg-16/
+Project-URL: Repository, https://github.com/yelabb/PiEEG-16-server
+Project-URL: Issues, https://github.com/yelabb/PiEEG-16-server/issues
+Keywords: eeg,bci,raspberry-pi,pieeg,neuroscience,websocket,brain-computer-interface,ads1299,spi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: POSIX :: Linux
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: websockets>=12.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: rich>=13.0
+Provides-Extra: rpi
+Requires-Dist: spidev>=3.6; extra == "rpi"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Dynamic: license-file
+
+# PiEEG-16-server
+
+A lightweight server for the [PiEEG-16](https://github.com/pieeg-club/PiEEG-16) shield that initializes the hardware, reads 16 channels at 250 Hz, streams live data over WebSocket, and serves a real-time dashboard — all on your local network.
+
+## Install
+
+> Pick **one** method. They all get you to the same place: `pieeg-server` ready to run.
+
+### Option A — One-line install (recommended)
+
+SSH into your Pi and paste:
+
+```bash
+curl -sSL https://raw.githubusercontent.com/yelabb/PiEEG-16-server/main/install.sh | bash
+sudo reboot   # only needed first time, to enable SPI
+```
+
+### Option B — Clone & setup
+
+```bash
+git clone https://github.com/yelabb/PiEEG-16-server.git
+cd PiEEG-16-server
+chmod +x setup.sh
+./setup.sh
+sudo reboot   # only needed first time, to enable SPI
+```
+
+---
+
+## Run
+
+```bash
+pieeg-server              # start streaming
+pieeg-server --filter     # with 1–40 Hz bandpass filter
+pieeg-server --monitor    # with live terminal display
+pieeg-server --mock       # synthetic data, no hardware needed
+pieeg-server doctor       # diagnose SPI, GPIO, deps, permissions
+```
+
+That's it. LEDs turn on, data streams to `ws://raspberrypi.local:1616`.
+
+Open **http://raspberrypi.local:1617** in any browser on your network for the real-time dashboard.
+
+<img height="400" alt="image" src="https://github.com/user-attachments/assets/3f33bfd4-c721-4b94-a672-2a0b744d127b" />
+
+### Terminal
+<img width="422" height="475" alt="image" src="https://github.com/user-attachments/assets/7d58af68-85c4-41d3-b1ab-89b23e99faff" />
+
+
+**Ports:**
+- **`:1616`** — WebSocket data stream (PiEEG-**16** → **1616**)
+- **`:1617`** — Web dashboard (next door)
+
+## Record data
+
+```bash
+pieeg-server record session.csv                   # record until Ctrl-C
+pieeg-server record session.csv --duration 300     # record 5 minutes
+pieeg-server --record session.csv                  # record while streaming
+pieeg-server --record session.csv --record-duration 60  # record 60s while streaming
+```
+
+CSV format: `timestamp, ch1, ch2, ..., ch16` (compatible with the official PiEEG-16 dataset format).
+
+## Terminal monitor
+
+```bash
+pieeg-server monitor          # standalone live view (no server)
+pieeg-server --monitor        # live view alongside the server
+```
+
+Displays all 16 channels with real-time µV values and sparkline waveforms directly in the terminal. Works over SSH — no browser or display needed.
+
+> **`pieeg-server: command not found`?** Run `pieeg-server doctor` (or `./setup.sh` again).
+> As a fallback: `cd PiEEG-16-server && .venv/bin/pieeg-server`
+
+## Troubleshooting
+
+```bash
+pieeg-server doctor
+```
+
+Checks everything in one shot: Pi model, Python version, SPI devices, GPIO chips, file permissions, port availability, installed dependencies, systemd service. Returns exit code `0` (all good), `1` (warnings), or `2` (errors) — scriptable with `--quiet`.
+
+### Windows: `Could not install packages due to an OSError`
+
+If `pip install -e .` fails with a `WinError 2` or `Failed to write executable` error, pip can't replace an old `pieeg-server.exe` in your Python Scripts folder. Fix it:
+
+```powershell
+pip uninstall pieeg-server -y
+pip install -e .
+```
+
+If that still fails, run your terminal **as Administrator** (right-click → Run as administrator).
+
+> On Windows you can only use mock mode (`pieeg-server --mock`) since SPI/GPIO hardware is not available.
+
+## Connect from any device
+
+### Python
+
+```python
+import asyncio, json, websockets
+
+async def main():
+    async with websockets.connect("ws://raspberrypi.local:1616") as ws:
+        async for message in ws:
+            frame = json.loads(message)
+            print(f"Sample #{frame['n']}: {frame['channels']}")
+
+asyncio.run(main())
+```
+
+### JavaScript (browser)
+
+```javascript
+const ws = new WebSocket("ws://raspberrypi.local:1616");
+ws.onmessage = (event) => {
+    const frame = JSON.parse(event.data);
+    console.log(`Sample #${frame.n}:`, frame.channels);
+};
+```
+
+## Data Format
+
+Each WebSocket message is a JSON frame:
+
+```json
+{
+    "t": 1711234567.123456,
+    "n": 42,
+    "channels": [12.34, -5.67, 8.90, ...]
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `t` | float | Unix timestamp (seconds) |
+| `n` | int | Sample number (monotonic) |
+| `channels` | float[16] | Voltage in microvolts (µV) per channel |
+
+## CLI Options
+
+```
+pieeg-server [OPTIONS] [COMMAND]
+
+Commands:
+  doctor                 Diagnose hardware, software, and configuration
+  record FILE            Record EEG data to CSV (standalone, no server)
+  monitor                Live terminal display (standalone, no server)
+
+Server options:
+  --host HOST            Bind address (default: 0.0.0.0)
+  --port PORT            WebSocket port (default: 1616)
+  --dashboard-port PORT  Dashboard HTTP port (default: 1617)
+  --no-dashboard         Disable the web dashboard
+  --gpio-chip PATH       GPIO chip device path (default: /dev/gpiochip4)
+  --filter               Enable 1–40 Hz bandpass filter server-side
+  --lowcut HZ            Filter low cutoff (default: 1.0)
+  --highcut HZ           Filter high cutoff (default: 40.0)
+  --record FILE          Record to CSV while streaming
+  --record-duration SEC  Stop recording after N seconds
+  --monitor              Show live terminal monitor alongside server
+  --mock                 Synthetic EEG data (no hardware needed)
+  -v, --verbose          Debug logging
+```
+
+## Runtime Commands
+
+Clients can send JSON commands over the WebSocket:
+
+```json
+{"cmd": "set_filter", "enabled": true, "lowcut": 1.0, "highcut": 40.0}
+{"cmd": "set_filter", "enabled": false}
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Raspberry Pi 5 + PiEEG-16 Shield                       │
+│                                                          │
+│  hardware.py     → SPI/GPIO init, ADC register config    │
+│       ↓                                                  │
+│  acquisition.py  → 250 Hz read loop (background thread)  │
+│       ↓ pub/sub (multiple consumers)                     │
+│       ├── server.py    → WebSocket broadcast             │
+│       ├── recorder.py  → CSV file writer                 │
+│       └── monitor.py   → Terminal sparkline display      │
+│       ↓                                                  │
+│  dashboard.py    → HTTP server for real-time web UI       │
+│       ↓                                                  │
+│  ws://0.0.0.0:1616  │  http://0.0.0.0:1617              │
+└──────────┬───────────────────────────────────────────────┘
+           │  Local network
+           ├── Browser (JS client)
+           ├── Python notebook
+           ├── Mobile app
+           └── Any WebSocket client
+```
+
+## Runs as a Service
+
+Setup creates a systemd service that auto-starts on boot:
+
+```bash
+sudo systemctl status pieeg-server    # check status
+sudo systemctl stop pieeg-server      # stop
+sudo systemctl restart pieeg-server   # restart
+journalctl -u pieeg-server -f         # view logs
+```
+
+## GPIO: No `gpiod` Dependency
+
+This server talks to GPIO directly via the Linux kernel's character device interface (`/dev/gpiochipN`) using standard `ioctl` calls — no `gpiod` pip package needed.
+
+We only use two GPIO pins (chip-select output + data-ready input), so the ~20 lines of `struct` packing replace an entire external dependency that:
+
+- Has **breaking API changes** between v1 and v2 (completely incompatible)
+- Requires **system C headers** (`libgpiod-dev`) to install via pip
+- Only works on **Linux** (blocks development/testing on macOS/Windows)
+
+The chardev v1 ioctl ABI has been stable since Linux 4.8 (2016) and is guaranteed not to break by the kernel's userspace compatibility policy.
+
+## Safety
+
+> **PiEEG-16 must operate from battery power (5V) only.**
+> Do NOT connect to mains-powered equipment via USB.
+> PiEEG-16 is NOT a medical device.
+
+## License
+
+MIT

pieeg_server-0.1.0/README.md

@@ -0,0 +1,233 @@
+# PiEEG-16-server
+
+A lightweight server for the [PiEEG-16](https://github.com/pieeg-club/PiEEG-16) shield that initializes the hardware, reads 16 channels at 250 Hz, streams live data over WebSocket, and serves a real-time dashboard — all on your local network.
+
+## Install
+
+> Pick **one** method. They all get you to the same place: `pieeg-server` ready to run.
+
+### Option A — One-line install (recommended)
+
+SSH into your Pi and paste:
+
+```bash
+curl -sSL https://raw.githubusercontent.com/yelabb/PiEEG-16-server/main/install.sh | bash
+sudo reboot   # only needed first time, to enable SPI
+```
+
+### Option B — Clone & setup
+
+```bash
+git clone https://github.com/yelabb/PiEEG-16-server.git
+cd PiEEG-16-server
+chmod +x setup.sh
+./setup.sh
+sudo reboot   # only needed first time, to enable SPI
+```
+
+---
+
+## Run
+
+```bash
+pieeg-server              # start streaming
+pieeg-server --filter     # with 1–40 Hz bandpass filter
+pieeg-server --monitor    # with live terminal display
+pieeg-server --mock       # synthetic data, no hardware needed
+pieeg-server doctor       # diagnose SPI, GPIO, deps, permissions
+```
+
+That's it. LEDs turn on, data streams to `ws://raspberrypi.local:1616`.
+
+Open **http://raspberrypi.local:1617** in any browser on your network for the real-time dashboard.
+
+<img height="400" alt="image" src="https://github.com/user-attachments/assets/3f33bfd4-c721-4b94-a672-2a0b744d127b" />
+
+### Terminal
+<img width="422" height="475" alt="image" src="https://github.com/user-attachments/assets/7d58af68-85c4-41d3-b1ab-89b23e99faff" />
+
+
+**Ports:**
+- **`:1616`** — WebSocket data stream (PiEEG-**16** → **1616**)
+- **`:1617`** — Web dashboard (next door)
+
+## Record data
+
+```bash
+pieeg-server record session.csv                   # record until Ctrl-C
+pieeg-server record session.csv --duration 300     # record 5 minutes
+pieeg-server --record session.csv                  # record while streaming
+pieeg-server --record session.csv --record-duration 60  # record 60s while streaming
+```
+
+CSV format: `timestamp, ch1, ch2, ..., ch16` (compatible with the official PiEEG-16 dataset format).
+
+## Terminal monitor
+
+```bash
+pieeg-server monitor          # standalone live view (no server)
+pieeg-server --monitor        # live view alongside the server
+```
+
+Displays all 16 channels with real-time µV values and sparkline waveforms directly in the terminal. Works over SSH — no browser or display needed.
+
+> **`pieeg-server: command not found`?** Run `pieeg-server doctor` (or `./setup.sh` again).
+> As a fallback: `cd PiEEG-16-server && .venv/bin/pieeg-server`
+
+## Troubleshooting
+
+```bash
+pieeg-server doctor
+```
+
+Checks everything in one shot: Pi model, Python version, SPI devices, GPIO chips, file permissions, port availability, installed dependencies, systemd service. Returns exit code `0` (all good), `1` (warnings), or `2` (errors) — scriptable with `--quiet`.
+
+### Windows: `Could not install packages due to an OSError`
+
+If `pip install -e .` fails with a `WinError 2` or `Failed to write executable` error, pip can't replace an old `pieeg-server.exe` in your Python Scripts folder. Fix it:
+
+```powershell
+pip uninstall pieeg-server -y
+pip install -e .
+```
+
+If that still fails, run your terminal **as Administrator** (right-click → Run as administrator).
+
+> On Windows you can only use mock mode (`pieeg-server --mock`) since SPI/GPIO hardware is not available.
+
+## Connect from any device
+
+### Python
+
+```python
+import asyncio, json, websockets
+
+async def main():
+    async with websockets.connect("ws://raspberrypi.local:1616") as ws:
+        async for message in ws:
+            frame = json.loads(message)
+            print(f"Sample #{frame['n']}: {frame['channels']}")
+
+asyncio.run(main())
+```
+
+### JavaScript (browser)
+
+```javascript
+const ws = new WebSocket("ws://raspberrypi.local:1616");
+ws.onmessage = (event) => {
+    const frame = JSON.parse(event.data);
+    console.log(`Sample #${frame.n}:`, frame.channels);
+};
+```
+
+## Data Format
+
+Each WebSocket message is a JSON frame:
+
+```json
+{
+    "t": 1711234567.123456,
+    "n": 42,
+    "channels": [12.34, -5.67, 8.90, ...]
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `t` | float | Unix timestamp (seconds) |
+| `n` | int | Sample number (monotonic) |
+| `channels` | float[16] | Voltage in microvolts (µV) per channel |
+
+## CLI Options
+
+```
+pieeg-server [OPTIONS] [COMMAND]
+
+Commands:
+  doctor                 Diagnose hardware, software, and configuration
+  record FILE            Record EEG data to CSV (standalone, no server)
+  monitor                Live terminal display (standalone, no server)
+
+Server options:
+  --host HOST            Bind address (default: 0.0.0.0)
+  --port PORT            WebSocket port (default: 1616)
+  --dashboard-port PORT  Dashboard HTTP port (default: 1617)
+  --no-dashboard         Disable the web dashboard
+  --gpio-chip PATH       GPIO chip device path (default: /dev/gpiochip4)
+  --filter               Enable 1–40 Hz bandpass filter server-side
+  --lowcut HZ            Filter low cutoff (default: 1.0)
+  --highcut HZ           Filter high cutoff (default: 40.0)
+  --record FILE          Record to CSV while streaming
+  --record-duration SEC  Stop recording after N seconds
+  --monitor              Show live terminal monitor alongside server
+  --mock                 Synthetic EEG data (no hardware needed)
+  -v, --verbose          Debug logging
+```
+
+## Runtime Commands
+
+Clients can send JSON commands over the WebSocket:
+
+```json
+{"cmd": "set_filter", "enabled": true, "lowcut": 1.0, "highcut": 40.0}
+{"cmd": "set_filter", "enabled": false}
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Raspberry Pi 5 + PiEEG-16 Shield                       │
+│                                                          │
+│  hardware.py     → SPI/GPIO init, ADC register config    │
+│       ↓                                                  │
+│  acquisition.py  → 250 Hz read loop (background thread)  │
+│       ↓ pub/sub (multiple consumers)                     │
+│       ├── server.py    → WebSocket broadcast             │
+│       ├── recorder.py  → CSV file writer                 │
+│       └── monitor.py   → Terminal sparkline display      │
+│       ↓                                                  │
+│  dashboard.py    → HTTP server for real-time web UI       │
+│       ↓                                                  │
+│  ws://0.0.0.0:1616  │  http://0.0.0.0:1617              │
+└──────────┬───────────────────────────────────────────────┘
+           │  Local network
+           ├── Browser (JS client)
+           ├── Python notebook
+           ├── Mobile app
+           └── Any WebSocket client
+```
+
+## Runs as a Service
+
+Setup creates a systemd service that auto-starts on boot:
+
+```bash
+sudo systemctl status pieeg-server    # check status
+sudo systemctl stop pieeg-server      # stop
+sudo systemctl restart pieeg-server   # restart
+journalctl -u pieeg-server -f         # view logs
+```
+
+## GPIO: No `gpiod` Dependency
+
+This server talks to GPIO directly via the Linux kernel's character device interface (`/dev/gpiochipN`) using standard `ioctl` calls — no `gpiod` pip package needed.
+
+We only use two GPIO pins (chip-select output + data-ready input), so the ~20 lines of `struct` packing replace an entire external dependency that:
+
+- Has **breaking API changes** between v1 and v2 (completely incompatible)
+- Requires **system C headers** (`libgpiod-dev`) to install via pip
+- Only works on **Linux** (blocks development/testing on macOS/Windows)
+
+The chardev v1 ioctl ABI has been stable since Linux 4.8 (2016) and is guaranteed not to break by the kernel's userspace compatibility policy.
+
+## Safety
+
+> **PiEEG-16 must operate from battery power (5V) only.**
+> Do NOT connect to mains-powered equipment via USB.
+> PiEEG-16 is NOT a medical device.
+
+## License
+
+MIT

pieeg_server-0.1.0/pieeg_server/__init__.py

@@ -0,0 +1,3 @@
+"""PiEEG-16-server: One-command EEG data streaming server."""
+
+__version__ = "0.1.0"