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).
