Operator Deployments

A deployment is a saved launcher that opens Serial Studio with a specific project file and a fixed set of command-line flags. Double-clicking the launcher starts the dashboard with the project already loaded, the toolbar hidden, and (optionally) auto-connect, fullscreen, and pre-armed exports.

The intended workflow: an engineer configures a project once, generates a deployment for it, and hands the deployment file to whoever runs the workstation. Operators get a single-icon entry point to a known dashboard layout instead of having to find the right .ssproj and remember which exports to enable.

Pro feature. Deployment generation and the --runtime flag are part of the commercial build. Deployments created on a Pro machine still launch under GPL builds (the runtime CLI flags are honoured by GPL builds), but they can only be generated from a Pro install.

Serial Studio must be installed on the target machine. A deployment is a launcher, not a self-contained bundle. It records the absolute path of the Serial Studio executable at the moment it was created, plus the project file path and runtime flags. If Serial Studio isn't installed on the operator's machine (or if it has been uninstalled, moved, or the project file is missing), double-clicking the deployment will fail with the OS's "missing application" or "file not found" error. Install Serial Studio on the target machine first (the same installer the engineer uses), then drop the deployment file onto the desktop.

What gets created

Pick Deploy from the toolbar. Fill in a name, optionally swap the icon, choose where to save, and Serial Studio writes a native launcher for your platform:

Every deployment hard-codes a single project file path plus the runtime flags you picked in the dialog. Double-clicking it relaunches Serial Studio with those exact arguments. There is no "remember last project" guessing involved.

