GUI Web

The Web Graphic User Interface is implemented using Flask, Bootstrap 5, jQuery, Socket.IO, and Chart.js. It serves as both a fully functional interface and an example of how to build a custom GUI using pyX2Cscope. This interface allows you to use multiple browser windows or access the application from smart devices on the same network.

The server runs by default on your local machine and does not allow external access. The default port is 5000 and the interface will be accessible at http://localhost:5000

Starting the Web GUI

Start the Web GUI with the following command:

python -m pyx2cscope -w

To open the server for external access (allowing connections from other devices on your network):

python -m pyx2cscope -w --host 0.0.0.0

To use a custom port:

python -m pyx2cscope -w -wp 8080

Command Line Options

Option	Description	Default
`-w`	Enable web GUI	-
`-wp`, `--web-port`	Web server port	5000
`--host`	Host address (use 0.0.0.0 for external access)	localhost

Interface Overview

The Web GUI consists of four main views accessible via the navigation bar:

Setup - Connection configuration
Watch View - Variable monitoring and modification
Scope View - Oscilloscope-like signal visualization
Dashboard - Custom widget-based monitoring
Scripting - Allows to run Python scritps with direct access to the x2cscope connection

Setup View

The Setup view is the starting point for establishing a connection to your microcontroller.

Interface Selection

Select the communication interface type:

Serial - For UART/USB-to-Serial connections
TCP/IP - For network-based connections
CAN - For CAN bus connections (coming soon)

Serial Configuration

When Serial is selected:

UART Dropdown - Select the COM port from the available ports list
Refresh Button - Click to rescan for available COM ports

TCP/IP Configuration

When TCP/IP is selected:

Host - Enter the IP address or hostname of the target device (default: localhost)
Port - Enter the TCP port number (default: 12666)

CAN Configuration (Coming Soon)

When CAN is selected:

Bus Type - USB or LAN
Channel - CAN channel number
Baudrate - 125K, 250K, 500K, or 1M
Mode - Standard or Extended
TX ID - Transmit message ID (hex)
RX ID - Receive message ID (hex)

ELF File Selection

Select an ELF file (or PKL/YML import file) containing the variable information from your firmware. Supported formats: .elf, .pkl, .yml

Connecting

Click the Connect button to establish communication with the target device. Once connected, the other views (Watch View, Scope View, Dashboard) become functional.

Watch View

The Watch View allows you to monitor and modify variables in real-time.

Adding Variables

Use the search dropdown to find and select a variable from the firmware
The variable will be added to the watch table

Variable Table Columns

Column	Description
Live	Checkbox to enable/disable live updates for this variable
Variable	The variable name
Type	Data type (int, float, etc.)
Value	Current raw value from the target
Scaling	Multiplication factor applied to the value
Offset	Offset added after scaling
Scaled Value	Calculated result: (Value x Scaling) + Offset
Actions	Write value and remove buttons

Live Updates

Click Refresh to manually update all variable values
Use the dropdown menu to set automatic refresh rates:
- Live @1s - Update every 1 second
- Live @3s - Update every 3 seconds
- Live @5s - Update every 5 seconds

Writing Values

To modify a variable value on the target:

Enter a new value in the Value column
Click the Write button (pencil icon) in the Actions column

Save/Load Configuration

Save - Export the current watch list to a .cfg file
Load - Import a previously saved watch list configuration

Scope View

The Scope View provides oscilloscope-like functionality for capturing and visualizing fast signals.

Scope Plot

The main chart displays captured waveforms. Features include:

Zoom - Use mouse scroll or pinch gestures to zoom in/out
Pan - Click and drag to pan the view
Reset Zoom - Use the Chart Actions menu to reset the view
Export Data - Export captured data to a file

Sample Control

The Sample Control panel manages data acquisition:

Control	Description
Sample	Start continuous sampling
Stop	Stop sampling
Burst	Capture a single frame of data
Sample Time	Prescaler value for sampling rate (1 = fastest)
Sampling Frequency	Display of the calculated sampling frequency

How Sampling Works

Click Sample to start continuous data acquisition
The firmware collects data points until the buffer is full
Data is transferred to the PC and displayed on the chart
The cycle repeats automatically until Stop is pressed
Use Burst mode to capture only one frame of data

Trigger Control

The Trigger Control panel configures when data capture begins:

Setting	Description
Trigger Enable/Disable	Enable triggers to start capture at a specific condition
Edge Detection	Rising edge or Falling edge detection
Level	The value threshold that triggers data capture
Delay	Pre/post trigger delay (-50% to +50%)

Trigger Modes

Disabled (Auto Mode)

Sampling starts immediately when requested
Useful for continuous signal monitoring

Enabled (Triggered Mode)

Sampling waits until the trigger condition is met
The trigger variable crosses the specified level in the specified direction
Pre-trigger delay (negative): Capture data before the trigger event
Post-trigger delay (positive): Capture data after the trigger event

Setting Up a Trigger

Enable the trigger by clicking Enable
Select Rising or Falling edge
Enter the trigger Level value
Set the Delay percentage:
- Negative values (-50 to 0): Pre-trigger - see what happened before the event
- Positive values (0 to +50): Post-trigger - see what happens after the event
Click Update Trigger to apply settings
In the Source Configuration, select which variable acts as the trigger source

Source Configuration (Variable Channels)

Configure up to 8 scope channels:

Column	Description
Trigger	Radio button to select this channel as the trigger source
Enable	Checkbox to include this channel in the capture
Variable	The variable name being monitored
Color	Click to change the waveform color on the chart
Gain	Visual scaling factor for display (does not affect raw data)
Offset	Visual offset for display (does not affect raw data)
Remove	Delete this channel from the scope

Adding Channels

Use the search dropdown to find a variable
The variable is automatically added as a new channel
Enable the channel checkbox to include it in captures

Tips for Best Results

Start with Sample Time = 1 for maximum resolution
Increase Sample Time to capture longer time periods
Use Gain to scale signals for better visualization
Use Offset to separate overlapping waveforms
Set up triggers to capture specific events consistently

Dashboard View

The Dashboard provides a customizable interface with drag-and-drop widgets for monitoring and controlling variables.

Edit Mode

Click the Edit button in the toolbar to enter edit mode:

A widget palette appears on the left side
Existing widgets can be moved and resized
New widgets can be added from the palette

Available Widgets

Widget Type	Description
Button	Write values to variables on press/release
Gauge	Circular gauge displaying a variable value
Label	Text placeholder, no write/read of variables
Number	Numeric display of a variable
Plot Logger	Plots data continuously as a logger
Plot Scope	Plots scope data, use together with Scope Control widget
Scope Control	Variable and Trigger configuration for scope functionality
Slider	Slider control to write values to a variable
Switch	On/Off toggle switch to write values to a variable
Text	Display text values of a variable

Adding Widgets

Enter Edit Mode
Click a widget type in the palette
Configure the widget:
- Select the target variable
- Set widget-specific options (min/max values, labels, etc.)
Click Add Widget
Position and resize the widget on the canvas

Update Rate

The update rate controls how frequently a widget reads its variable value from the target device.

Setting	Description
Off (0)	No automatic updates - value is read only on manual refresh
Live	Update as fast as possible (continuous polling)
Interval (seconds)	Update at specified interval (0.5s, 1s, 2s, 5s, etc.)

Widgets that support Update Rate:

Widget	Update Rate	Reason
Button	Yes	May reflect current variable state
Gauge	Yes	Displays live variable value
Number	Yes	Displays live variable value
Plot Logger	Yes	Continuously logs data points
Slider	Yes	May sync with current value
Switch	Yes	May reflect current state
Text	Yes	Displays live variable value

Widgets that do NOT use Update Rate:

Widget	Reason
Label	Static text, no variable binding
Plot Scope	Uses scope sampling mechanism (controlled by Scope Control)
Scope Control	Configuration widget, triggers scope sampling

Save/Load Layout

Save Layout - Save the current dashboard configuration to a JSON file
Load Layout - Load a previously saved dashboard layout
Layouts include widget positions, sizes, and configurations

Dashboard Toolbar

Button	Description
Edit	Toggle edit mode on/off
Save	Save current layout
Load	Load a saved layout
Export	Export the current Dashboard to a file
Import	Import a Dashboard from a file
Clear	Remove all widgets from the dashboard

Scripting View

The Scripting view allows you to run Python scripts that interact with the connected device.

Features

Load and execute Python scripts
Scripts have access to the x2cscope object for device communication
Real-time output display
Stop button to interrupt running scripts

Script API

Scripts can use the x2cscope global variable, you don’t need to instantiate it.

# Read a variable
value = x2cscope.get_variable("motor_speed").get_value()
print(f"Motor speed: {value}")

# Write a variable
x2cscope.get_variable("target_speed").set_value(1000)

# Check if stop was requested
if stop_requested():
    print("Script stopped by user")

Special Function Registers (SFR)

The Web GUI exposes SFR access through an SFR toggle switch placed inline next to every variable search dropdown.

Watch View and Scope View

Each view has an SFR toggle (Bootstrap form-switch) beside the Select2 search bar:

When the toggle is off (default) the dropdown searches firmware variables.
When the toggle is on the dropdown searches Special Function Registers instead.

Switching the toggle clears the current selection and reinitialises the dropdown so the next search already queries the correct namespace. When an SFR is selected and added to the watch or scope table it is retrieved with sfr=True on the backend, mapping it to its fixed hardware address.

Dashboard

The widget configuration modal includes the same SFR toggle above the variable name selector. The toggle resets to off every time the modal is opened and behaves identically to the Watch/Scope toggles described above.

Tips and Best Practices

Performance

The web interface uses WebSocket for real-time updates
For best performance, limit the number of live-updating variables
Use Burst mode in Scope View for one-time captures

Network Access

By default, the server only accepts local connections
Use --host 0.0.0.0 to allow network access
Consider network security when exposing the interface

Browser Compatibility

The Web GUI is tested with modern browsers:

Chrome (recommended)
Firefox
Edge
Safari

Troubleshooting

Issue	Solution
Cannot connect	Check COM port selection, ensure device is powered
No variables shown	Verify ELF file matches the running firmware
Scope not updating	Check that channels are enabled and sampling is started
Scope not updating	Check the trigger level is in range of Variable’s values
Dashboard not saving	Ensure browser allows local storage

API Endpoints

For advanced users, the Web GUI exposes REST API endpoints:

Endpoint	Method	Description
`/connect`	POST	Establish connection
`/disconnect`	POST	Close connection
`/is-connected`	GET	Check connection status
`/variables`	GET	Get list of available variables
`/serial-ports`	GET	Get available COM ports

Additional information can be found in the API documentation.