pyixblue 0.9.1__tar.gz

pyixblue-0.9.1/.github/workflows/publish.yml

@@ -0,0 +1,94 @@
+# PyPI publish — OIDC Trusted Publishing.
+#
+# First publish: register a pending publisher at
+# https://pypi.org/manage/account/publishing/ with claims matching THIS file:
+#   Owner=TTCMarine  Repository=pyixblue  Workflow=publish.yml  Environment=pypi
+# Without it the publish step fails `invalid-publisher`.
+
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"            # release on a version tag only — never on ordinary pushes
+
+permissions: {}        # least privilege: grant per-job below
+
+concurrency:           # never let two tag pushes publish the same project at once
+  group: pypi-publish-${{ github.repository }}
+  cancel-in-progress: false   # let an in-flight publish finish; queue the next
+
+jobs:
+  build:
+    name: Build + audit (locked)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: false
+
+      - name: Sync locked environment
+        run: uv sync --locked --no-dev
+
+      - name: Audit dependencies
+        run: uvx pip-audit --progress-spinner off
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Validate artifacts (PyPI ingestion check)
+        run: uvx twine check dist/*
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI (trusted publishing)
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write       # OIDC for trusted publishing — the only elevated grant
+      contents: read
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          attestations: true   # PEP 740 signed provenance
+
+  verify:
+    name: Verify on PyPI
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Confirm version is queryable on PyPI
+        env:
+          DIST_NAME: "pyixblue"
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          echo "Verifying ${DIST_NAME}==${version} is live on PyPI..."
+          for attempt in 1 2 3 4 5; do
+            if curl -fsS "https://pypi.org/pypi/${DIST_NAME}/${version}/json" >/dev/null; then
+              echo "OK ${DIST_NAME}==${version} is live"
+              exit 0
+            fi
+            echo "  attempt ${attempt}: not visible yet, waiting 15s..."
+            sleep 15
+          done
+          echo "FAIL ${DIST_NAME}==${version} not visible after 75s"
+          exit 1

pyixblue-0.9.1/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Test and tool caches
+.pytest_cache/

pyixblue-0.9.1/.python-version

@@ -0,0 +1 @@
+3.14

pyixblue-0.9.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pyixblue contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyixblue-0.9.1/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: pyixblue
+Version: 0.9.1
+Summary: Python parser for the iXblue stdbin protocol
+License: MIT License
+        
+        Copyright (c) 2026 pyixblue contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pyixblue
+
+Python parser for the iXblue stdbin output protocol (versions 2 through 5).
+
+stdbin is the binary navigation output of iXblue inertial systems. This package
+reassembles and decodes those frames. It does not open a socket or a serial
+port; pass in the bytes you receive over UDP, TCP, or serial.
+
+The block layout and checksum follow the MIT-licensed
+[ixblue_stdbin_decoder](https://github.com/ixblue/ixblue_stdbin_decoder).
+
+## Install
+
+```sh
+pip install .
+```
+
+From a checkout, with the development tests:
+
+```sh
+uv sync
+```
+
+## Usage
+
+```python
+from pyixblue import StdBinDecoder
+
+decoder = StdBinDecoder()
+decoder.add_new_data(chunk)  # bytes-like; a chunk may be a partial frame
+while decoder.parse_next_frame():  # False when more bytes are needed
+    header = decoder.last_header
+    if header.message_type == "nav":
+        nav = decoder.last_nav  # missing blocks are None
+        if nav.position is not None:
+            print(nav.position.latitude_deg, nav.position.longitude_deg)
+    else:
+        payload = decoder.last_answer
+```
+
+`parse_next_frame` raises `StdBinError` when a frame is recognized but its
+protocol version or checksum is invalid. The decoder drops the bad version
+byte, or the whole frame after a bad checksum, so the next call can resync.
+
+Navigation, extended-navigation, and external-sensor blocks are present only
+when their mask bit is set. INS algorithm and system status words are `IntFlag`
+values (`1 << bit`), so they compare equal to the raw integer:
+
+```python
+from pyixblue.models import InsAlgorithmStatus1
+
+if nav.ins_algorithm_status is not None:
+    status = nav.ins_algorithm_status.status1
+    if InsAlgorithmStatus1.NAVIGATION in status:
+        print(hex(status))
+```
+
+## Protocol
+
+Supported output frames:
+
+| Kind | Magic | Versions |
+| --- | --- | --- |
+| Navigation | `IX` | 2, 3, 4, 5 |
+| Answer | `AN` | 3, 4, 5 |
+
+Multi-byte fields are big-endian. The checksum is the low 32 bits of the sum of
+every preceding byte, stored as a big-endian `uint32`.
+
+Version 3 adds the extended-navigation mask. Versions 4 and 5 add the
+navigation-data size. The header also keeps the frame `counter`, which the
+reference C++ header discards.
+
+## License
+
+MIT. Sample frames under `tests/fixtures/` were converted from the
+ixblue_stdbin_decoder test logs (MIT, Copyright (c) 2019 iXblue SAS).

pyixblue-0.9.1/README.md

@@ -0,0 +1,77 @@
+# pyixblue
+
+Python parser for the iXblue stdbin output protocol (versions 2 through 5).
+
+stdbin is the binary navigation output of iXblue inertial systems. This package
+reassembles and decodes those frames. It does not open a socket or a serial
+port; pass in the bytes you receive over UDP, TCP, or serial.
+
+The block layout and checksum follow the MIT-licensed
+[ixblue_stdbin_decoder](https://github.com/ixblue/ixblue_stdbin_decoder).
+
+## Install
+
+```sh
+pip install .
+```
+
+From a checkout, with the development tests:
+
+```sh
+uv sync
+```
+
+## Usage
+
+```python
+from pyixblue import StdBinDecoder
+
+decoder = StdBinDecoder()
+decoder.add_new_data(chunk)  # bytes-like; a chunk may be a partial frame
+while decoder.parse_next_frame():  # False when more bytes are needed
+    header = decoder.last_header
+    if header.message_type == "nav":
+        nav = decoder.last_nav  # missing blocks are None
+        if nav.position is not None:
+            print(nav.position.latitude_deg, nav.position.longitude_deg)
+    else:
+        payload = decoder.last_answer
+```
+
+`parse_next_frame` raises `StdBinError` when a frame is recognized but its
+protocol version or checksum is invalid. The decoder drops the bad version
+byte, or the whole frame after a bad checksum, so the next call can resync.
+
+Navigation, extended-navigation, and external-sensor blocks are present only
+when their mask bit is set. INS algorithm and system status words are `IntFlag`
+values (`1 << bit`), so they compare equal to the raw integer:
+
+```python
+from pyixblue.models import InsAlgorithmStatus1
+
+if nav.ins_algorithm_status is not None:
+    status = nav.ins_algorithm_status.status1
+    if InsAlgorithmStatus1.NAVIGATION in status:
+        print(hex(status))
+```
+
+## Protocol
+
+Supported output frames:
+
+| Kind | Magic | Versions |
+| --- | --- | --- |
+| Navigation | `IX` | 2, 3, 4, 5 |
+| Answer | `AN` | 3, 4, 5 |
+
+Multi-byte fields are big-endian. The checksum is the low 32 bits of the sum of
+every preceding byte, stored as a big-endian `uint32`.
+
+Version 3 adds the extended-navigation mask. Versions 4 and 5 add the
+navigation-data size. The header also keeps the frame `counter`, which the
+reference C++ header discards.
+
+## License
+
+MIT. Sample frames under `tests/fixtures/` were converted from the
+ixblue_stdbin_decoder test logs (MIT, Copyright (c) 2019 iXblue SAS).

pyixblue-0.9.1/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "pyixblue"
+version = "0.9.1"
+description = "Python parser for the iXblue stdbin protocol"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pyixblue-0.9.1/src/pyixblue/__init__.py

@@ -0,0 +1,15 @@
+"""Parse iXblue stdbin navigation and answer frames."""
+
+from pyixblue.decoder import StdBinDecoder
+from pyixblue.errors import StdBinError
+from pyixblue.models import MessageType, NavData, NavHeader
+
+__all__ = [
+    "MessageType",
+    "NavData",
+    "NavHeader",
+    "StdBinDecoder",
+    "StdBinError",
+]
+
+__version__ = "0.9.1"

pyixblue-0.9.1/src/pyixblue/blocks.py

@@ -0,0 +1,242 @@
+"""Declarative stdbin memory-block table.
+
+Sizes and bit positions match the reference ``MemoryBlockParser`` constructors.
+Blocks are stored in bit order, which is the order they are packed on the wire.
+Logbook is the 40 bytes the reference parser actually reads (``int32``,
+``uint32``, and 32 text bytes), not the 12-byte guard declared on that parser.
+``vehicle_attitude_heading_deviation`` is included even though the reference
+decoder constructs no parser for it, so a set extended-mask bit 4 is consumed.
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass, fields
+from struct import calcsize
+from typing import Any
+
+from pyixblue.models import (
+    AccelerationGeographicFrame,
+    AccelerationVesselFrame,
+    AccelerationVesselFrameDeviation,
+    AhrsAlgorithmStatus,
+    AhrsSystemStatus,
+    AhrsUserStatus,
+    AttitudeHeading,
+    AttitudeHeadingDeviation,
+    AttitudeQuaternion,
+    AttitudeQuaternionDeviation,
+    CourseSpeedOverGround,
+    CurrentGeographicFrame,
+    CurrentGeographicFrameDeviation,
+    Depth,
+    Dmi,
+    DvlGroundSpeed,
+    DvlWaterSpeed,
+    Emlog,
+    EventMarker,
+    Gnss,
+    HeadingRollPitchRate,
+    HeaveSurgeSwaySpeed,
+    InsAlgorithmStatus,
+    InsAlgorithmStatus1,
+    InsAlgorithmStatus2,
+    InsAlgorithmStatus3,
+    InsAlgorithmStatus4,
+    InsSystemStatus,
+    InsSystemStatus1,
+    InsSystemStatus2,
+    InsSystemStatus3,
+    InsUserStatus,
+    Lbl,
+    LogBook,
+    Position,
+    PositionDeviation,
+    RawAccelerationVesselFrame,
+    RawRotationRateVesselFrame,
+    RealTimeHeaveSurgeSway,
+    RotationAccelerationVesselFrame,
+    RotationAccelerationVesselFrameDeviation,
+    RotationRateVesselFrame,
+    RotationRateVesselFrameDeviation,
+    SensorStatus,
+    SmartHeave,
+    SoundVelocity,
+    SpeedGeographicFrame,
+    SpeedGeographicFrameDeviation,
+    SpeedVesselFrame,
+    SystemDate,
+    Temperatures,
+    TurretAngles,
+    Usbl,
+    Utc,
+    VehicleAttitudeHeading,
+    VehicleAttitudeHeadingDeviation,
+    VehiclePosition,
+    VehiclePositionDeviation,
+    Vtg,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Block:
+    """One optional memory block identified by a mask bit."""
+
+    field: str
+    bit: int
+    fmt: str
+    build: Callable[[tuple[Any, ...]], Any]
+
+    @property
+    def size(self) -> int:
+        return calcsize(self.fmt)
+
+
+def _build(
+    cls: type[Any], converters: tuple[Callable[[int], Any] | None, ...] = ()
+) -> Callable[[tuple[Any, ...]], Any]:
+    names = tuple(item.name for item in fields(cls))
+
+    def build(values: tuple[Any, ...]) -> Any:
+        converted: list[Any] = []
+        for index, value in enumerate(values):
+            converter = converters[index] if index < len(converters) else None
+            converted.append(converter(value) if converter is not None else value)
+        return cls(**dict(zip(names, converted, strict=True)))
+
+    return build
+
+
+def _block(
+    field: str,
+    bit: int,
+    fmt: str,
+    cls: type[Any],
+    converters: tuple[Callable[[int], Any] | None, ...] = (),
+) -> Block:
+    return Block(field, bit, fmt, _build(cls, converters))
+
+
+def _sorted(blocks: tuple[Block, ...]) -> tuple[Block, ...]:
+    return tuple(sorted(blocks, key=lambda block: block.bit))
+
+
+NAVIGATION_BLOCKS = _sorted(
+    (
+        _block("attitude_heading", 0, ">fff", AttitudeHeading),
+        _block("attitude_heading_deviation", 1, ">fff", AttitudeHeadingDeviation),
+        _block("rt_heave_surge_sway", 2, ">ffff", RealTimeHeaveSurgeSway),
+        _block("smart_heave", 3, ">If", SmartHeave),
+        _block("heading_roll_pitch_rate", 4, ">fff", HeadingRollPitchRate),
+        _block("rotation_rate_vessel_frame", 5, ">fff", RotationRateVesselFrame),
+        _block("acceleration_vessel_frame", 6, ">fff", AccelerationVesselFrame),
+        _block("position", 7, ">ddBf", Position),
+        _block("position_deviation", 8, ">ffff", PositionDeviation),
+        _block("speed_geographic_frame", 9, ">fff", SpeedGeographicFrame),
+        _block("speed_geographic_frame_deviation", 10, ">fff", SpeedGeographicFrameDeviation),
+        _block("current_geographic_frame", 11, ">ff", CurrentGeographicFrame),
+        _block("current_geographic_frame_deviation", 12, ">ff", CurrentGeographicFrameDeviation),
+        _block("system_date", 13, ">BBH", SystemDate),
+        _block("sensor_status", 14, ">II", SensorStatus),
+        _block(
+            "ins_algorithm_status",
+            15,
+            ">IIII",
+            InsAlgorithmStatus,
+            (
+                InsAlgorithmStatus1,
+                InsAlgorithmStatus2,
+                InsAlgorithmStatus3,
+                InsAlgorithmStatus4,
+            ),
+        ),
+        _block(
+            "ins_system_status",
+            16,
+            ">III",
+            InsSystemStatus,
+            (InsSystemStatus1, InsSystemStatus2, InsSystemStatus3),
+        ),
+        _block("ins_user_status", 17, ">I", InsUserStatus),
+        _block("ahrs_algorithm_status", 18, ">I", AhrsAlgorithmStatus),
+        _block("ahrs_system_status", 19, ">III", AhrsSystemStatus),
+        _block("ahrs_user_status", 20, ">I", AhrsUserStatus),
+        _block("heave_surge_sway_speed", 21, ">fff", HeaveSurgeSwaySpeed),
+        _block("speed_vessel_frame", 22, ">fff", SpeedVesselFrame),
+        _block("acceleration_geographic_frame", 23, ">fff", AccelerationGeographicFrame),
+        _block("course_speed_over_ground", 24, ">ff", CourseSpeedOverGround),
+        _block("temperatures", 25, ">fff", Temperatures),
+        _block("attitude_quaternion", 26, ">ffff", AttitudeQuaternion),
+        _block("attitude_quaternion_deviation", 27, ">fff", AttitudeQuaternionDeviation),
+        _block("raw_acceleration_vessel_frame", 28, ">fff", RawAccelerationVesselFrame),
+        _block(
+            "acceleration_vessel_frame_deviation",
+            29,
+            ">fff",
+            AccelerationVesselFrameDeviation,
+        ),
+        _block(
+            "rotation_rate_vessel_frame_deviation",
+            30,
+            ">fff",
+            RotationRateVesselFrameDeviation,
+        ),
+    )
+)
+
+EXTENDED_BLOCKS = _sorted(
+    (
+        _block(
+            "rotation_acceleration_vessel_frame",
+            0,
+            ">fff",
+            RotationAccelerationVesselFrame,
+        ),
+        _block(
+            "rotation_acceleration_vessel_frame_deviation",
+            1,
+            ">fff",
+            RotationAccelerationVesselFrameDeviation,
+        ),
+        _block("raw_rotation_rate_vessel_frame", 2, ">fff", RawRotationRateVesselFrame),
+        _block("vehicle_attitude_heading", 3, ">fff", VehicleAttitudeHeading),
+        _block(
+            "vehicle_attitude_heading_deviation",
+            4,
+            ">fff",
+            VehicleAttitudeHeadingDeviation,
+        ),
+        _block("vehicle_position", 5, ">ddBf", VehiclePosition),
+        _block("vehicle_position_deviation", 6, ">ffff", VehiclePositionDeviation),
+    )
+)
+
+EXTERNAL_BLOCKS = _sorted(
+    (
+        _block("utc", 0, ">IB", Utc),
+        _block("gnss1", 1, ">iBBddffffff", Gnss),
+        _block("gnss2", 2, ">iBBddffffff", Gnss),
+        _block("gnss_manual", 3, ">iBBddffffff", Gnss),
+        _block("emlog1", 4, ">iBff", Emlog),
+        _block("emlog2", 5, ">iBff", Emlog),
+        _block("usbl1", 6, ">iB8sddfffff", Usbl),
+        _block("usbl2", 7, ">iB8sddfffff", Usbl),
+        _block("usbl3", 8, ">iB8sddfffff", Usbl),
+        _block("depth", 9, ">iff", Depth),
+        _block("dvl_ground_speed1", 10, ">iBffffffff", DvlGroundSpeed),
+        _block("dvl_water_speed1", 11, ">iBfffffff", DvlWaterSpeed),
+        _block("sound_velocity", 12, ">if", SoundVelocity),
+        _block("dmi", 13, ">ii", Dmi),
+        _block("lbl1", 14, ">iB8sddfff", Lbl),
+        _block("lbl2", 15, ">iB8sddfff", Lbl),
+        _block("lbl3", 16, ">iB8sddfff", Lbl),
+        _block("lbl4", 17, ">iB8sddfff", Lbl),
+        _block("event_marker_a", 18, ">iBI", EventMarker),
+        _block("event_marker_b", 19, ">iBI", EventMarker),
+        _block("event_marker_c", 20, ">iBI", EventMarker),
+        _block("dvl_ground_speed2", 21, ">iBffffffff", DvlGroundSpeed),
+        _block("dvl_water_speed2", 22, ">iBfffffff", DvlWaterSpeed),
+        _block("turret_angles", 24, ">ifff", TurretAngles),
+        _block("vtg1", 25, ">iBfff", Vtg),
+        _block("vtg2", 26, ">iBfff", Vtg),
+        _block("log_book", 27, ">iI32s", LogBook),
+    )
+)