flowchart LR
    A["Project Editor
configured project"] --> B["Deploy dialog
name + icon + flags"]
    B --> C[".lnk / .app / .desktop
on the desktop"]
    C --> D["Serial Studio
--runtime --project foo.ssproj"]
    D --> E["Dashboard launches
(toolbar hidden, auto-connect)"]

Legend: Deployments capture the project path and CLI flags at creation time. Editing the project later doesn't re-stamp the deployment; it just keeps pointing at the same file.

The dialog

Three tabs.

General

• Icon. Click the 96×96 preview (or Change Icon…) to pick your own. macOS prefers .icns, Windows prefers .ico, Linux accepts SVG or PNG. Leave it alone to use the bundled deployment icon.
• Name. Defaults to the project's title. Used as the deployment filename and the displayed label in the operator's shell. Reserved characters (\ / : * ? " < > |) are replaced with _ automatically when saving.
• Project. Read-only field showing the currently loaded project. Use the folder button to switch projects without leaving the dialog. A project must be loaded for Save to enable.
• Theme. Defaults to Same as Serial Studio, which means the deployment inherits whatever theme the operator's installation has set globally. Pick a specific theme from the dropdown to pin the deployment to that palette regardless of the host's preference. Useful for kiosks where the dashboard should always look the same, or for paired light/dark deployments off the same project. The selection adds --theme "<name>" to the launcher; an unknown theme name on the target machine falls back to the host's default with a warning.
• Fullscreen. When on, the deployment adds --fullscreen so the dashboard launches full-screen with no window chrome.
• Actions Panel. When on (the default), the deployment adds --actions-panel so the dashboard's action panel is shown.
• File Transmission. When on, the deployment adds --file-transmission, allowing the operator to open the File Transmission dialog in runtime mode.

Taskbar

Controls the dashboard taskbar in runtime mode.

• Mode. Always shown (default), Auto-hide (slides in near the bottom edge), or Hidden (removes window minimize/maximize/close buttons and forces auto-layout). Anything other than the default adds --taskbar-mode <mode>.
• Pinned Buttons. Toggles for which taskbar buttons stay pinned (Console, Notifications, Clock, Stopwatch, Pause, File Transmission). The selection adds --taskbar-buttons <ids>. Disabled when the taskbar mode is Hidden.

Logging

Optional toggles that pre-arm the export modules at startup. These are the same flags as the corresponding modules' Enable Export checkboxes. Turning them on in the deployment means the export starts the moment the device connects, with no extra clicks.

Each export module decides where the file lands; the deployment just flips the switch.

Save

Press Save. A native Save dialog opens with the right file filter for your OS. Pick a location, and Serial Studio writes the launcher and reveals it in your file manager so you can move it onto a desktop, share it, or include it in an installer payload.

If anything goes wrong while writing the file, an inline red banner shows the OS error in the dialog. The dialog stays open so you can retry without losing your selections.

Runtime mode

Every generated deployment adds --runtime. This flag adjusts the dashboard for unattended/operator use:

Runtime mode does not change anything about the data pipeline, frame parsers, exports, or the API server. The dashboard, MCP/JSON-RPC, gRPC, MQTT, and Session Database all behave exactly as they would in a normal Serial Studio session. Only the surrounding chrome is changed.

The recovery dialog

When the initial connection fails or an active connection drops in runtime mode, the dialog shows two pages:

1. Page 0 — summary. A warning icon, a one-line headline ("The connection to your device was lost." or "Serial Studio couldn't reach your device."), and three buttons: Quit, Pick Different Device, Try Again / Reconnect. The dialog auto-closes when a connection is re-established, so the user can leave it open and come back.
2. Page 1 — driver picker. A bus-type combo plus the Hardware setup pane embedded in the dialog. Lets the user choose a different port or device without exposing the rest of the toolbar. Press Connect when ready.

This is the only piece of the setup UI an operator interacts with under runtime mode, and it only appears when the connection is not established.

CLI reference

A deployment is a saved invocation of serial-studio with these flags. The same command can be run by hand, dropped into a service unit, or scripted in CI (the full flag list lives in Command-Line Interface):

serial-studio \
    --project /path/to/project.ssproj \
    --runtime \
    --fullscreen \
    --csv-export \
    --mdf-export \
    --session-export \
    --console-export \
    --shortcut-path /path/to/deployment.lnk

The deployment generator passes --shortcut-path automatically; you only need it when crafting flags by hand and want the broken-deployment self-cleanup behaviour.

When the project file goes missing

If a project file is moved or deleted after the deployment was generated, the runtime detects this before any window appears and offers to clean up:

flowchart TD
    A["Double-click
deployment"] --> B{"Project file
still exists?"}
    B -- yes --> C["Launch dashboard
and auto-connect"]
    B -- no --> D["'Project file not found'
dialog"]
    D --> E{"Delete the
deployment?"}
    E -- yes --> F["Deployment removed
app quits"]
    E -- no  --> G["App quits"]

The cleanup treats macOS .app bundles as directories (recursive remove) and Windows .lnk / Linux .desktop as plain files. Nothing else on disk is touched.

Tips for kiosk-style setups

• Install Serial Studio first. The deployment is a launcher, not a bundle. Use the Serial Studio installer on the target machine before dropping the deployment file in place. If Serial Studio isn't installed on the operator's machine, the deployment will fail with the OS's "missing application" error.
• Pair it with a project lock. A locked .ssproj plus a runtime-mode deployment limits the editor surface available at the workstation. See Project Lock.
• Pre-flight your exports. Toggle the recorders on in the Logging tab so files start collecting the moment the device connects.
• Use full-screen on dedicated displays. Combine --fullscreen with the OS's autostart hook to bring up the dashboard on boot.
• Linux launcher integration. Save the .desktop file to ~/.local/share/applications/ to make it appear in GNOME/KDE/etc. application menus. Most desktop environments pick up new entries automatically; some need an update-desktop-database run.
• Windows icon caching. If a deployment keeps showing the previous icon after you regenerate it, that's the Windows icon cache — sign out and back in, or rebuild it with ie4uinit.exe -show.
• macOS Gatekeeper. First launch of an unsigned .app deployment may prompt for confirmation. Right-click → Open works around it. Signed/notarized Serial Studio installs don't carry the warning over to their generated deployments because the launcher just execs the original signed binary.

Frequently asked

Does the deployment include Serial Studio itself? No. It's a launcher that points at the Serial Studio binary already installed on the machine. Install Serial Studio on the operator's computer separately, the same way you'd install any other application. Without it, double-clicking the deployment fails.

Can a deployment launch in QuickPlot or Console-Only mode? Not via the dialog. Deployments target Project mode; that's the intended use. You can still hand-craft a CLI invocation with --quick-plot if you have a reason to.

Does the deployment bundle the project file inside it? No. It records the absolute path to the .ssproj. Move the project, and the deployment breaks (cleanly — see the missing-file flow above).

Can I edit a deployment after creating it? Yes. Windows .lnk exposes Properties → Target. The macOS .app keeps a small Bash launcher at Contents/MacOS/<bundle-name> (the executable named in Info.plist's CFBundleExecutable). Linux .desktop files are plain text. All three can be edited by hand if you need to adjust the flags.

Will the deployment still work on a machine without a Pro license? Yes — the runtime CLI flags are honoured by GPL builds. You just can't generate deployments there. The target machine still needs Serial Studio installed.

What if the user has multiple devices and the deployment points at one of them? The recovery dialog's Pick Different Device page lets them switch on the fly without leaving runtime mode. The deployment's auto-connect behaviour is a starting point, not a hard wire.

Does the deployment survive a Serial Studio update? Usually yes. The deployment targets the Serial Studio executable by absolute path; package upgrades that overwrite the binary in place leave the deployment intact. Reinstalls that move the executable will require regenerating the deployment.

See also

• Project Lock: pair a locked project with a runtime deployment to limit the editor surface at the workstation.
• Operation Modes: how Project mode (the only one runtime deployments use) compares to QuickPlot and Console-Only.
• Project Editor: where the project that the deployment points to is built.
• CSV Export & Playback, Session Database: the recorders the Logging tab pre-arms.
• Pro vs Free Features: what's bundled with a Pro license.