Widget Configuration

This guide explains how to configure dashboard widgets, including data sources (readers), outputs (writers), and visual options.

Widget Editor Overview

Click the + button in the dashboard toolbar to open the Widget Editor. The editor has three main areas:

Preview Panel (top-left) - Live preview of your widget as you configure it
Configuration Panel (bottom-left) - Reader/Writer and Widget options tabs
Widget Selector (right) - Choose between Charts and Controls

Creating a New Widget

Step 1: Choose Widget Category

Use the Charts / Controls tabs in the right panel:

Charts - Display widgets that show data (Time Series, Gauges, Console)
Controls - Input widgets that send data (Slider, Toggle, Knob, etc.)

Step 2: Select Widget Type

Click on a widget type card to select it. The preview updates immediately.

Chart Categories:

Category	Widget Types
Charts	Time Series (Multi-Axis Line Chart), Shared Y-Axis (Shared Y-Axis Line Chart)
Debug	Console
Automotive	Radial Gauge, Linear Gauge
Industrial	Coming soon

Control Categories:

Category	Widget Types
Basic	Slider, Toggle, Numeric
Advanced	Knob, Stepper

Step 3: Configure Data Sources

For Chart widgets, configure Readers in the Reader(s) tab. For Control widgets, configure Writers in the Writer(s) tab.

Step 4: Customize Appearance

Switch to the Widget tab to configure visual options specific to each widget type.

Step 5: Add to Dashboard

Click Add to dashboard (or Modify widget when editing) to save.

Reader Types

Readers define how data is extracted from CAN frames or system metrics and fed to chart widgets.

Raw Reader (ReaderRaw)

The most common reader type. Manually configure CAN signal extraction.

Field	Description
Name	Display name for the signal (shown in legends)
Color	Line/gauge color for this signal
Channel	CAN channel: 1 or 2
CAN ID	Arbitration ID in decimal (e.g., 291 for 0x123)
Bit Start	First bit position (0-63)
Bit End	Last bit position (0-63)
Byte Order	Little endian (Intel) or Big endian (Motorola)
Signal Type	Unsigned, Signed, Float, or Double
Factor	Multiplier for scaling (physical = raw × factor + offset)
Offset	Offset for scaling
Disabled	Toggle to temporarily disable without removing

Example: To read a 16-bit unsigned speed signal from CAN ID 0x123, bytes 0-1:

Channel: 1, CAN ID: 291, Bit Start: 0, Bit End: 15
Byte Order: Little, Signal Type: Unsigned
Factor: 0.01, Offset: 0

DBC Reader (Signal Picker)

Import signals directly from a DBC file:

Click Add Reader → DBC
The Signal Picker modal opens
Select one or more signals from your uploaded DBC files
Click Import to add them as readers

Benefits: automatic CAN ID, bit positions, encoding, factor, offset, and unit.

Plugin Reader (ReaderPlugin)

Use readers provided by Orbit plugins for custom data processing.

Field	Description
Plugin	Select the installed plugin
Reader	Choose the reader exposed by the plugin
Channel	CAN channel for frame routing
Config	Plugin-specific configuration options

System Reader (ReaderSystem)

Display system metrics instead of CAN data.

Field	Available Metrics
Load Metrics	CPU Usage (%), Load Average (1/5/15 min)
RAM Metrics	Used (MB), Total (MB), Usage (%)
Temperature	Core 0/1, Board temperature (°C)
Disk (eMMC)	Free (MB), Total (MB), Usage (%)
Disk (SD Card)	Free (MB), Total (MB), Usage (%)
Logger	Messages logged, Errors, Flush time (ms)

Available System Stat Fields:

Field ID	Description	Unit
`load_usage`	CPU usage percentage	%
`load_one`	1-minute load average	-
`load_five`	5-minute load average	-
`load_fifteen`	15-minute load average	-
`ram_used`	RAM currently used	MB
`ram_total`	Total RAM	MB
`ram_percent`	RAM usage percentage	%
`temp_core_0`	CPU core 0 temperature	°C
`temp_core_1`	CPU core 1 temperature	°C
`temp_board_0`	Board temperature	°C
`disk_emmc_free`	eMMC free space	MB
`disk_emmc_total`	eMMC total space	MB
`disk_emmc_percent`	eMMC usage percentage	%
`disk_sd_free`	SD card free space	MB
`disk_sd_total`	SD card total space	MB
`disk_sd_percent`	SD card usage percentage	%
`logger_messages`	Total messages logged	count
`logger_errors`	Logger error count	count
`logger_flush_time`	Last flush time	ms

Derived Reader (ReaderDerived)

Combine multiple signals into a single computed value using mathematical expressions. Derived readers are self-contained — each one defines its own source signals internally, independent of other readers in the widget.

Configuration:

Field	Description
Name	Display name for the computed signal (shown in legends)
Color	Line/gauge color for this signal
Source Signals	One or more embedded readers (Raw, DBC, Plugin, or System) that provide input values
Expression	Mathematical formula using source variable names (A, B, C...)

Adding Source Signals:

