What Cascade does · USB & APIB

The USB–APIB link, byte by byte

Chris asked for this page: "I would like a page in The Correction Log about how the app communicates with the instrument and the USB-APIB interface. there is a page in tehre now, but it does not cover technical details about the USB protocol translating the commands and things like that> I would like to understand that more fully. One of the reasons i am interested in this, is that there may be a way to make an APIB to Ethernet interface. Companies like Prologix have done this with GPIB controllers, for instance."

Everything below comes from three places, and each statement says which: the app's code (Cascade/Cascade/APDevice.swift), USB captures of APWIN (T92, a three-minute capture of 111,118 commands, is used for the counts and timings), and AP's manuals. Where something is a guess, it says so.

The chain

Cascade (macOS)  ──libusb──▶  USB cable  ──▶  S1/S2 USB adapter  ──APIB cable──▶  SYS-2522
APWIN (Windows)  ──driver──▶  USB cable  ──▶  (the same adapter)  ──APIB cable──▶  SYS-2522
APWIN, originally ──ISA bus──▶ ISA-WIN card, 8 I/O ports at 0x2B8 ──APIB cable──▶ System Two

• The adapter is third-party, not AP's: the "S1/S2 USB Adapter by Duke Aguiar", USB vendor ID 0x16D0, product ID 0x0AF0 (repo protocol_notes.md, APDevice.swift). It replaces the interface card AP shipped: an ISA card that took eight I/O port addresses, 0x2B8 by default, selectable with two jumpers (installation guide p.75).
• APIB is AP's own bus, on a D-connector labelled "AUDIO PRECISION INTERFACE BUS (APIB)" on the rear panel (GPIB reference, Fig 1-4). Switchers and the DCX-127 daisy-chain on the same cable. ⚠️ None of the manuals we have describe APIB's electrical signals or timing. Everything we know about it is what crosses the USB side.
• APIB is not GPIB. On a System Two, GPIB is a factory option with its own firmware inside the instrument, which accepts text commands like :AGEN:FREQ 1000HZ and does the work itself (GPIB reference p.8, p.12–14). Over APIB nothing like that happens: the PC reads and writes the instrument's registers directly and does all the thinking (uploading DSP programs, waiting for readings to settle, scaling results). A rear switch chooses one or the other; in APIB mode the GPIB port goes dead.

Opening the adapter

What the app does at connect, verbatim from APDevice.swift (and the same as APWIN in the captures):

libusb_open_device_with_vid_pid(0x16D0, 0x0AF0)
set_configuration(1) if not already; claim_interface(0)
control IN  bmRequestType 0xC0, bRequest 0x54, wValue 0,      wIndex 0, length 2  → replies 00 0C
control OUT bmRequestType 0x40, bRequest 0x53, wValue 0xFFFF, wIndex 0, length 0
control OUT bmRequestType 0x40, bRequest 0x55, wValue 0x0000, wIndex 0, length 0

After those three vendor requests, everything is bulk transfers: commands out on endpoint 0x06, replies in on endpoint 0x82. The code's comments call the adapter's chip an "FX2" (a common Cypress USB microcontroller); that has not been checked against the device's own descriptors.

One command, one packet

Each command is one bulk OUT transfer. If the command produces a reply, the reply is the next bulk IN transfer, before the next command is sent; many commands produce none. (Getting this pairing rule wrong once produced about 4,000 false differences in a replay-versus-capture comparison: docs/usb_pairs.py.)

The first byte is the opcode. These are all the opcodes in T92, with how many times each appears:

Two observations about the structure, both inferences rather than documentation:

• Opcodes in the E… family always get a reply; 8A, 82, 83 and 03 never do. It looks like a bit in the opcode decides whether the adapter waits for the bus to answer.
• The ISA card was eight I/O ports. The opcodes may well be the USB adapter's encoding of the same port reads and writes APWIN used to do on the card. If so, the protocol was never designed for a network; it is a remote register file.

The register space: 8A and EB

For six months the app's code named the second byte of 8A and EB a "module" (0x01 system, 0x02 "sys2"). It is a width. In all 72,000 of these commands in T92, 8A 01 … is always 4 bytes long (one data byte) and 8A 02 … always 5 (two data bytes); EB 01 xx always returns one byte and EB 02 xx always two. The third byte is the register address, in one flat space. (Found while writing this page, 2026-10-21; the code still uses the old names.)

