doc/help/Getting-Started.md
Serial Studio is a cross-platform telemetry dashboard application for visualizing real-time data from embedded devices, sensors, and other data sources. It runs on Windows, macOS, and Linux.
Core capabilities:
Whether you are reading temperature from an Arduino, monitoring a CAN Bus on a vehicle, or building a ground station for a rocket, Serial Studio provides the visualization layer so you can focus on your hardware and firmware.
The following diagram shows the steps from launching Serial Studio to seeing data on your dashboard.
flowchart LR
A["Launch"] --> B["Select Mode"]
B --> C["Configure"]
C --> D["Connect"]
D --> E["Dashboard"]
Unknown Developer Warning: Windows may show a warning because the installer is not digitally signed. Click More Info, then click Run Anyway.
Visual C++ Redistributable: On a fresh Windows installation, Serial Studio may fail to launch. If this happens, install the Microsoft Visual C++ Redistributable (64-bit) and try again.
Alternatively, install via Homebrew (community-maintained):
brew install --cask serial-studio
Note: The Homebrew cask is not officially maintained by the Serial Studio team. Use the DMG for guaranteed compatibility.
Multiple installation methods are available:
AppImage (recommended):
chmod +x SerialStudio-*.AppImage
./SerialStudio-*.AppImage
You may need to install libfuse2 first:
sudo apt update && sudo apt install libfuse2
Flatpak (via Flathub):
flatpak install flathub com.serial_studio.Serial-Studio
DEB/RPM packages are also available on the releases page.
Serial port permissions on Linux: If your serial device does not appear, add your user to the dialout group:
sudo usermod -a -G dialout $USER
Then log out and log back in for the change to take effect.
If you prefer to compile from source, you need Qt 6.9+ and CMake:
git clone https://github.com/Serial-Studio/Serial-Studio.git
cd Serial-Studio
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
The resulting binary will be in the build/ directory.
When you launch Serial Studio, the main window is organized into four areas:
The toolbar spans the top of the window and contains:
When you first connect, the console panel shows raw incoming data from your device. You can toggle between ASCII and hexadecimal display modes. The console is useful for verifying that your device is sending data correctly before configuring a dashboard.
Once Serial Studio successfully parses at least one valid frame, the view automatically switches from the Console to the Dashboard. The Dashboard displays real-time widgets (plots, gauges, maps, grids, and more) arranged according to your configuration. You can toggle individual widgets on and off using the sidebar on the left.
The Setup Panel is where you configure everything about your connection:
You can collapse the Setup Panel by clicking its header to give the Dashboard more screen space.
This is the fastest way to see data on screen. We will use an Arduino as an example, but the same approach works with any device that sends comma-separated values over a serial port.
Upload this sketch to an Arduino (or adapt it for your board):
void setup() {
Serial.begin(115200);
pinMode(A0, INPUT);
pinMode(A1, INPUT);
pinMode(A2, INPUT);
}
void loop() {
Serial.print(analogRead(A0));
Serial.print(",");
Serial.print(analogRead(A1));
Serial.print(",");
Serial.print(analogRead(A2));
Serial.print("\n");
delay(20);
}
The key requirement is that your device sends comma-separated numeric values terminated by a newline character (\n, \r, or \r\n). For example: 512,1023,300\n.
COM3 on Windows, /dev/ttyUSB0 on Linux, /dev/cu.usbmodem* on macOS).115200 (must match the value in your Arduino sketch).Click the Connect button in the toolbar. You will see:
That is all it takes. No project file, no JSON — just connect and visualize.
Project File mode gives you full control over how Serial Studio interprets your data and what widgets appear on the dashboard. You create a .json project file using the built-in Project Editor, and Serial Studio uses it to parse incoming data and build the dashboard. This is the recommended mode for most real-world projects.
Click the wrench icon in the toolbar, or select Project Editor from the menu. This opens a separate editor window.
.json file).Configure your I/O interface and click Connect. Serial Studio uses your project file to parse incoming frames and display the widgets you configured.
Note: This mode is not recommended for most projects. The JSON frame structure may change between Serial Studio versions, which can break firmware. Consider using Project File mode instead — it keeps the dashboard definition on the host and does not require transmitting large JSON payloads over the data link.
If your device can generate JSON, it can define its own dashboard layout. Serial Studio wraps JSON frames in delimiters so it can find them in the data stream.
Your device must output JSON frames wrapped in /* and */ delimiters:
/*{"title":"Weather Station","groups":[{"title":"Environment","widget":"datagrid","datasets":[{"title":"Temperature","value":"23.5","units":"°C"},{"title":"Pressure","value":"1013","units":"hPa"},{"title":"Humidity","value":"45.2","units":"%"}]}]}*/
The JSON structure tells Serial Studio everything: how to name the dashboard, what groups to create, which widget to use for each group, and what datasets to display.
/* and */, parses them, and builds the dashboard automatically.This mode exists for cases where the firmware must control the dashboard layout at runtime, for example when the device switches between operating modes that expose different sensors.
Serial Studio provides three operation modes. Choosing the right one depends on how much control you need and how your device formats its output.
| Aspect | Detail |
|---|---|
| Configuration needed | None |
| Data format | Comma-separated numeric values |
| Line terminator | \n, \r, or \r\n |
| Dashboard generated | Automatic (Data Grid + MultiPlot) |
| Best for | Prototyping, quick debugging, simple sensors |
Quick Plot treats each line as a frame and each comma-separated field as a dataset. It automatically creates one plot per field. This is the fastest way to get data on screen, but it offers no control over widget types, labels, or units.
| Aspect | Detail |
|---|---|
| Configuration needed | JSON project file (created in Project Editor) |
| Data format | Configurable (CSV with custom delimiters, binary with JS parser) |
| Dashboard generated | From project file |
| Best for | Production telemetry, complex protocols, multi-sensor systems |
This mode provides full control. You define frame delimiters, map data fields to datasets, choose widget types, set units and ranges, configure alarms, add FFT analysis, and write JavaScript parsers for binary protocols. Project File mode also supports multiple data sources for multi-device setups. This is the recommended mode for most real-world projects.
| Aspect | Detail |
|---|---|
| Configuration needed | None (device defines everything) |
| Data format | JSON wrapped in /* and */ |
| Dashboard generated | From JSON structure |
| Best for | Devices that change dashboard layout at runtime |
The device sends complete JSON frames that define groups, datasets, widget types, units, and actions. Serial Studio reads these frames and builds the dashboard accordingly. This mode is generally not recommended — it requires transmitting verbose JSON over the data link, and the JSON frame structure may change between Serial Studio versions. Use it only when the firmware must dynamically control its own dashboard layout.
sudo usermod -a -G dialout $USER, then log out and log back in. Verify the device appears with ls /dev/ttyUSB* or ls /dev/ttyACM*./dev/cu.usbmodem* or /dev/cu.usbserial*./* and */ and that the JSON is valid.Now that you have made your first connection, here are the recommended paths for learning more:
Click Examples in the toolbar to browse working project files that ship with Serial Studio. These include GPS trackers, IMU visualizers, sensor dashboards, and more. Opening an example is one of the best ways to understand how project files are structured.