Your application.
Our AIS engine.

THE PURPOSE

Reuse the engine. Build your own interface.

AIS4CBM’s BASIC 7 text viewer and BASIC 8 graphics viewer already share the same machine-language foundation. Serial reception, AIS decoding, the vessel registry, REU storage and map filtering live below the presentation layer. The API makes that separation available to other applications.

Here, an application programming interface means a set of entry addresses with defined inputs and results. BASIC reaches them through SYS; assembly can use JSR; another language can use a small register-and-memory bridge. The caller does not have to be written in BASIC.

The current interface grew out of the BASIC viewers. Some entries are direct register calls; others prepare a BASIC USR() operation or manage BASIC 8 graphics state. Reusing the binaries from another language is possible, but a new frontend must respect those dependencies and the C128 memory layout.

Start with the repository README, then inspect the exported API implementation. This is a local C128 binary interface; the existing binaries contain 8502 code.

THE CALLING CONTRACT

An address is only half an API.

The public entries occupy the BasicApi segment beginning at $8000. These small wrappers give callers known entry points while the implementation behind them can move. Use the symbols and modules from the same build: out/buildBASIC8.sym is the address authority.

The current standard build uses SwiftLink-compatible serial input and the REU layout for 512 KiB or larger units. A replacement frontend must preserve the runtime’s reserved memory and hardware contracts as well as its call addresses.

• Registers carry arguments. Each call defines its own use of A, X, Y and carry. Do not assume registers or flags survive unless the routine promises it.
• Pointer getters return A/X. A is the low byte and X the high byte. The result is an address, not the counter or record value stored there.
• Memory mapping is part of the contract. A native caller must make the runtime code and its working memory visible, with the expected MMU and zero-page setup. A bare JSR from an arbitrary bank is insufficient.
• Calls belong in foreground code. The runtime shares scratch buffers, delegates and banking helpers. Treat these interfaces as non-reentrant, and keep one owner of the vessel-access transaction.

// Called after runtime initialization, in its valid memory mapping.
jsr $8004             // getNotifyFlagPointer
sta eventAddress      // low byte
stx eventAddress+1    // high byte
// Continue in the caller; eventAddress is its own two-byte variable.

This is the same entry used by BASIC. The caller’s bridge changes; the meaning of the API result stays the same. Prefer a getter to copying a current internal address into your application.

THE MAIN DATA TRANSACTION

Lock. Read. Release.

The application identifies a vessel by a 16-bit record ID, currently 0–999. This is a registry handle, not a Bank 0 pointer and not an MMSI. Records live in Bank 1; each owns a fixed 128-byte REU slot. Reclaimed IDs can be reused, so a long-lived ID alone does not guarantee the same vessel identity.

After a successful lock, BASIC reads fields through USR(field). Numeric results use the C128 floating-point accumulator; string results use BASIC string services. The $807A getter exposes the fetched scratch buffer, and $800E exposes the nine-byte registry scratch record. A native frontend can wrap the field reader or interpret the fetched data using the matching build’s layout.

Keep the record locked while copying the fields you need, then release it. The scratch space belongs to the runtime and is reused by the next transaction; it is not a permanent per-vessel buffer. Unlock with the same ID, and only after a successful lock.

For a guided example of the BASIC side, see Getting vessel data with USR, including field selectors and numeric/string results.

Lock, field-access and unlock implementation · Registry and record IDs · REU layout

CALLS IN / NOTIFICATIONS OUT

The runtime tells your application what changed.

The notification pointer returned by $8004 leads to a shared flag byte and its event context. BASIC uses WAIT to wait for selected flags. Another frontend can read the same state from its own event loop.

These flags are a shared handshake, not an event queue. Repeated signals can coalesce. Read the relevant context before acknowledging an event, preserve unrelated bits, and coordinate acknowledgements with interrupt updates. Keep the wait-mask mirror consistent with the events your frontend can currently handle: the runtime uses it when deciding what to deliver.

IRQ supplies the bits needed to get BASIC going; once IGONE runs, foreground ML can publish further events. A native loop replaces that foreground scheduling role. It still needs to service the runtime and consume its notifications.

The WAIT tutorial explains masks and acknowledgement; the IGONE tutorial explains execution and wake-ups. The graphics frontend shows the complete event handling.

CURRENT EXPORTED ENTRIES

Find the service you need.

The tables retain the source names, including legacy names. Addresses describe the checked build. Detailed payload layouts and implementation helpers should always be taken from its source and symbols.

Runtime and lifecycle

Vessel access and scratch

Notifications and pointer state

Runtime counters

Filtering and chart extent

BASIC and viewer helpers

Multi-byte counters listed here are little-endian. Take a consistent snapshot before converting or displaying them; their bytes are shared runtime state. Flags and field/string representations have their own contracts.

Implementations: API wrappers and viewer helpers · cleanup status · chart extent handlers · mouse bridge modes

A FRONTEND OF YOUR OWN

BASIC is one caller. Yours can be another.

An application written in another language can provide its own foreground loop: service the AIS runtime, inspect notifications, update its interface, and repeat. IRQ and NMI handlers still handle their interrupt work. The integration needs a bridge that supplies registers, captures results and manages memory mapping around calls.

1. Load a matched runtime. Use the module set and placement in the current build and loader. The disk separates serial code, bridges, registry, decoder/API, runtime support, AIS logic, file operations and REU support. Loading DECODER alone does not provide the complete engine.
2. Respect the memory contract. Reserve the Bank 1 registry and hash, REU slots, shared scratch, low-memory bridges and zero-page/FAC areas. Use the existing banking and REU helpers; REU DMA must go through reu.runDma, which forces 1 MHz for the transfer.
3. Supply the execution schedule. Initialize in the expected environment, arrange IRQ/NMI and foreground servicing, and select the events your frontend will consume. Do not install the BASIC IGONE hook and assume it will run in a native-only loop.
4. Choose your field-access bridge. Register calls are straightforward to wrap. USR/FAC/string helpers still need their C128 ROM and BASIC workspace contracts, even when the application itself is written in another language. A native typed-field interface would be an additional adapter.

The same division of responsibilities can guide a future implementation on another platform. Reusing these particular binaries, however, requires the C128 execution environment or emulation of it.