gea-program 0.15.0__tar.gz → 0.17.0__tar.gz

{gea_program-0.15.0/gea_program.egg-info → gea_program-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.15.0
+Version: 0.17.0
 Summary: GEA-Program: downhole gauge monitoring - canonical measurement records, quality rules, drift evaluation with a re-fit change log, well-test validation, alarm management, model cards, store-and-forward, monthly SLA measurement, FAT/SAT protocols and a dashboard, generated from live objects in the client's reporting outline.
 Author: Daniel T. Murphy
 License: MPL-2.0
@@ -72,7 +72,7 @@ reaches a client document. Nothing unmeasured is ever reported as met.
   rate-controlled replay, duplicate suppression, per-record latency.
 - **Configuration versioning, SBOM, monthly SLA, FAT/SAT**
   (`config_versioning.py`, `sbom.py`, `sla_report.py`, `fat_sat.py`).
-- **Live protocol ports** (`live_ports.py`, `wits0.py`, `witsml.py`, `opcua_port.py`,
+- **Live protocol ports** (`live_ports.py`, `wits0.py`, `witsml.py`, `etp.py`, `seedlink.py`, `opcua_port.py`,
   `mqtt_port.py`, `modbus.py`): WITS Level 0 from the drill floor (TCP connect,
   TCP listen, serial), WITSML 1.4.1 stores (read-only, polled), OPC UA (read and
   subscribe), MQTT (number, JSON, Sparkplug B), Modbus TCP; every message becomes
@@ -125,7 +125,7 @@ gea dashboard --catalog-well volve_f12_f14_production_excerpt:15/9-F-12:10000 --
 gea client-report --report accuracy --out client_report
 gea model-cards --out model_cards
 gea sbom --out sbom
-gea accept                     # the product gate (333 checks)
+gea accept                     # the product gate (340 checks)
 gea help drift                 # the help library, by the job (16 pages; the same text is on every dashboard page)
 gea guide                      # the click-by-click tester guide (docs/TESTER_GUIDE.md)
 gea gui                        # the desktop window (pip install "gea-program[desktop]")
@@ -143,7 +143,7 @@ gea swaps / gea certificates / gea notify / gea housekeeping / gea loadtest   #
 
 ## Live data
 
-The engine reads live data through five protocol ports. All are **read-only**,
+The engine reads live data through six protocol ports. All are **read-only**,
 all map only what the site declares (a tag map the client owns; an empty map
 is declined), and all write every received message to a JSON-lines recording
 that `--replay` turns back into records without a connection - which is how a
@@ -156,6 +156,9 @@ gea wits0-sim --port 5001                             # a WITS0 sender to rehear
 gea wits0  --config wits0.json --seconds 60 --record floor/session.jsonl --out floor --stream-csv floor/stream.csv   # in the first window, while the sender runs
 gea witsml --write-example-config witsml.json         # a WITSML 1.4.1 store: url, uids, mnemonics -> tags; credentials by env name
 gea witsml --config witsml.json --seconds 60 --out store                 # needs a real store: the example url is a placeholder until you edit it
+gea etp    --write-example-config etp.json            # a WITSML 2.x store over ETP v1.2: ws:// or wss:// url, bearer token by env name, channel URIs -> tags, units
+gea etp-sim --port 9800                               # an ETP store with two channels to rehearse with - run it in a SECOND window and leave it running
+gea etp    --config etp.json --seconds 60 --record rig/session.jsonl --out rig   # subscribes; the store pushes every value as it is written
 gea opcua  --write-example-config opcua.json          # edit: endpoint, security, credential env names, nodes
 gea opcua  --config opcua.json --seconds 60 --record opc/session.jsonl --out opc --stream-csv opc/stream.csv   # needs a real OPC UA server, likewise
 gea mqtt   --write-example-config mqtt.json           # edit: broker, TLS, credential env names, topics
@@ -167,6 +170,7 @@ gea ingest --file floor/stream.csv                    # a stream CSV feeds the h
 |---|---|---|---|
 | `wits0` | WITS Level 0 frames (`&&` ... `!!`, four-digit item codes) over TCP connect, TCP listen or serial; record-01 dictionary built in | numeric GOOD; sentinels (-9999, -999.25) and non-numeric -> GAP with the reason | items 0105/0106 (date, time) when present, else arrival; ingest at arrival |
 | `witsml` | WITSML 1.4.1 SOAP store: GetVersion, GetCap, GetFromStore on one log object, rows newer than the last seen at each poll | numeric GOOD; the store's nullValue and empty fields -> GAP | the index curve of a time log; arrival for a depth log |
+| `etp` | Energistics ETP v1.2 over WebSocket (`etp12.energistics.org`, Avro binary to the published schemas): RequestSession/OpenSession, GetChannelMetadata for the declared URIs, SubscribeChannels, ChannelData pushed by the store (Protocol 21) | numeric GOOD; a non-numeric or null value -> BAD with the reason; a channel the map does not name is counted unmapped | the store's own index: an ETP DateTime index is microseconds since the epoch; an ElapsedTime index is seconds from its declared start; a depth index leaves the arrival time standing, named |
 | `opcua` | opc.tcp, read + subscribe; Basic256Sha256 SignAndEncrypt when a certificate and key are given | StatusCode severity bits: Good -> GOOD, Uncertain -> STALE, Bad -> GAP (value withheld) | source timestamp, else server timestamp, else arrival |
 | `mqtt` | MQTT v5 / v3.1.1, TLS optional, QoS per topic; `+`/`#` wildcards | number: GOOD or GAP; JSON: value/time/quality paths; Sparkplug B: `is_null` -> GAP, `Quality` != 192 -> STALE | JSON time path, Sparkplug metric timestamp, else arrival |
 | `modbus_g6` | Modbus TCP, user-supplied register map with a citation | read failures -> GAP | arrival |
@@ -619,6 +623,54 @@ promoted; the group and the support are declarations; a matched frequency
 is not a fault size. CSV or miniSEED/SAC; `gea vibration` runs the labelled
 pump; `gea help vibration`.
 
+### Live stations (SeedLink)
+
+The seismic leg had run on records that were already files. The stations
+serve SeedLink - the real-time protocol every data centre and most
+digitisers speak - and `gea/seedlink.py` is the customer: the TCP session on
+port 18000, `HELLO` read for what the server offers, SeedLink 3 (`STATION
+STA NET`, `SELECT LLCCC.T`, `DATA` with a hexadecimal sequence, `END`, the
+8-byte `SL` header on each 512-byte record) or SeedLink 4.0 (`SLPROTO 4.0`,
+`STATION NET_STA`, `SELECT LOC_B_S_SS`, a decimal sequence, the `SE` header
+with its length, uint64 sequence and station id, `ERROR <CODE>`), whichever
+the server speaks. Every record is appended byte for byte to a day file per
+channel under the station's `live/` folder with the state beside it - the
+last sequence number per station, so a reconnection (with backoff) resumes
+where it stopped and no record is filed twice; per channel the last sample,
+the latency, the records, the samples, the gaps (counted, never bridged).
+On the dashboard's Seismic page a live station is added with its host, port,
+network, station and selectors, started and stopped (the serving process
+keeps every enabled one up), and **folded**: the finished day files move into
+the station's record list, hashed, vertical first, and Refresh runs the leg
+on them as on any brought file. `gea seedlink-sim` is a three-component
+synthetic station speaking both versions; `gea seedlink --selftest` runs both
+against it; `gea seedlink --config ... --hello` prints what a server says of
+itself; `gea help seedlink`. A TexNet station is served by EarthScope at
+`rtserve.iris.washington.edu:18000`, network `TX`.
+
+### WITSML 2.x over ETP
+
+The newer rigs and stores do not poll: Energistics ETP v1.2 is a WebSocket
+session, Avro-encoded to the published schemas, on which the customer names
+the channels it wants and the store pushes every value as it is written.
+`gea/etp.py` is that customer: the handshake with the subprotocol, the
+binary encoding and the payload limits; RequestSession for Discovery, Store
+and ChannelSubscribe and what the store answered; the channel metadata for
+the URIs the mapping declares (a URI the store does not have is named as
+missing); the subscription; and each ChannelData DataItem as a record under
+the mapping's tag and unit, with the store's own index as the source time -
+microseconds since the epoch for a DateTime index, seconds from the declared
+start for ElapsedTime, the arrival time standing (and named) for a depth
+index - and the arrival as the ingest time, so the latency is per record.
+Client message ids even, the store's odd; a ProtocolException carried with
+its code; a client or a store without the subprotocol refused at the
+handshake. The patch supervisor runs it like every other port; the page
+offers it; `gea etp-sim` is a store with two channels of a synthetic
+disposal well; `gea etp --selftest` runs the codec and a loopback session;
+`gea help etp`. The doctor now also names a panel started through the
+`gea.exe` launcher, which pip cannot replace while it runs - stop, update,
+start with `python -m gea serve`.
+
 ### Conformity, in the standards' words
 
 The drift report's "bias inside the instrument's class" is a statement of

{gea_program-0.15.0 → gea_program-0.17.0}/README.md

@@ -33,7 +33,7 @@ reaches a client document. Nothing unmeasured is ever reported as met.
   rate-controlled replay, duplicate suppression, per-record latency.
 - **Configuration versioning, SBOM, monthly SLA, FAT/SAT**
   (`config_versioning.py`, `sbom.py`, `sla_report.py`, `fat_sat.py`).
-- **Live protocol ports** (`live_ports.py`, `wits0.py`, `witsml.py`, `opcua_port.py`,
+- **Live protocol ports** (`live_ports.py`, `wits0.py`, `witsml.py`, `etp.py`, `seedlink.py`, `opcua_port.py`,
   `mqtt_port.py`, `modbus.py`): WITS Level 0 from the drill floor (TCP connect,
   TCP listen, serial), WITSML 1.4.1 stores (read-only, polled), OPC UA (read and
   subscribe), MQTT (number, JSON, Sparkplug B), Modbus TCP; every message becomes
@@ -86,7 +86,7 @@ gea dashboard --catalog-well volve_f12_f14_production_excerpt:15/9-F-12:10000 --
 gea client-report --report accuracy --out client_report
 gea model-cards --out model_cards
 gea sbom --out sbom
-gea accept                     # the product gate (333 checks)
+gea accept                     # the product gate (340 checks)
 gea help drift                 # the help library, by the job (16 pages; the same text is on every dashboard page)
 gea guide                      # the click-by-click tester guide (docs/TESTER_GUIDE.md)
 gea gui                        # the desktop window (pip install "gea-program[desktop]")
@@ -104,7 +104,7 @@ gea swaps / gea certificates / gea notify / gea housekeeping / gea loadtest   #
 
 ## Live data
 
-The engine reads live data through five protocol ports. All are **read-only**,
+The engine reads live data through six protocol ports. All are **read-only**,
 all map only what the site declares (a tag map the client owns; an empty map
 is declined), and all write every received message to a JSON-lines recording
 that `--replay` turns back into records without a connection - which is how a
@@ -117,6 +117,9 @@ gea wits0-sim --port 5001                             # a WITS0 sender to rehear
 gea wits0  --config wits0.json --seconds 60 --record floor/session.jsonl --out floor --stream-csv floor/stream.csv   # in the first window, while the sender runs
 gea witsml --write-example-config witsml.json         # a WITSML 1.4.1 store: url, uids, mnemonics -> tags; credentials by env name
 gea witsml --config witsml.json --seconds 60 --out store                 # needs a real store: the example url is a placeholder until you edit it
+gea etp    --write-example-config etp.json            # a WITSML 2.x store over ETP v1.2: ws:// or wss:// url, bearer token by env name, channel URIs -> tags, units
+gea etp-sim --port 9800                               # an ETP store with two channels to rehearse with - run it in a SECOND window and leave it running
+gea etp    --config etp.json --seconds 60 --record rig/session.jsonl --out rig   # subscribes; the store pushes every value as it is written
 gea opcua  --write-example-config opcua.json          # edit: endpoint, security, credential env names, nodes
 gea opcua  --config opcua.json --seconds 60 --record opc/session.jsonl --out opc --stream-csv opc/stream.csv   # needs a real OPC UA server, likewise
 gea mqtt   --write-example-config mqtt.json           # edit: broker, TLS, credential env names, topics
@@ -128,6 +131,7 @@ gea ingest --file floor/stream.csv                    # a stream CSV feeds the h
 |---|---|---|---|
 | `wits0` | WITS Level 0 frames (`&&` ... `!!`, four-digit item codes) over TCP connect, TCP listen or serial; record-01 dictionary built in | numeric GOOD; sentinels (-9999, -999.25) and non-numeric -> GAP with the reason | items 0105/0106 (date, time) when present, else arrival; ingest at arrival |
 | `witsml` | WITSML 1.4.1 SOAP store: GetVersion, GetCap, GetFromStore on one log object, rows newer than the last seen at each poll | numeric GOOD; the store's nullValue and empty fields -> GAP | the index curve of a time log; arrival for a depth log |
+| `etp` | Energistics ETP v1.2 over WebSocket (`etp12.energistics.org`, Avro binary to the published schemas): RequestSession/OpenSession, GetChannelMetadata for the declared URIs, SubscribeChannels, ChannelData pushed by the store (Protocol 21) | numeric GOOD; a non-numeric or null value -> BAD with the reason; a channel the map does not name is counted unmapped | the store's own index: an ETP DateTime index is microseconds since the epoch; an ElapsedTime index is seconds from its declared start; a depth index leaves the arrival time standing, named |
 | `opcua` | opc.tcp, read + subscribe; Basic256Sha256 SignAndEncrypt when a certificate and key are given | StatusCode severity bits: Good -> GOOD, Uncertain -> STALE, Bad -> GAP (value withheld) | source timestamp, else server timestamp, else arrival |
 | `mqtt` | MQTT v5 / v3.1.1, TLS optional, QoS per topic; `+`/`#` wildcards | number: GOOD or GAP; JSON: value/time/quality paths; Sparkplug B: `is_null` -> GAP, `Quality` != 192 -> STALE | JSON time path, Sparkplug metric timestamp, else arrival |
 | `modbus_g6` | Modbus TCP, user-supplied register map with a citation | read failures -> GAP | arrival |
@@ -580,6 +584,54 @@ promoted; the group and the support are declarations; a matched frequency
 is not a fault size. CSV or miniSEED/SAC; `gea vibration` runs the labelled
 pump; `gea help vibration`.
 
+### Live stations (SeedLink)
+
+The seismic leg had run on records that were already files. The stations
+serve SeedLink - the real-time protocol every data centre and most
+digitisers speak - and `gea/seedlink.py` is the customer: the TCP session on
+port 18000, `HELLO` read for what the server offers, SeedLink 3 (`STATION
+STA NET`, `SELECT LLCCC.T`, `DATA` with a hexadecimal sequence, `END`, the
+8-byte `SL` header on each 512-byte record) or SeedLink 4.0 (`SLPROTO 4.0`,
+`STATION NET_STA`, `SELECT LOC_B_S_SS`, a decimal sequence, the `SE` header
+with its length, uint64 sequence and station id, `ERROR <CODE>`), whichever
+the server speaks. Every record is appended byte for byte to a day file per
+channel under the station's `live/` folder with the state beside it - the
+last sequence number per station, so a reconnection (with backoff) resumes
+where it stopped and no record is filed twice; per channel the last sample,
+the latency, the records, the samples, the gaps (counted, never bridged).
+On the dashboard's Seismic page a live station is added with its host, port,
+network, station and selectors, started and stopped (the serving process
+keeps every enabled one up), and **folded**: the finished day files move into
+the station's record list, hashed, vertical first, and Refresh runs the leg
+on them as on any brought file. `gea seedlink-sim` is a three-component
+synthetic station speaking both versions; `gea seedlink --selftest` runs both
+against it; `gea seedlink --config ... --hello` prints what a server says of
+itself; `gea help seedlink`. A TexNet station is served by EarthScope at
+`rtserve.iris.washington.edu:18000`, network `TX`.
+
+### WITSML 2.x over ETP
+
+The newer rigs and stores do not poll: Energistics ETP v1.2 is a WebSocket
+session, Avro-encoded to the published schemas, on which the customer names
+the channels it wants and the store pushes every value as it is written.
+`gea/etp.py` is that customer: the handshake with the subprotocol, the
+binary encoding and the payload limits; RequestSession for Discovery, Store
+and ChannelSubscribe and what the store answered; the channel metadata for
+the URIs the mapping declares (a URI the store does not have is named as
+missing); the subscription; and each ChannelData DataItem as a record under
+the mapping's tag and unit, with the store's own index as the source time -
+microseconds since the epoch for a DateTime index, seconds from the declared
+start for ElapsedTime, the arrival time standing (and named) for a depth
+index - and the arrival as the ingest time, so the latency is per record.
+Client message ids even, the store's odd; a ProtocolException carried with
+its code; a client or a store without the subprotocol refused at the
+handshake. The patch supervisor runs it like every other port; the page
+offers it; `gea etp-sim` is a store with two channels of a synthetic
+disposal well; `gea etp --selftest` runs the codec and a loopback session;
+`gea help etp`. The doctor now also names a panel started through the
+`gea.exe` launcher, which pip cannot replace while it runs - stop, update,
+start with `python -m gea serve`.
+
 ### Conformity, in the standards' words
 
 The drift report's "bias inside the instrument's class" is a statement of

{gea_program-0.15.0 → gea_program-0.17.0}/gea/__init__.py

@@ -87,6 +87,7 @@ from .opcua_port import ASYNCUA_AVAILABLE, OpcUaTap          # registers the 'op
 from .mqtt_port import PAHO_AVAILABLE, MqttTap                # registers the 'mqtt' port at import
 from .wits0 import Wits0Tap, SERIAL_AVAILABLE                  # registers the 'wits0' port at import
 from .witsml import WitsmlTap                                  # registers the 'witsml' port at import
+from .etp import EtpTap                                        # registers the 'etp' port at import (WITSML 2.x over ETP v1.2)
 from .well_assembler import (
     WellAssembly, WellComponent, assemble, assemble_ktb_hb, assemble_odp_504b,
     assemble_site_1027, assemble_u1324, BUILTIN_ASSEMBLIES,
@@ -122,7 +123,7 @@ from .profile_catalog import (
     read_pangaea_txt,
 )
 
-__version__ = "0.15.0"
+__version__ = "0.17.0"
 __all__ = [
     "aging_rate", "rate_psi_yr", "accuracy_psi",
     "Sensor", "SimulatorConfig", "DownholeEngine",

{gea_program-0.15.0 → gea_program-0.17.0}/gea/__main__.py

@@ -265,7 +265,8 @@ def main(argv=None) -> int:
     for name, helptxt in (("opcua", "OPC UA client port: read once or subscribe; record; replay a recording offline"),
                           ("mqtt", "MQTT subscriber port (3.1.1/5.0; number | json | Sparkplug B): run; record; replay offline"),
                           ("wits0", "WITS Level 0 port (drill floor: mud logger / EDR) over TCP connect, TCP listen or serial: run; record; replay offline"),
-                          ("witsml", "WITSML 1.4.1 read-only client: poll a log object from the store; record; replay offline")):
+                          ("witsml", "WITSML 1.4.1 read-only client: poll a log object from the store; record; replay offline"),
+                          ("etp", "WITSML 2.x over Energistics ETP v1.2 (WebSocket, Avro): subscribe to channels and the store pushes; record; replay the session's shape")):
         p_lp = sub.add_parser(name, help=helptxt)
         p_lp.add_argument("--config", type=str, default=None, help="site map JSON (client-owned)")
         p_lp.add_argument("--write-example-config", type=str, default=None, help="write an example map here and exit")
@@ -275,6 +276,7 @@ def main(argv=None) -> int:
         p_lp.add_argument("--read-once", action="store_true", help="opcua: one Read of all nodes instead of a subscription")
         p_lp.add_argument("--out", type=str, default=None, help="write the records CSV here")
         p_lp.add_argument("--stream-csv", type=str, default=None, help="also write a historian-style CSV the other commands ingest")
+        p_lp.add_argument("--selftest", action="store_true", help="etp: the codec round-trip and a session against the simulated store on the loopback")
 
     p_ws = sub.add_parser("workspace", help="the client site folder: init, add wells (file | catalogue | live), list, migrate a --out folder, refresh the dashboard, audit log")
     p_ws.add_argument("--path", type=str, required=True, help="the workspace folder")
@@ -282,7 +284,8 @@ def main(argv=None) -> int:
                       choices=["init", "add-file", "add-catalog", "add-live", "remove", "list", "migrate", "refresh", "audit",
                                "add-seismic", "refresh-seismic", "remove-seismic", "sar-film", "refresh-all", "add-track", "refresh-track", "remove-track",
                                "seismic-dataset", "seismic-field", "add-site", "sites", "site-report", "remove-site", "rename",
-                               "set-well", "sra-define", "sra-report", "associate", "osdu-export", "quakeml-export", "well-identity", "vibration-report"])
+                               "set-well", "sra-define", "sra-report", "associate", "osdu-export", "quakeml-export", "well-identity", "vibration-report",
+                               "add-live-station", "live-fold", "live-run"])
     p_ws.add_argument("--stations", type=str, nargs="+", default=None, help="add-track: two or more array station ids of this workspace")
     p_ws.add_argument("--site", type=str, default=None, help="site-report/remove-site: the site id")
     p_ws.add_argument("--api", type=str, default=None, help="set-well: the API number")
@@ -352,7 +355,10 @@ def main(argv=None) -> int:
     p_ws.add_argument("--unit", type=str, default="m", help="add-seismic with --permits and --zone: the grid unit (m, usft, ft)")
     p_ws.add_argument("--band", type=float, nargs=2, default=None, metavar=("LO", "HI"), help="add-seismic: the band, Hz (default 1 50)")
     p_ws.add_argument("--permits", type=str, default=None, help="add-seismic: a permit export to turn into the rigs CSV (instead of --sources)")
-    p_ws.add_argument("--station", type=str, default=None, help="refresh-seismic / remove-seismic: the station id")
+    p_ws.add_argument("--station", type=str, default=None, help="refresh-seismic / remove-seismic / live-fold / live-run: the station id")
+    p_ws.add_argument("--seedlink-config", type=str, default=None, help="add-live-station: the SeedLink config JSON (gea seedlink --write-example-config)")
+    p_ws.add_argument("--include-open", action="store_true", help="live-fold: fold the current day's files too (they are still being written)")
+    p_ws.add_argument("--seconds", type=float, default=None, help="live-run: how long to run (default: until Ctrl+C)")
     p_ws.add_argument("--name", type=str, default=None, help="init: site name; add-*: display name")
     p_ws.add_argument("--file", type=str, default=None, help="add-file: the client's data file; add-live: the port configuration JSON")
     p_ws.add_argument("--entry", type=str, default=None, help="add-catalog: catalogue entry")
@@ -400,6 +406,26 @@ def main(argv=None) -> int:
     p_us.add_argument("--password-env", type=str, default="GEA_PASSWORD", help="environment variable holding the password (never a flag, never on the command line)")
     p_us.add_argument("--actor", type=str, default="cli")
 
+    p_es = sub.add_parser("etp-sim", help="an ETP v1.2 store for testing a patch without a rig: two channels of a synthetic disposal well, pushed as a customer subscribes")
+    p_es.add_argument("--port", type=int, default=9800)
+    p_es.add_argument("--frames", type=int, default=600)
+    p_es.add_argument("--interval", type=float, default=1.0, help="seconds between samples")
+    p_es.add_argument("--seed", type=int, default=1)
+    p_sl = sub.add_parser("seedlink", help="the seismic leg's live port: a SeedLink (3 / 4.0) station's records as it writes them, byte for byte into day files; --selftest against the simulator")
+    p_sl.add_argument("--config", type=str, default=None, help="the SeedLink config JSON (host, port, streams)")
+    p_sl.add_argument("--write-example-config", type=str, default=None, help="write an example config here and exit")
+    p_sl.add_argument("--out", type=str, default="seedlink", help="the folder for the day files and the state (default ./seedlink)")
+    p_sl.add_argument("--seconds", type=float, default=60.0, help="how long to run (the state resumes the next run from the last sequence number)")
+    p_sl.add_argument("--max-records", type=int, default=None, help="stop after this many records")
+    p_sl.add_argument("--selftest", action="store_true", help="both protocols against the simulator on the loopback")
+    p_sl.add_argument("--hello", action="store_true", help="connect, print what the server says of itself (HELLO) and its INFO ID, and exit")
+    p_ss = sub.add_parser("seedlink-sim", help="a SeedLink server (3 and 4.0) for rehearsing the live station without a data centre: one synthetic three-component station")
+    p_ss.add_argument("--port", type=int, default=18000)
+    p_ss.add_argument("--network", type=str, default="XX")
+    p_ss.add_argument("--station", type=str, default="PAD3")
+    p_ss.add_argument("--channels", type=str, default="HHZ,HHN,HHE")
+    p_ss.add_argument("--rate", type=float, default=100.0, help="samples per second")
+    p_ss.add_argument("--seed", type=int, default=7)
     p_w0 = sub.add_parser("wits0-sim", help="a WITS0 sender for testing a patch without a rig: listens once, then streams a deterministic drilling sequence")
     p_w0.add_argument("--port", type=int, default=5001)
     p_w0.add_argument("--frames", type=int, default=600)
@@ -1908,6 +1934,31 @@ def main(argv=None) -> int:
                     raise SystemExit("well-identity needs --well <id>")
                 r = ws.well_identity(a.well)
                 print(_ppdm_text(r)); return 0
+            elif a.action == "add-live-station":
+                if not a.seedlink_config or not a.name:
+                    raise SystemExit("add-live-station needs --name <display> and --seedlink-config <json>")
+                st = ws.add_live_station(a.name, a.seedlink_config, a.lat, a.lon, actor=a.actor, band=a.band, stationxml=a.stationxml, sources_csv=a.sources)
+                print(f"live station {st['id']}: {st['live']['host']}:{st['live']['port']} {st['live']['stations']} - run `gea workspace --path ... --action live-run --station {st['id']}` or Start it on the page")
+                return 0
+            elif a.action == "live-fold":
+                if not a.station:
+                    raise SystemExit("live-fold needs --station <id>")
+                r = ws.fold_live_station(a.station, actor=a.actor, include_open=a.include_open)
+                print(f"folded {len(r['folded'])} file(s) into {a.station}: {r['folded']}; still open: {r['kept_open']}")
+                return 0
+            elif a.action == "live-run":
+                from . import seedlink as _L
+                if not a.station:
+                    raise SystemExit("live-run needs --station <id>")
+                cfg = ws.live_station_config(a.station)
+                d = ws.live_dir(a.station)
+                tap = _L.SeedLinkTap(cfg, d, os.path.join(d, "seedlink_state.json"))
+                try:
+                    st = tap.run(a.seconds if a.seconds else None)
+                except KeyboardInterrupt:
+                    tap.stop(); st = tap.state
+                print(_L.report_text(st))
+                return 0 if st["records"] else 1
             elif a.action == "quakeml-export":
                 from .quakeml import report_text as _qml_text
                 if not a.site:
@@ -1966,10 +2017,84 @@ def main(argv=None) -> int:
             stop.set()
             print("wits0-sim: stopped")
         return 0
-    elif a.cmd in ("opcua", "mqtt", "wits0", "witsml"):
+    elif a.cmd == "seedlink":
+        import json as _json
+        from . import seedlink as _L
+        if a.selftest:
+            r = _L.selftest()
+            print(_json.dumps({k: r[k] for k in ("label", "status", "checks")}, indent=1))
+            print(_json.dumps(r["detail"], indent=1, default=str))
+            return 0 if r["status"] == "OK" else 1
+        if a.write_example_config:
+            print("config:", _L.write_example_config(a.write_example_config))
+            return 0
+        if not a.config:
+            raise SystemExit("seedlink needs --config (or --write-example-config to start one, or --selftest)")
+        try:
+            cfg = _L.load_config(a.config)
+        except (ValueError, OSError) as e:
+            raise SystemExit(f"seedlink: {e}")
+        if a.hello:
+            try:
+                cl = _L.SeedLinkClient(cfg["host"], cfg["port"], cfg["timeout_s"]).connect()
+                h = cl.say_hello()
+                print(f"seedlink: {cfg['host']}:{cfg['port']} says {h['software']!r}; organization {cl.organization!r}; protocols {h['protocols']}; capabilities {h['capabilities']}")
+                cl.info("ID")
+                cl.sock.settimeout(cfg["timeout_s"])
+                pkt = cl.read_packet()
+                print(f"  INFO ID: {pkt['kind']} packet, SeedLink {pkt.get('protocol')}, {len(pkt.get('payload') or b'')} bytes")
+                cl.close()
+            except (OSError, ValueError, _L.SeedLinkError) as e:
+                raise SystemExit(f"seedlink: {e}\n  no SeedLink server answers at that host:port - start `gea seedlink-sim --port {cfg['port']}` in a SECOND window first, or point the config at the data centre (rtserve.iris.washington.edu:18000 for TexNet)")
+            return 0
+        tap = _L.SeedLinkTap(cfg, a.out)
+        try:
+            st = tap.run(a.seconds, max_records=a.max_records)
+        except KeyboardInterrupt:
+            tap.stop(); st = tap.state
+        print(_L.report_text(st))
+        if st["status"] == "REFUSED" or (st["records"] == 0 and st.get("last_error")):
+            print(f"  no records: start `gea seedlink-sim --port {cfg['port']}` in a SECOND window first, or point the config at the data centre (rtserve.iris.washington.edu:18000, network TX for TexNet)")
+            return 1
+        return 0
+    elif a.cmd == "seedlink-sim":
+        from . import seedlink as _L
+        srv = _L.simulate_server(port=a.port, network=a.network, station=a.station, channels=[c.strip().upper() for c in a.channels.split(",") if c.strip()], rate=a.rate, seed=a.seed)
+        print(f"seedlink-sim: a SeedLink server (3.1 and 4.0) listening on 127.0.0.1:{srv.port} - this window is the STATION and stays here; it writes {a.network}.{a.station} "
+              f"({a.channels}) at {a.rate:g} Hz in 512-byte records and serves them as customers ask.\n"
+              f"  Open a SECOND window and run:  gea seedlink --write-example-config seedlink.json; gea seedlink --config seedlink.json --seconds 60 --out live\n"
+              f"  or on the dashboard: Seismic -> Live stations -> Add (host 127.0.0.1, port {srv.port}, network {a.network}, station {a.station}) -> Start. Ctrl+C stops it.", flush=True)
+        try:
+            while srv.is_alive():
+                srv.join(0.5)
+        except KeyboardInterrupt:
+            srv.stop()
+            print("seedlink-sim: stopped")
+        return 0
+    elif a.cmd == "etp-sim":
+        from . import etp as _E
+        th, port, stop = _E.simulate_store(port=a.port, frames=a.frames, interval_s=a.interval, seed=a.seed, verbose=True)
+        print(f"etp-sim: an ETP v1.2 store listening on ws://127.0.0.1:{port}/ - this window is the STORE and stays here; nothing happens until a customer connects.\n"
+              f"  Open a SECOND window and run:  gea etp --config etp.json --seconds 60 --out floor   (with etp.json: url ws://127.0.0.1:{port}/ and the two example channel URIs)\n"
+              f"  or on the dashboard: Patch panel -> Add a patch -> etp, url ws://127.0.0.1:{port}/. Then it pushes {a.frames} samples per channel {a.interval:g} s apart. Ctrl+C stops it.", flush=True)
+        try:
+            while th.is_alive():
+                th.join(0.5)
+        except KeyboardInterrupt:
+            stop.set()
+            print("etp-sim: stopped")
+        return 0
+    elif a.cmd in ("opcua", "mqtt", "wits0", "witsml", "etp"):
         import json as _json
         from .live_ports import records_to_stream, summarize, write_records_csv
-        mod = __import__({"opcua": "gea.opcua_port", "mqtt": "gea.mqtt_port", "wits0": "gea.wits0", "witsml": "gea.witsml"}[a.cmd], fromlist=["x"])
+        mod = __import__({"opcua": "gea.opcua_port", "mqtt": "gea.mqtt_port", "wits0": "gea.wits0", "witsml": "gea.witsml", "etp": "gea.etp"}[a.cmd], fromlist=["x"])
+        if a.cmd == "etp" and getattr(a, "selftest", False):
+            r = mod.selftest()
+            print(f"etp selftest [{r['label']}]: {r['status']}")
+            for k, v in r["checks"].items():
+                print(f"  {'ok ' if v else 'BAD'} {k}")
+            print(f"  {r['n_records']} record(s) on {r['tags']}; store {r['store'].get('application')} protocols {r['store'].get('protocols')}; counts {r['counts']}")
+            return 0 if r["status"] == "OK" else 1
         if a.write_example_config:
             print("config:", mod.write_example_config(a.write_example_config))
             return 0
@@ -1994,6 +2119,11 @@ def main(argv=None) -> int:
                 tap = mod.Wits0Tap(a.config, recording_path=a.record)
                 recs = tap.run(a.seconds)
                 src = f"{tap.cfg['transport']} {tap.cfg.get('host') or tap.cfg.get('device') or ('listen:' + str(tap.cfg.get('listen_port')))}"
+            elif a.cmd == "etp":
+                tap = mod.EtpTap(a.config, recording_path=a.record)
+                recs = tap.run(a.seconds)
+                src = tap.cfg["url"] + (f"  (store: {tap.state.get('store', {}).get('application')}, {tap.state.get('channels')} channel(s) subscribed"
+                                        + (f", missing {tap.state.get('missing_uris')}" if tap.state.get('missing_uris') else '') + ')')
             else:
                 tap = mod.WitsmlTap(a.config, recording_path=a.record)
                 recs = tap.run(a.seconds)
@@ -2001,11 +2131,17 @@ def main(argv=None) -> int:
         except (NotImplementedError, ConnectionError, ValueError) as e:
             hint = {"wits0": "nothing is sending on that host:port - start `gea wits0-sim --port 5001` in a SECOND window first (it must be running while this reads), or point the config at the rig's real WITS0 feed",
                     "witsml": "no WITSML store answers at that url - the example config points at 127.0.0.1:8000, a placeholder; put the real store's url, uids and credential env names in it",
+                    "etp": "no ETP store answers at that url - start `gea etp-sim --port 9800` in a SECOND window first, or point the config at the rig's ETP endpoint (wss://...) with the channel URIs it publishes",
                     "opcua": "no OPC UA server answers at that endpoint - the example config is a placeholder; put the real server's endpoint, security and node ids in it",
                     "mqtt": "no MQTT broker answers at that host:port - the example config is a placeholder; put the real broker in it"}.get(a.cmd, "")
             raise SystemExit(f"{a.cmd}: {e}" + (f"\n  {hint}" if hint else ""))          # the reason and what to do, without a traceback
         print(f"{a.cmd}: {src}")
-        print(_json.dumps(summarize(recs), indent=1))
+        if a.cmd == "etp" and a.replay:
+            shape = getattr(mod.replay, "summary", {})
+            print(_json.dumps({"session_shape": shape, "records": 0,
+                               "note": "an ETP recording holds the messages as received with ChannelData as counts (the samples went to --out); the replay reproduces the session's shape, not the samples"}, indent=1))
+        else:
+            print(_json.dumps(summarize(recs), indent=1))
         if a.out:
             print("  records:", write_records_csv(recs, a.out))
         if a.stream_csv and recs: