docs

unetpy Documentation

unetpy is the Python gateway for UnetStack, providing a simple and intuitive API for communicating with underwater acoustic modems and simulators. It wraps the low-level fjagepy primitives and adds UnetStack-specific functionality.

Table of Contents

• Installation
• Quick Start
• API Reference
  • UnetSocket - High-level socket interface
  • Constants - Protocol numbers and service identifiers
  • Messages - Pre-defined message classes
  • Utilities - Coordinate conversion functions

Note: API documentation in docs/api/ is auto-generated from source code docstrings. To regenerate, run: python docs/generate_api_docs.py

Features

• High-level UnetSocket API - Simple socket-like interface for sending and receiving datagrams
• Socket-level send metadata - Configure TTL, priority, reliability, route, MIME type, mailbox, and remote recipients once and reuse them across sends
• Provider and send-mode control - Override the service provider when needed and choose non-blocking, semi-blocking, or blocking send behavior
• Full fjåge compatibility - All fjåge primitives are re-exported for low-level access
• Pre-defined message classes - All UnetStack messages available as direct imports (DatagramReq, DatagramNtf, etc.)
• Coordinate utilities - Convert between GPS and local coordinates
• Context manager support - Use with statements for automatic cleanup

Basic Example

from unetpy import UnetSocket, Protocol

# Connect to a UnetStack node
with UnetSocket("localhost", 1100) as sock:
    # Bind to user protocol
    sock.bind(Protocol.USER)

    # Send data to node 31
    sock.send([1, 2, 3], to=31, protocol=Protocol.USER)

    # Receive with timeout
    sock.setTimeout(5000)
    ntf = sock.receive()
    if ntf:
        print(f"Received: {ntf.data}")