refactor and add functionality

Author: pdxlocations

README.md

@@ -1,24 +1,63 @@
-
-
 # meshdb
 
 A lightweight Python library for storing Meshtastic node, telemetry, and message data in per-node SQLite databases.
 
-## Quick Start
+## Installation
+
+Install from source within a virtual environment:
+
+```bash
+git clone https://github.com/pdxlocations/meshdb.git
+cd meshdb
+pip install -e .
+```
+
+Or install via Poetry:
+
+```bash
+poetry install
+```
+
+## Quick Usage Example
+
+Set a default database path and handle incoming packets:
 
 ```python
 from meshdb import handle_packet, set_default_db_path
 
 set_default_db_path("./data")
 
-# example packet (decoded from Meshtastic interface)
 packet = {
     "from": 12345678,
     "rxTime": 1700000000,
-    "decoded": {"portnum": "NODEINFO_APP", "user": {"longName": "TestNode"}}
+    "decoded": {
+        "portnum": "NODEINFO_APP",
+        "user": {"longName": "TestNode"}
+    }
 }
 
-handle_packet(packet, owner_node_num=12345678)
+handle_packet(packet, node_database_number=12345678)
 ```
 
-Run `python -m meshdb` to view all known nodes and their latest telemetry in JSON format.
+## Viewing Stored Data
+
+You can run:
+
+```bash
+python -m meshdb --db ./data
+```
+
+This prints a JSON summary of all known nodes and their latest telemetry, if available.
+
+## Lookups in Code
+
+```python
+import meshdb
+
+node = meshdb.get_node(12345678, owner_node_num=12345678)
+battery = meshdb.get_node_metric("TestNode", "battery_level", owner_node_num=12345678)
+```
+
+## Project Status
+
+Early development. Schema and API changes may occur.

examples/basic-integration.py

@@ -0,0 +1,138 @@
+import os
+import time
+import json
+from typing import List
+from pubsub import pub
+
+import meshtastic.serial_interface
+import meshdb
+
+"""
+Basic MeshDB integration demo
+=============================
+
+How to customize:
+  1) Set DB_BASE to where you want your per-owner DB files written.
+  2) Edit TARGETS to the nodes you want to query (id/hex suffix/short/long/numeric).
+  3) Run the script while a Meshtastic device is attached over USB/serial.
+
+What this demo shows:
+  - Resolving node numbers from many identifier forms (hex suffix, names, numeric)
+  - Pretty-printing a full node snapshot (nodeinfo + latest telemetry + latest position)
+  - Fetching a single metric (e.g., battery_level) via a convenience helper
+  - Live packet handling that persists NODEINFO/POSITION/TELEMETRY/TEXT_MESSAGE
+  - Auto-syncing the device's NodeDB into your local SQL DB on connect
+"""
+
+# -----------------------------
+# 1) Easy knobs
+# -----------------------------
+# Where to store DB files. Examples:
+#   "~/meshdb_data"            → creates <owner>.db files in that directory
+#   "./mesh.sqlite3"          → creates mesh.<owner>.sqlite3 alongside this script
+#   None or ""                 → current working directory
+DB_BASE = os.environ.get("MESHDB_BASE", "~/Meshtastic/github/pdxlocations/meshdb/")
+
+# Nodes to query for examples. You can use any of:
+#   - "!deadbeef" (full hex id)
+#   - "deadbeef" or "1adc" (hex suffix)
+#   - "FONE" (short name)
+#   - "New Phone Who Dis?" (long name)
+#   - 4062650989 (node number)
+TARGETS: List[object] = [
+    "Meshtastic 1adc",  # free text with hex suffix
+    "1adc",  # hex suffix
+    "SenseRAT",  # long name
+    "FONE",  # short name
+]
+
+# A single metric to fetch for demonstration
+DEMO_METRIC = os.environ.get("MESHDB_METRIC", "hw_model")  # e.g., "battery_level"
+
+# -----------------------------
+# 2) Configure MeshDB base path
+# -----------------------------
+meshdb.set_default_db_path(DB_BASE)
+print(f"[meshdb] DB base set to: {DB_BASE}")
+
+# -----------------------------
+# 3) Connect to device (Serial)
+# -----------------------------
+# You can also use meshtastic.tcp_interface.TCPInterface(hostname="127.0.0.1:4403")
+interface = meshtastic.serial_interface.SerialInterface()
+
+# Resolve connected device node number AND sync its NodeDB into our local DB
+CONNECTED_NODE_NUM = meshdb.get_connected_device_node_num(interface)
+if CONNECTED_NODE_NUM is None:
+    print("[meshdb] Warning: Could not resolve connected device node number; falling back to 0.")
+    CONNECTED_NODE_NUM = 0
+else:
+    print(f"[meshdb] Connected device node number: {CONNECTED_NODE_NUM}")
+
+# -----------------------------
+# 4) Helper to pretty print JSON
+# -----------------------------
+
+
+def jprint(obj):
+    print(json.dumps(obj, indent=2, sort_keys=True, ensure_ascii=False))
+
+
+# -----------------------------
+# 5) Show resolution examples
+# -----------------------------
+print("\n=== Node number resolution examples ===")
+for ident in TARGETS:
+    resolved = meshdb.get_node_num(ident, owner_node_num=CONNECTED_NODE_NUM)
+    print(f"identifier= {ident!r} → node_num= {resolved}")
+
+# -----------------------------
+# 6) Show full snapshots for targets
+# -----------------------------
+print("\n=== Full node snapshots (nodeinfo + latest telemetry + latest position) ===")
+for ident in TARGETS:
+    snap = meshdb.get_node(ident, owner_node_num=CONNECTED_NODE_NUM)
+    if snap is None:
+        print(f"snapshot for {ident!r}: NOT FOUND")
+    else:
+        print(f"\n# snapshot for {ident!r}")
+        jprint(snap)
+
+# -----------------------------
+# 7) Show a single metric value (first-found subtype priority)
+# -----------------------------
+print("\n=== Single metric lookup ===")
+for ident in TARGETS:
+    val = meshdb.get_node_metric(ident, DEMO_METRIC, owner_node_num=CONNECTED_NODE_NUM)
+    print(f"{DEMO_METRIC} for {ident!r} → {val}")
+
+# Bonus: show a NodeInfo field via metric helper
+
+val = meshdb.get_node_metric("SenseRAT", "hw_model", owner_node_num=CONNECTED_NODE_NUM)
+print(f"hw_model for 'SenseRAT' → {val}")
+
+# -----------------------------
+# 8) Live receive: store packets and optionally observe
+# -----------------------------
+
+
+def on_receive(packet=None, interface=None):
+    """Store NODEINFO/POSITION/TELEMETRY/TEXT_MESSAGE into the DB automatically."""
+    try:
+        result = meshdb.handle_packet(packet, node_database_number=CONNECTED_NODE_NUM)
+
+        # Example: derive readable sender names
+        sender = packet.get("from")
+        ln = meshdb.get_long_name(sender, node_database_number=CONNECTED_NODE_NUM)
+        sn = meshdb.get_short_name(sender, node_database_number=CONNECTED_NODE_NUM)
+        print(f"saved={result} from={sender} long='{ln}' short='{sn}' port={packet.get('decoded',{}).get('portnum')}")
+
+    except Exception as e:
+        print(f"on_receive error: {e}")
+
+
+# Hook PubSub topic and idle forever
+pub.subscribe(on_receive, "meshtastic.receive")
+print("\n[meshdb] Listening for packets… (Ctrl+C to exit)")
+while True:
+    time.sleep(1)

