Name: AISMixer
Author: Iliyan Iliev

AIS stream processing

From receiver traffic to a clean, source-aware feed

AISMixer keeps transport, NMEA assembly, metadata, deduplication, and delivery in one near-real-time processing path. The AISMixer ecosystem combines the aismixer stream-processing and routing service, nmea_sproxy, aismixerctl, secure transport, deployment tooling, and related components.

Flexible ingress

Receive plain UDP over IPv4 or IPv6, or authenticated encrypted UDPSEC station traffic.

AIS sentence extraction

Extract both !AIVDM and !AIVDO from realistic receiver and application output.

Multipart assembly

Assemble fully out-of-order fragments into complete logical messages and emit them in ordinal order.

Near-real-time deduplication

Make one group-atomic decision for each complete multipart message, globally in broadcast mode or separately for each routing target.

Controlled TAG metadata

Control NMEA TAG s, c, and g across the multipart lifecycle while keeping metadata separate from routing identity.

Selected forwarding

Forward accepted sentences to every configured UDP output in broadcast mode or to the named targets selected by logical routing.

Project explainer

How AISMixer works

A short visual walkthrough from multiple AIS sources through assembly, deduplication, TAG handling, and logical routing to selected outputs, including nmea_sproxy and UDPSEC. The explainer is in English.

Campaign C–F native-ready data-plane foundation

Explicit processing, bounded stages, and unified egress

Immutable bytes-based ingress moves through bounded, explicit single-process stages. After shared processing capacity becomes available, each admitted frame is bound to one ProcessingSnapshot and handled by the instance-owned PythonDataPlaneProcessor—the sole current production and reference processor. It returns one ordered immutable OutputBatch whose ProcessorOutput values carry exact bytes and numeric target IDs through the bounded egress handoff.

UDP / UDPSEC producers Private bounded IngressFrame queue per input

Bounded processing admission Backpressure, then bind one ProcessingSnapshot

Instance-owned PythonDataPlaneProcessor Bytes scan, assembly, TAG policy, and deduplication

Bounded ordered OutputBatch handoff Exact bytes and explicit numeric targets

Unified UDP egress Sequential local dispatch through send_to_ids()

Immutable ingress boundary

Built-in UDP and UDPSEC producers create immutable bytes-based IngressFrame objects. Bytes-native scanning and parse-once ParsedSentence metadata carry fragment and TAG information into processing without repeated extraction.

Capacity-safe snapshot admission

Processing capacity is obtained before one immutable ProcessingSnapshot is bound to the frame. Admitted work keeps that snapshot; frames still waiting for capacity may observe a later process-local routing replacement.

Instance-owned Python processor

One long-lived PythonDataPlaneProcessor owns mutable assembler, deduplication, source, multipart-metadata, and processor-metric state. No native processor or binding exists today.

Exact bytes in ordered results

Each emitted NMEA sentence is encoded as UTF-8 once and becomes one exact immutable payload in an ordered OutputBatch. Every ProcessorOutput carries explicit numeric target IDs; multipart fragments remain separate payloads.

Backpressure and ordered completion

A full private-ingress, shared-processing, or egress boundary waits instead of dropping its queued item. A non-empty batch prevents later-frame processing until sequential local dispatch completes. This is neither durability nor remote delivery acknowledgement, and UDP remains lossy.

Process-local fail-fast lifecycle

Essential asyncio stages share one supervised lifecycle within the current process. Failure or unexpected completion cancels and awaits sibling tasks; there is no automatic restart, retry, rollback, delivery acknowledgement, or replay.

Need the exact edge-case semantics? Read the behavioural contract.

Explicit lifecycle ownership

Deterministic state under load

The reference implementation makes retained state, lifetime progress, capacity admission, cleanup, and observation explicit instead of relying on incidental container behaviour.

Deduplication state

Identity is the exact sentence or ordered multipart tuple, in a global or per-target scope. TTL is deterministic, duplicates do not refresh retention, and expired entries are removed before the oldest live entry is evicted.

The Python object accepts optional max_entries; current service wiring leaves it at None, so this dimension is unbounded in the current service.

Multipart assembly state

Fragments occupy ordinal slots. Unique progress refreshes group lifetime; an exact duplicate does not. Conflict, expiry, capacity removal, completion, and reset remain distinct lifecycle outcomes and clean related TAG context.

The Python object accepts optional max_fragments_per_group and max_pending_groups; current service wiring leaves both at None.

Secure replay and sessions

