seismo-relay/README.md

seismo-relay v0.5.0

A ground-up replacement for Blastware — Instantel's aging Windows-only software for managing MiniMate Plus seismographs.

Built in Python. Runs on Windows. Connects to instruments over direct RS-232 or cellular modem (Sierra Wireless RV50 / RV55).

Status: Active development. Core read pipeline working (device info, config, event index). Event download and write commands in progress. See CHANGELOG.md for version history.

---

What's in here

seismo-relay/
├── seismo_lab.py              ← Main GUI (Bridge + Analyzer + Console tabs)
│
├── minimateplus/              ← MiniMate Plus client library
│   ├── transport.py           ←   SerialTransport and TcpTransport
│   ├── protocol.py            ←   DLE frame layer (read/write/parse)
│   ├── client.py              ←   High-level client (connect, get_config, etc.)
│   ├── framing.py             ←   Frame builder/parser primitives
│   └── models.py              ←   DeviceInfo, EventRecord, etc.
│
├── sfm/                       ← SFM REST API server (FastAPI)
│   └── server.py              ←   /device/info, /device/events, /device/event
│
├── bridges/
│   ├── s3-bridge/
│   │   └── s3_bridge.py       ←   RS-232 serial bridge (capture tool)
│   ├── tcp_serial_bridge.py   ←   Local TCP↔serial bridge (bench testing)
│   ├── gui_bridge.py          ←   Standalone bridge GUI (legacy)
│   └── raw_capture.py         ←   Simple raw capture tool
│
├── parsers/
│   ├── s3_parser.py           ←   DLE frame extractor
│   ├── s3_analyzer.py         ←   Session parser, differ, Claude export
│   ├── gui_analyzer.py        ←   Standalone analyzer GUI (legacy)
│   └── frame_db.py            ←   SQLite frame database
│
└── docs/
    └── instantel_protocol_reference.md  ← Reverse-engineered protocol spec

---

Quick start

Seismo Lab (main GUI)

The all-in-one tool. Three tabs: Bridge, Analyzer, Console.

python seismo_lab.py

SFM REST server

Exposes MiniMate Plus commands as a REST API for integration with other systems.

cd sfm
uvicorn server:app --reload

Endpoints:

Method	URL	Description
GET	/device/info?port=COM5	Device info via serial
GET	/device/info?host=1.2.3.4&tcp_port=9034	Device info via cellular modem
GET	/device/events?port=COM5	Event index
GET	/device/event?port=COM5&index=0	Single event record

---

Seismo Lab tabs

Bridge tab

Captures live RS-232 traffic between Blastware and the seismograph. Sits in the middle as a transparent pass-through while logging everything to disk.

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

Set your COM ports and log directory, then hit Start Bridge. Use Add Mark to annotate the capture at specific moments (e.g. "changed trigger level"). When the bridge starts, the Analyzer tab automatically wires up to the live files and starts updating in real time.

Analyzer tab

Parses raw captures into DLE-framed protocol sessions, diffs consecutive sessions to show exactly which bytes changed, and lets you query across all historical captures via the built-in SQLite database.

• Inventory — all frames in a session, click to drill in
• Hex Dump — full payload hex dump with changed-byte annotations
• Diff — byte-level before/after diff between sessions
• Full Report — plain text session report
• Query DB — search across all captures by SUB, direction, or byte value

Use Export for Claude to generate a self-contained .md report for AI-assisted field mapping.

Console tab

Direct connection to a MiniMate Plus — no bridge, no Blastware. Useful for diagnosing field units over cellular without a full capture session.

Connection: choose Serial (COM port + baud) or TCP (IP + port for cellular modem).

Commands:

Button	What it does
POLL	Startup handshake — confirms unit is alive and identifies model
Serial #	Reads unit serial number
Full Config	Reads full 166-byte config block (firmware version, channel scales, etc.)
Event Index	Reads stored event list

Output is colour-coded: TX in blue, raw RX bytes in teal, decoded fields in green, errors in red. Save Log writes a timestamped .log file to bridges/captures/. Send to Analyzer injects the captured bytes into the Analyzer tab for deeper inspection.

---

Connecting over cellular (RV50 / RV55 modems)

Field units connect via Sierra Wireless RV50 or RV55 cellular modems. Use TCP mode in the Console or SFM:

# Console tab
Transport: TCP
Host: <modem public IP>
Port: 9034          ← Device Port in ACEmanager (call-up mode)

# In code
from minimateplus.transport import TcpTransport
from minimateplus.client import MiniMateClient

client = MiniMateClient(transport=TcpTransport("1.2.3.4", 9034))
info = client.connect()

Required ACEmanager settings (Serial tab)

These must match exactly — a single wrong setting causes the unit to beep on connect but never respond:

Setting	Value	Why
Configure Serial Port	38400,8N1	Must match MiniMate baud rate
Flow Control	None	Hardware flow control blocks unit TX if pins unconnected
Quiet Mode	Enable	Critical. Disabled → modem injects RING/CONNECT onto serial line, corrupting the S3 handshake
Data Forwarding Timeout	1 (= 0.1 s)	Lower latency; 5 works but is sluggish
TCP Connect Response Delay	0	Non-zero silently drops the first POLL frame
TCP Idle Timeout	2 (minutes)	Prevents premature disconnect
DB9 Serial Echo	Disable	Echo corrupts the data stream

---

minimateplus library

from minimateplus import MiniMateClient
from minimateplus.transport import SerialTransport, TcpTransport

# Serial
client = MiniMateClient(port="COM5")

# TCP (cellular modem)
client = MiniMateClient(transport=TcpTransport("1.2.3.4", 9034), timeout=30.0)

with client:
    info    = client.connect()        # DeviceInfo — model, serial, firmware
    serial  = client.get_serial()     # Serial number string
    config  = client.get_config()     # Full config block (bytes)
    events  = client.get_events()     # Event index

---

Protocol quick-reference

Term	Value	Meaning
DLE	0x10	Data Link Escape
STX	0x02	Start of frame
ETX	0x03	End of frame
ACK	0x41 ('A')	Frame-start marker sent before every frame
DLE stuffing	10 10 on wire	Literal 0x10 in payload

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

De-stuffed payload header:

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

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

Full protocol documentation: docs/instantel_protocol_reference.md

---

Requirements

pip install pyserial fastapi uvicorn

Python 3.10+. Tkinter is included with the standard Python installer on Windows (make sure "tcl/tk and IDLE" is checked during install).

---

Virtual COM ports (bridge capture)

The bridge needs two COM ports on the same PC — one that Blastware connects to, and one wired to the seismograph. Use a virtual COM port pair (com0com or VSPD) to give Blastware a port to talk to.

Blastware → COM4 (virtual) ↔ s3_bridge.py ↔ COM5 (physical) → MiniMate Plus

---

Roadmap

• Event download — pull waveform records from the unit (SUBs 1E → 0A → 0C → 5A)
• Write commands — push config changes to the unit (compliance setup, channel config, trigger settings)
• ACH inbound server — accept call-home connections from field units
• Modem manager — push standard configs to RV50/RV55 fleet via Sierra Wireless API
• Full Blastware parity — complete read/write/download cycle without Blastware