# 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