WEDA Node Installation Guide

This guide covers WEDA Node installation and local service management on an edge device. For Cloud registration and credential preparation, see Register WEDA Node.

The package contains two separate tools. Run install.sh to place the WEDA Node files and WEDA Node Activator onto the device. Then use the Activator terminal application to configure and start the WEDA Node services.

Before You Start

What You Need

Item	Description	Where to Get It
Edge Device	Linux-based system (Ubuntu, Debian, Yocto, Jetson/L4T)	Your hardware
Installer Package	`weda-installer-ubuntu-{arch}-v{version}-build.{build}-{online\|offline}.tgz`	Download
Terminal Access	SSH or direct terminal access	Your infrastructure

System Requirements

Note: WEDA Node minimum requirements

The requirements below cover WEDA Node itself. When sizing the device, also account for the operating system, platform SDKs and planned application workloads. Check free space on the filesystems used by Docker, model files and application data as well as /opt.

Mandatory System Environment
- Operating System: Linux (Ubuntu, Debian, Yocto, Jetson/L4T)
- User Permissions: Root (sudo) access required to write to /opt, /etc, and to manage Docker
- Terminal Size: Recommended 100 columns x 30 rows - the Activator does not block on smaller terminals, but layout, help text, and status boxes may wrap or clip below this size
- Architecture: x64 (x86_64) or ARM64 (aarch64)
Mandatory Software Dependencies
- Docker Engine v27.5 or above, installed and running
- Docker Compose plugin v2.32.4 or above (or docker-compose standalone)
- Filesystem access to create and modify directories in /opt/Advantech
Mandatory Hardware & Networking
- At least one physical Ethernet interface (e.g., eth0, eno1)
- Minimum 512 MB free RAM
- Minimum 1 GB free disk space in /opt
Outbound Connectivity
- HTTPS (port 443) to your configured WEDA site and messaging (port 4222) to its WEDA Core Message Service
- For an online installer package, HTTPS access to the container registries used to download WEDA Node images
- An offline installer package includes container images for local loading. WEDA Node still needs access to its configured WEDA Core environment to activate and communicate
- Tunnel service connectivity (port 58443) when using Tunnel features
- Local messaging port 4224 must be free (used for local WEDA Node communication)

Pre-Flight Verification Script

The pre-flight script is included in the installer package, so extract the package you downloaded before running it. From the extracted directory:

sudo ./verify-requirements.sh

The script reports [PASS], [WARN], or [FAIL] for each requirement and saves a detailed plain-text report as weda-requirements-YYYYMMDD-HHMMSS.txt. Resolve all [FAIL] items before proceeding.

Terminal Setup

Ensure your terminal meets these requirements before launching:

stty size                    # check current size - "30 100" recommended
resize -s 30 100            # resize if needed
export TERM=xterm-256color  # ensure 256-color mode

Font: A Unicode-capable font is required for status icons (●, ⚠, ✗, ○). Nerd Fonts and Cascadia Code both work.

Running the Installer

The installer package deploys WEDA Node and WEDA Node Activator onto the device. Run this step once per device or during device image creation.

Use the exact version, build number, architecture and online or offline variant of the package you downloaded. The examples below use the v1.2.0_20261016.2 build 33757 package layout. Change PACKAGE_VERSION and PACKAGE_VARIANT to match your file before running the commands.

The archive filename includes ubuntu, while the directory inside it starts with weda-installer-x64- or weda-installer-arm64-.

Ubuntu/Debian - x64:

PACKAGE_VERSION='v1.2.0_20261016.2-build.33757'
PACKAGE_VARIANT='online'
tar -xzf "weda-installer-ubuntu-x64-${PACKAGE_VERSION}-${PACKAGE_VARIANT}.tgz"
cd "weda-installer-x64-${PACKAGE_VERSION}-${PACKAGE_VARIANT}"
sudo ./verify-requirements.sh
sudo ./install.sh

Ubuntu/Debian - ARM64:

PACKAGE_VERSION='v1.2.0_20261016.2-build.33757'
PACKAGE_VARIANT='online'
tar -xzf "weda-installer-ubuntu-arm64-${PACKAGE_VERSION}-${PACKAGE_VARIANT}.tgz"
cd "weda-installer-arm64-${PACKAGE_VERSION}-${PACKAGE_VARIANT}"
sudo ./verify-requirements.sh
sudo ./install.sh

What install.sh does:

