3.2 KiB
Seismo-Relay
Technical Specification v0.1
Module: s3-bridge
1. Overview
Seismo-Relay is a modular relay and protocol observability framework for legacy and modern monitoring devices.
The first module, s3-bridge, implements a transparent serial man-in-the-middle (MITM) proxy for Instantel Series-3 (Minimate Plus) seismographs.
The goal of this phase is pure protocol capture — not decoding, not modification, not emulation.
2. Problem Statement
Series-3 units rely on legacy modem transport and proprietary software (Blastware/DL2).
There is currently no internal visibility into the native serial protocol.
To build vendor-independent tooling, we must first capture the raw protocol traffic between Blastware and the device.
3. Scope (Phase 1 — v0.1)
In Scope
- Serial ↔ Serial transparent proxy
- Full duplex forwarding
- Raw byte logging (HEX)
- Timestamped directional logs
- Configurable serial parameters
- Graceful shutdown handling
Out of Scope
- TCP transport
- Protocol decoding
- Frame parsing
- AT modem emulation
- Data modification
- Replay system
- GUI
- Terra-View integration
Any feature not explicitly listed in Scope is not allowed in v0.1.
4. System Architecture
Topology
Blastware
↓
Virtual COM Port A
↓
s3-bridge
↓
Physical COM Port B
↓
Minimate
Behavior
Thread A: Read Port A → Log → Write Port B
Thread B: Read Port B → Log → Write Port A
No transformation of bytes under any condition.
5. Functional Requirements
5.1 Port Handling
- Must open two serial ports simultaneously
- Must fail clearly if ports unavailable
- Default configuration: 38400 baud, 8N1
- Must allow configurable baud, parity, stopbits
5.2 Logging
Each log entry must include:
- Timestamp (millisecond precision)
- Direction label (BW→S3 or S3→BW)
- Hex dump of raw bytes
Logging must never alter forwarded data.
5.3 Stability
- Must handle continuous streaming without blocking
- Must survive device disconnect without crashing
- Must close ports cleanly on shutdown
6. Non-Functional Requirements
- Python 3.10+
- pyserial dependency only
- Cross-platform compatible (Windows first)
- No OS-specific hacks
7. Success Criteria
Phase 1 is complete when:
- Blastware can operate normally through s3-bridge.
- An event can be downloaded successfully.
- A full session log is captured.
- No data corruption occurs.
If these conditions are met, v0.1 is complete.
8. Future Phases (Not Part of v0.1)
- Protocol frame detection
- Checksum/CRC identification
- Command replay capability
- TCP bridge layer
- Terra-View integration
These items are explicitly deferred.
9. Guardrails for Implementation
The bridge must:
- Never interpret payload data
- Never modify payload data
- Never auto-respond to commands
- Never inject bytes
- Never attempt protocol decoding
This module is a transparent wire.
If behavior exceeds “transparent relay,” it violates spec.
10. Roadmap
Phase 1 — Transparent Serial Relay
Phase 2 — Protocol Analysis
Phase 3 — Minimal Command Injection
Phase 4 — Independent Downloader
Phase 5 — Terra Integration