seismo-relay/README.md

seismo-relay

Tools for capturing and reverse-engineering the RS-232 serial protocol between Blastware software and Instantel MiniMate Plus seismographs.

Built for Windows, stdlib-only (plus pyserial for the bridge).

---

What's in here

seismo-relay/
├── bridges/
│   ├── s3-bridge/
│   │   └── s3_bridge.py       ← The serial bridge (core capture tool)
│   ├── gui_bridge.py          ← Tkinter GUI wrapper for s3_bridge
│   └── raw_capture.py         ← Simpler raw-only capture tool
└── parsers/
    ├── s3_parser.py           ← Low-level DLE frame extractor
    ├── s3_analyzer.py         ← Protocol analyzer (sessions, diffs, exports)
    ├── gui_analyzer.py        ← Tkinter GUI for the analyzer
    └── frame_db.py            ← SQLite frame database

---

How it all fits together

The workflow has two phases: capture, then analyze.

  Blastware PC
       │
  Virtual COM (e.g. COM4)
       │
  s3_bridge.py  ←─── sits in the middle, forwards all bytes both ways
       │              writes raw_bw.bin and raw_s3.bin
  Physical COM (e.g. COM5)
       │
  MiniMate Plus seismograph

After capturing, you point the analyzer at the two .bin files to inspect what happened.

---

Part 1 — The Bridge

s3_bridge.py — Serial bridge

Transparently forwards bytes between Blastware and the seismograph while logging everything to disk. Blastware operates normally and has no idea the bridge is there.

Run it:

python bridges/s3-bridge/s3_bridge.py --bw COM4 --s3 COM5 --logdir captures/

Key flags:

Flag	Default	Description
--bw	required	COM port connected to Blastware
--s3	required	COM port connected to the seismograph
--baud	38400	Baud rate (match your device)
--logdir	.	Where to write log/bin files
--raw-bw	off	Also write a flat raw file for BW→S3 traffic
--raw-s3	off	Also write a flat raw file for S3→BW traffic

Output files (in --logdir):

• s3_session_<timestamp>.bin — structured binary log with timestamps and direction tags (record format: [type:1][ts_us:8][len:4][payload])
• s3_session_<timestamp>.log — human-readable hex dump (text)
• raw_bw.bin — flat BW→S3 byte stream (if --raw-bw used)
• raw_s3.bin — flat S3→BW byte stream (if --raw-s3 used)

The analyzer needs raw_bw.bin + raw_s3.bin. Always use --raw-bw and --raw-s3 when capturing.

Interactive commands (type while bridge is running):

• m + Enter → prompts for a label and inserts a MARK record into the log
• q + Enter → quit

---

gui_bridge.py — Bridge GUI

A simple point-and-click wrapper around s3_bridge.py. Easier than the command line if you don't want to type flags every time.

python bridges/gui_bridge.py

Set your COM ports, log directory, and tick the raw tap checkboxes before hitting Start. The Add Mark button lets you annotate the capture at any point (e.g. "changed record time to 13s").

---

Part 2 — The Analyzer

After capturing, you have raw_bw.bin (bytes Blastware sent) and raw_s3.bin (bytes the seismograph replied with). The analyzer parses these into protocol frames, groups them into sessions, and helps you figure out what each byte means.

What's a "session"?

Each time you open the settings dialog in Blastware and click Apply/OK, that's one session — a complete read/modify/write cycle. The bridge detects session boundaries by watching for the final write-confirm packet (SUB 0x74).

Each session contains a sequence of request/response frame pairs:

• Blastware sends a request (BW→S3): "give me your config block"
• The seismograph sends a response (S3→BW): here it is
• At the end, Blastware sends the modified settings back in a series of write packets

The analyzer lines these up and diffs consecutive sessions to show you exactly which bytes changed.

---

gui_analyzer.py — Analyzer GUI

python parsers/gui_analyzer.py

This is the main tool. It has five tabs:

Toolbar

• S3 raw / BW raw — browse to your raw_s3.bin and raw_bw.bin files
• Analyze — parse and load the captures
• Live: OFF/ON — watch the files grow in real time while the bridge is running
• Export for Claude — generate a self-contained .md report for AI-assisted analysis

