146 lines
2.9 KiB
Markdown
146 lines
2.9 KiB
Markdown
# 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:
|
|
|
|
1. Blastware can operate normally through s3-bridge.
|
|
2. An event can be downloaded successfully.
|
|
3. A full session log is captured.
|
|
4. 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. Roadmap
|
|
|
|
Phase 1 — Transparent Serial Relay
|
|
Phase 2 — Protocol Analysis
|
|
Phase 3 — Minimal Command Injection
|
|
Phase 4 — Independent Downloader
|
|
Phase 5 — Terra-View Integration |