pyfastnet 2.0.18__tar.gz → 3.1.0__tar.gz

{pyfastnet-2.0.18/pyfastnet.egg-info → pyfastnet-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyfastnet
-Version: 2.0.18
+Version: 3.1.0
 Summary: A Python library for decoding FastNet protocol data streams.
 Author-email: Alex Salmon <alex@ivila.net>
 License: MIT License
@@ -54,8 +54,13 @@ Dynamic: license-file
 
 A Python library for decoding the **FastNet** protocol used by B&G Hydra / H2000
 instruments. Feed it raw bytes from the Fastnet bus and it handles
-synchronisation, checksum validation, and decoding — returning structured
-instrument data ready for further processing.
+synchronisation, checksum validation, and decoding — returning instrument data as
+**Signal K paths in SI units**, ready for further processing.
+
+> **v3.0 changes the output format.** Decoded frames are now `{signalk_path:
+> SI_value}` (e.g. `navigation.speedThroughWater = 3.6`) instead of the v2
+> name-keyed `{value, display_text, layout}` dicts. See **Output format** below.
+> The full v2-style decode is still available via `FrameBuffer(project=False)`.
 
 Developed for personal use and published for general interest. Runs on Raspberry
 Pi, macOS, or Linux.
@@ -91,8 +96,8 @@ try:
         fb.get_complete_frames()
         while not fb.frame_queue.empty():
             frame = fb.frame_queue.get()
-            for channel, decoded in frame["values"].items():
-                print(channel, decoded)
+            for path, value in frame["values"].items():
+                print(path, value)   # e.g. navigation.speedThroughWater 3.6
 finally:
     ser.close()
 ```
@@ -108,7 +113,7 @@ data to end up:
 
 | Project | What it does | Use it when |
 |---|---|---|
-| **pyfastnet** *(this library)* | **Decoder.** Turns raw Fastnet bytes into named instrument channels. | You're writing your own Python and want the decoded data. |
+| **pyfastnet** *(this library)* | **Decoder.** Turns raw Fastnet bytes into Signal K paths in SI units. | You're writing your own Python and want the decoded data. |
 | [fastnet2ip](https://github.com/ghotihook/fastnet2ip) | **Serial → network.** Broadcasts decoded data over UDP as NMEA 0183 or NMEA 2000 (over IP). | Feeding Signal K, OpenCPN, or a plotter over WiFi / Ethernet. |
 | [fastnet2n2k](https://github.com/ghotihook/fastnet2n2k) | **Serial → physical NMEA 2000 bus.** Transmits PGNs onto a CAN backbone via SocketCAN. | Wiring into a real NMEA 2000 network / chartplotter. |
 
@@ -126,7 +131,8 @@ port, a live data store, rate limiting, and output for you.
 ## Output format
 
 Each decoded frame is a dict with `to_address`, `from_address`, `command`, and
-`values`. Each entry in `values` is keyed by channel name:
+`values`. `values` maps **Signal K paths to SI values** — one canonical entry per
+physical quantity:
 
 ```python
 {
@@ -134,68 +140,83 @@ Each decoded frame is a dict with `to_address`, `from_address`, `command`, and
   "from_address": "Normal CPU (Wind Board in H2000)",
   "command":      "Broadcast",
   "values": {
-    "Apparent Wind Speed (Knots)": {
-      "channel_id":   "0x4D",
-      "value":        7.0,
-      "display_text": "7.0",
-      "layout":       None,
-    },
-    "Apparent Wind Angle": {
-      "channel_id":   "0x51",
-      "value":        -6.0,
-      "display_text": "-6.0",
-      "layout":       "-[data]",
-    },
-    "True Wind Direction": {
-      "channel_id":   "0x6D",
-      "value":        213.0,
-      "display_text": "213.0°M",
-      "layout":       "°M",
-    },
+    "environment.wind.speedApparent":     4.6,    # m/s
+    "environment.wind.angleApparent":     0.419,  # radians
+    "environment.wind.directionMagnetic": 1.239,  # radians
+    "navigation.speedThroughWater":       3.19,   # m/s
   }
 }
 ```
 
-### Position (LatLon) frames
+Units follow the Signal K spec: angles in **radians**, speed in **m/s**, distance
+in **metres**, temperature in **Kelvin**, pressure in **Pascals**. A value is a
+`float` (SI), a `str` enum (e.g. `steering.autopilot.state` → `"standby"`), a
+position object, or `None` when unavailable.
+
+Redundant unit-variant channels the bus sends (feet/fathoms depth, knots wind, °F)
+are collapsed to one canonical path. B&G-proprietary channels with no standard
+Signal K path — including the pre-calibration `raw` sensor values — are emitted
+under a `bandg.*` namespace (e.g. `bandg.wind.rawAngleApparent`).
+
+### Units and the full path map
 
-Position frames (command `LatLon`) appear under the `"LatLon"` key. The raw
-coordinate string (`DDMM.mmm` with hemisphere letters) is carried in
-`display_text`; `value` is `None`. The originating source's marker byte is
-preserved in `channel_id` (e.g. `0x47`, `0x4E`) but does not affect the key:
+Every emitted path has a canonical SI unit, available programmatically:
 
 ```python
-"LatLon": {
-    "channel_id":   "0x4E",
-    "value":        None,
-    "display_text": "3352.450S15113.920E",
-    "layout":       None,
-}
+from fastnet_decoder import unit_for
+unit_for("navigation.speedThroughWater")   # "m/s"
+unit_for("navigation.headingMagnetic")      # "rad"
+unit_for("environment.water.temperature")   # "K"
+unit_for("navigation.position")             # "deg"
+```
+
+The master reference — every B&G channel number → name → Signal K path + unit — is
+`channel_map()`, derived from the projection tables so it can't drift:
+
+```python
+from fastnet_decoder import channel_map
+channel_map()[0x41]
+# {'name': 'Boatspeed (Knots)', 'path': 'navigation.speedThroughWater',
+#  'unit': 'm/s', 'kind': 'standard'}
 ```
 
-### Layout field
+It is rendered as a table in [`docs/channel_map.md`](docs/channel_map.md). The design
+rationale, `bandg.*` namespace, Magnetic/True routing, and open TBCs are in
+[`docs/v3_signalk_mapping.md`](docs/v3_signalk_mapping.md).
 
-The `layout` field describes the indicator symbol shown on the physical display
-around the numeric value. It is the **only** place True/Magnetic, port/starboard
-sign, and similar context is carried — the raw stream contains no magnetic
-variation or deviation.
+### Position
 
-| `layout` | Meaning | Sign |
-|---|---|---|
-| `None` | No indicator symbol | positive |
-| `"[data]="` | `=` after value (starboard) | positive |
-| `"=[data]"` | `=` before value (port) | negative |
-| `"[data]-"` | `-` after value (starboard) | positive |
-| `"-[data]"` | `-` before value (port) | negative |
-| `"H[data]"` | `H` prefix — heading | positive |
-| `"°M"` | Magnetic bearing suffix | positive |
-| `"u[data]"` | `u` prefix — upwind (VMG) | positive |
-| `"d[data]"` | `d` prefix — downwind (VMG) | positive |
-| `"L[data]"` | `L` before — leeway port | negative |
-| `"[data]L"` | `L` after — AP compass target | positive |
-| `"[data]°C"` | Celsius suffix | positive |
-| `"[data]°F"` | Fahrenheit suffix | positive |
-| `"[data]z"` / `"z[data]"` | Dog-leg symbol — AP off course | positive |
-| `"TBC"` | Symbol seen but not yet identified | positive |
+Position frames are emitted as `navigation.position`, a decimal-degree object
+(negative for S / W):
+
+```python
+"navigation.position": {"latitude": -33.8742, "longitude": 151.2320}
+```
+
+### True vs Magnetic
+
+The reference is carried by the **path**, not a separate field:
+`navigation.headingMagnetic` vs `navigation.headingTrue`,
+`environment.wind.directionMagnetic` vs `directionTrue`,
+`environment.current.setMagnetic` vs `setTrue`. The decoder selects the right path
+from the display's indicator symbol at decode time. (The raw stream carries no
+magnetic variation or deviation, so it cannot convert between the two.)
+
+### Complete (rich) decode
+
+`FrameBuffer(project=False)` queues the full internal decode instead of the Signal K
+projection. Each value is then a dict — `value`, `display_text`, `layout`,
+`channel_id` — keyed by human-readable channel name (the v2 format). Useful for
+debugging and reverse-engineering; `display_text` and `layout` are not exposed in
+the default Signal K output.
+
+You can also project a single decoded frame yourself:
+
+```python
+from fastnet_decoder import decode_frame, project
+rich = decode_frame(raw_frame_bytes)      # complete decode
+si = project(rich)                        # {signalk_path: SI_value}
+```
 
 ### Debug API
 

pyfastnet-3.1.0/README.md

@@ -0,0 +1,190 @@
+# pyfastnet
+
+A Python library for decoding the **FastNet** protocol used by B&G Hydra / H2000
+instruments. Feed it raw bytes from the Fastnet bus and it handles
+synchronisation, checksum validation, and decoding — returning instrument data as
+**Signal K paths in SI units**, ready for further processing.
+
+> **v3.0 changes the output format.** Decoded frames are now `{signalk_path:
+> SI_value}` (e.g. `navigation.speedThroughWater = 3.6`) instead of the v2
+> name-keyed `{value, display_text, layout}` dicts. See **Output format** below.
+> The full v2-style decode is still available via `FrameBuffer(project=False)`.
+
+Developed for personal use and published for general interest. Runs on Raspberry
+Pi, macOS, or Linux.
+
+## Quick start
+
+```bash
+pip install pyfastnet
+```
+
+```python
+#!/usr/bin/env python3
+import serial
+from fastnet_decoder import FrameBuffer
+
+fb = FrameBuffer()
+
+ser = serial.Serial(
+    port="/dev/ttyUSB0",
+    baudrate=28800,
+    bytesize=serial.EIGHTBITS,
+    stopbits=serial.STOPBITS_TWO,
+    parity=serial.PARITY_ODD,
+    timeout=0.1,
+)
+
+try:
+    while True:
+        data = ser.read(256)
+        if not data:
+            continue
+        fb.add_to_buffer(data)
+        fb.get_complete_frames()
+        while not fb.frame_queue.empty():
+            frame = fb.frame_queue.get()
+            for path, value in frame["values"].items():
+                print(path, value)   # e.g. navigation.speedThroughWater 3.6
+finally:
+    ser.close()
+```
+
+Serial settings for a B&G Fastnet bus are **28,800 baud, 8 data bits, odd parity,
+2 stop bits**. No instruments to hand? The companion apps below ship recorded
+captures you can replay.
+
+## The Fastnet toolkit
+
+Three projects stack together — pick the layer that matches where you want the
+data to end up:
+
+| Project | What it does | Use it when |
+|---|---|---|
+| **pyfastnet** *(this library)* | **Decoder.** Turns raw Fastnet bytes into Signal K paths in SI units. | You're writing your own Python and want the decoded data. |
+| [fastnet2ip](https://github.com/ghotihook/fastnet2ip) | **Serial → network.** Broadcasts decoded data over UDP as NMEA 0183 or NMEA 2000 (over IP). | Feeding Signal K, OpenCPN, or a plotter over WiFi / Ethernet. |
+| [fastnet2n2k](https://github.com/ghotihook/fastnet2n2k) | **Serial → physical NMEA 2000 bus.** Transmits PGNs onto a CAN backbone via SocketCAN. | Wiring into a real NMEA 2000 network / chartplotter. |
+
+```
+                          ┌─ fastnet2ip   → UDP (NMEA 0183 / NMEA 2000 over IP) → Signal K, OpenCPN, plotters
+B&G Fastnet bus ─(serial)─→ pyfastnet ─┤
+                          └─ fastnet2n2k → SocketCAN (NMEA 2000 PGNs)           → CAN backbone, chartplotter
+```
+
+pyfastnet is the **engine** at the bottom of the stack. If you only want the
+decoded data on your network or NMEA 2000 bus — including running it as an
+always-on systemd service — use one of the companion apps; they handle the serial
+port, a live data store, rate limiting, and output for you.
+
+## Output format
+
+Each decoded frame is a dict with `to_address`, `from_address`, `command`, and
+`values`. `values` maps **Signal K paths to SI values** — one canonical entry per
+physical quantity:
+
+```python
+{
+  "to_address":   "Entire System",
+  "from_address": "Normal CPU (Wind Board in H2000)",
+  "command":      "Broadcast",
+  "values": {
+    "environment.wind.speedApparent":     4.6,    # m/s
+    "environment.wind.angleApparent":     0.419,  # radians
+    "environment.wind.directionMagnetic": 1.239,  # radians
+    "navigation.speedThroughWater":       3.19,   # m/s
+  }
+}
+```
+
+Units follow the Signal K spec: angles in **radians**, speed in **m/s**, distance
+in **metres**, temperature in **Kelvin**, pressure in **Pascals**. A value is a
+`float` (SI), a `str` enum (e.g. `steering.autopilot.state` → `"standby"`), a
+position object, or `None` when unavailable.
+
+Redundant unit-variant channels the bus sends (feet/fathoms depth, knots wind, °F)
+are collapsed to one canonical path. B&G-proprietary channels with no standard
+Signal K path — including the pre-calibration `raw` sensor values — are emitted
+under a `bandg.*` namespace (e.g. `bandg.wind.rawAngleApparent`).
+
+### Units and the full path map
+
+Every emitted path has a canonical SI unit, available programmatically:
+
+```python
+from fastnet_decoder import unit_for
+unit_for("navigation.speedThroughWater")   # "m/s"
+unit_for("navigation.headingMagnetic")      # "rad"
+unit_for("environment.water.temperature")   # "K"
+unit_for("navigation.position")             # "deg"
+```
+
+The master reference — every B&G channel number → name → Signal K path + unit — is
+`channel_map()`, derived from the projection tables so it can't drift:
+
+```python
+from fastnet_decoder import channel_map
+channel_map()[0x41]
+# {'name': 'Boatspeed (Knots)', 'path': 'navigation.speedThroughWater',
+#  'unit': 'm/s', 'kind': 'standard'}
+```
+
+It is rendered as a table in [`docs/channel_map.md`](docs/channel_map.md). The design
+rationale, `bandg.*` namespace, Magnetic/True routing, and open TBCs are in
+[`docs/v3_signalk_mapping.md`](docs/v3_signalk_mapping.md).
+
+### Position
+
+Position frames are emitted as `navigation.position`, a decimal-degree object
+(negative for S / W):
+
+```python
+"navigation.position": {"latitude": -33.8742, "longitude": 151.2320}
+```
+
+### True vs Magnetic
+
+The reference is carried by the **path**, not a separate field:
+`navigation.headingMagnetic` vs `navigation.headingTrue`,
+`environment.wind.directionMagnetic` vs `directionTrue`,
+`environment.current.setMagnetic` vs `setTrue`. The decoder selects the right path
+from the display's indicator symbol at decode time. (The raw stream carries no
+magnetic variation or deviation, so it cannot convert between the two.)
+
+### Complete (rich) decode
+
+`FrameBuffer(project=False)` queues the full internal decode instead of the Signal K
+projection. Each value is then a dict — `value`, `display_text`, `layout`,
+`channel_id` — keyed by human-readable channel name (the v2 format). Useful for
+debugging and reverse-engineering; `display_text` and `layout` are not exposed in
+the default Signal K output.
+
+You can also project a single decoded frame yourself:
+
+```python
+from fastnet_decoder import decode_frame, project
+rich = decode_frame(raw_frame_bytes)      # complete decode
+si = project(rich)                        # {signalk_path: SI_value}
+```
+
+### Debug API
+
+```python
+from fastnet_decoder import set_log_level
+import logging
+set_log_level(logging.DEBUG)
+```
+
+```python
+fb.get_buffer_size()      # bytes currently in buffer
+fb.get_buffer_contents()  # hex string of buffer contents
+```
+
+## Acknowledgments
+
+- [trlafleur](https://github.com/trlafleur) — background research
+- [Oppedijk](https://www.oppedijk.com/bandg/fastnet.html) — protocol documentation
+- [timmathews](https://github.com/timmathews/bg-fastnet-driver) — C++ reference implementation
+
+## License
+
+MIT — see [LICENSE](LICENSE).

{pyfastnet-2.0.18 → pyfastnet-3.1.0}/fastnet_decoder/__init__.py

@@ -1,7 +1,9 @@
-__version__ = "2.0.18"
+__version__ = "3.1.0"
 
 from .frame_buffer import FrameBuffer
 from .decode_fastnet import decode_frame, decode_ascii_frame, decode_light_frame
+from .signalk_map import project, unit_for, channel_map  # projection + units + master map
 from .logger import logger, set_log_level  # Import set_log_level for user control
 
-__all__ = ["FrameBuffer", "decode_frame", "decode_ascii_frame", "decode_light_frame", "logger", "set_log_level"]
+__all__ = ["FrameBuffer", "decode_frame", "decode_ascii_frame", "decode_light_frame",
+           "project", "unit_for", "channel_map", "logger", "set_log_level"]

{pyfastnet-2.0.18 → pyfastnet-3.1.0}/fastnet_decoder/decode_fastnet.py

@@ -13,7 +13,8 @@ _DECIMAL_PLACES_MAP = {1: 0, 10: 1, 100: 2, 1000: 3}
 #   "[data]-"  →  value is positive, trailing minus means port/starboard convention
 #   "-[data]"  →  value is negative (subtract sign)
 #   "=[data]"  →  value is negative (equals sign variant)
-#   "H[data]"  →  "H" prefix, e.g. H045 for a heading
+#   "H[data]"  →  heel to port; H carries the sign, value stored negative (e.g. H20.4)
+#   "[data]H"  →  heel to starboard; value positive (e.g. 33.8H)
 #   "°M"       →  magnetic bearing, suffix added after value
 
 def _sign_from_layout(layout: str) -> int:
@@ -192,6 +193,8 @@ def decode_ascii_frame(frame: bytes) -> dict:
         command      = frame[3]
         body         = frame[5:-1]
 
+        # TBC: no len(body) guard here (unlike decode_frame/decode_light_frame) —
+        # a short/empty body raises IndexError and falls to the except below.
         channel_id   = body[0]
         # body[1] is a format byte — not used for ASCII frames
         data_bytes   = body[2:]

{pyfastnet-2.0.18 → pyfastnet-3.1.0}/fastnet_decoder/frame_buffer.py

@@ -2,6 +2,7 @@ import logging
 from .utils import calculate_checksum
 from .mappings import COMMAND_LOOKUP, IGNORED_COMMANDS
 from .decode_fastnet import decode_frame, decode_ascii_frame, decode_light_frame, probe_frame
+from . import signalk_map
 from .logger import logger
 from queue import Queue, Full
 
@@ -17,10 +18,13 @@ class FrameBuffer:
         3. Pull decoded frames from frame_queue
     """
 
-    def __init__(self, max_buffer_size=8192, max_queue_size=1000):
+    def __init__(self, max_buffer_size=8192, max_queue_size=1000, project=True):
         self.buffer = bytearray()
         self.max_buffer_size = max_buffer_size
         self.frame_queue = Queue(maxsize=max_queue_size)
+        # v3: queue the {signalk_path: SI_value} projection by default. project=False
+        # queues the complete (rich) decode instead — for the golden guard / debugging.
+        self.project = project
 
     def add_to_buffer(self, new_data):
         if not isinstance(new_data, (bytes, bytearray)):
@@ -103,20 +107,37 @@ class FrameBuffer:
             probe_frame(frame)
             return
 
-        if decoded_frame and "values" in decoded_frame:
-            try:
-                self.frame_queue.put_nowait(decoded_frame)
+        if not (decoded_frame and "values" in decoded_frame):
+            if logger.isEnabledFor(logging.DEBUG):
+                logger.debug(f"  QUEUE fail    decode error  [{frame.hex()}]")
+            return
+
+        if self.project:
+            values = signalk_map.project(decoded_frame)
+            if not values:
+                # every channel dropped / unmapped (e.g. Backlight, protocol) — nothing to emit
                 if logger.isEnabledFor(logging.DEBUG):
-                    channel_names = list(decoded_frame["values"].keys())
-                    names_str = ", ".join(channel_names[:4])
-                    if len(channel_names) > 4:
-                        names_str += f", +{len(channel_names) - 4} more"
-                    logger.debug(f"  QUEUE {len(channel_names)} channel(s)  [{names_str}]")
-            except Full:
-                logger.warning("Frame queue full, dropping frame.")
+                    logger.debug(f"  QUEUE skip    no mapped paths  cmd={command_name}")
+                return
+            queued = {
+                "to_address":   decoded_frame.get("to_address"),
+                "from_address": decoded_frame.get("from_address"),
+                "command":      decoded_frame.get("command"),
+                "values":       values,
+            }
         else:
+            queued = decoded_frame
+
+        try:
+            self.frame_queue.put_nowait(queued)
             if logger.isEnabledFor(logging.DEBUG):
-                logger.debug(f"  QUEUE fail    decode error  [{frame.hex()}]")
+                keys = list(queued["values"].keys())
+                names_str = ", ".join(keys[:4])
+                if len(keys) > 4:
+                    names_str += f", +{len(keys) - 4} more"
+                logger.debug(f"  QUEUE {len(keys)} value(s)  [{names_str}]")
+        except Full:
+            logger.warning("Frame queue full, dropping frame.")
 
     def get_buffer_size(self):
         return len(self.buffer)

{pyfastnet-2.0.18 → pyfastnet-3.1.0}/fastnet_decoder/logger.py

@@ -15,6 +15,11 @@ logger.setLevel(DEFAULT_LOG_LEVEL)
 
 def set_log_level(level_name: str):
     """Sets the log level dynamically at runtime."""
-    level = getattr(logging, level_name.upper(), DEFAULT_LOG_LEVEL)
+    level = logging.getLevelName(level_name.upper())
+    if not isinstance(level, int):
+        logger.warning(
+            f"Unknown log level '{level_name}'; keeping current level."
+        )
+        return
     logger.setLevel(level)
     logger.info(f"Log level set to {level_name.upper()}.")