# TTY eBPF Monitor Python Client
[](https://badge.fury.io/py/tty-egpf-monitor)
[](https://pypi.org/project/tty-egpf-monitor/)
[](https://www.gnu.org/licenses/gpl-3.0)
A Python client library for [TTY eBPF Monitor](https://github.com/seelso-net/tty-egpf-monitor), providing a clean, Pythonic interface to monitor serial port activity using eBPF technology.
## Features
- 🐍 **Pure Python** - No C dependencies, works with any Python 3.8+
- 🔌 **Unix Socket API** - Communicates with daemon via Unix domain socket
- 📊 **Parsed Log Entries** - Automatic parsing of log format with timestamps
- 🔄 **Live Streaming** - Real-time event streaming with iterator interface
- 🛠️ **CLI Wrapper** - Drop-in replacement for the C CLI tool
- 📚 **Rich Examples** - Comprehensive examples for common use cases
- 🔍 **Data Analysis** - Built-in support for protocol analysis and debugging
## Installation
### Install from PyPI
```bash
pip install tty-egpf-monitor
```
### Install the Daemon
The Python client requires the `tty-egpf-monitord` daemon to be running:
```bash
# Install daemon via APT repository
curl -fsSL https://raw.githubusercontent.com/seelso-net/tty-egpf-monitor/main/install.sh | bash
# Or install manually
CODENAME=$(lsb_release -cs)
REPO_URL=https://seelso-net.github.io/tty-egpf-monitor
curl -fsSL ${REPO_URL}/public-apt-key.asc | sudo gpg --dearmor -o /usr/share/keyrings/tty-egpf-monitor.gpg
echo "deb [signed-by=/usr/share/keyrings/tty-egpf-monitor.gpg] ${REPO_URL} ${CODENAME} main" | sudo tee /etc/apt/sources.list.d/tty-egpf-monitor.list
sudo apt-get update && sudo apt-get install -y tty-egpf-monitord
sudo systemctl enable --now tty-egpf-monitord
```
## Quick Start
### Library Usage
```python
from tty_egpf_monitor import TTYMonitorClient
# Create client
client = TTYMonitorClient()
# Add a port to monitor
idx = client.add_port("/dev/ttyUSB0", baudrate=115200)
print(f"Monitoring port {idx}")
# List all ports
ports = client.list_ports()
for port in ports:
print(f"Port {port.idx}: {port.device}")
# Stream live events
for entry in client.stream_parsed_logs("/dev/ttyUSB0"):
print(f"[{entry.timestamp}] {entry.event_type}: {entry.process}")
if entry.data:
print(f" Data: {entry.data}")
# Remove port when done
client.remove_port("/dev/ttyUSB0")
```
### CLI Usage
The package includes a CLI tool compatible with the C version:
```bash
# Add a port
tty-egpf-monitor-py add /dev/ttyUSB0 115200
# List ports
tty-egpf-monitor-py list
# Stream logs (by index or device path)
tty-egpf-monitor-py stream 0
tty-egpf-monitor-py stream /dev/ttyUSB0
# Download logs
tty-egpf-monitor-py logs /dev/ttyUSB0 > captured.jsonl
# Remove port
tty-egpf-monitor-py remove /dev/ttyUSB0
```
## API Reference
### TTYMonitorClient
#### Methods
- **`list_ports()`** → `List[Port]`
List all configured ports.
- **`add_port(device, baudrate=115200, log_path=None)`** → `int`
Add a port to monitor. Returns the port index.
- **`remove_port(port_identifier)`** → `bool`
Remove a port by index (int) or device path (str).
- **`get_logs(port_identifier)`** → `str`
Download full log content for a port.
- **`stream_logs(port_identifier)`** → `Iterator[str]`
Stream raw log lines as they arrive.
- **`stream_parsed_logs(port_identifier)`** → `Iterator[LogEntry]`
Stream parsed log entries as they arrive.
- **`wait_for_event(port_identifier, event_type, timeout=30.0)`** → `Optional[LogEntry]`
Wait for a specific event type with timeout.
### LogEntry
Represents a parsed log entry:
```python
@dataclass
class LogEntry:
timestamp: datetime # When the event occurred
event_type: str # OPEN, CLOSE, READ, WRITE, IOCTL, MODE_CHANGE
process: str # Process name that triggered the event
direction: Optional[str] # APP->DEV or DEV->APP (for READ/write)
data: Optional[bytes] # Raw data (for read/write events)
raw_line: str # Original log line
```
### Port
Represents a monitored port:
```python
@dataclass
class Port:
idx: int # Port index
device: str # Device path
baudrate: Optional[int] # Configured baud rate
log_path: Optional[str] # Log file path
```
## Examples
See the [`examples/`](examples/) directory for comprehensive usage examples:
- **`basic_usage.py`** - Core functionality demonstration
- **`monitor_serial_data.py`** - Real-time monitoring with processing
- **`automation_script.py`** - Automated testing and analysis
## Error Handling
```python
from tty_egpf_monitor import TTYMonitorError
try:
client = TTYMonitorClient()
client.add_port("/dev/ttyUSB0")
except TTYMonitorError as e:
print(f"Error: {e}")
```
## Requirements
- **Python**: 3.8 or later
- **Operating System**: Linux (Ubuntu 22.04+ recommended)
- **Daemon**: `tty-egpf-monitord` must be installed and running
- **Permissions**: Access to the daemon's Unix socket (usually `/run/tty-egpf-monitord.sock`)
## Related Projects
- **[TTY eBPF Monitor](https://github.com/seelso-net/tty-egpf-monitor)** - Main project with C daemon and CLI
- **[APT Repository](https://seelso-net.github.io/tty-egpf-monitor)** - Binary packages for Ubuntu
## License
This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](https://github.com/seelso-net/tty-egpf-monitor/blob/main/LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/seelso-net/tty-egpf-monitor",
"name": "tty-egpf-monitor",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "TTY eBPF Monitor Team <contact@seelso.net>",
"keywords": "serial, tty, monitoring, ebpf, uart, debugging, reverse-engineering, protocol-analysis, hardware",
"author": "TTY eBPF Monitor Team",
"author_email": "TTY eBPF Monitor Team <contact@seelso.net>",
"download_url": "https://files.pythonhosted.org/packages/56/41/925ba2685ee65186e5c4bdf20d890965f3e1709c8a86ae5a2dfd2decf6e4/tty_egpf_monitor-0.6.3.tar.gz",
"platform": null,
"description": "# TTY eBPF Monitor Python Client\n\n[](https://badge.fury.io/py/tty-egpf-monitor)\n[](https://pypi.org/project/tty-egpf-monitor/)\n[](https://www.gnu.org/licenses/gpl-3.0)\n\nA Python client library for [TTY eBPF Monitor](https://github.com/seelso-net/tty-egpf-monitor), providing a clean, Pythonic interface to monitor serial port activity using eBPF technology.\n\n## Features\n\n- \ud83d\udc0d **Pure Python** - No C dependencies, works with any Python 3.8+\n- \ud83d\udd0c **Unix Socket API** - Communicates with daemon via Unix domain socket\n- \ud83d\udcca **Parsed Log Entries** - Automatic parsing of log format with timestamps\n- \ud83d\udd04 **Live Streaming** - Real-time event streaming with iterator interface \n- \ud83d\udee0\ufe0f **CLI Wrapper** - Drop-in replacement for the C CLI tool\n- \ud83d\udcda **Rich Examples** - Comprehensive examples for common use cases\n- \ud83d\udd0d **Data Analysis** - Built-in support for protocol analysis and debugging\n\n## Installation\n\n### Install from PyPI\n\n```bash\npip install tty-egpf-monitor\n```\n\n### Install the Daemon\n\nThe Python client requires the `tty-egpf-monitord` daemon to be running:\n\n```bash\n# Install daemon via APT repository\ncurl -fsSL https://raw.githubusercontent.com/seelso-net/tty-egpf-monitor/main/install.sh | bash\n\n# Or install manually\nCODENAME=$(lsb_release -cs)\nREPO_URL=https://seelso-net.github.io/tty-egpf-monitor\ncurl -fsSL ${REPO_URL}/public-apt-key.asc | sudo gpg --dearmor -o /usr/share/keyrings/tty-egpf-monitor.gpg\necho \"deb [signed-by=/usr/share/keyrings/tty-egpf-monitor.gpg] ${REPO_URL} ${CODENAME} main\" | sudo tee /etc/apt/sources.list.d/tty-egpf-monitor.list\nsudo apt-get update && sudo apt-get install -y tty-egpf-monitord\nsudo systemctl enable --now tty-egpf-monitord\n```\n\n## Quick Start\n\n### Library Usage\n\n```python\nfrom tty_egpf_monitor import TTYMonitorClient\n\n# Create client\nclient = TTYMonitorClient()\n\n# Add a port to monitor\nidx = client.add_port(\"/dev/ttyUSB0\", baudrate=115200)\nprint(f\"Monitoring port {idx}\")\n\n# List all ports\nports = client.list_ports()\nfor port in ports:\n print(f\"Port {port.idx}: {port.device}\")\n\n# Stream live events\nfor entry in client.stream_parsed_logs(\"/dev/ttyUSB0\"):\n print(f\"[{entry.timestamp}] {entry.event_type}: {entry.process}\")\n if entry.data:\n print(f\" Data: {entry.data}\")\n\n# Remove port when done\nclient.remove_port(\"/dev/ttyUSB0\")\n```\n\n### CLI Usage\n\nThe package includes a CLI tool compatible with the C version:\n\n```bash\n# Add a port\ntty-egpf-monitor-py add /dev/ttyUSB0 115200\n\n# List ports\ntty-egpf-monitor-py list\n\n# Stream logs (by index or device path)\ntty-egpf-monitor-py stream 0\ntty-egpf-monitor-py stream /dev/ttyUSB0\n\n# Download logs\ntty-egpf-monitor-py logs /dev/ttyUSB0 > captured.jsonl\n\n# Remove port\ntty-egpf-monitor-py remove /dev/ttyUSB0\n```\n\n## API Reference\n\n### TTYMonitorClient\n\n#### Methods\n\n- **`list_ports()`** \u2192 `List[Port]`\n \n List all configured ports.\n\n- **`add_port(device, baudrate=115200, log_path=None)`** \u2192 `int`\n \n Add a port to monitor. Returns the port index.\n\n- **`remove_port(port_identifier)`** \u2192 `bool`\n \n Remove a port by index (int) or device path (str).\n\n- **`get_logs(port_identifier)`** \u2192 `str`\n \n Download full log content for a port.\n\n- **`stream_logs(port_identifier)`** \u2192 `Iterator[str]`\n \n Stream raw log lines as they arrive.\n\n- **`stream_parsed_logs(port_identifier)`** \u2192 `Iterator[LogEntry]`\n \n Stream parsed log entries as they arrive.\n\n- **`wait_for_event(port_identifier, event_type, timeout=30.0)`** \u2192 `Optional[LogEntry]`\n \n Wait for a specific event type with timeout.\n\n### LogEntry\n\nRepresents a parsed log entry:\n\n```python\n@dataclass\nclass LogEntry:\n timestamp: datetime # When the event occurred\n event_type: str # OPEN, CLOSE, READ, WRITE, IOCTL, MODE_CHANGE\n process: str # Process name that triggered the event\n direction: Optional[str] # APP->DEV or DEV->APP (for READ/write)\n data: Optional[bytes] # Raw data (for read/write events)\n raw_line: str # Original log line\n```\n\n### Port\n\nRepresents a monitored port:\n\n```python\n@dataclass \nclass Port:\n idx: int # Port index\n device: str # Device path\n baudrate: Optional[int] # Configured baud rate\n log_path: Optional[str] # Log file path\n```\n\n## Examples\n\nSee the [`examples/`](examples/) directory for comprehensive usage examples:\n\n- **`basic_usage.py`** - Core functionality demonstration\n- **`monitor_serial_data.py`** - Real-time monitoring with processing\n- **`automation_script.py`** - Automated testing and analysis\n\n## Error Handling\n\n```python\nfrom tty_egpf_monitor import TTYMonitorError\n\ntry:\n client = TTYMonitorClient()\n client.add_port(\"/dev/ttyUSB0\")\nexcept TTYMonitorError as e:\n print(f\"Error: {e}\")\n```\n\n## Requirements\n\n- **Python**: 3.8 or later\n- **Operating System**: Linux (Ubuntu 22.04+ recommended)\n- **Daemon**: `tty-egpf-monitord` must be installed and running\n- **Permissions**: Access to the daemon's Unix socket (usually `/run/tty-egpf-monitord.sock`)\n\n## Related Projects\n\n- **[TTY eBPF Monitor](https://github.com/seelso-net/tty-egpf-monitor)** - Main project with C daemon and CLI\n- **[APT Repository](https://seelso-net.github.io/tty-egpf-monitor)** - Binary packages for Ubuntu\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0 - see the [LICENSE](https://github.com/seelso-net/tty-egpf-monitor/blob/main/LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "Python client library for TTY eBPF Monitor daemon",
"version": "0.6.3",
"project_urls": {
"APT Repository": "https://seelso-net.github.io/tty-egpf-monitor",
"Bug Tracker": "https://github.com/seelso-net/tty-egpf-monitor/issues",
"Documentation": "https://github.com/seelso-net/tty-egpf-monitor/blob/main/README.md",
"Homepage": "https://github.com/seelso-net/tty-egpf-monitor",
"Repository": "https://github.com/seelso-net/tty-egpf-monitor"
},
"split_keywords": [
"serial",
" tty",
" monitoring",
" ebpf",
" uart",
" debugging",
" reverse-engineering",
" protocol-analysis",
" hardware"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cdccec0fde4361284541b737be2e4e188b16e88cdbbeb83ee5c18bd9edb90aee",
"md5": "5607cb6d3441a7440038a0e1bab3502b",
"sha256": "6316fe8a9340615a2209160a4b8b472aa0bc24295969f657809c2bbbfd8ccbe1"
},
"downloads": -1,
"filename": "tty_egpf_monitor-0.6.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5607cb6d3441a7440038a0e1bab3502b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10929,
"upload_time": "2025-09-08T14:47:05",
"upload_time_iso_8601": "2025-09-08T14:47:05.359056Z",
"url": "https://files.pythonhosted.org/packages/cd/cc/ec0fde4361284541b737be2e4e188b16e88cdbbeb83ee5c18bd9edb90aee/tty_egpf_monitor-0.6.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5641925ba2685ee65186e5c4bdf20d890965f3e1709c8a86ae5a2dfd2decf6e4",
"md5": "da5d9d7b04f8dc9ebd82b36eaf8b388a",
"sha256": "b7dde286a57cc36884b0fdb321198efc3c5000b49e41bbcd5a3804641a19691e"
},
"downloads": -1,
"filename": "tty_egpf_monitor-0.6.3.tar.gz",
"has_sig": false,
"md5_digest": "da5d9d7b04f8dc9ebd82b36eaf8b388a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 17208,
"upload_time": "2025-09-08T14:47:06",
"upload_time_iso_8601": "2025-09-08T14:47:06.664253Z",
"url": "https://files.pythonhosted.org/packages/56/41/925ba2685ee65186e5c4bdf20d890965f3e1709c8a86ae5a2dfd2decf6e4/tty_egpf_monitor-0.6.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-08 14:47:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "seelso-net",
"github_project": "tty-egpf-monitor",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tty-egpf-monitor"
}
JSON
