Operation Modes

Overview

Serial Studio supports three parsing modes that determine how incoming data is interpreted and displayed. The mode is selected in the Setup Panel on the right side of the main window. Each 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, are:

1. Quick Plot — automatic CSV plotting with zero configuration.
2. Project File — a JSON project file on the host defines the dashboard, while the device sends only raw values.
3. Device Sends JSON — the device transmits a self-describing JSON frame that defines both data and dashboard layout.

The following diagram compares the data flow through each operation mode side by side.

flowchart LR
    subgraph QP["Quick Plot"]
        Q1["CSV"] --> Q2["Auto Dashboard"]
    end
    subgraph PF["Project File"]
        P1["Any Format"] --> P2["Custom Dashboard"]
    end
    subgraph JSON["JSON Mode"]
        J1["JSON Frame"] --> J2["Device Layout"]
    end

Note: All modes work with any data source: Serial, TCP/UDP, BLE, and all Pro drivers.

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

Quick Plot Mode

Selection

Choose 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 treated as one frame.
• Data format: comma-separated numeric values. Each value maps to one channel.
• CSV delimiter: comma only. Other delimiters are not supported in this mode.
• Header detection: if the first received row contains only non-numeric strings, those strings become channel labels for the dashboard.

When a connection is established, Serial Studio reads each line, splits it 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 is required. No JavaScript parsing is 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. Subsequent lines are plotted in real time.

Limitations

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

When to Use

Quick Plot is the fastest way to visualize data. Use it when you want to verify that a device is transmitting correctly, prototype a new sensor, or demonstrate real-time plotting in an educational setting.

Project File Mode

Selection

Choose the "Parse via JSON Project File" radio button in the Setup Panel. Then load or create a project file using the Project Editor (wrench icon 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, etc.). Serial Studio maps each value to the corresponding dataset by index.
• JavaScript parser: an optional parse(frame) function can transform arbitrary protocols into the array of values that 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 full access to every widget type and configuration option in Serial Studio. It is the most commonly used mode for real-world projects.

Frame Detection Methods

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

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

Decoder Methods

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

JavaScript Frame Parser

When the incoming data is not simple comma-separated text, you can write a JavaScript function to transform each frame into the array of values that Serial Studio expects.

The function signature is:

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:

• 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, etc.)
• Frame detection method and delimiters
• Decoder method
• JavaScript parser code
• Connection settings

This enables monitoring multiple devices simultaneously 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, with both feeding into the same dashboard.

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

When to Use

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 is the most common mode for production telemetry systems, competition dashboards (CanSat, rocketry), and industrial monitoring.

Device Sends JSON Mode

Note: This mode is provided for specific use cases where the device must control its own dashboard layout at runtime. For most projects, Project File mode is the recommended approach — it is more flexible, does not require firmware changes, and is not affected by protocol changes between Serial Studio versions. The JSON frame structure used by this mode may change across versions, which can break firmware that was written for an older format.

Selection

Choose the "No Parsing (Device Sends JSON Data)" radio button in the Setup Panel.

How It Works

• Frame detection: fixed delimiters. Every frame must begin with /* and end with */. These delimiters are hardcoded and cannot be changed.
• Data format: a complete JSON object enclosed between the delimiters. The JSON defines both the dashboard layout and the current data values.
• Dashboard behavior: Serial Studio rebuilds the dashboard dynamically whenever the JSON structure changes (new groups, different widgets, etc.). If only values change, the existing dashboard updates in place.

No project file is required. No JavaScript parsing is involved. The device firmware is entirely responsible for generating valid JSON.

Transmission Format

/*{ ... JSON payload ... }*/

The device sends the opening /*, followed by a JSON object, followed by */. Whitespace inside the delimiters is allowed.

JSON Frame Structure

A complete frame contains a root object with three optional top-level keys:

Group Object

Each group represents a panel on the dashboard containing one or more datasets.

Group widget values:

Dataset Object

Each dataset represents a single data channel within a group.

Action Object

Actions define buttons in the dashboard toolbar that send data back to the connected device.

Full Example

/*{
  "title": "Weather Station",
  "groups": [
    {
      "title": "Environment",
      "widget": "datagrid",
      "datasets": [
        {
          "title": "Temperature",
          "value": "23.5",
          "units": "degC",
          "widget": "gauge",
          "widgetMin": -20,
          "widgetMax": 60,
          "graph": true,
          "alarmEnabled": true,
          "alarmHigh": 50
        },
        {
          "title": "Humidity",
          "value": "45.2",
          "units": "%",
          "widget": "bar",
          "widgetMin": 0,
          "widgetMax": 100,
          "graph": true
        },
        {
          "title": "Pressure",
          "value": "1013",
          "units": "hPa",
          "graph": true
        }
      ]
    }
  ],
  "actions": [
    {
      "title": "Reset Sensor",
      "icon": "Refresh",
      "txData": "RST",
      "eol": "\r\n"
    }
  ]
}*/

When to Use

Device Sends JSON is suited for cases where the firmware must control its own dashboard layout at runtime — for example, when a device switches between operating modes and needs different widgets for each mode. Keep in mind that transmitting large JSON payloads over a serial port adds significant overhead compared to sending raw values, and the JSON structure is tied to the specific Serial Studio version you are using.

Choosing the Right Mode

Feature Comparison

Getting Started Recommendations

If you are new to Serial Studio, start with Quick Plot. Connect your device, make sure it sends comma-separated numbers terminated by a newline, and click Connect. You will see data on screen within seconds.

Once you need more control — specific widget types, unit labels, alarm thresholds, or a polished dashboard layout — move to Project File mode. Open the Project Editor, define your groups and datasets, and load the resulting .ssproj file. This is the recommended mode for most real-world projects.

Device Sends JSON mode exists for niche cases where the device firmware needs to control the dashboard layout dynamically at runtime. It is generally not recommended: it requires transmitting verbose JSON over the data link, and the expected JSON structure may change between Serial Studio versions, which can break your firmware without warning. If you are unsure which mode to use, choose Project File.