XenseConsole

XenseConsole is a local web console for Xense devices that brings software updates, firmware upgrades, device diagnostics, and network maintenance into one interface.

Three update pathsWheel, Console, and MCU firmware

Device diagnosticsDDS discovery, gripper motion tests, and task logs

System maintenanceNetwork configuration and Python package inspection

Interface Overview

The top of the page includes:

• XenseConsole branding and title.
• Language switcher: 中文 / EN.
• Global status label.
• Refresh button: refreshes Wheel, Console, MCU, network and DDS status at once.
• Tabs: Updates and Info.

On the Updates page, tasks are split into three cards: Wheel, Console, and MCU. Each card contains, from top to bottom: an upload area, file information, install options, progress/status, and a log.

Updates Page

The Updates page performs three kinds of update tasks: Wheel updates, Console service updates, and MCU firmware updates.

Wheel Update

Wheel update: upload, install, and verify Python packages

The Wheel update uploads, installs, and verifies Python packages.

Supported files: *.whl

Basic workflow:

1. Drag a .whl file into the upload area, or click the area to select a file.
2. Click Upload Wheel.
3. After the upload succeeds, review the uploaded file, package name, wheel version, currently installed version, and storage path in the table.
4. Adjust the install options as needed.
5. Click Install Wheel.
6. Watch the progress bar, status table, and wheel log.

Install options:

Option	Default	Description
Delete uploaded file after install	On	Removes the wheel file from the upload directory after installation.
Restart xense service	On	Stops and restarts xense.service after installation.
Motion test after restart	Off	Runs a DDS gripper motion check after install and restart.
DDS service	empty	Auto-discovers gripper_* services when left empty; or enter a specific service name.
Test sequence	75 -> 65 -> 75 mm	Fixed target sequence for the motion test.

Wheel install backend behavior

Activate the target Python environment → run python -m pip install <wheel> --force-reinstall --no-deps → restart xense.service per the option → optionally run the DDS motion check. The status endpoint returns progress, exit code, message, stdout, and stderr.

Notes:

• Only .whl files are accepted.
• If the wheel contains native extensions, it must match the target machine's Python and architecture.
• The known target environment is aarch64, Python 3.10, glibc. Prepare a manylinux/aarch64 wheel; do not use a musllinux wheel just because the backend binary is a musl static build.

Console Service Update

Console update: upload a new version and safely restart the web service

The Console service update uploads a new XenseConsole binary from the page and restarts the current web service.

Supported file names:

XenseConsole
xense-console-backend-*

Basic workflow:

1. Drag in or select the Console binary.
2. Click Upload Console.
3. After the upload succeeds, check the uploaded file and its storage path.
4. Keep Delete uploaded file after install on as needed.
5. Click Install and restart Console.
6. Wait for the service install, health check, and restart.

Self-update protection:

• The new binary is installed to XENSE_CONSOLE_BIN_PATH, default /usr/local/bin/XenseConsole.
• The previous version is kept as a backup at /usr/local/bin/XenseConsole.bak.
• After restart, the service checks XENSE_CONSOLE_HEALTH_URL, default http://127.0.0.1:8080/health.
• If the health check fails, it rolls back to the backup and restarts the old version.

Notes:

• The uploaded file must be an AArch64 ELF64 little-endian binary.
• The current page may disconnect briefly during installation; this is normal while the service restarts.
• If the address and port stay the same, wait a moment and refresh the page.

MCU Firmware Update

MCU update: upgrade firmware over a serial port with YMODEM

The MCU firmware update uploads a .bin firmware image, upgrades the MCU over a serial port with the YMODEM protocol, and can optionally run a DDS motion closed-loop check.

Supported files: *.bin

Basic workflow:

1. Drag in or select a .bin firmware file.
2. Click Upload .bin.
3. After the upload succeeds, check the uploaded file, storage path, and serial port.
4. Enable Motion check after install as needed.
5. Click Install MCU firmware.
6. Watch the progress, bytes sent, status, and MCU log.

Install options:

Option	Default	Description
Delete uploaded file after install	On	Removes the uploaded .bin file after installation.
Motion check after install	Off	Runs a DDS motion check after the firmware is sent and the service is restored.
DDS service	empty	Auto-discovers gripper_* services when left empty.
Test sequence	75 -> 65 -> 75 mm	Fixed verification sequence.
Max speed	40	Speed limit for the motion test.
Max force	10	Force limit for the motion test.
Timeout (s)	20	Timeout for a single motion wait.
Tolerance (mm)	1	Allowed error for position feedback.

Notes:

• Do not power off the device during the update.
• If the serial port is occupied by another service, first confirm that xense.service can be stopped cleanly.
• If motion verification is enabled, the DDS service and the gripper status topic must be available.

Info Page

The Info page shows device runtime status and provides non-upgrade maintenance: DDS device discovery, gripper motion testing, network interface configuration, and the Python environment package list.

DDS Device Discovery

DDS discovery: inspect EzROS/DDS nodes, topics, and services

