initial commit, added spec sheet

docs/spec_v0.1_s3-bridge.md

@@ -0,0 +1,162 @@
+# 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. 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