Handshake replay records, pending sessions, active sessions, and each session's private DATA-nonce replay ledger are hard-bounded. Handshake and session lifetimes use monotonic TTLs. Every admitted DATA nonce is instead retained for the full usable directional traffic-key epoch, has no independent TTL, and is not evicted while that epoch remains usable. Exhaustion fails closed for that key epoch; recovery uses a fresh authenticated handshake with fresh directional keys.

A pending candidate replaces only an older candidate for the same physical-listener/peer relation and preserves any active session until authenticated encrypted confirmation succeeds. Sessions from the same peer on separate physical UDPSEC listeners are isolated from one another; aggregate capacity budgets remain process-wide. All secure state is in-memory, process-local, and lost at restart.

Observable component and runtime state

Deduplication, assembly, and secure owners expose immutable internal lifecycle snapshots. The runtime separately offers fresh pull-based views of queues, processor and egress activity, and input and output traffic. Reading either kind of snapshot does not mutate processing state.

These views are process-local and non-durable; they are not distributed metrics or a Prometheus/time-series export system.

Local by design. This state is non-durable and is not shared across processes. The current runtime supervises essential asyncio tasks within one process; coordinator/worker processes, IPC, and cross-process state synchronization do not exist yet.

Campaign F — implemented

Worker-ready boundaries in one process

Campaign F completed bounded, observable boundaries around the current Python runtime. Mutable processing state has an explicit instance owner, work is admitted only when capacity is available, and fresh pull-based statistics make stage activity visible without changing it.

Private bounded ingress

Every configured UDP or UDPSEC input has its own bounded queue, keeping one input’s queued backlog from consuming another input’s private capacity.

Capacity-safe admission

Shared processing admission is bounded. A frame receives its immutable ProcessingSnapshot only after capacity is obtained, and a full stage waits with backpressure.

Processor-instance ownership

One processor instance owns mutable assembly, deduplication, source, multipart-metadata, and processor-metric state behind an explicit lifecycle boundary.

Bounded ordered egress

A bounded handoff carries each non-empty OutputBatch to sequential local dispatch. The completion barrier preserves processing order but is not remote receipt.

Pull-based runtime observability

Fresh immutable snapshots cover queue and backpressure state, processor and egress activity, raw and admitted input traffic, and per-target output messages and bytes.

Worker Readiness is implemented; workers are not. The current service still has one process with supervised asyncio stages. There is no coordinator, separate ingress or egress worker process, multiprocessing, IPC, cross-process routing or metrics aggregation, or automatic worker restart and recovery. No native processor or bindings exist today.

Routing and logical zones

Express stream policy with source identities

Static logical routing connects named ingress sources to named UDP egress targets through reusable source sets and ordered routes. Names remain the configuration and control interface, while production matching uses a precompiled numeric target-only plan.

Named ingressUDP and UDPSEC sources

Logical zonesSets of source identities

Ordered routesDeclarative target selection

Named egressSelected UDP targets

Composable source sets

Define zones with include, union, intersection, and difference.

Logical, not geographic

Zones are sets of internal source identities—not map areas, MMSI filters, vessel filters, or payload rules.

Preserved order and per-target quality

The compiled plan preserves declared target order. Routing mode scopes deduplication to each logical target, so one dispatch path does not suppress another.

Names stay operator-facing. Process-local numeric target IDs are not configuration values. source_id remains separate from the NMEA TAG s value emitted downstream.

Local control and runtime observability

Control routing and inspect runtime activity

The optional local POSIX Unix-domain control plane exposes routing operations and read-only aggregate, per-input, and per-output runtime statistics through the globally installed aismixerctl command.

Routing status and atomic changes

Inspect the active generation, zones, routes, and targets; replace a validated snapshot or disable routing to return to legacy broadcast mode. Optional generation checks reject stale updates.

Aggregate runtime statistics

runtime.statistics reports bounded queue and backpressure state, processor activity, and egress activity in one fresh process-local pull.

Input and output traffic

runtime.statistics.inputs separates transport traffic from accepted frames. runtime.statistics.outputs reports per-target local dispatches, messages, and bytes.

Local operator interface

Use aismixerctl for local routing changes and read-only runtime inspection, with human-readable output for operators and JSON output for one-shot automation.

Read-only statistics boundary. Statistics are in-memory, process-local, non-durable, and reset at restart. They are not persistent history, distributed metrics, or a Prometheus/time-series system. Successful local UDP dispatch is not remote delivery acknowledgement.