Inventory tab

Shows all frames in the selected session — direction, SUB command, page, length, and checksum status. Click any frame in the left tree to drill in.

Hex Dump tab

Full hex dump of the selected frame's payload. If the frame had changed bytes vs the previous session, those are listed below the dump with before/after values and field names where known.

Diff tab

Side-by-side byte-level diff between the current session and the previous one. Only SUBs (command types) that actually changed are shown.

Full Report tab

Raw text version of the session report — useful for copying into notes.

Query DB tab

Search across all your captured sessions using the built-in database.

---

s3_analyzer.py — Analyzer (command line)

If you prefer the terminal:

python parsers/s3_analyzer.py --s3 raw_s3.bin --bw raw_bw.bin

Flags:

Flag	Description
--s3	Path to raw_s3.bin
--bw	Path to raw_bw.bin
--live	Tail files in real time (poll mode)
--export	Also write a claude_export_<ts>.md file
--outdir	Where to write .report files (default: same folder as input)
--poll	Live mode poll interval in seconds (default: 0.05)

Writes one .report file per session and prints a summary to the console.

---

The Frame Database

Every time you click Analyze, the frames are automatically saved to a SQLite database at:

C:\Users\<you>\.seismo_lab\frames.db

This accumulates captures over time so you can query across sessions and dates.

Query DB tab

Use the filter bar to search:

• Capture — narrow to a specific capture (timestamp shown)
• Dir — BW (requests) or S3 (responses) only
• SUB — filter by command type (e.g. 0xF7 = EVENT_INDEX_RESPONSE)
• Offset — filter to frames that have a specific byte offset
• Value — combined with Offset: "show frames where byte 85 = 0x0A"

Click any result row, then use the Byte interpretation panel at the bottom to see what that offset's bytes look like as uint8, int8, uint16 BE/LE, uint32 BE/LE, and float32 BE/LE simultaneously.

This is the main tool for mapping unknown fields — if you change one setting in Blastware, capture before and after, then query for frames where that offset moved, you can pin down exactly which byte controls what.

---

Export for Claude

The Export for Claude button (orange, in the toolbar) generates a single .md file containing:

1. Protocol background and known field map
2. Capture summary (session count, frame counts, what changed)
3. Per-diff tables — before/after bytes for every changed offset, with field names where known
4. Full hex dumps of all frames in the baseline session

Paste this file into a Claude conversation to get help mapping unknown fields, interpreting data structures, or understanding sequences.

---

Protocol quick-reference

Term	Value	Meaning
DLE	0x10	Data Link Escape
STX	0x02	Start of frame
ETX	0x03	End of frame
ACK	0x41	Frame start marker (BW side)
DLE stuffing	10 10 on wire	Literal 0x10 in payload

S3-side frame (seismograph → Blastware): DLE STX [payload] DLE ETX BW-side frame (Blastware → seismograph): ACK STX [payload] ETX

De-stuffed payload header (first 5 bytes after de-stuffing):

[0] CMD        0x10 = BW request, 0x00 = S3 response
[1] ?          0x00 (BW) or 0x10 (S3)
[2] SUB        Command/response identifier  ← the key field
[3] OFFSET_HI  Page address high byte
[4] OFFSET_LO  Page address low byte
[5+] DATA      Payload content

Response SUB rule: response_SUB = 0xFF - request_SUB Example: request SUB 0x08 → response SUB 0xF7

---

Requirements

pip install pyserial

Python 3.10+. Everything else is stdlib (Tkinter, sqlite3, struct, hashlib).

Tkinter is included with the standard Python installer on Windows. If it's missing, reinstall Python and make sure "tcl/tk and IDLE" is checked.

---

Virtual COM ports

The bridge needs two COM ports on the same PC — one that Blastware connects to, and one wired to the actual seismograph. On Windows, use a virtual COM port pair (e.g. com0com or VSPD) to give Blastware a port to talk to while the bridge sits in the middle.

Blastware → COM4 (virtual) ↔ s3_bridge ↔ COM5 (physical) → MiniMate