Live connections

The three layers

Packet-based transports and self-describing formats supply their own message boundaries; Refract disables the framing section in those cases.

Open the sheet with File → Open Connection… (⇧⌘O).

Transports

TCP

Refract listens; your producer connects. Set a port (default 9000). The browser shows Listening: 9000 until a client attaches.

Serial

Reads a /dev/cu.* device. Choose a port and baud rate (9600 to 921600). Use the refresh button after plugging in a board.

Serial has no inherent message boundaries. For a board printing CSV lines, use delimiter framing on 0D 0A; the Serial / CSV preset is preconfigured for this.

USB HID

Reads input reports from a HID device. Report ID filters which reports are accepted; 0 accepts all.

Refract adds two columns of its own: Timestamp and Report ID. These appear as hollow-dot rows and can be used as an x-axis.

Bluetooth LE

Scan for peripherals and choose one. The characteristic list offers the peripheral's notifiable characteristics; select one to subscribe to its notifications.

Previously used devices remain selectable when out of range, marked (cached).

RefractIO

A gRPC server built into Refract. Set a port (default 50051). Refract listens and advertises itself over Bonjour.

RefractIO supplies named, typed columns and supports multiple independent tables in one connection, each with its own schema, buffer and rate. Traces are grouped by table.

See RefractIO from Python.

Permissions

Selecting a transport requests the macOS permission it needs.

Denied permissions can be restored in System Settings → Privacy & Security.

Decoders

Arrow IPC

Column names and types come from the Arrow schema, and the format frames itself, so there is nothing to configure. The highest-throughput option.

CSV / TSV

Each frame is a line of delimited text.

Separator

Comma, Tab, Space, Semicolon, or custom.

First line is a header

When on, the first record names the columns.

Framing defaults to delimiter, with presets for \r\n and \n.

Binary packet builder

Describe a fixed-layout packet once, and Refract decodes every frame against it.

Each element has a name and byte order (LE or BE). Drag elements to reorder them. A running total shows bytes per sample, so you can check the layout against a datasheet.

Save and Load store the layout as an .rfpl file.

Protobuf

Drop a .proto file on the schema well and choose a message type. Numeric fields become traces. Framing defaults to length-prefixed.

Framing

Framing splits a byte stream into messages. A diagram under the controls shows the layout you have configured.

None

For transports that already deliver packets.

Delimiter

Frames end at a byte sequence, entered as hex.

Length-prefixed

A 1, 2 or 4-byte header gives the payload length, little- or big-endian.

Fixed-size

Every frame is N bytes.

Self-framed

Selected automatically for Arrow IPC.

Sync pattern

Length-prefixed and fixed-size framing accept an optional sync pattern in hex, such as AA 55. Refract discards bytes before it, recovering alignment mid-stream. Discarded bytes appear in the raw stream console.

Automatic selection

Buffer

A live source holds a rolling window.

Last N seconds

Trim by arrival time. Default 60 seconds.

Last N samples

Trim by sample count.

Clear Stream Buffers (⌘K) empties every window without disconnecting.

Persist to database

Appends everything received to an Arrow file in your Application Support folder under Refract.

Presets

The sheet's sidebar lists presets. Two are built in:

• TCP / Arrow IPC — port 9000, Arrow IPC.
• Serial / CSV — 115200 baud, CSV, \r\n framing.

Save overwrites the open preset; Save As… creates a new one. Right-click a preset to rename, export or delete it. Presets are .rfpreset files and can be shared.

Connection lifecycle

A connection appears in the source browser with a status line: Connecting…, Connected, Listening, Disconnected, or an error. Traces appear once the schema is known.

From the connection's context menu:

Edit Connection…

Reopens the sheet on this configuration.

View Raw Stream

Opens the raw byte console.

Clear Buffer

Empties the window, keeping the connection open.

Reconnect

Restarts the transport and resets buffers. Traces and track assignments are preserved when the schema is unchanged.

Close Connection

Stops and removes it.

Raw stream console

View Raw Stream docks a console at the bottom of the track area showing frames as they are extracted.

Each row is one entry — a framed packet, or bytes discarded while searching for a sync pattern.

• Hex / Decimal / Char switches the byte format.
• Stop freezes capture; Restart resumes.
• Auto-scroll follows the newest entry.
• Clear empties the log.
• Select rows and copy them in the displayed format.

Throughput

The display refreshes about 30 times a second whatever the incoming rate, so a high-rate source does not slow the window down.