Click the + button in the Source Signals section. The dropdown shows the same reader types available at the widget level (Raw Signal, DBC Import, Plugin, System Stats) — except Derived, to prevent nesting.

Each source is assigned a variable letter (A, B, C...) that you use in the expression. Sources are fully configurable inline — expand them to edit CAN ID, bit range, factor, offset, etc., just like standalone readers.

Expression Syntax:

Category	Supported
Operators	`+`, `-`, `*`, `/`, `^` (power)
Grouping	Parentheses `( )`
Functions	`sin`, `cos`, `tan`, `abs`, `sqrt`, `pow`, `min`, `max`, `floor`, `ceil`, `round`, `log`, `ln`
Constants	`pi`, `e`

Quick Formulas: When two or more sources are added, quick formula buttons appear for common operations: sum, difference, product, ratio, percentage difference, and magnitude.

Expression Examples:

Expression	Description
`A + B`	Sum of two signals
`A * 0.01 + 273.15`	Scale and offset a single signal
`(A - B) / (A + B) * 100`	Percentage difference
`sqrt(A^2 + B^2)`	Vector magnitude from two components
`A / B`	Ratio (near-zero divisors are clamped to avoid infinity)

How It Works:

Each source signal subscribes independently to its data stream (CAN bus, system stats, or plugin)
When any source updates, the expression is re-evaluated with the latest values from all sources
The computed result is emitted as a new data point to the chart
If not all sources have received at least one value yet, no output is produced

Tip: Derived readers work with all chart types — time series, radial gauges, linear gauges, and shared-axis charts.

Writer Types

Writers define how control widget values are encoded and transmitted to the CAN bus or agents.

CAN Frame Writer (WriterCanFrame)

Send CAN frames directly to the bus. Supports multiple signals per frame.

Frame Configuration:

Field	Description
Name	Display name for the writer
Channel	CAN channel: 1 or 2
CAN ID	Arbitration ID in decimal
Frame Type	Standard (11-bit) or Extended (29-bit)
FD Mode	Classic CAN or CAN FD
DLC	Data Length Code (1-8 for classic, 1-64 for FD)

Signal Configuration (per signal):

Field	Description
Name	Signal name
Color	Display color for the control
Bit Start/End	Bit position within the frame
Byte Order	Little or Big endian
Signal Type	Unsigned, Signed, Float, Double
Factor	Scaling factor (raw = (physical - offset) / factor)
Offset	Scaling offset
Min/Max	Value limits for UI controls

DBC Import: You can populate CAN Frame writers from DBC files for accurate signal definitions.

Agent API Writer (WriterAgentApi)

Control signals via an external agent process using REST API.

Field	Description
Agent Name	Name of the agent to control
Signals	List of signals to control from this agent

Per-Signal: Signal Name, Min/Max Value, Step, Unit.

Plugin Writer (WriterPlugin)

Use writers provided by Orbit plugins for custom encoding or protocol handling.

Field	Description
Plugin	Select the installed plugin
Writer	Choose the writer exposed by the plugin
Channel	CAN channel for transmission
Config	Plugin-specific configuration options

Widget Options

Each widget type has specific configuration options available in the Widget tab.

Time Series Options

Option	Description
Title	Chart title displayed in header
X-Axis Range Mode	Scrolling (fixed window) or Auto-fit
Scrolling Window	Window size in milliseconds when scrolling
Tick Format	Time format for X-axis labels
Y-Axis Configs	Per-axis min, max, and auto-scale settings

Radial Gauge Options

Option	Description
Title	Widget title
Gap	Spacing between multiple gauges
Template	Preset style (Speedometer, Tachometer, etc.)
Per-Gauge Overrides	Customize individual gauge appearance

Linear Gauge Options

Option	Description
Title	Widget title
Orientation	Horizontal or Vertical
Gap	Spacing between multiple gauges
Template	Preset style for gauge appearance

Console Chart Options

Option	Description
Title	Widget title
Channel	CAN channel to display (1 or 2)
Max Lines	Maximum rows to keep in buffer
Auto-scroll	Scroll to newest frames automatically
Show Timestamp	Display timestamp column
Show Delta	Show time delta between frames
Font Size	Text size in pixels

Control Widget Options

Common options for all control widgets:

Option	Description
Title	Widget title
Layout	Grid or List arrangement
Gap	Spacing between controls

Slider-specific: Orientation (Horizontal or Vertical).

Reader Limits by Widget Type

Widget Type	Max Readers	Notes
Time Series	50	Multiple series on multiple Y-axes
Radial Gauge	8	One gauge per reader
Linear Gauge	8	One gauge per reader
Console Chart	50	Filters by CAN ID

When adding readers beyond the limit, they are automatically disabled.

Tips

Use DBC Import - Import signals from DBC files for accurate configuration
Test with Live Data - Configure widgets while live data is flowing to verify signal extraction
Name Signals Clearly - Use descriptive names that indicate the signal's meaning
Set Appropriate Ranges - Configure min/max values for gauges and controls
Use Color Coding - Assign distinct colors to related signals for easy identification
Disable Unused Readers - Instead of deleting, disable readers you might need later
Check Units - Verify that factor and offset produce values in the expected units