Installs the WEDA Node Docker service stack configuration to /opt/Advantech/dmagent/
Places the WEDA Node Activator binary at /opt/Advantech/dmagent/weda-node-activator/bin/weda-node-activator
Sets up required directories and file permissions
Creates a desktop shortcut (~/Desktop/weda-node.desktop) for easy access on GUI systems

After install.sh completes, the WEDA Node service is not yet running. You must launch WEDA Node Activator to set up and start it.

Starting WEDA Node Activator

# Must be run with sudo (required for Docker operations and /opt file access)
sudo /opt/Advantech/dmagent/weda-node-activator/bin/weda-node-activator

Note: The application will refuse to start without sudo / root privileges.

After launch you will see the main menu. The footer always shows the detected Device ID, Device Model, and Activator version (including the build number).

Before WEDA Node is set up:

┌──────────────────────────────────────────────────┐
│  WEDA Node Activator                             │
└──────────────────────────────────────────────────┘

Welcome to WEDA (WISE-Edge Developer Architecture)
Accelerating your Edge AI Development

╭──────────────────────────────────────────────────╮
│ WEDA Node Activator                              │
│                                                  │
│ Set up and manage your WEDA Node -- accelerate   │
│ Edge AI development and edge-cloud orchestration │
╰──────────────────────────────────────────────────╯

Main Menu

	 What is WEDA?
		 Learn about WEDA platform and features

 > Setup WEDA Node
		 Begin setup wizard

	 Exit
		 Close WEDA Node Activator

↑/↓: Navigate Menu • Enter: Select Option • Ctrl+C: Exit

WEDA Node Activator vx.x.x_xxxxxxxx.x (built xxxx-xx-xx xx:xx:xx) · Build #xxxxx  |  Device: 74fe488d5d54  |  Model: EPC-U2217

After WEDA Node is set up:

	 What is WEDA?
 > Manage WEDA Node
	 Exit

Navigation:

↑/↓ or j/k - move between items
Enter - select
Ctrl+C - quit (or q when cursor is on Exit)

Setting Up WEDA Node (First-Time Setup)

Select "Setup WEDA Node" from the main menu to run the setup wizard. The visible flow is short and depends on the credential source you pick:

Path	Screens shown to the user
Register & Connect (default)	License -> Credential Source -> Review and Confirm -> Installing / Verifying -> Service Status Overview
Use Local Credential File	License -> Credential Source -> Authentication Configuration -> Review and Confirm -> Installing / Verifying -> Service Status Overview

Two things to expect in the flow:

The device model is detected automatically. It appears read-only in the Review and Confirm summary. There is no screen for entering or editing it.
Installation and Cloud connectivity are separate checks. After installation, the wizard checks connection status and opens Service Status Overview. Opening this panel alone does not prove that activation or the Cloud connection succeeded. A Setup Failed screen reports an installation error.

License Agreement

	WEDA NODE SETUP WIZARD

License Agreement

Please review the WEDA Node license terms:

	[ ] I have read and accept the terms and conditions

Scroll to read • Space: Accept/Page Down • Enter: Continue (if accepted) • Esc: Cancel

Scroll to read the full license (↑/↓, j/k, PgUp/PgDn, Home/End)
At the bottom, press Space to check acceptance: [☑]
Press Enter to continue

Credential Source

Device Credential Setup

How would you like to set up your device credentials?

	⦿ Register & Connect device to WEDA site
			Connect to Public WEDA Site and provision this device

	○ Use Local Credential File
			I already have a device credential file (.bin) from WEDA Core

Use ↑/↓ to pick a source and press Enter. The wizard branches as follows:

Selection	Next screen	Use when
Register & Connect device to WEDA site (default)	Continue to Review and Confirm	Standard Advantech devices connecting to the public WEDA Cloud
Use Local Credential File	Continue to Authentication Configuration	A credential file has been prepared for your device or deployment

Authentication Configuration (local-file path only)

For Use Local Credential File, follow the authentication-method and file-selection steps in Local Credential File Path. Use the method that matches the file prepared for your device or deployment. After selecting the file, press n to continue to Review and Confirm.

Review and Confirm

Ready to Set Up

Review your setup configuration:

	Setup Settings

	Authentication:    Auto Provision
	Master Key:        /tmp/weda-public-masterKey-….bin
	Device Model:      EPC-R7300
	Location:          /opt/Advantech/dmagent
	Compose File:      /opt/Advantech/dmagent/docker-compose.yml
	Disk Space:        ~500MB

	Docker Services

	• WEDA Node(dmagent)
	• system-agent
	• watchtower

Services will start automatically after setup

Enter: Begin Setup • Esc: Go Back

Review the summary and press Enter to start. Services always auto-start - the wizard does not expose a "no auto-start" option here.

Installing / Verifying Connection

This screen runs in two phases:

Phase 1 - Setting Up WEDA Node:

The screen shows a stage checklist, live progress and elapsed time:

Prepare and copy files
Download container images, or load the images included in an offline package
Start services
Verify setup

Image download or loading time depends on the device, package and network. The installation phase has a 30-minute timeout. Keep the terminal open and do not interrupt setup with Ctrl+C.

Phase 2 - Verifying Connection:

Verifying Connection

Checking WEDA Node connection to server...

[ pulsing animation ]

Verification in Progress
Validating server connection...

After the connection-status check, the wizard opens Service Status Overview without a key press. Inspect the displayed values before treating the device as ready.

Check the result: For a device prepared for Cloud connection, confirm Provision State: Activated, Connection: Connected, and Service Status: Running. Running services alone do not confirm activation or connectivity.

Setup Failed (failure path only)

This screen reports an installation error. When installation completes without an error, the wizard checks the connection status and opens Service Status Overview, where you must verify the result.

Setup Failed

Setup encountered an error:

	<error message>

Troubleshooting:
	• Browse below URL: Request your WEDA Account & Register your device at
		WEDA server:
		https://learn.advantech.com/weda/docs/Introduction
	• Verify Docker is installed and running
	• Check WEDA Node Activator is running with root permissions
	• Check file permissions for device credentials/key files
	• Ensure sufficient disk space
	• Review system logs for details

Press Enter to return to main menu.

Esc: Device Credential Setup

Press Enter to return to the main menu, or Esc to jump back to Credential Source and try a different credential source.

Service Status Overview (Management Panel)

Open "Manage WEDA Node" from the main menu, or inspect this panel when the installation wizard opens it after the connection-status check. Confirm the status values rather than using the panel opening as proof of a successful Cloud connection.

┌──────────────────────────────────────────────────┐
│  WEDA Node Activator                             │
└──────────────────────────────────────────────────┘

Service Status Overview

╭──────────────────────────────────────────────────╮
│ WEDA Node Version: x.x.x_xxxxxxxx.x              │
│ Auth Method:       Auto Provision                │
│ Provision State:   Activated                     │
│ Connection:        Connected                     │
│ Service Status:    ● Running                     │
│                                                  │
│ Containers                                       │
│   ● dmagent                       2h 34m         │
│   ● system-agent                  2h 34m         │
│   ● watchtower                    2h 34m         │
│                                                  │
│ Device Information                               │
│   Device: Device ID: 74fe488d5d54, Model: ...    │
│   Server: <your-weda-site>:4222                  │
╰──────────────────────────────────────────────────╯

WEDA Node Version identifies the installed Node services. The Activator version shown in the footer identifies the management tool; the two versions can differ.

Status icons and labels:

● green - running / connected / activated (Connection and Provision State render as colored text without the bullet)
⚠ orange - degraded (running but unhealthy)
● red - stopped / failed

Provision State is driven by /opt/Advantech/dmagent/data/provision_state.json and displays the following labels:

Activated
Activation In Progress
Activation Pending
Waiting for Activation
Activation Failed
Unknown

An unfamiliar state appears as Unrecognized state (<raw state>). When dmagent is not running, the panel marks the recorded provision state as last known. Even a recorded Activated value is historical in this case and does not confirm that the device is currently connected.

Connection reads Connected only when dmagent is running, provisioning is Activated, authentication information is loaded, and a connection to the WEDA server's messaging service is established. Otherwise it reads Disconnected.

Values in the Service Status Overview auto-refresh every 5 seconds in the background.

Service Status Values

Status	Meaning
Running	All 3 containers (`dmagent`, `system-agent`, `watchtower`) are running and healthy
Degraded	One or more containers are stopped or unhealthy
Stopped	No containers are running

When Degraded, the status box shows which containers have issues:

│ Service Status:   ⚠ Degraded                     │
│                   system-agent -> not running    │

Press ? to toggle the troubleshooting panel when service status is Degraded.

Onboarding and Connection Hints

When Service Status is Running, Connection is Disconnected, and a provisioning or connection error is present, the status box appends an onboarding note with the WEDA Learn URL. This example shows an activation failure:

│ Provision State:  Activation Failed: <error>        │
│ Connection:       Disconnected                       │
│ Service Status:   ● Running                          │
│ ...                                                  │
│   [Note: Onboarding This Device ]                    │
│   Browse below URL: Request your WEDA Account &      │
│   Register your device at WEDA server                │
│   https://learn.advantech.com/weda/docs/Introduction │

The note can also appear with Provision State: Activated, for example when authentication information has not loaded or the server connection has failed. Read Provision State and Connection together to determine the next action. For registration and credential preparation, follow Register WEDA Node.

Management Actions

Management Actions

 > Update Authentication Credentials
		 Change WEDA Node authentication credentials

	 Restart Service
		 Restart all WEDA Node containers

	 Remove WEDA Node
		 Uninstall and remove all components

↑/↓: Navigate • Enter: Select Action • Esc: Back to Main Menu • Ctrl+C: Quit • ?: Troubleshooting

The ? hint only appears while Service Status is Degraded. Pressing it toggles the orange troubleshooting panel with the WEDA support URL. When the panel is open the hint changes to ?: Hide Troubleshooting.

Action	Description
Update Authentication Credentials	Apply a prepared provisioning key or device credential, restart the services, and verify the connection
Restart Service	Stop and restart the WEDA Node Docker containers
Remove WEDA Node	Remove WEDA Node services and configuration after you type `REMOVE` to confirm

Updating credentials: Prepare the correct file as described in the local credential path linked above. Applying it restarts services and temporarily interrupts their connection. If the new credential does not work, the Activator attempts to restore the previous credentials and restart the services. E5005 reports that the previous credentials were restored; check the status values again. E5006 reports that restoration failed; reapply a known working file before relying on the connection.

Removing WEDA Node: The Activator and its desktop launchers remain available so you can configure WEDA Node again. Removal deletes the WEDA Node containers, images, volumes and configuration. The Also remove WEDA Node operation data checkbox is unchecked by default, preserving /opt/Advantech/system-agent/weda-data/.

Caution: Removing operation data

Select Also remove WEDA Node operation data only when you intend to delete the retained operation data as well. Review this choice before typing REMOVE and confirming removal.

Keyboard Reference

Global

Key	Action
↑/↓ or j/k	Navigate
Enter	Select / Confirm
Esc or q	Cancel / Back
Ctrl+C	Force quit

Contextual

Screen	Key	Action
License	Space	Page down / check acceptance at bottom
File Picker	←	Go to parent directory
File Picker	→ / Enter	Open folder / select file
File Picker	n	Confirm selection and proceed
Management Panel	?	Toggle troubleshooting panel (when Degraded)
Remove Node	Space	Toggle "Also remove WEDA Node operation data" checkbox
Remove Node	Type `REMOVE`	Unlock the removal confirmation

Troubleshooting

Quick Diagnosis

Running with sudo? Required: sudo /opt/Advantech/dmagent/weda-node-activator/bin/weda-node-activator
Terminal large enough? stty size - 30 100 recommended (rows columns)
WEDA endpoints reachable? Check DNS and access to your configured WEDA site (HTTPS, port 443) and message-service endpoint (port 4222). For an online package, also check registry access; for Tunnel features, check port 58443. Use the actual endpoints provided for your deployment. You can check the site's HTTPS response with the following command after replacing the example URL:
```
WEDA_SITE_URL='https://weda.example.com'
curl -I "$WEDA_SITE_URL"
```
An HTTP response checks HTTPS reachability to that endpoint. Verify messaging, registry and Tunnel connectivity separately as applicable.
Docker running? sudo systemctl status docker

Display Problems

All three symptoms below come from terminal setup. The commands that fix them are in Terminal Setup, under Before You Start.

Icons appear as □ or ? The terminal font has no Unicode coverage. Switch to a Unicode-capable font and reconnect.

Colors missing TERM is not set to a 256-color mode.

Screen too small warning (TERMINAL TOO SMALL) The terminal is below the recommended 100 columns x 30 rows. You can continue at a smaller size, but menus, help text, and status boxes may wrap or clip.

Provision State: Activation Failed (REG_FAILED)

Activation Failed is the display label for REG_FAILED. Read any error detail shown after the label. The [Note: Onboarding This Device ] hint alone does not identify an activation failure; it can also accompany a connection error.

Steps to resolve:

Follow Register WEDA Node to check the device record and credential preparation.
Return to the Activator, apply the appropriate credentials if needed, and verify the displayed connection and service state.

Service Status: Degraded

The Management Panel shows ⚠ Degraded when one or more containers are stopped or unhealthy.

Steps to resolve:

In the Management Panel, select "Restart Service" and wait for the action to complete

If still degraded, check container logs:

sudo docker logs dmagent
sudo docker logs system-agent
sudo docker logs watchtower

Press ? in the Management Panel for the troubleshooting panel with links and hints

Credential Problems

Device credential not found (E8040) or download failed (E8041)

Check that the credential is available for the intended device and WEDA environment, and that the configured endpoint is reachable. For file preparation and method selection, follow Local Credential File Path.

Setup Fails Midway

Installation appears to pause

Check the current stage and elapsed time. Online packages download images; offline packages load bundled images locally
For an online download, check access to the configured registries. For offline loading, check the package and Docker daemon
Ensure sufficient disk space: df -h /opt
Keep the terminal open while installation is progressing. If the 30-minute timeout is reached or an error appears, use the reported error and container logs to diagnose it before retrying

Docker errors

docker --version                        # verify Docker is installed
sudo systemctl start docker             # start Docker service
sudo docker ps -a                       # check container state
sudo docker logs dmagent                # view service logs

Error Code Reference

Code	Meaning	Action
E1007	Credential file is empty	Obtain the correct file again from its source
E1008	File exceeds the 10 MiB size limit	Check that you selected the intended credential file rather than an archive or another file
E1011	Invalid authentication file	Check the file, selected authentication method and intended device; decryption or content validation can also fail
E3008	Failed to load bundled Docker images	Check the offline package, free space and Docker daemon
E3009	Docker is not installed or is not on PATH	Install Docker, then run setup again
E3010	Docker daemon is not responding	Start Docker and check daemon access
E3011	Docker version is too old	Install a version meeting the software requirements above
E3012	Neither Docker Compose command is available	Install the Compose plugin or supported standalone command
E4001	Failed to start services	Inspect `sudo docker ps -a` and the affected container's logs
E4005	Docker or Docker Compose is unavailable	Check Docker, its daemon and the Compose command
E5005	New credentials failed; previous credentials restored	Verify the current connection and prepare a valid replacement file
E5006	Credential restoration failed	Reapply a known working file through Update Authentication Credentials and verify the result
E8001	Server hostname cannot be resolved	Check the configured hostname and DNS
E8002	Connection refused	Check the configured service, host, port and firewall
E8003	Connection timed out	Check the route and availability of the configured service
E8004	TLS certificate error	Check the server certificate and device clock
E8005	Connection to WEDA Core failed	Check the configured endpoint and network

Still Stuck?

Run the Activator with debug output enabled:

sudo env WEDA_DEBUG=1 /opt/Advantech/dmagent/weda-node-activator/bin/weda-node-activator 2>&1 | tee activator.log

Using sudo env passes WEDA_DEBUG to the privileged Activator process. The command captures terminal output in activator.log in the current directory.

If an API operation produces a separate debug log, use the file path reported by the Activator. These files are normally saved as /var/log/weda-node/weda-setup-debug_YYYYMMDD_HHMMSS.log, with the current directory used if the log directory cannot be created. A separate API log is not produced for every operation.

Before sharing either log with your WEDA administrator, remove access tokens, credential contents and other secrets.

Before You Start​

What You Need​

System Requirements​

Pre-Flight Verification Script​

Terminal Setup​

Running the Installer​

Starting WEDA Node Activator​

Main Menu​

Setting Up WEDA Node (First-Time Setup)​

License Agreement​

Credential Source​

Authentication Configuration (local-file path only)​

Review and Confirm​

Installing / Verifying Connection​

Setup Failed (failure path only)​

Service Status Overview (Management Panel)​

Service Status Values​

Onboarding and Connection Hints​

Management Actions​

Keyboard Reference​

Global​

Contextual​

Troubleshooting​

Quick Diagnosis​

Display Problems​

Provision State: Activation Failed (REG_FAILED)​

Service Status: Degraded​

Credential Problems​

Setup Fails Midway​

Error Code Reference​

Still Stuck?​

Is this helpful?