examples/meshdb_demo.py

@@ -8,3 +8,10 @@
     LocationDB,
     TelemetryDB,
 )
+
+from .db_lookup import (
+    get_node_num,
+    get_nodeinfo,
+    get_node,
+    get_node_metric,
+)

meshdb/__init__.py

@@ -34,13 +34,13 @@ def _fmt_ts(ts: Optional[int]) -> str:
         return str(ts)
 
 
-def _latest_location(ldb: LocationDB, node_id: int) -> Optional[Dict[str, Any]]:
+def _latest_location(ldb: LocationDB, node_num: int) -> Optional[Dict[str, Any]]:
     with ldb.connect() as con:
         cur = con.cursor()
         cur.execute(
             f"SELECT timestamp, latitude, longitude, altitude, location_source FROM {ldb.table} "
-            "WHERE node_id = ? ORDER BY timestamp DESC LIMIT 1",
-            (node_id,),
+            "WHERE node_num = ? ORDER BY timestamp DESC LIMIT 1",
+            (node_num,),
         )
         row = cur.fetchone()
         if not row:
@@ -54,13 +54,13 @@ def _latest_location(ldb: LocationDB, node_id: int) -> Optional[Dict[str, Any]]:
         }
 
 
-def _latest_device_telemetry(tdb: TelemetryDB, node_id: int) -> Optional[Dict[str, Any]]:
+def _latest_device_telemetry(tdb: TelemetryDB, node_num: int) -> Optional[Dict[str, Any]]:
     with tdb.connect() as con:
         cur = con.cursor()
         cur.execute(
             f"SELECT timestamp, battery_level, voltage, channel_utilization, air_util_tx, uptime_seconds "
-            f"FROM {tdb.table_device} WHERE node_id = ? ORDER BY timestamp DESC LIMIT 1",
-            (node_id,),
+            f"FROM {tdb.table_device} WHERE node_num = ? ORDER BY timestamp DESC LIMIT 1",
+            (node_num,),
         )
         row = cur.fetchone()
         if not row:
@@ -75,13 +75,13 @@ def _latest_device_telemetry(tdb: TelemetryDB, node_id: int) -> Optional[Dict[st
         }
 
 
-def _latest_power_telemetry(tdb: TelemetryDB, node_id: int) -> Optional[Dict[str, Any]]:
+def _latest_power_telemetry(tdb: TelemetryDB, node_num: int) -> Optional[Dict[str, Any]]:
     with tdb.connect() as con:
         cur = con.cursor()
         cur.execute(
             f"SELECT timestamp, ch1_voltage, ch1_current, ch2_voltage, ch2_current, ch3_voltage, ch3_current "
-            f"FROM {tdb.table_power} WHERE node_id = ? ORDER BY timestamp DESC LIMIT 1",
-            (node_id,),
+            f"FROM {tdb.table_power} WHERE node_num = ? ORDER BY timestamp DESC LIMIT 1",
+            (node_num,),
         )
         row = cur.fetchone()
         if not row:
@@ -122,7 +122,7 @@ def _infer_owner_candidates(db_hint: str | None) -> list[int]:
     return sorted(out)
 
 
-def main() -> None:
+def start() -> None:
     db_base = os.environ.get("MESHTASTIC_DB")
     set_default_db_path(db_base)
 
@@ -157,7 +157,7 @@ def main() -> None:
     with ndb.connect() as con:
         cur = con.cursor()
         cur.execute(
-            f"SELECT node_id, long_name, short_name, last_heard, hops_away, snr FROM {ndb.table} "
+            f"SELECT node_num, long_name, short_name, last_heard, hops_away, snr FROM {ndb.table} "
             "ORDER BY (last_heard IS NULL), last_heard DESC"
         )
         rows = cur.fetchall()
@@ -167,15 +167,15 @@ def main() -> None:
         return
 
     node_list = []
-    for node_id, long_name, short_name, last_heard, hops_away, snr in rows:
-        uid = int(node_id) if isinstance(node_id, (int, str)) else node_id
+    for node_num, long_name, short_name, last_heard, hops_away, snr in rows:
+        uid = int(node_num) if isinstance(node_num, (int, str)) else node_num
         name_long = long_name or ndb.get_name(uid, "long")
         name_short = short_name or ndb.get_name(uid, "short")
         loc = _latest_location(ldb, uid)
         dev = _latest_device_telemetry(tdb, uid)
         pwr = _latest_power_telemetry(tdb, uid)
         node_data = {
-            "node_id": uid,
+            "node_num": uid,
             "long_name": name_long,
             "short_name": name_short,
             "last_heard": last_heard,
@@ -193,7 +193,7 @@ def main() -> None:
             cur = con.cursor()
             # Environment telemetry
             cur.execute(
-                f"SELECT * FROM {tdb.table_environment} WHERE node_id = ? ORDER BY timestamp DESC LIMIT 1", (uid,)
+                f"SELECT * FROM {tdb.table_environment} WHERE node_num = ? ORDER BY timestamp DESC LIMIT 1", (uid,)
             )
             env_row = cur.fetchone()
             if env_row:
@@ -202,22 +202,22 @@ def main() -> None:
 
             # Air quality telemetry
             cur.execute(
-                f"SELECT * FROM {tdb.table_air_quality} WHERE node_id = ? ORDER BY timestamp DESC LIMIT 1", (uid,)
+                f"SELECT * FROM {tdb.table_air_quality} WHERE node_num = ? ORDER BY timestamp DESC LIMIT 1", (uid,)
             )
             aq_row = cur.fetchone()
             if aq_row:
                 columns = [d[0] for d in cur.description]
                 node_data["telemetry_air_quality"] = dict(zip(columns, aq_row))
 
             # Health telemetry
-            cur.execute(f"SELECT * FROM {tdb.table_health} WHERE node_id = ? ORDER BY timestamp DESC LIMIT 1", (uid,))
+            cur.execute(f"SELECT * FROM {tdb.table_health} WHERE node_num = ? ORDER BY timestamp DESC LIMIT 1", (uid,))
             health_row = cur.fetchone()
             if health_row:
                 columns = [d[0] for d in cur.description]
                 node_data["telemetry_health"] = dict(zip(columns, health_row))
 
             # Host telemetry
-            cur.execute(f"SELECT * FROM {tdb.table_host} WHERE node_id = ? ORDER BY timestamp DESC LIMIT 1", (uid,))
+            cur.execute(f"SELECT * FROM {tdb.table_host} WHERE node_num = ? ORDER BY timestamp DESC LIMIT 1", (uid,))
             host_row = cur.fetchone()
             if host_row:
                 columns = [d[0] for d in cur.description]
@@ -228,4 +228,4 @@ def main() -> None:
 
 
 if __name__ == "__main__":
-    main()
+    start()