Application Management

Adapnex tools provide end-to-end management for application binaries running on industrial hardware. You can deploy versioned updates, monitor process output, manage auto-restart supervision, and attach interactive debuggers using either the VS Code extension or the Adapnex CLI.

Deploying Applications

The primary command for deploying and executing code on a remote controller is adapnex app run.

Basic Deployment

To compile a CMake target and launch it on a controller:

adapnex app run line_1_plc conveyor_app

When you execute this command:

  1. The build system cross-compiles the target for the controller architecture.

  2. The compiled binary is packaged and securely transferred to the controller.

  3. The Adapnex Daemon manages versioning automatically, creating an isolated version directory with an incremented version number.

  4. The daemon launches the application and streams standard console output and errors back to your workstation.

In the VS Code extension, you can achieve the identical deployment by clicking the Run on Target button next to your device in the Adapnex sidebar.

Accompanying Assets and Configurations

If your application requires configuration files, recipe definitions, or assets, pass them as additional arguments:

adapnex app run line_1_plc conveyor_app ./config.json ./calibration.csv

The uploaded assets are placed alongside the executable in its working directory on the target controller.

Multi-Application Hosting

You can run multiple distinct applications simultaneously on a single controller by assigning logical names using the --app flag:

adapnex app run line_1_plc pump_controller --app pump
adapnex app run line_1_plc ventilation_fan --app ventilation

Each named application maintains its own versioning, supervision lifecycle, and output streams. If omitted, --app defaults to "main".

Execution Modes

Adapnex supports both interactive monitoring during commissioning and unattended background operation in production.

Attached Mode

By default, adapnex app run operates in attached mode. Your terminal remains connected to the controller, displaying live output in real time.

If you disconnect your terminal or press Ctrl+C, the application continues running undisturbed on the controller. You can reattach to the live console stream at any time using adapnex app attach:

adapnex app attach line_1_plc

Detached Background Mode

For production environments where applications must run continuously in the background without keeping a terminal open, use the --detached flag:

adapnex app run line_1_plc conveyor_app --detached

The command exits immediately after verifying process launch, returning control to your terminal while the application runs under daemon supervision.

Process Supervision and Restart Policies

The daemon continuously supervises running applications. If an unhandled exception causes a process to crash, or if the physical controller reboots after a power interruption, the daemon automatically restarts the application.

For one-off maintenance routines, sensor calibration scripts, or diagnostic utilities that should not restart, supply the --once flag:

adapnex app run line_1_plc calibrate_sensors --once

When started with --once, the daemon allows the process to exit normally upon completion without triggering an automatic restart.

Inspecting Application State

To view all managed applications and their active status on a controller, run adapnex app list:

adapnex app list line_1_plc

The output displays the application name, execution status, auto-restart policy, executable name, and version:

╭──────────┬─────────┬──────────────┬─────────────────────┬────────────╮
│   App    │ Status  │ Auto Restart │     Executable      │  Version   │
├──────────┼─────────┼──────────────┼─────────────────────┼────────────┤
│ main     │ running │ enabled      │ conveyor_app        │ main_1     │
│ pump     │ running │ enabled      │ pump_controller     │ pump_3     │
│ cal      │ stopped │ disabled     │ calibrate_sensors   │ cal_2      │
╰──────────┴─────────┴──────────────┴─────────────────────┴────────────╯

The Auto Restart column indicates whether automatic process restart is enabled. The Version column displays version identifiers formatted as <app>_<version_number>, which the daemon increments automatically on each deployment.

In the VS Code extension, expanding a controller in the Devices explorer displays an Apps entry listing all applications on the device.

Lifecycle Control

Attaching to Output

To view the live console output of a background application, use adapnex app attach:

adapnex app attach line_1_plc --app pump

Disconnecting your terminal leaves the application running on the controller.

Stopping and Starting Applications

To terminate a running process, use adapnex app stop:

adapnex app stop line_1_plc --app pump

If auto-restart is enabled, stopping an application suspends it until the controller reboots or until you explicitly start it again.

To start a stopped application using its previously deployed binary, use adapnex app start:

adapnex app start line_1_plc --app pump --detached

Removing Applications

To stop an application and delete its binaries and associated files from the controller, use adapnex app remove:

adapnex app remove line_1_plc --app pump

In the VS Code extension, applications listed under the Apps node provide inline action buttons: a running application displays Stop App and Remove App buttons, while a stopped application displays Start App and Remove App buttons.

Remote Interactive Debugging

Debugging embedded industrial controllers typically requires tedious manual setup with remote debug servers and port redirection. Adapnex integrates remote debugging directly into your workflow.

Fast One-Click Debugging with VS Code

The Adapnex VS Code extension offers a seamless, out-of-the-box debugging experience. Simply set your breakpoints in the source editor and click the Run on Target button next to each device in the Adapnex sidebar.

The extension automatically:

  1. Cross-compiles the application with debug symbols enabled.

  2. Deploys the binary and launches it under remote debug supervision.

  3. Establishes an encrypted debugging tunnel between your workstation and the controller.

  4. Attaches the debugger using LLDB, halting execution at your breakpoints.

You can inspect local variables, evaluate memory registers, step through real-time task execution, and view thread stacks directly inside the editor.

Command-Line Debugging with LLDB and GDB

For terminal-based workflows or CI environments, you can start a remote debugging session using the CLI.

To deploy and pause an application at startup for debugging:

adapnex app run line_1_plc conveyor_app --debug

The CLI establishes a secure tunnel and listens on localhost:1234. You can specify a different local port using --port <number>.

To debug an application that is already running on the controller:

adapnex app attach line_1_plc --debug

Once the tunnel is active, you can attach using either LLDB or GDB.

Connecting with LLDB

Launch LLDB on your workstation and connect to the forwarded port using the gdb-remote command:

lldb ./build_wago_cc100/conveyor_app
(lldb) gdb-remote localhost:1234
(lldb) breakpoint set --name MotorController::Update
(lldb) continue

Connecting with GDB

Launch your architecture-compatible GDB binary on your workstation and connect to the local port:

gdb-multiarch ./build_wago_cc100/conveyor_app
(gdb) target remote localhost:1234
(gdb) break MotorController::Update
(gdb) continue