WEDA Node Installation Guide

This guide shows you how to install and manage WEDA Node on edge devices using the WEDA Node Activator.

Compatible with WEDA Core v1.0.0 or above

Understanding the Components

Before you start, it is important to understand the two distinct parts of this package:

Installer Package (`installer.sh`)

The installer package and its installer.sh script are used once to deploy the software onto a device or device image. Running installer.sh installs:

WEDA Node - the edge-side Docker service stack (dmagent, system-agent, watchtower containers) that connects the device to the WEDA platform
WEDA Node Activator - the interactive TUI application binary placed at /opt/Advantech/dmagent/weda-node-activator/bin/weda-node-activator

Done once per device (or device image build). After this step, neither Docker nor the service stack is running yet.

WEDA Node Activator (TUI Application)

WEDA Node Activator is the interactive terminal application you run after the installer has placed everything on the device. It is responsible for:

Setting up WEDA Node - configuring and starting the WEDA Node Docker containers for the first time
WEDA Core Credential Management - setting up device credentials and registering with the WEDA platform
Ongoing Management - monitoring service health, updating credentials, restarting services, and removing the installation

The Activator is not the installer. It is the day-to-day management tool for your WEDA Node.

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-{arch}-v{version}.tgz`	Download from Azure Artifacts or CI pipeline
WEDA Account	See https://learn.advantech.com/weda/docs/Introduction	Self-registration
Terminal Access	SSH or direct terminal access	Your infrastructure

System Requirements

Mandatory System Environment
- Operating System: Linux (Ubuntu, 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 / Go GOARCH=amd64) 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 weda.advantech.com and container registries
- NATS (port 4222) to the WEDA Core Message Service
- Tunnel (port 58443) to the Tunnel Service
- Local NATS port 4224 must be free (used for internal node communication)

Pre-Flight Verification Script

Before installing, run the pre-flight script to confirm all requirements are met:

sudo ./tools/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 - need at least "30 100"
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 (●, ⚠, ✗, ○).

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.

Ubuntu/Debian - x64:

tar -xzf weda-installer-ubuntu-x64-v{version}.tgz
cd weda-installer-x64-v{version}
sudo ./installer.sh

Ubuntu/Debian - ARM64:

tar -xzf weda-installer-ubuntu-arm64-v{version}.tgz
cd weda-installer-arm64-v{version}
sudo ./installer.sh

What installer.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 installer.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 pipeline build number when built by CI).

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 v1.0.0 (built 2026-03-20 12:00:00) · Build #release_v1.0.0_20260320.1  |  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 screens are reserved in the wizard but are not rendered in the current build:

Device Model entry is skipped - the auto-detected model is shown read-only in the Review and Confirm summary and cannot be edited from the wizard.
Setup Complete is shown only on setup failure (Setup Failed). On success, the wizard runs a "Verifying Connection" animation and then jumps straight to the Service Status Overview.

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)	Jumps to Review and Confirm - uses the embedded master key, no input required	Standard Advantech devices connecting to the public WEDA Cloud
Use Local Credential File	Goes to Authentication Configuration - pick a `.bin` from disk	Offline deployments or pre-provisioned devices

Authentication Configuration (local-file path only)

Shown when "Use Local Credential File" was selected in Credential Source.

Authentication Configuration

Select authentication method for WEDA Node:

	⦿ Auto Provision (Recommended)
			Centralized key management with automatic provisioning

	○ Device Credentials Setup (Advanced)
			Manual configuration with pre-configured credentials

After choosing a method, press Enter to open the file picker:

Key	Action
↑/↓	Navigate files
←	Parent directory
→ / Enter on folder	Open directory
Enter on file	Select file
Esc	Back to method selection

Once a file is selected:

Authentication file selected

Press 'n' to continue or Enter to change file

Press n to advance 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

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:

Setting Up WEDA Node

Setup in progress...

[████████████████░░░░░] 65% Complete - Downloading Docker images...

Please wait, do not close this window

Status messages cycle through: Preparing setup -> Copying authentication files -> Loading Docker images -> Downloading Docker images -> Starting containers -> Configuring services -> Verifying setup.

Fast network: 2-3 minutes
Slow network: 5-10 minutes (5-minute installation timeout)
Do NOT close the terminal or press Ctrl+C

Phase 2 - Verifying Connection:

Verifying Connection

Checking WEDA Node connection to server...

[ pulsing animation ]

Verification in Progress
Validating server connection...

Once the verification completes, the wizard transitions automatically to the Service Status Overview - no key press required.

Setup Failed (failure path only)

This screen renders only when setup encountered an error. On success, the wizard skips it and goes straight from the Verifying Connection phase to the Service Status Overview.

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)

Access via "Manage WEDA Node" from the main menu, or automatically at the end of a successful setup (the wizard transitions here directly after Verifying Connection - no key press required).

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

Service Status Overview

╭──────────────────────────────────────────────────╮
│ Version:          1.0.0                          │
│ Auth Method:      Auto Provision                 │
│ Provision State:  Activated                      │
│ Connection:       Connected                      │
│ Service Status:   ● Running                      │
│                                                  │
│ Containers                                       │
│   ● dmagent                       2h 34m         │
│   ● system-agent                  2h 34m         │
│   ● watchtower                    2h 34m         │
│                                                  │
│ Connection Details                               │
│   Device: Device ID: 74fe488d5d54, Model: ...   │
│   Server: 219.87.150.116:4222                    │
╰──────────────────────────────────────────────────╯

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

Connection is derived from the live state of the dmagent container plus the provision file - it reads Connected only when dmagent is running and the provision file reports a connection to the WEDA server; 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.

When the Device Is Not Yet Activated

When Provision State is anything other than Activated and the service is running but the Connection is Disconnected, the Service Status box appends an onboarding note with the WEDA Learn URL:

│ 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 is suppressed while the service is stopped or while the provision file reports Activated - it only appears when the user still needs to finish onboarding.

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	Replace the master key or credential file without reinstalling
Restart Service	Stop and restart all WEDA Node Docker containers
Remove WEDA Node	Uninstall containers, volumes, and configuration (type `REMOVE` to confirm)

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 operation data" checkbox
Remove Node	Type `REMOVE`	Unlock the removal confirmation

Troubleshooting

Quick Diagnosis

Running with sudo? Required: sudo ./weda-node-activator
Terminal large enough? stty size - need at least 30 100 (rows columns)
Network working? curl -I https://www.advantech.com
Docker running? sudo systemctl status docker

Display Problems

Icons appear as □ or ?

Install a Unicode font (e.g. Nerd Fonts, Cascadia Code) and reconnect

Colors missing

export TERM=xterm-256color

Screen too small warning (TERMINAL TOO SMALL)

resize -s 30 100

The recommended minimum is 100 columns x 30 rows. Smaller terminals will still let you continue, but menus, help text, and status boxes may wrap or clip.

Provision State: Activation Failed (REG_FAILED)

The Management Panel shows [Note: Onboarding This Device ] in red when the Service is Running but the device has not completed activation on the WEDA server. The human-readable label is Activation Failed.

Steps to resolve:

Register your WEDA account and add this device to your organization
Re-run WEDA Node Activator and update credentials if needed

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 ~30 seconds

If still degraded, check container logs:

docker logs dmagent
docker logs system-agent
docker logs watchtower

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

Credential Problems

Master key not found (E8040)

Wait 10-15 seconds after device registration and retry

Master key download failed (E8041)

Check network connection; ensure at least 500 MB free disk space: df -h /opt

Setup Fails Midway

Progress bar stops or hangs

Check network (Docker images are pulled during setup)
Ensure sufficient disk space: df -h /opt
Wait at least 10 minutes on slow networks - do NOT press Ctrl+C

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	Re-export the `.bin` from WEDA Core portal
E1008	Credential file is too large	Wrong file selected - credential files are < 10 KB
E1011	Credential validation failed	File doesn't match this hardware - see Activator Execution troubleshooting
E4001	Service degraded	Check container logs: `sudo docker logs dmagent`
E4005	Docker not running	`sudo systemctl start docker`
E9010	Cannot connect	Check firewall, DNS, proxy

Still Stuck?

WEDA_DEBUG=1 sudo ./weda-node-activator 2>&1 | tee activator.log

Share activator.log with your WEDA administrator.

Understanding the Components​

Installer Package (installer.sh)​

WEDA Node Activator (TUI Application)​

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​

When the Device Is Not Yet Activated​

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?