Deliberately local control. Runtime routes are not persisted after restart, configuration files are not rewritten, and adapters are not created dynamically. Unix socket permissions are the current authorization boundary; there is no application-level control token.

Network endpoint controls

Constrain peers and outbound source addresses

Small application-level controls make IPv4 and IPv6 endpoints easier to place inside an operator’s wider firewall and routing policy.

Ingress allow_from

Restrict UDP and UDPSEC listeners to literal IP addresses or CIDR networks, with explicit deny-all behavior available.

Outbound source_ip

Bind an egress socket to a literal IPv4 or IPv6 source address and constrain destination resolution to the same family.

Part of a layered boundary

These policies complement operating-system firewall and routing rules; they do not replace them.

source_ip is source-address binding—not interface selection, routing-table selection, socket marking, or SDN.

UDPSEC lifecycle

Authenticated transport with bounded local state

The current source-tree UDPSEC path between nmea_sproxy and aismixer uses configured long-term P-256 ECDSA identities, signed ephemeral P-256 ECDHE, fresh directional AES-256-GCM keys, and encrypted sequence-zero proof of key possession before the client treats a new session as established.

Authenticated ClientHello Identity-signed, fresh P-256 ephemeral key

Ephemeral P-256 ECDHE Fresh shared secret for this handshake

HKDF-SHA256 Independent C2S and S2C keys

Encrypted sequence-zero confirmation C2S ping, then S2C pong

Active session Authenticated ping promotes; authenticated pong completes

Authenticated ephemeral key agreement

For every session handshake, each endpoint creates a fresh ephemeral P-256 ECDHE keypair. Long-term P-256 identity keys only authenticate canonical, role-separated SHA-256 transcript digests with ECDSA; they are not ECDHE key-agreement inputs.

HKDF-SHA256 derives independent C2S and S2C keys from the shared secret and authenticated transcript. AES-256-GCM protects encrypted data and control traffic.

Encrypted mutual confirmation

The client sends an encrypted sequence-zero ping for the pending session. The server promotes only after authenticating it and returns an encrypted sequence-zero pong under the promoted S2C key; the client treats the session as established only after authenticating that pong.

Unrelated, malformed, stale-key, wrong-sequence, and wrong-source datagrams neither confirm the candidate nor extend its fixed confirmation deadline.

Coordinated update and local state

Both endpoints must be updated together. After confirmation, NMEA DATA, ping/pong liveness, and best-effort close are authenticated and encrypted. An unresolved liveness check or enabled planned session refresh proactively starts a fresh signed ECDHE handshake with fresh directional keys; UDPSEC does not buffer or replay NMEA payloads during recovery.

Recovery uses a fresh authenticated handshake. UDPSEC has no plaintext reset, NOSESSION recovery, downgrade control, or automatic fallback to plain UDP. DATA for an unknown old session is ignored without a plaintext recovery response. Secure session and replay state is in-memory, process-local, non-durable, and lost at restart.

UDPSEC works through NAT or CGNAT while the server-observed source address and port remain stable. Rebinding or network change requires a fresh authenticated handshake; an established session is not automatically migrated.

Forward-secrecy boundary: Later compromise of a long-term identity key does not by itself reconstruct keys for completed sessions when old ephemeral private keys and raw shared secrets are gone and neither endpoint was compromised while they were in memory. An identity key compromised in the present enables future impersonation. This implemented property is supported by engineering validation, not formal cryptographic verification.

Transport boundary: UDPSEC authenticates and encrypts data and control packets within its scope, but does not prove vessel identity, position, physical origin, or the absence of AIS spoofing; guarantee UDP delivery or ordering; protect compromised endpoints; or provide complete denial-of-service resistance. It does not hide peer IP addresses, packet timing or lengths, or the cleartext ClientHello station identifier.

Read the security policy, behavioural contract, nmea_sproxy guide, and Wiki for the detailed boundaries.

nmea_sproxy and physical AIS receivers

Connect networked or physical AIS receivers through nmea_sproxy

nmea_sproxy is the station-side proxy that connects one local UDP or physical serial/USB AIS input to one network output: UDPSEC or explicitly configured plain UDP.

Physical AIS receiver

physical serial or USB virtual serial

nmea_sproxy

UDPSEC or explicitly trusted plain UDP

Network output aismixer over UDPSEC or a plain-UDP consumer on a trusted network

Implemented local inputs

UDP from a local networked receiver or AIS application.
Physical serial input through nmea_sproxy, including USB virtual serial devices exposed by the OS.

Implemented outputs