Examples, all verified on the instrument:

8A 02 21 7D A8      generator frequency word: 7000 Hz (two bytes, little-endian)
8A 01 20 81         generator mode: analog IMD
8A 01 2B 48         generator output: balanced, floating, 40 Ω
EB 02 1C  → 70 44   channel A level mantissa: 0x4470 = 17520 (T92, during SMPTE)
EB 01 0D  → 0D      the instrument's handshake counter

Two-byte values are little-endian. An early note read the second byte of a level reply (7C) as a "valid" flag; it is the high byte of the number.

The DSP side: E6, E9, ED, EC, 08

The second byte of these is a DSP address: 0x30 and 0x38 are analyzer channels A and B, 0x40 and 0x48 the generator side (the app's naming, from captures). The third byte is almost always 0A, a DSP port. E9 replies carry a status byte (0x86 busy, 0x87 done) ahead of a 24-bit fixed-point value.

The DSP programs travel over this link too: APWIN uploads them, 207 08 blocks in T92's re-initialisation. That is a large part of why every Cascade measurement begins by replaying a recorded setup.

Volume and timing

Measured in T92 from the capture's own timestamps:

How many commands real work takes, from the app's own recordings:

And it is a conversation, not a stream. APWIN, and Cascade, poll until the instrument says ready before the next write: a DSP write sent while the DSP is busy is refused (EC replies 00), and in October that left a replay broken until the next one. The instrument also keeps its state across USB disconnects (a hung run in October needed a power cycle).

An APIB-to-Ethernet interface

The comparison Chris drew, Prologix, works for GPIB because GPIB is the easy case: a published standard (IEEE-488), and an instrument that understands text. A box can take a line of text from the network and put it on the bus, and the round trip hardly matters, because one command does a lot of work.

APIB is the hard case: tens of thousands of small register transactions per measurement, most of them waiting on a reply. So the question is not whether the bytes can travel over Ethernet (they can) but where the waiting happens. Three ways to build it:

1. Tunnel the USB. Put the existing adapter on a small computer next to the instrument and forward the USB traffic over the network (Linux has a standard way to do this, USB/IP). Cascade would not change. But every reply-bearing command pays a network round trip instead of 100 µs. On a wired network a round trip is commonly a few hundred µs; on Wi-Fi often several ms (typical figures, not measured here). For the 122,703-command FFT setup that is roughly the difference between tens of seconds and many minutes. It works; it is slow.

2. Network the commands, not the USB (recommended to try first). The same small computer and adapter, but running a small server that speaks this opcode protocol. Cascade sends commands over TCP instead of libusb; the server sends them to the adapter and returns the replies. The win comes from moving the waiting to the instrument's side:

• writes that have no reply (8A, 82, 03) are streamed without waiting;
• a recorded setup (the blobs) is stored on the server and replayed there, at USB speed, with one request from Cascade;
• "poll until ready" loops run on the server and return only the result.

Cascade's code already funnels every transaction through a few functions, so swapping the transport is a contained change. Nothing about the instrument has to be learned that we don't already know.

3. A true APIB-Ethernet adapter, like a Prologix box: a microcontroller with Ethernet on one side and the APIB connector on the other, replacing the USB adapter entirely. This needs what we don't have: APIB's electrical layer and bus timing. Getting it means putting a logic analyzer on the APIB cable between today's adapter and the instrument while a known command sequence runs, and matching bus activity to the USB commands above. It is the most work, and the most interesting. It could also absorb approach 2's server into the box.

Approach 2 gives a networked Cascade with the hardware already on the bench and teaches us which operations need to live next to the instrument, which is the design input approach 3 would need anyway.

What we still don't know

• APIB's physical layer: connector pinout, signal levels, handshake, bus speed.
• What the adapter does inside: whether it buffers, how it turns one USB packet into bus cycles, whether opcodes map one-to-one to the old card's port operations.
• The meaning of 03, 83 and much of the register space.
• The adapter's chip, from its own USB descriptors (diag_usb.py in the repo root lists them; one run settles it next time the adapter is connected).