Operation modes

Overview

Serial Studio has three parsing modes that determine how incoming data is interpreted and displayed. The mode is picked in the Setup panel on the right side of the main window. Every mode works with any data source: Serial (UART), Bluetooth LE, Network (TCP/UDP), and all Pro sources (Audio, Modbus, CAN Bus, USB, HID, Process).

The three modes, in order of increasing complexity:

1. Console Only. No parsing, no dashboard. Raw bytes stream to the terminal so you can inspect what your device is sending.
2. Quick Plot. Automatic CSV plotting with zero configuration.
3. Project File. A .ssproj project file on the host defines the dashboard, and the device sends raw values (CSV, binary, or anything a frame parser can decode).

The diagram below compares data flow through each mode side by side.

flowchart LR
    subgraph CO["Console Only"]
        C1["Raw Bytes"] --> C2["Terminal"]
    end
    subgraph QP["Quick Plot"]
        Q1["CSV"] --> Q2["Auto Dashboard"]
    end
    subgraph PF["Project File"]
        P1["Any Format"] --> P2["Custom Dashboard"]
    end

Note. All modes work with any data source: Serial, TCP/UDP, BLE, and all Pro drivers (MQTT, Modbus, CAN Bus, Audio, USB, HID, Process I/O).

Frame detection options (Project File mode only): End Only, Start+End, Start Only, No Delimiters.

Console Only mode

Selection

Pick the "Console Only (No Parsing)" radio button in the Setup panel.

How it works

• Frame detection. None. Serial Studio doesn't scan for delimiters, doesn't buffer frames, and doesn't build a dashboard.
• Data flow. Raw bytes from the data source go straight to the terminal. The circular buffer, frame queue, and FrameBuilder are all skipped.
• Display. The terminal shows the raw stream in ASCII or hex. You can still save the console transcript to a file.
• Transmit. The console input box still works, so you can send bytes back to the device.

Console Only is not a parsing mode. No widgets render, no CSV export, no frame parser scripts. It exists purely as a diagnostic view.

When to use it

• Figuring out what protocol your device is using.
• Verifying baud rate / pin wiring / framing before you commit to a project file.
• Debugging a stream that isn't being parsed correctly in another mode.
• Interactively driving a device with a simple text protocol (AT commands, CLI, and so on).

Once you've confirmed the data looks sane, switch to Quick Plot or Project File to visualize it.

Quick Plot mode

Selection

Pick the "Quick Plot (Comma Separated Values)" radio button in the Setup panel.

How it works

• Frame detection. Line-based. Each line of text terminated by CR, LF, or CRLF is one frame.
• Data format. Comma-separated numeric values. Each value maps to one channel.
• CSV delimiter. Comma only. Other delimiters aren't supported in this mode.
• Header detection. If the first received row is all non-numeric strings, those strings become channel labels on the dashboard.

When a connection is established, Serial Studio reads each line, splits on commas, and creates a dashboard with:

• A Data Grid widget showing all current values.
• A MultiPlot widget overlaying all channels on a single time-series chart.
• Individual per-channel plots.

No project file required. No JavaScript parsing involved.

Example input

Temperature,Pressure,Humidity
23.5,1013.2,45.0
23.6,1013.1,45.1
23.7,1013.0,45.3

The first line sets channel labels. Later lines are plotted in real time.

Limitations

• Comma is the only supported delimiter.
• No custom widgets (gauges, bars, compass, GPS map, FFT, and so on).
• No alarm thresholds.
• No per-channel configuration (units, ranges, scaling).
• No JavaScript frame parsing.
• No multi-source support.

When to use it

Quick Plot visualizes data without any configuration. Use it when you want to check that a device is transmitting correctly, prototype a new sensor, or demonstrate real-time plotting in a classroom.

Project File mode

Selection

Pick the "Parse via Project File" radio button in the Setup panel. Then load or create a project file in the Project Editor (the Project Editor button in the toolbar).

How it works