Authenticated encrypted UDPSEC using the bounded session lifecycle described above.
Explicit plain UDP for a trusted LAN, VPN, or equivalent boundary.

Clear relation boundary

One local input maps to one configured output. The proxy forwards the bare supported AIS sentence match, stripping ingress TAG blocks, prefixes, surrounding bytes, and input terminators. nmea_sproxy does not mix, fan out, route, deduplicate, or assemble multipart AIS.

A networked receiver can feed local UDP into nmea_sproxy or send UDP directly to aismixer, depending on the deployment. The main aismixer process does not read serial ports directly. Trusted plain UDP does not provide UDPSEC encryption, authentication, replay protection, or liveness.

OpenWrt edge deployment

Run aismixer or nmea_sproxy on OpenWrt

The signed AISMixer APK repository for OpenWrt 25.12 currently publishes the 0.2.1-r1 Python/procd package snapshot for x86_64 and mips_24kc.

Signed packages

Install aismixer or nmea_sproxy. The shared aismixer-common dependency is resolved automatically when installing either package.

Published repository indexes:

x86_64: signed packages.adb index
mips_24kc: signed packages.adb index

Both architectures use the same repository public key; add it under /etc/apk/keys/ before using either repository index.

Key SHA-256: 170d30219e0e05d59898cd8ccd5ec9804e915df7882ab56b8e869ef6e99c8f9c

Two edge deployment roles

The aismixer service can run on an OpenWrt edge/router host. nmea_sproxy can run independently near a receiver with UDP or physical serial input, including USB virtual serial devices exposed by the OS. Its output can be plain UDP, or UDPSEC can protect the network hop to the aismixer service.

CDC ACM devices commonly appear as /dev/ttyACM*; USB-UART adapters commonly appear as /dev/ttyUSB*. The required OpenWrt kernel driver may already be available in the image or may need the appropriate kmod package, such as kmod-usb-acm for CDC ACM. Native UART and UDP input do not require a USB serial driver.

Explicit UDPSEC trust

The packages ship no private keys. The OpenWrt aismixer init flow prepares its local identity and, when a valid private key exists, can repair the matching public key. nmea_sproxy may create the canonical station key pair only when both key files are absent; a partial, invalid, or mismatched proxy pair fails closed without automatic replacement. UDPSEC peer trust is always provisioned manually: install the aismixer public key at the station and authorize the station public key on the aismixer side.

Package architecture. PKGARCH:=all describes the architecture-independent Python and shell payload; it does not make the package available in every target feed. The currently built, published, and validated feeds are x86_64 and mips_24kc, without intentionally excluding other suitable targets. Select the feed architecture configured for the device; do not derive it from apk --print-arch.

Writable space. The Python runtime and dependencies require materially more writable space than a minimal OpenWrt installation. Verify available overlay space before installation; extroot is an OpenWrt deployment option where internal writable storage is limited.

First-start safety. Apply firewall or network isolation and verify writable space before installation. The package hooks enable and start aismixer during installation, and the seeded configuration includes broadly listening plain-UDP listeners. Stop the service immediately afterward, configure listeners and UDPSEC authorization, and only then start and inspect it.

# Currently published feeds: x86_64 or mips_24kc
AISMIXER_ARCH='x86_64'

wget -O /etc/apk/keys/aismixer-openwrt.pem \
  https://aismixer.net/openwrt/keys/aismixer-openwrt.pem

REPO_FILE=/etc/apk/repositories.d/customfeeds.list
REPO_URL="https://aismixer.net/openwrt/25.12/${AISMIXER_ARCH}/packages.adb"

grep -qxF "$REPO_URL" "$REPO_FILE" 2>/dev/null || {
  printf '\n# AISMixer OpenWrt 25.12 %s repository\n%s\n' \
    "$AISMIXER_ARCH" "$REPO_URL" >> "$REPO_FILE"
}

apk update
apk add aismixer
/etc/init.d/aismixer stop
vi /etc/aismixer/config.yaml
vi /etc/aismixer/authorized_keys.yaml
/etc/init.d/aismixer start
/etc/init.d/aismixer status
logread -e aismixer

Package snapshot. Published 0.2.1-r1 packages use a pinned source revision and may trail later main changes. Check the package revision, Changelog, and Releases before assuming newer hardening is included.

End-to-end validation. The mips_24kc deployment path has been validated end to end with physical serial AIS ingress, nmea_sproxy, authenticated UDPSEC, processing by the aismixer service, procd service operation, and local runtime control and observability.

