bottomtime 0.2.0__tar.gz → 0.3.0__tar.gz

{bottomtime-0.2.0 → bottomtime-0.3.0}/.gitignore

@@ -3,6 +3,8 @@ __pycache__/
 *.egg-info/
 dist/
 .pytest_cache/
+.mypy_cache/
+.claude/settings.local.json
 
 # Personal dive data lives outside version control
 data/

{bottomtime-0.2.0 → bottomtime-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bottomtime
-Version: 0.2.0
+Version: 0.3.0
 Summary: Lossless dive-log store: ingest, decode, and reconcile dives from Garmin (FIT) and Shearwater (Petrel Native Format) dive computers
 Project-URL: Homepage, https://github.com/snehankekre/bottomtime
 Project-URL: Issues, https://github.com/snehankekre/bottomtime/issues

{bottomtime-0.2.0 → bottomtime-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bottomtime"
-version = "0.2.0"
+version = "0.3.0"
 description = "Lossless dive-log store: ingest, decode, and reconcile dives from Garmin (FIT) and Shearwater (Petrel Native Format) dive computers"
 readme = "README.md"
 license = "MIT"

{bottomtime-0.2.0 → bottomtime-0.3.0}/src/bottomtime/__init__.py

@@ -1,6 +1,6 @@
 """bottomtime: lossless dive-log store for multi-computer divers."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 from .api import list_dives, load_dive
 

{bottomtime-0.2.0 → bottomtime-0.3.0}/src/bottomtime/decode/pnf.py

@@ -23,6 +23,18 @@ DECODER_VERSION history:
      dive_details.EndGF99 and decays during surface offgassing; byte 24 sits
      just below the 3 m-quantized stop depth and zeroes when deco clears;
      byte 18 equals the XML export's batteryVoltage x 100
+  3  reconciled against Shearwater Cloud's own parser (DiveLogParser.dll,
+     class PetrelNativeLogV14Parser, read from the desktop app). Every sample
+     byte 0-31 is now named. Changes vs v2:
+     - bytes 24/25 are ceiling/gf99 only under gradient-factor deco models;
+       under DCIEM (deco model 3) they are a safe-ascent depth instead
+       (byte 24 integer metres, byte 25 hundredths), decoded to
+       safe_ascent_depth_m with ceiling_m/gf99 left None.
+     - battery_v is a 16-bit value: (byte 17 << 8 | byte 18) / 100, not byte 18
+       alone (byte 17 is zero only because a ~1.5 V cell never needs it; a
+       higher-voltage computer such as a Teric would overflow the old read).
+     - byte 11 is battery_pct (BATTERY_PERCENT_REMAINING).
+     - bytes 30-31 are sac (surface air consumption, u16 / 100; 0xFFFF = n/a).
 """
 
 from __future__ import annotations
@@ -31,7 +43,7 @@ import gzip
 import struct
 from dataclasses import dataclass, field
 
-DECODER_VERSION = 2
+DECODER_VERSION = 3
 
 RECORD_SIZE = 32
 
@@ -44,12 +56,17 @@ INFO_EVENT = 0x30
 DIVE_SAMPLE_EXT = 0xE1
 FINAL = 0xFF
 
-# status flag bits (sample byte 12)
+# Sample byte 12 is a packed status/mode byte. Bit meanings per Shearwater's
+# PetrelNativeLogV14Parser: 0 gas-switch-needed, 1 external ppO2, 2 setpoint
+# type (high/low), 3 circuit-switch type, 4 circuit mode (set = OC on this
+# family), 5 CCR mode, 6-7 solenoid-fired count.
 FLAG_GASSWITCH = 0x01
 FLAG_PPO2_EXTERNAL = 0x02
 FLAG_SETPOINT_HIGH = 0x04
 FLAG_SC = 0x08
 FLAG_OC = 0x10
+FLAG_CCR_MODE = 0x20
+SOLENOID_COUNT_SHIFT = 6
 
 DIVE_MODES = {
     0: "cc",
@@ -82,10 +99,9 @@ COMPUTER_MODELS = {
     12: "Tern",
 }
 
-# Sample bytes not (yet) assigned a meaning; kept per sample as b<offset>.
-# 18 (battery), 24 (ceiling), 25 (gf99), 26-27 (@+5) were identified
-# empirically and promoted in v2. 30-31 read 0xFFFF (sentinel) so far.
-UNMAPPED_SAMPLE_BYTES = (11, 17, 30, 31)
+# As of v3 every sample byte 0-31 is named (reconciled against Shearwater's
+# own PetrelNativeLogV14Parser), so no bytes are stashed raw in extra_json.
+SAC_SENTINEL = 0xFFFF  # bytes 30-31 when no air integration / no SAC
 
 
 def _u16be(data: bytes, off: int) -> int:
@@ -127,6 +143,9 @@ class PnfSample:
     cns_pct: float | None = None
     gf99: float | None = None
     ceiling_m: float | None = None
+    safe_ascent_depth_m: float | None = None  # DCIEM only (bytes 24-25)
+    battery_pct: int | None = None
+    sac: float | None = None
     sensor1_raw: int | None = None
     sensor2_raw: int | None = None
     sensor3_raw: int | None = None
@@ -135,6 +154,13 @@ class PnfSample:
     sensor3_ppo2: float | None = None
     battery_v: float | None = None
     status_flags: int | None = None
+    gas_switch_needed: bool | None = None
+    ppo2_external: bool | None = None
+    setpoint_high: bool | None = None
+    circuit_switch: bool | None = None
+    circuit_mode: int | None = None
+    ccr_mode: int | None = None
+    solenoid_fired_count: int | None = None
     tank0_psi: float | None = None
     tank1_psi: float | None = None
     gas_time_min: float | None = None
@@ -230,11 +256,15 @@ def decode(blob: bytes) -> PnfDive:
     seq = 0
     t = 0.0
 
+    is_dciem = header["deco_model"] == "dciem"
+
     for rtype, off in raw_records:
         rec = data[off : off + RECORD_SIZE]
         if rtype in (DIVE_SAMPLE, AVELO_SAMPLE):
             samples.append(
-                _parse_sample(rec, t, imperial, calibrated, calibration, rtype)
+                _parse_sample(
+                    rec, t, imperial, calibrated, calibration, rtype, is_dciem
+                )
             )
             t += interval_ms / 1000.0
         elif rtype == FREEDIVE_SAMPLE:
@@ -295,6 +325,7 @@ def _parse_sample(
     calibrated: int,
     calibration: list[float],
     rtype: int,
+    is_dciem: bool,
 ) -> PnfSample:
     ft = 0.3048
     depth = _u16be(rec, 1) / 10.0
@@ -311,6 +342,7 @@ def _parse_sample(
 
     status = rec[12] if rtype != AVELO_SAMPLE else 0
     ccr = (status & FLAG_OC) == 0 if rtype != AVELO_SAMPLE else False
+    decoded_status = rtype != AVELO_SAMPLE
 
     sample = PnfSample(
         t_s=t,
@@ -328,11 +360,34 @@ def _parse_sample(
         sensor2_raw=rec[15],
         sensor3_raw=rec[16],
         cns_pct=float(rec[23]),
-        ceiling_m=float(rec[24]) if rec[24] != 0xFF else None,
-        gf99=float(rec[25]) if rec[25] != 0xFF else None,  # 0xFF = not available
-        battery_v=rec[18] / 100.0,
+        battery_pct=rec[11],
+        battery_v=((rec[17] << 8) | rec[18]) / 100.0,
     )
 
+    if decoded_status:
+        sample.gas_switch_needed = bool(status & FLAG_GASSWITCH)
+        sample.ppo2_external = bool(status & FLAG_PPO2_EXTERNAL)
+        sample.setpoint_high = bool(status & FLAG_SETPOINT_HIGH)
+        sample.circuit_switch = bool(status & FLAG_SC)
+        sample.circuit_mode = (status >> 4) & 1
+        sample.ccr_mode = (status >> 5) & 1
+        sample.solenoid_fired_count = (status >> SOLENOID_COUNT_SHIFT) & 3
+
+    # Bytes 24-25 are ceiling + GF99 under gradient-factor deco models. Under
+    # DCIEM (deco model 3) the same two bytes are a safe-ascent depth: byte 24
+    # whole metres, byte 25 hundredths, subtracted.
+    if is_dciem:
+        sample.safe_ascent_depth_m = rec[24] - rec[25] / 100.0
+    else:
+        if rec[24] != 0xFF:
+            sample.ceiling_m = float(rec[24])
+        if rec[25] != 0xFF:  # 0xFF = not available (still on-gassing)
+            sample.gf99 = float(rec[25])
+
+    sac_raw = _u16be(rec, 30)
+    if sac_raw != SAC_SENTINEL:
+        sample.sac = sac_raw / 100.0
+
     if ccr:
         sample.setpoint = rec[19] / 100.0
         if not (status & FLAG_PPO2_EXTERNAL):
@@ -363,10 +418,6 @@ def _parse_sample(
     if at_plus_five != 0xFFFF:
         sample.extra["at_plus_five_min"] = at_plus_five
 
-    for b in UNMAPPED_SAMPLE_BYTES:
-        if rec[b]:
-            sample.extra[f"b{b}"] = rec[b]
-
     return sample
 
 

{bottomtime-0.2.0 → bottomtime-0.3.0}/src/bottomtime/ingest/shearwater_db.py

@@ -139,19 +139,22 @@ def _ingest_log(
     con.executemany(
         "INSERT INTO shearwater_samples (source_dive_id, t_s, depth_m, temp_c,"
         " stop_depth_m, stop_or_ndl_min, tts_min, in_deco, avg_ppo2, o2_pct, he_pct,"
-        " setpoint, cns_pct, gf99, ceiling_m, sensor1_raw, sensor2_raw, sensor3_raw,"
+        " setpoint, cns_pct, gf99, ceiling_m, safe_ascent_depth_m, battery_pct, sac,"
+        " sensor1_raw, sensor2_raw, sensor3_raw,"
         " sensor1_ppo2, sensor2_ppo2, sensor3_ppo2, battery_v, status_flags,"
-        " tank0_psi, tank1_psi, gas_time_min, extra_json)"
-        " VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+        " solenoid_fired_count, tank0_psi, tank1_psi, gas_time_min, extra_json)"
+        " VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
         [
             (
                 dive_id, s.t_s, s.depth_m, s.temp_c,
                 s.stop_depth_m, s.stop_or_ndl_min, s.tts_min, s.in_deco,
                 s.avg_ppo2, s.o2_pct, s.he_pct,
                 s.setpoint, s.cns_pct, s.gf99, s.ceiling_m,
+                s.safe_ascent_depth_m, s.battery_pct, s.sac,
                 s.sensor1_raw, s.sensor2_raw, s.sensor3_raw,
                 s.sensor1_ppo2, s.sensor2_ppo2, s.sensor3_ppo2,
                 s.battery_v, s.status_flags,
+                s.solenoid_fired_count,
                 s.tank0_psi, s.tank1_psi, s.gas_time_min,
                 json.dumps(s.extra, separators=(",", ":")) if s.extra else None,
             )

{bottomtime-0.2.0 → bottomtime-0.3.0}/src/bottomtime/store/schema.py

@@ -11,7 +11,7 @@ Design principles:
   dives is the canonical entity built from matches + singletons.
 """
 
-SCHEMA_VERSION = 1
+SCHEMA_VERSION = 2
 
 DDL = """
 CREATE TABLE IF NOT EXISTS meta (
@@ -89,8 +89,11 @@ CREATE TABLE IF NOT EXISTS shearwater_samples (
   he_pct REAL,
   setpoint REAL,
   cns_pct REAL,
-  gf99 REAL,                       -- populated at decoder_version >= 2
-  ceiling_m REAL,                  -- populated at decoder_version >= 2
+  gf99 REAL,                       -- populated at decoder_version >= 2; NULL under DCIEM
+  ceiling_m REAL,                  -- populated at decoder_version >= 2; NULL under DCIEM
+  safe_ascent_depth_m REAL,        -- DCIEM only (bytes 24-25); NULL otherwise, v3
+  battery_pct INTEGER,             -- battery percent remaining (byte 11), v3
+  sac REAL,                        -- surface air consumption (bytes 30-31), v3
   sensor1_raw INTEGER,
   sensor2_raw INTEGER,
   sensor3_raw INTEGER,
@@ -98,7 +101,8 @@ CREATE TABLE IF NOT EXISTS shearwater_samples (
   sensor2_ppo2 REAL,
   sensor3_ppo2 REAL,
   battery_v REAL,
-  status_flags INTEGER,
+  status_flags INTEGER,             -- raw sample byte 12 (packed mode/status bits)
+  solenoid_fired_count INTEGER,     -- CCR O2 solenoid firings, byte 12 bits 6-7, v3
   tank0_psi REAL,
   tank1_psi REAL,
   gas_time_min REAL,

{bottomtime-0.2.0 → bottomtime-0.3.0}/src/bottomtime/verify/crosscheck.py

@@ -30,6 +30,7 @@ TOL = {
     "temp_c": 0.51,
     "battery_v": 0.011,
     "ndl_min": 0.001,
+    "sac": 0.011,
 }
 
 
@@ -71,6 +72,10 @@ def check_xml(con: sqlite3.Connection, xml_dir: Path, failures: list) -> None:
             ("averagePPO2", "avg_ppo2", 1.0),
             ("waterTemp", "temp_c", 1.0),
             ("batteryVoltage", "battery_v", 1.0),
+            # SAC (bytes 30-31) only present with wireless air integration. The
+            # XML is produced by the same parser, so it should match exactly;
+            # inert on dives without AI (both sides None).
+            ("sac", "sac", 1.0),
         ]
         for i, (db_row, x) in enumerate(zip(samples, xs)):
             for xml_field, col, scale in pairs:

{bottomtime-0.2.0 → bottomtime-0.3.0}/tests/test_pnf.py

@@ -25,8 +25,10 @@ def _sample(depth_dm: int, **kw) -> bytearray:
     rec[8] = kw.get("o2", 21)
     rec[9] = kw.get("he", 0)
     rec[10] = kw.get("ndl_min", 99)
+    rec[11] = kw.get("battery_pct", 100)
     rec[12] = kw.get("flags", pnf.FLAG_OC)
     rec[14] = kw.get("temp", 27) & 0xFF
+    rec[17] = kw.get("battery_msb", 0)
     rec[18] = kw.get("battery_raw", 152)
     struct.pack_into(">H", rec, 20, 0xFFFF)  # AI off
     rec[22] = 0xFF  # gas time not paired
@@ -35,10 +37,11 @@ def _sample(depth_dm: int, **kw) -> bytearray:
     rec[25] = kw.get("gf99", 0xFF)
     struct.pack_into(">H", rec, 26, kw.get("at_plus_five", 0))
     struct.pack_into(">H", rec, 28, 0xFFFF)  # AI off
+    struct.pack_into(">H", rec, 30, kw.get("sac_raw", 0xFFFF))  # SAC n/a
     return rec
 
 
-def build_blob(samples=None, interval_ms=10000, extra_records=None) -> bytes:
+def build_blob(samples=None, interval_ms=10000, extra_records=None, deco_model=0) -> bytes:
     records = []
 
     opening0 = _record(0x10)
@@ -53,7 +56,7 @@ def build_blob(samples=None, interval_ms=10000, extra_records=None) -> bytes:
     records.append(opening1)
 
     opening2 = _record(0x12)
-    opening2[18] = 0  # GF deco model
+    opening2[18] = deco_model  # 0=GF, 1=VPM-B, 2=VPM-B/GFS, 3=DCIEM
     records.append(opening2)
 
     opening3 = _record(0x13)
@@ -123,6 +126,43 @@ def test_samples():
     assert s1.depth_m == 52.8
     assert (s1.stop_depth_m, s1.tts_min, s1.in_deco) == (9.0, 14.0, 1)
     assert (s1.ceiling_m, s1.gf99, s1.cns_pct) == (9.0, 30.0, 4.0)
+    assert s0.battery_pct == 100
+    assert s0.sac is None  # 0xFFFF sentinel
+
+
+def test_battery_voltage_is_16bit():
+    # A higher-voltage computer (e.g. Teric rechargeable ~4.2 V) overflows a
+    # single byte, so the decoder must read bytes 17-18 together.
+    dive = pnf.decode(build_blob(samples=[_sample(24, battery_msb=1, battery_raw=164)]))
+    assert dive.samples[0].battery_v == round((1 << 8 | 164) / 100.0, 2)  # 4.20 V
+
+
+def test_sac_when_present():
+    dive = pnf.decode(build_blob(samples=[_sample(24, sac_raw=1234)]))
+    assert dive.samples[0].sac == 12.34
+
+
+def test_status_byte_bits_decoded():
+    flags = 0x01 | 0x20 | (2 << 6)  # gas-switch-needed + CCR mode + solenoid count 2
+    dive = pnf.decode(build_blob(samples=[_sample(24, flags=flags)]))
+    s = dive.samples[0]
+    assert s.gas_switch_needed is True
+    assert s.ccr_mode == 1
+    assert s.solenoid_fired_count == 2
+    assert s.circuit_mode == 0
+    assert s.setpoint_high is False
+    assert s.status_flags == flags
+
+
+def test_dciem_uses_safe_ascent_depth():
+    # Under DCIEM (deco model 3), bytes 24-25 are a safe-ascent depth, not
+    # ceiling/GF99: byte 24 whole metres minus byte 25 hundredths.
+    blob = build_blob(samples=[_sample(300, ceiling=6, gf99=50)], deco_model=3)
+    dive = pnf.decode(blob)
+    assert dive.header["deco_model"] == "dciem"
+    s = dive.samples[0]
+    assert s.ceiling_m is None and s.gf99 is None
+    assert s.safe_ascent_depth_m == 6 - 0.50  # 5.5 m
 
 
 def test_unknown_records_preserved():

bottomtime-0.2.0/.claude/settings.local.json

@@ -1,30 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(sqlite3 \"file:data/dives.db?mode=ro\" \"SELECT source, count(*) FROM source_dives GROUP BY source;\" \"SELECT json_extract(header_json,'$.pnf.computer_model'), json_extract(header_json,'$.pnf.computer_firmware'), json_extract(header_json,'$.dive_details.Product'), count(*) FROM source_dives WHERE source='shearwater' GROUP BY 1,2,3;\")",
-      "Bash(sqlite3 \"file:data/dives.db?mode=ro\" \"SELECT json_extract(header_json,'$.file_id_mesgs[0].product_name'), json_extract(header_json,'$.file_id_mesgs[0].manufacturer'), json_extract(header_json,'$.file_id_mesgs[0].product'), count(*) FROM source_dives WHERE source='garmin' GROUP BY 1,2,3 LIMIT 10;\")",
-      "Bash(sqlite3 \"file:$(pwd)/data/dives.db?mode=ro&immutable=1\" \"SELECT source, count(*) FROM source_dives GROUP BY source;\")",
-      "Bash(DB=\"file:$(pwd)/data/dives.db?mode=ro&immutable=1\")",
-      "Bash(sqlite3 \"$DB\" \"SELECT json_extract(header_json,''$.pnf.computer_model''), json_extract(header_json,''$.pnf.computer_firmware''), json_extract(header_json,''$.dive_details.Product''), count(*) FROM source_dives WHERE source=''shearwater'' GROUP BY 1,2,3;\")",
-      "Bash(sqlite3 \"$DB\" \"SELECT json_extract(header_json,''$.file_id_mesgs[0].product_name''), json_extract(header_json,''$.device_info_mesgs[0].product_name''), json_extract(header_json,''$.device_info_mesgs[0].software_version''), count(*) FROM source_dives WHERE source=''garmin'' GROUP BY 1,2,3 LIMIT 10;\")",
-      "Bash(DB=\"file:$(pwd)/data/dives.db?mode=ro&immutable=1\")",
-      "Bash(sqlite3 \"$DB\" \"SELECT json_extract(header_json,''$.file_id_mesgs[0]'') FROM source_dives WHERE source=''garmin'' LIMIT 1;\")",
-      "Bash(sqlite3 \"$DB\" \"SELECT json_extract(header_json,''$.device_info_mesgs[0]'') FROM source_dives WHERE source=''garmin'' LIMIT 1;\")",
-      "Bash(sqlite3 \"$DB\" \"SELECT DISTINCT json_extract(header_json,''$.file_id_mesgs[0].garmin_product'') FROM source_dives WHERE source=''garmin'';\")",
-      "Bash(TMP=/var/folders/xx/8wmmss0x7lb3v3mrhc1rzzc00000gn/T/tmp.yC0jxrHEY0)",
-      "Bash(python -c \"import matplotlib; print(matplotlib.__version__)\")",
-      "Bash(python -m bottomtime.cli --db \"$TMP/dives.db\" plot 318 -o \"$TMP/d318.png\")",
-      "Bash(python -c \"\nfrom bottomtime.api import load_dive\nfrom bottomtime.plot import aligned_series\nd = load_dive(''$TMP/dives.db'', 318)\nfor s in aligned_series(d):\n    print(s[''source''], s[''label''], ''x0=%.0f'' % s[''x''][0], ''xN=%.0f'' % s[''x''][-1])\n\")",
-      "Bash(python -m pytest tests/ -q 2 >& 1)",
-      "Bash(python -c \"import sys; print(sys.prefix != sys.base_prefix, sys.prefix)\")",
-      "Bash(rg -n \"—|–\" --no-heading /Users/snehan/Downloads/bottomtime/README.md /Users/snehan/Downloads/bottomtime/src /Users/snehan/Downloads/bottomtime/tests /Users/snehan/Downloads/bottomtime/pyproject.toml)",
-      "Bash(rg -ni \"leverage|seamless|robust|delve|deep dive|journey|landscape|ecosystem|empower|unlock|supercharge|elevate|streamline|game-chang|cutting-edge|state-of-the-art|best-in-class|thrilled|excited|passionate|humbled|honored|compelling|actionable|utilize|in order to|testament|underscores|boasts|not just|isn''t about|not about\" --no-heading /Users/snehan/Downloads/bottomtime/README.md /Users/snehan/Downloads/bottomtime/src /Users/snehan/Downloads/bottomtime/tests)",
-      "Bash(ls -R /Users/snehan/Downloads/snehankekre.github.io/.claude 2 > /dev/null)",
-      "Bash(ls /Users/snehan/.claude/projects/-Users-snehan-Downloads-snehankekre-github-io/memory/ 2>/dev/null)",
-      "Bash(rg -n \"—|–\" /Users/snehan/Downloads/bottomtime/README.md /Users/snehan/Downloads/bottomtime/src /Users/snehan/Downloads/bottomtime/tests /Users/snehan/Downloads/bottomtime/pyproject.toml)",
-      "Bash(echo \"clean: $?\")",
-      "Bash(python -m pytest tests/ -q)"
-    ],
-    "deny": []
-  }
-}