doc/help/Auto-Generating-Projects.md
For three of the most painful protocol configurations, Serial Studio can build the project for you from a vendor file. Drop in a .dbc for CAN Bus, a register-map CSV/XML/JSON for Modbus, or a .proto schema for Protocol Buffers, and you get back a complete .ssproj with groups, datasets, dashboard widgets, and a working frame parser. No hand-typed register addresses, no copy-paste from PDFs.
The DBC and Modbus importers live in the Setup Panel of the relevant driver and are Pro features. The Protobuf importer lives in the Project Editor toolbar (Import > Protobuf), applies to any transport that delivers a serialized message blob, and is available in all builds. (Any Pro widgets the generated projects use still require a license, but .proto import itself does not.)
Hand-configuring an industrial protocol is the slow part of using Serial Studio. A typical PLC has dozens of holding registers, each with a name, data type, scale factor, and units. A typical automotive ECU has hundreds of CAN signals across multiple message IDs. Typing those into the Project Editor one at a time is tedious and error-prone.
The shortcut is to start from the file the vendor already wrote. CAN networks are documented in .dbc files. Modbus devices are documented in register tables. Serial Studio reads those directly.
Both importers produce the same shape of output:
.ssproj) with one or more groups representing logical chunks of the device (a CAN message, a contiguous Modbus register block).title, units, min/max, scale, and a sensible default widget (gauge, bar, plot, LED, accelerometer, GPS, depending on what the importer can infer).MESSAGES table or a per-block BLOCKS table) plus a generic decoder whose map comes from the imported file; the source starts on the Lua platform. The Protobuf import emits a Lua varint/length-delimited decoder.The result is a project that is already wired up. From there you arrange widgets in workspaces, adjust titles, and connect.
| Importer | Source format | Driver pre-load | Output |
|---|---|---|---|
| DBC | .dbc | No | Project + Lua parser, signals grouped by CAN ID |
| Modbus map | .csv / .xml / .json | Yes (register groups) | Project + Lua parser, registers grouped by type/contiguity |
| Protobuf | .proto | No | Project + Lua parser, groups per message, recursive descent into nested messages |
All three importers preview before committing. You see the parsed messages, registers, or fields, click Create Project, and a .ssproj is generated and opened in the Project Editor.
A DBC (CAN Database) file describes every message and signal on a CAN network: message IDs, signal bit positions, byte order, scaling, units, and value tables. Most automotive and industrial CAN networks come with one. Serial Studio's importer parses it with Qt's QCanDbcFileParser and turns each message into a group.
.dbc. Serial Studio parses it and shows a preview listing every message: 1: EngineData @ 0x100 (5 signals), 2: VehicleSpeed @ 0x101 (2 signals), and so on.Messages are sorted by CAN ID so dataset positions stay stable across re-imports.
For each CAN message:
MESSAGES spec) that selects the message by CAN ID, extracts each signal at the correct bit offset and byte order, applies factor and offset, and publishes the value, which each dataset reads back through its transform.The DBC importer is fairly aggressive about picking the right widget. It looks at signal names and groupings to detect:
If the inference picks the wrong widget, change it in the Project Editor. The generated parser doesn't care which widget renders the value.
Simple multiplexing is supported. When a message declares a MultiplexorSwitch (the selector signal in the DBC) plus one or more MultiplexedSignal entries, the importer:
<name> (selector).<name> (mux N) so you can distinguish payloads that share the same bits.Extended multiplexing (DBC SG_MUL_VAL_ rows, SwitchAndSignal intermediates, multi-range parents) is not supported. Those signals are skipped during import; the post-import dialog tells you how many were dropped. To handle them, switch the source to Lua or JavaScript and write a custom parser.
Modbus register maps come in a hundred ad-hoc formats. Serial Studio accepts the three most common ones (CSV, XML, JSON), auto-detects which one it is from the file extension, and groups contiguous registers of the same type into one register group for efficient polling.
.csv, .xml, or .json file.1: Temperature @ 0 (Holding Registers, uint16) [°C], 2: Pressure @ 1 (Holding Registers, uint16) [PSI], ....ssproj.For each contiguous block of same-type registers (holding, input, coil, discrete input):
BLOCKS spec) that decodes each register from the Modbus response (handling word order for 32-bit and 64-bit values automatically).The detailed format spec for CSV, XML, and JSON register maps lives in Protocol Setup Guides → Modbus Register Map Import. Highlights:
address, name, type, dataType, units, min, max, scale, offset. Common aliases (addr, register, data_type, etc.) are auto-recognized. # lines are comments.<register address="0" type="holding" .../>) or nested (<holding-registers><register address="0" .../></holding-registers>) form.You can usually get going with just address and name. Everything else has reasonable defaults.
Protocol Buffers is a schema-defined binary serialization format from Google, widely used by drones, robotics stacks, and any device whose firmware was written against protoc. A .proto file declares messages, fields, scalar types, and tags; the device serialises one of those messages per frame and the receiver decodes it back into named values.
Serial Studio's importer parses the schema directly (no protoc invocation, no generated code) and produces a project that decodes the wire format at runtime using a hand-written varint/length-delimited reader emitted into the frame parser.
.proto schema file.repeated flag..ssproj is generated and opened in the editor.The importer does not load the result into any specific driver. You wire the project to whatever transport delivers the serialised bytes (UART, TCP, MQTT, BLE, anything that yields a complete message blob per frame).
Strings, bytes, enums, and maps decode to their natural Lua representations; repeated scalar fields decode into arrays. Nested messages are flattened into the dataset list in declaration order so the dashboard layout follows the schema.
proto3 syntax. Imports the subset that covers scalar fields, nested messages, enums, repeated, oneof (flattened to plain fields), and map<K, V> (decoded as a repeated bytes field). service and RPC blocks are skipped, and message types whose definitions are not present in the file (including Any and the Well-Known Types) are not expanded into datasets.Auto-generation is the right call when:
.dbc, a register-map file, or a .proto schema and it's reasonably accurate.Build the project by hand when:
oneof, map, Any).The generated project is a project like any other. Once it's open in the Project Editor, everything is editable: rename datasets, regroup them, swap widgets, add transforms, attach datasets to workspaces. The importer produces a starting layout, not a fixed one. DBC and Modbus imports configure a generated Lua parser whose signal/register map comes from the imported file: re-import to regenerate the map, edit the Lua directly, or switch the source's parser platform to JavaScript for custom decoding logic. The Protobuf parser is generated Lua and can be edited directly.
If you need to re-import (the vendor published a new DBC, you added a register, the protobuf schema gained a field), the safest path is to import again as a new project and copy over your dashboard customizations, rather than trying to merge by hand.