Receiver-side endpoint only. Use apk add nmea_sproxy instead of apk add aismixer to install the station proxy independently. See the README, nmea_sproxy guide, and OpenWrt Deployment Wiki for complete deployment and trust-provisioning steps.

Debian-family deployment and operations

A Debian-family and systemd lifecycle built for real installations

For Debian-family systemd hosts, including Debian and Raspberry Pi OS, the repository-managed deployment keeps runtime files, operator state, local routing control, and read-only runtime statistics aligned. OpenWrt uses the APK/procd path described above.

Repository-managed systemd

The aismixer service provisions /run/aismixer while running and supports the optional local control socket.

Install, update, and uninstall

Privilege-aware lifecycle scripts handle root or sudo operation and maintain the deployed runtime and service units. The AISMixer updater restarts its service and can start an inactive service; the nmea_sproxy updater reloads systemd but does not start or restart proxy instances. See the README and nmea_sproxy guide.

Operator state preserved

Normal install, update, and uninstall flows preserve operator configuration and cryptographic keys.

Global operator CLI

The installed workflow places aismixerctl in /usr/local/bin for local runtime routing and read-only statistics.

Documentation and project status

Implemented foundations, clearly separated from what comes next

The Wiki is the detailed guide to architecture, configuration, routing, security, and operations. The Roadmap separates the completed baseline from future work without promising dates.

Implemented now

Immutable bytes-based IngressFrame values, bytes-native scanning, parse-once metadata, and PythonDataPlaneProcessor as the sole current production and reference processor.
Private bounded ingress queues, shared bounded processing admission, bounded egress handoff, backpressure, processor-instance state ownership, and admission-time ProcessingSnapshot binding.
Compiled numeric target-only routing, exact immutable bytes encoded once per emitted sentence, ordered OutputBatch results, and an ordered local egress completion barrier.
Logical zones and target-scoped deduplication, atomic process-local routing updates, interactive aismixerctl, and read-only aggregate, per-input, and per-output statistics.
Deterministic multipart assembly, TAG s/c/g handling, and global or target-scoped deduplication.
Authenticated ephemeral P-256 ECDHE UDPSEC, configured long-term P-256 ECDSA identities, fresh directional AES-256-GCM keys, encrypted key-possession confirmation, authenticated and encrypted data, liveness, and best-effort close, full-epoch DATA replay protection, fail-closed bounded state, and physical-listener session isolation.
One UDP or serial input to one UDPSEC or explicit trusted plain-UDP output per nmea_sproxy process or systemd instance, plus IPv4/IPv6 endpoint controls.
Debian-family deployment with systemd RuntimeDirectory, privilege-aware lifecycle scripts, preserved operator state, and the global operator CLI, alongside the signed OpenWrt 25.12 APK/procd deployment published for x86_64 and mips_24kc.

Planned work

A coordinator process and actual separate ingress and egress worker processes.
IPC, cross-process routing-snapshot distribution and supervision, worker restart and recovery policy, and metrics aggregation where required.
A future native processor and bindings behind the established contracts, with differential conformance; none exists today, and no performance result is claimed.
A broader ingress and egress adapter architecture beyond the current UDP pathways.

Main repository GitHub Wiki Quick Start Behavioural contract Roadmap nmea_sproxy guide Security policy License

Project community

Community and contact

Choose the public channel that fits the conversation. Discussions, Ideas, and Q&A help other users too; reproducible defects belong in Issues. Private contact remains available in the maintainer profile below.

Browse discussions

Explore public project conversations, announcements, deployment experience, field testing, and other community topics.

Browse GitHub Discussions

Share an idea

Discussions is suitable for architecture proposals, integration ideas, deployment experience, AIS field testing, and academic or research collaboration that can be discussed publicly.

Open Ideas

Report a problem

Use GitHub Issues for reproducible defects and concrete repository work, not general private correspondence.

Open GitHub Issues

Ask in Q&A

Use Q&A for focused questions about installation, configuration, usage, architecture, and operation.

Open Q&A

Founder and maintainer

Iliyan Iliev, PhD

Founder, originator, and maintainer of AISMixer

Backend and network systems developer and researcher with interests in AIS/NMEA processing, maritime and regional security, transport, and tourism.

AI-assisted development: ChatGPT has supported architectural reasoning, planning, documentation, and review. OpenAI Codex has supported repository analysis, implementation, testing, and validation. Anthropic Claude Code has supported repository review, implementation handoff, cross-checking, testing, and validation. These tools are used under the founder’s direction; project decisions and final responsibility remain human.

GitHub profile ORCID ResearchGate Private email