DDS device discovery scans EzROS/DDS nodes, topics, and services.

Configurable fields:

Field	Default	Description
Timeout (s)	5	Scan wait time; the frontend limits it to 1-30 s.
Domain ID	0	DDS Domain ID; the frontend limits it to 0-232.

The result table lists nodes, types, topic counts, and service counts. Expand a row to see the node's topics, type names, services, and service actions.

Device type inference:

• Node names starting with gripper_: type gripper.
• Node names starting with master_: type master.
• Other nodes: type sensor.

Gripper Motion Test

Motion test: verify gripper movement and position feedback over DDS

The gripper motion test drives the gripper directly over DDS with a fixed sequence: 75 mm -> 65 mm -> 75 mm.

Configurable fields:

Field	Default	Description
Domain ID	0	DDS Domain ID.
DDS service	empty	Auto-discovers gripper_* when left empty; or enter a service name.
Max speed	40	Speed limit sent to the motion service.
Max force	10	Force limit sent to the motion service.
Timeout (s)	20	Timeout for reaching the target position; the frontend limits it to 3-60 s.
Tolerance (mm)	1	Allowed error for closed-loop confirmation.
Closed-loop confirmation	Off	When enabled, waits for the status topic to reach the target position.

Usage tips:

• First confirm that a gripper_* device exists in DDS device discovery.
• Keep the DDS service empty when you are unsure of the service name, and let the system auto-discover it.
• Enabling closed-loop confirmation gives more reliable results but depends on the status topic being published.

Network Interface Configuration

Network configuration: inspect and maintain device IPv4 addresses

Network interface configuration shows and persistently maintains the IPv4 address of eth0.

The page shows: interface name (fixed to eth0), MAC address, interface state, IPv4 address list, default gateway, DNS, MTU, and IPv6 addresses.

Editable fields:

• IPv4 address list.
• Add IPv4/CIDR, e.g. 192.168.99.3/24.
• Gateway, e.g. 192.168.99.1.

Applying the configuration makes the backend:

• Write /etc/systemd/network/eth0.network.
• Run networkctl reload.
• Run networkctl reconfigure eth0.
• Refresh the runtime IPv4 addresses immediately.
• Replace the default route as needed.

Safety notes for changing IPs

• Always add the new IP before removing the old one.
• Before adding an IP, confirm the subnet is reachable from the current maintenance network (e.g. the maintenance computer or an upstream gateway can reach it).
• Use the correct CIDR prefix (e.g. 192.168.110.134/24) and make sure the gateway matches the subnet.
• After adding the new IP, verify from the maintenance computer that XenseConsole is reachable at the new address before removing the old one.
• Keep at least one IPv4 address.
• Only eth0 is managed; other interfaces do not appear in the frontend configuration list.
• If you remove the IP you are currently using, the web connection drops; reconnect using a kept or newly configured IP.
• The service usually runs as root, so passwordless sudo for normal users is not required.

Python Environment Packages

Environment packages: view package names and versions in the target Python environment

The Python environment packages panel lists the distribution packages installed in the target Python environment. Table columns: package name and version. Click the refresh button to reload the package information; after a wheel upload, the system also tries to refresh the installed version of the corresponding package.

Status, Progress, and Logs

All three update tasks share a common set of statuses:

Status	Meaning
Idle	No task is running.
Installing	The backend is running an update task.
Success	The task finished with a successful exit status.
Failed	The task failed; the message and log show the reason.

The progress bar shows backend task progress. The log area formats backend output with time, module, and level, for example:

[2026-06-08 12:00:00.000] [wheel/python] running pip install ...

If a task fails, check in this order:

1. The "Message" column in the status table.
2. The log of the corresponding update module.
3. The backend service log.

Backend log tail can be read via the API: GET /api/logs/tail?max_bytes=65536.

English Interface

The page supports Chinese and English. The language setting is stored in the browser local storage key xense-console-locale. After switching to English, the layout stays the same.

English Info page

English Updates page

Troubleshooting

Symptom	Possible cause and fix
scp reports permission denied or missing directory	Make sure REMOTE_DIR exists and the account can write to it; run mkdir -p first
Permission denied on start	You forgot to chmod +x, or the file platform does not match (e.g. a Windows executable copied to an ARM device)
The process exits immediately	Redirect the log to a file first and check for missing libraries or configuration errors
The program runs but cannot connect	Check whether the process is listening on the port and the device firewall (ufw status / firewall-cmd --list-all)
Wheel install fails	Confirm the .whl matches the target Python version and architecture (use a manylinux wheel for aarch64 / Python 3.10 / glibc)
Page unreachable after Console update	The service restart is normal; wait and refresh. If it still fails, check the backup at /usr/local/bin/XenseConsole.bak and the health check log
Web page drops after changing IP	You used the IP you were accessing or the gateway does not match; reconnect with a kept or newly configured IP
Motion test fails	First confirm a gripper_* device exists in DDS discovery, then check the status topic and the DDS service name