pyfastnet 2.0.16__tar.gz → 2.0.18__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyfastnet
-Version: 2.0.16
+Version: 2.0.18
 Summary: A Python library for decoding FastNet protocol data streams.
 Author-email: Alex Salmon <alex@ivila.net>
 License: MIT License
@@ -52,20 +52,20 @@ Dynamic: license-file
 
 # pyfastnet
 
-Python library for decoding the FastNet protocol used by B&G Hydra/H2000 instruments. Developed for personal use and published for general interest.
+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.
 
-## Purpose
+Developed for personal use and published for general interest. Runs on Raspberry
+Pi, macOS, or Linux.
 
-Feed a raw byte stream from a FastNet bus into the library. It handles synchronisation, checksum validation, and decoding — returning structured instrument data ready for further processing.
+## Quick start
 
-## Installation
-
-```
+```bash
 pip install pyfastnet
 ```
 
-## Example usage
-
 ```python
 #!/usr/bin/env python3
 import serial
@@ -97,9 +97,36 @@ 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 named instrument channels. | 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`. Each entry in `values` is keyed by channel name:
+Each decoded frame is a dict with `to_address`, `from_address`, `command`, and
+`values`. Each entry in `values` is keyed by channel name:
 
 ```python
 {
@@ -131,10 +158,10 @@ Each decoded frame is a dict with `to_address`, `from_address`, `command`, and `
 
 ### Position (LatLon) frames
 
-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:
+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:
 
 ```python
 "LatLon": {
@@ -147,7 +174,10 @@ string (`DDMM.mmm` with hemisphere letters) is carried in `display_text`; `value
 
 ### Layout field
 
-The `layout` field describes the indicator symbol shown on the physical display around the numeric value:
+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.
 
 | `layout` | Meaning | Sign |
 |---|---|---|
@@ -167,7 +197,7 @@ The `layout` field describes the indicator symbol shown on the physical display
 | `"[data]z"` / `"z[data]"` | Dog-leg symbol — AP off course | positive |
 | `"TBC"` | Symbol seen but not yet identified | positive |
 
-## Debug API
+### Debug API
 
 ```python
 from fastnet_decoder import set_log_level
@@ -180,14 +210,12 @@ fb.get_buffer_size()      # bytes currently in buffer
 fb.get_buffer_contents()  # hex string of buffer contents
 ```
 
-## Companion apps
-
-- [fastnet2ip](https://github.com/ghotihook/fastnet2ip) — reads FastNet from serial and broadcasts it over UDP as either NMEA 0183 or NMEA 2000 (selected with `--output`). Install with `pipx install fastnet2ip`.
-
-Runs on Raspberry Pi, macOS, or Linux.
-
 ## 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.16 → pyfastnet-2.0.18}/README.md

@@ -1,19 +1,19 @@
 # pyfastnet
 
-Python library for decoding the FastNet protocol used by B&G Hydra/H2000 instruments. Developed for personal use and published for general interest.
+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.
 
-## Purpose
+Developed for personal use and published for general interest. Runs on Raspberry
+Pi, macOS, or Linux.
 
-Feed a raw byte stream from a FastNet bus into the library. It handles synchronisation, checksum validation, and decoding — returning structured instrument data ready for further processing.
+## Quick start
 
-## Installation
-
-```
+```bash
 pip install pyfastnet
 ```
 
-## Example usage
-
 ```python
 #!/usr/bin/env python3
 import serial
@@ -45,9 +45,36 @@ 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 named instrument channels. | 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`. Each entry in `values` is keyed by channel name:
+Each decoded frame is a dict with `to_address`, `from_address`, `command`, and
+`values`. Each entry in `values` is keyed by channel name:
 
 ```python
 {
@@ -79,10 +106,10 @@ Each decoded frame is a dict with `to_address`, `from_address`, `command`, and `
 
 ### Position (LatLon) frames
 
-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:
+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:
 
 ```python
 "LatLon": {
@@ -95,7 +122,10 @@ string (`DDMM.mmm` with hemisphere letters) is carried in `display_text`; `value
 
 ### Layout field
 
-The `layout` field describes the indicator symbol shown on the physical display around the numeric value:
+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.
 
 | `layout` | Meaning | Sign |
 |---|---|---|
@@ -115,7 +145,7 @@ The `layout` field describes the indicator symbol shown on the physical display
 | `"[data]z"` / `"z[data]"` | Dog-leg symbol — AP off course | positive |
 | `"TBC"` | Symbol seen but not yet identified | positive |
 
-## Debug API
+### Debug API
 
 ```python
 from fastnet_decoder import set_log_level
@@ -128,14 +158,12 @@ fb.get_buffer_size()      # bytes currently in buffer
 fb.get_buffer_contents()  # hex string of buffer contents
 ```
 
-## Companion apps
-
-- [fastnet2ip](https://github.com/ghotihook/fastnet2ip) — reads FastNet from serial and broadcasts it over UDP as either NMEA 0183 or NMEA 2000 (selected with `--output`). Install with `pipx install fastnet2ip`.
-
-Runs on Raspberry Pi, macOS, or Linux.
-
 ## 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.16 → pyfastnet-2.0.18}/fastnet_decoder/__init__.py

@@ -1,7 +1,7 @@
-__version__ = "2.0.16"
+__version__ = "2.0.18"
 
 from .frame_buffer import FrameBuffer
-from .decode_fastnet import decode_frame, decode_ascii_frame
+from .decode_fastnet import decode_frame, decode_ascii_frame, decode_light_frame
 from .logger import logger, set_log_level  # Import set_log_level for user control
 
-__all__ = ["FrameBuffer", "decode_frame", "decode_ascii_frame", "logger", "set_log_level"]
+__all__ = ["FrameBuffer", "decode_frame", "decode_ascii_frame", "decode_light_frame", "logger", "set_log_level"]

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

@@ -1,6 +1,7 @@
 import datetime
+import logging
 from .mappings import ADDRESS_LOOKUP, COMMAND_LOOKUP, CHANNEL_LOOKUP, FORMAT_SIZE_MAP
-from .mappings import SEGMENT_A, SEGMENT_B, AUTOPILOT_MODES
+from .mappings import SEGMENT_A, SEGMENT_B, AUTOPILOT_MODE_BY_LOW, BACKLIGHT_LEVELS
 from .logger import logger
 
 
@@ -109,6 +110,81 @@ def decode_frame(frame: bytes) -> dict:
         return {"error": "Decoding failure"}
 
 
+def probe_frame(frame: bytes) -> None:
+    """
+    Speculatively unpack a non-broadcast frame using the same channel-record
+    assembly as Broadcast frames, for reverse-engineering only.
+
+    The body layout of non-broadcast commands (pilot messages, NMEA-sourced
+    data, etc.) is NOT known to match the Broadcast channel-record format, so
+    everything decoded here is a guess: results are logged at DEBUG and are
+    never queued or assigned to channels. The point is to eyeball whether the
+    same (channel_id, format_byte, data...) structure holds for these frames.
+    """
+    if not logger.isEnabledFor(logging.DEBUG):
+        return
+    try:
+        to_address   = frame[0]
+        from_address = frame[1]
+        command      = frame[3]
+        body         = frame[5:-1]
+
+        to_name   = ADDRESS_LOOKUP.get(to_address,   f"Unknown (0x{to_address:02X})")
+        from_name = ADDRESS_LOOKUP.get(from_address, f"Unknown (0x{from_address:02X})")
+        cmd_name  = COMMAND_LOOKUP.get(command,      f"Unknown (0x{command:02X})")
+
+        logger.debug(
+            f"  PROBE cmd={cmd_name}  {to_name}←{from_name}  body=[{body.hex()}]"
+        )
+
+        index = 0
+        while index < len(body):
+            if index + 1 >= len(body):
+                logger.debug(f"    PROBE trailing byte  [{body[index:].hex()}]")
+                break
+
+            channel_id   = body[index]
+            format_byte  = body[index + 1]
+            channel_name = CHANNEL_LOOKUP.get(channel_id, f"Unknown (0x{channel_id:02X})")
+            index += 2
+
+            data_length = FORMAT_SIZE_MAP.get(format_byte & 0x0F, 0)
+            if data_length == 0:
+                logger.debug(
+                    f"    PROBE 0x{channel_id:02X} {channel_name}  "
+                    f"fmt=0x{format_byte:02X}  unknown format, stop  "
+                    f"remaining=[{body[index:].hex()}]"
+                )
+                break
+            if index + data_length > len(body):
+                logger.debug(
+                    f"    PROBE 0x{channel_id:02X} {channel_name}  "
+                    f"fmt=0x{format_byte:02X}  incomplete  need={data_length}B  "
+                    f"have={len(body) - index}B  remaining=[{body[index:].hex()}]"
+                )
+                break
+
+            data_bytes = body[index:index + data_length]
+            index     += data_length
+
+            decoded = decode_format_and_data(channel_id, format_byte, data_bytes)
+            if decoded:
+                logger.debug(
+                    f"    PROBE 0x{channel_id:02X} {channel_name}  "
+                    f"fmt=0x{format_byte:02X}  data=[{data_bytes.hex()}]  "
+                    f"value={decoded['value']}  display='{decoded['display_text']}'  "
+                    f"layout={decoded['layout']}"
+                )
+            else:
+                logger.debug(
+                    f"    PROBE 0x{channel_id:02X} {channel_name}  "
+                    f"fmt=0x{format_byte:02X}  data=[{data_bytes.hex()}]  (no decode)"
+                )
+
+    except Exception as e:
+        logger.debug(f"  PROBE error: {e}  [{frame.hex()}]")
+
+
 def decode_ascii_frame(frame: bytes) -> dict:
     try:
         to_address   = frame[0]
@@ -158,6 +234,50 @@ def decode_ascii_frame(frame: bytes) -> dict:
         return {"error": str(e)}
 
 
+def decode_light_frame(frame: bytes) -> dict:
+    """
+    Decode a Light Intensity (0xC9) command into the system backlight level.
+
+    Broadcast from a Pilot FFD to the whole system; the body is a single byte
+    giving the backlight level (Off/Low/Medium/High). Surfaced as a synthetic
+    "Backlight" channel so it queues like other channel data.
+    """
+    try:
+        to_address   = frame[0]
+        from_address = frame[1]
+        command      = frame[3]
+        body         = frame[5:-1]
+
+        if len(body) < 1:
+            return {"error": "Invalid body size"}
+
+        level     = body[0]
+        cmd_name  = COMMAND_LOOKUP.get(command)
+        to_name   = ADDRESS_LOOKUP.get(to_address)
+        from_name = ADDRESS_LOOKUP.get(from_address)
+
+        display_text = BACKLIGHT_LEVELS.get(level, f"Unknown ({level})")
+        logger.debug(f"  CH  Backlight  level={level}  display='{display_text}'")
+
+        return {
+            "to_address":   to_name   if to_name   is not None else f"Unknown (0x{to_address:02X})",
+            "from_address": from_name if from_name is not None else f"Unknown (0x{from_address:02X})",
+            "command":      cmd_name  if cmd_name  is not None else f"Unknown (0x{command:02X})",
+            "values": {
+                "Backlight": {
+                    "channel_id":   None,
+                    "value":        float(level),
+                    "display_text": display_text,
+                    "layout":       None,
+                }
+            }
+        }
+
+    except Exception as e:
+        logger.error(f"Error decoding Light Intensity frame: {e}")
+        return {"error": str(e)}
+
+
 def decode_format_and_data(channel_id, format_byte, data_bytes):
     try:
         divisor        = _DIVISOR_MAP[(format_byte >> 6) & 0b11]
@@ -174,8 +294,14 @@ def decode_format_and_data(channel_id, format_byte, data_bytes):
                 return None
             raw = int.from_bytes(data_bytes, byteorder="big", signed=True)
             if channel_id == 0xB5:
-                value        = float(raw)
-                display_text = AUTOPILOT_MODES.get(raw, f"Unknown ({raw})")
+                value     = float(raw)
+                high, low = (raw >> 8) & 0xFF, raw & 0xFF
+                if high == 0x50:
+                    display_text = "Standby"
+                elif high in (0x51, 0x59):
+                    display_text = AUTOPILOT_MODE_BY_LOW.get(low, f"Unknown ({raw})")
+                else:
+                    display_text = f"Unknown ({raw})"
             else:
                 value        = raw / divisor
                 display_text = f"{value:.{decimal_places}f}"

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

@@ -1,7 +1,7 @@
 import logging
 from .utils import calculate_checksum
 from .mappings import COMMAND_LOOKUP, IGNORED_COMMANDS
-from .decode_fastnet import decode_frame, decode_ascii_frame
+from .decode_fastnet import decode_frame, decode_ascii_frame, decode_light_frame, probe_frame
 from .logger import logger
 from queue import Queue, Full
 
@@ -84,9 +84,25 @@ class FrameBuffer:
             self.decode_and_queue_frame(frame, command_name)
 
     def decode_and_queue_frame(self, frame, command_name):
-        """Decode a frame and add it to the queue if valid."""
-        decoder = decode_ascii_frame if command_name == "LatLon" else decode_frame
-        decoded_frame = decoder(frame)
+        """
+        Decode a frame and add it to the queue if valid.
+
+        Broadcast frames carry the channel-record body layout, LatLon frames
+        carry ASCII, and Light Intensity frames carry a backlight level byte;
+        those are decoded and queued. Every other command (pilot messages,
+        NMEA-sourced data, etc.) has an unknown body structure, so it is never
+        queued — it is only probed speculatively for debugging.
+        """
+        if command_name == "Broadcast":
+            decoded_frame = decode_frame(frame)
+        elif command_name == "LatLon":
+            decoded_frame = decode_ascii_frame(frame)
+        elif command_name == "Light Intensity":
+            decoded_frame = decode_light_frame(frame)
+        else:
+            probe_frame(frame)
+            return
+
         if decoded_frame and "values" in decoded_frame:
             try:
                 self.frame_queue.put_nowait(decoded_frame)

{pyfastnet-2.0.16 → pyfastnet-2.0.18}/fastnet_decoder/mappings.py

@@ -146,7 +146,10 @@ ADDRESS_LOOKUP = {
 }
 
 
-IGNORED_COMMANDS = {"Keep Alive", "Light Intensity"}
+IGNORED_COMMANDS = {"Keep Alive"}
+
+# Backlight level carried in the 1-byte body of a Light Intensity (0xC9) command.
+BACKLIGHT_LEVELS = {0x00: "Off", 0x01: "Low", 0x02: "Medium", 0x04: "High"}
 
 COMMAND_LOOKUP = {
     0x01: "Broadcast",
@@ -323,9 +326,12 @@ SEGMENT_B = {
     0xB8: "C",   # Celsius label — a,d,e,f segments
 }
 
-AUTOPILOT_MODES = {
-    20484: "Standby", 20737: "Compass", 20738: "Power",
-    20740: "Wind",    20755: "NMEA WP",
+# Autopilot Mode (channel 0xB5) is a 16-bit composite, not an opaque code:
+#   high byte = engagement state  (0x50 standby, 0x51 engaged, 0x59 compass steering)
+#   low  byte = selected mode     (see AUTOPILOT_MODE_BY_LOW)
+# When in standby (high 0x50) the mode is "Standby" regardless of the low byte.
+AUTOPILOT_MODE_BY_LOW = {
+    0x01: "Compass", 0x02: "Power", 0x04: "Wind", 0x13: "NMEA WP",
 }
 
 FORMAT_SIZE_MAP = {

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyfastnet
-Version: 2.0.16
+Version: 2.0.18
 Summary: A Python library for decoding FastNet protocol data streams.
 Author-email: Alex Salmon <alex@ivila.net>
 License: MIT License
@@ -52,20 +52,20 @@ Dynamic: license-file
 
 # pyfastnet
 
-Python library for decoding the FastNet protocol used by B&G Hydra/H2000 instruments. Developed for personal use and published for general interest.
+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.
 
-## Purpose
+Developed for personal use and published for general interest. Runs on Raspberry
+Pi, macOS, or Linux.
 
-Feed a raw byte stream from a FastNet bus into the library. It handles synchronisation, checksum validation, and decoding — returning structured instrument data ready for further processing.
+## Quick start
 
-## Installation
-
-```
+```bash
 pip install pyfastnet
 ```
 
-## Example usage
-
 ```python
 #!/usr/bin/env python3
 import serial
@@ -97,9 +97,36 @@ 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 named instrument channels. | 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`. Each entry in `values` is keyed by channel name:
+Each decoded frame is a dict with `to_address`, `from_address`, `command`, and
+`values`. Each entry in `values` is keyed by channel name:
 
 ```python
 {
@@ -131,10 +158,10 @@ Each decoded frame is a dict with `to_address`, `from_address`, `command`, and `
 
 ### Position (LatLon) frames
 
-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:
+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:
 
 ```python
 "LatLon": {
@@ -147,7 +174,10 @@ string (`DDMM.mmm` with hemisphere letters) is carried in `display_text`; `value
 
 ### Layout field
 
-The `layout` field describes the indicator symbol shown on the physical display around the numeric value:
+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.
 
 | `layout` | Meaning | Sign |
 |---|---|---|
@@ -167,7 +197,7 @@ The `layout` field describes the indicator symbol shown on the physical display
 | `"[data]z"` / `"z[data]"` | Dog-leg symbol — AP off course | positive |
 | `"TBC"` | Symbol seen but not yet identified | positive |
 
-## Debug API
+### Debug API
 
 ```python
 from fastnet_decoder import set_log_level
@@ -180,14 +210,12 @@ fb.get_buffer_size()      # bytes currently in buffer
 fb.get_buffer_contents()  # hex string of buffer contents
 ```
 
-## Companion apps
-
-- [fastnet2ip](https://github.com/ghotihook/fastnet2ip) — reads FastNet from serial and broadcasts it over UDP as either NMEA 0183 or NMEA 2000 (selected with `--output`). Install with `pipx install fastnet2ip`.
-
-Runs on Raspberry Pi, macOS, or Linux.
-
 ## 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.16 → pyfastnet-2.0.18}/pyfastnet.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ pyfastnet.egg-info/top_level.txt
 tests/test_autopilot.py
 tests/test_awa.py
 tests/test_aws.py
+tests/test_backlight.py
 tests/test_battery.py
 tests/test_boatspeed.py
 tests/test_depth_frame.py

{pyfastnet-2.0.16 → pyfastnet-2.0.18}/tests/test_autopilot.py

@@ -70,5 +70,38 @@ class TestAutopilotWind(unittest.TestCase):
         self.assertEqual(self.v["Autopilot Compass Target"]["display_text"], "331°M")
 
 
+class TestAutopilotModeComposite(unittest.TestCase):
+    """
+    Autopilot Mode (0xB5) is a 16-bit composite: high byte = engagement state
+    (0x50 standby / 0x51 engaged / 0x59 compass steering), low byte = selected
+    mode. These real frames cover values that previously decoded as Unknown.
+    """
+
+    def _mode(self, frame):
+        return _decode(frame)["Autopilot Mode"]["display_text"]
+
+    def test_compass_standby(self):
+        # 0x5001 — standby, Compass selected
+        self.assertEqual(
+            self._mode("ff121c01d2b5015001a606bee8e800af06bee8e8005306bee8e8007606bee8e8008b"),
+            "Standby",
+        )
+
+    def test_power_standby(self):
+        # 0x5002 — standby, Power selected
+        self.assertEqual(
+            self._mode("ff121c01d2b5015002a606bee8e800af06bee8e8005306bee8e8007606bee8e8008a"),
+            "Standby",
+        )
+
+    def test_power_engaged(self):
+        # 0x5102 — engaged, Power
+        self.assertEqual(self._mode("ff120a01e4b5015102a6070066012eb5"), "Power")
+
+    def test_compass_steering(self):
+        # 0x5901 — compass engaged and actively steering to a heading
+        self.assertEqual(self._mode("ff120a01e4b5015901a60700660124b8"), "Compass")
+
+
 if __name__ == "__main__":
     unittest.main()

pyfastnet-2.0.18/tests/test_backlight.py

@@ -0,0 +1,42 @@
+import unittest
+from fastnet_decoder.frame_buffer import FrameBuffer
+
+
+def _decode(hex_str):
+    """Feed a raw frame through the buffer and return the queued decoded frame."""
+    fb = FrameBuffer()
+    fb.add_to_buffer(bytes.fromhex(hex_str))
+    fb.get_complete_frames()
+    assert not fb.frame_queue.empty(), f"No frame queued for {hex_str}"
+    return fb.frame_queue.get_nowait()
+
+
+class TestBacklight(unittest.TestCase):
+    """
+    Light Intensity command (0xC9), broadcast 0x50 -> 0xFF, 1-byte body giving
+    the system backlight level. Real frames captured while toggling the FFD
+    backlight off/low/med/high.
+    """
+
+    CASES = {
+        "ff5001c9e70000": ("Off", 0.0),
+        "ff5001c9e701ff": ("Low", 1.0),
+        "ff5001c9e702fe": ("Medium", 2.0),
+        "ff5001c9e704fc": ("High", 4.0),
+    }
+
+    def test_levels(self):
+        for frame, (text, value) in self.CASES.items():
+            with self.subTest(frame=frame):
+                decoded = _decode(frame)
+                bl = decoded["values"]["Backlight"]
+                self.assertEqual(bl["display_text"], text)
+                self.assertEqual(bl["value"], value)
+
+    def test_command_name(self):
+        decoded = _decode("ff5001c9e70000")
+        self.assertEqual(decoded["command"], "Light Intensity")
+
+
+if __name__ == "__main__":
+    unittest.main()