• Frame detection. Configurable per source. Four detection methods are available.
• Data format. Configurable. Incoming bytes can be decoded as plain text (UTF-8), hexadecimal, Base64, or raw binary.
• Dashboard definition. A .ssproj JSON file on the host defines all groups, datasets, widgets, alarms, FFT settings, and actions.
• Device data. The device sends only raw values (CSV text, binary packets, and so on). Serial Studio maps each value to the corresponding dataset by index.
• Frame parser script. An optional parse(frame) function (Lua or JavaScript) can transform arbitrary protocols into the array of values Serial Studio expects.
• Multi-source. A single project file can define multiple data sources, each with its own connection, frame detection, and decoder settings.

This mode provides access to every widget type and configuration option in Serial Studio. It's the most commonly used mode for real-world projects.

Frame detection methods

Frame detection determines how Serial Studio finds the boundaries of each data frame in a continuous byte stream. The method is configured per source in the Project Editor.

Delimiters can be specified as plain text or hexadecimal byte sequences (toggle "Hexadecimal Delimiters" in the Project Editor).

Decoder methods

The decoder determines how raw bytes are converted before being passed to the frame parser (or split as CSV).

Frame parser script

When the incoming data isn't simple comma-separated text, you can write a Lua or JavaScript parse() function to transform each frame into the array of values Serial Studio expects. Lua is the default and recommended language for new projects because it's faster.

The signature:

function parse(frame) {
    // 'frame' is a string (for PlainText/Hex/Base64 decoders)
    // or an array of integers (for the Binary decoder).
    //
    // Return a flat array of values:
    return [value1, value2, value3];
}

Key behaviors:

• parse() takes exactly one argument. The two-argument parse(frame, separator) form from Serial Studio v2 projects is rejected when the script loads.
• The returned array is mapped to datasets by index: element 0 goes to dataset index 1, element 1 goes to dataset index 2, and so on.
• Multi-frame return. Return an array of arrays to emit multiple frames from a single parse call: [[row1_val1, row1_val2], [row2_val1, row2_val2]].
• Mixed scalar/vector. Returning [scalar, [vec1, vec2, vec3]] auto-expands the inner array into separate dataset values.

Example: parsing a semicolon-delimited protocol.

function parse(frame) {
    return frame.split(";");
}

Example: parsing a fixed-size binary packet.

function parse(frame) {
    // frame is an array of bytes (Binary decoder)
    // Bytes 0-1: uint16 temperature (big-endian, x0.1)
    // Bytes 2-3: uint16 pressure (big-endian)
    var temp = ((frame[0] << 8) | frame[1]) * 0.1;
    var pres = (frame[2] << 8) | frame[3];
    return [temp, pres];
}

Multi-source support

Project File mode supports multiple data sources within a single project. Each source is an independent entry with its own:

• Source ID and title.
• Bus type (UART, Network, BLE, and so on).
• Frame detection method and delimiters.
• Decoder method.
• Frame parser code (Lua or JavaScript).
• Connection settings.

That's how you monitor multiple devices at the same time on a single dashboard. For example, a weather station project might define one UART source for a ground sensor array and one TCP source for a remote wind station, both feeding one dashboard.

Multi-source is a Pro feature. The free (GPL) edition is limited to a single source per project.

When to use it

Project File mode is the right choice for any application that needs custom widgets, alarm thresholds, FFT analysis, per-channel configuration, multi-device monitoring, or a carefully designed dashboard layout. It's the most common mode for production telemetry systems, competition dashboards (CanSat, rocketry), and industrial monitoring.

Picking the right mode

Feature comparison

Getting started recommendations

If you're hooking up a new device and don't yet know what it sends, start in Console Only mode. Connect, watch the raw bytes, confirm the baud rate and framing make sense.

Once you can see clean comma-separated numbers in the console, switch to Quick Plot. You'll get a dashboard with one plot per CSV field in seconds, with no configuration.

Once you need more control (specific widget types, unit labels, alarm thresholds, a custom dashboard layout, binary protocol parsing, or multiple concurrent data sources), move to Project File mode. Open the Project Editor, define your groups and datasets, save a .ssproj file, and load it from the Setup panel. This is the recommended mode for most real-world projects.