Device Management
Overview
A device in WEDA represents a physical edge machine running WEDA Node — the edge-side agent that connects hardware to WEDA Cloud. Before a device can report telemetry or receive container deployments, it must be registered in WEDA Cloud and activated by running WEDA Node Activator on the physical machine.
Each device is identified by two values reported by WEDA Node Activator:
deviceId— the device's MAC address (lowercase, no separators, e.g.cc827f50f406)hwModel— the hardware model string (e.g.MIC-710,ADVANTECH-EDGE)
A device belongs to exactly one Org. Device operations, including telemetry configuration, container deployments, and AI model deployments, are governed by its Org association and the caller's permissions.
WEDA also supports SubNode devices — connectors defined in WEDA Edge that represent third-party equipment or Advantech I/O modules. Once configured, SubNode devices receive their own deviceId and appear in the same device list APIs. However, SubNode onboarding and DTDL configuration are handled entirely in WEDA Edge, not through these Cloud APIs. See SubNode for details.
Device Status
| Status | Meaning |
|---|---|
Registered | Device record created in WEDA Cloud; WEDA Node not yet connected |
Activated | WEDA Node has connected and synced; device is fully operational |
Deactivated | Manually deactivated; device cannot connect to WEDA Core — telemetry stops and new deployments queue until reactivated |
Onboarding Flow
Device onboarding spans both WEDA Cloud and the physical edge machine:
Step 1 — Get device identifiers (Edge)
Start WEDA Node Activator on the physical machine. It displays deviceId (Device field) and hwModel (Model field). Copy both values before proceeding.
Step 2 — Register device (Cloud)
Call POST /api/v1/orgs/{orgId}/devices with deviceId and hwModel. The target orgId is provided in the URL path. deviceName is optional — if omitted, WEDA Core auto-generates it as {hwModel}-{deviceId}. The device record is created with status Registered.
Step 3 — Connect WEDA Node (Edge)
Run WEDA Node Activator to install and start the WEDA Node service. Two activation methods are available:
| Method | How it works | When to use |
|---|---|---|
| Register & Connect device to WEDA site (default) | Uses the built-in key bundled with the installer; no file required | Standard devices connecting to WEDA Cloud |
| Use Local Credential File | Uses a .bin credential file downloaded via API | Offline/LAN environments, pre-provisioned devices |
To use the Local Credential method: download the .bin file via Node Activation, place it on the edge device, and select Use Local Credential File in WEDA Node Activator.
Step 4 — Verify activation (Cloud)
Query the device list under the Org and confirm the device status is Activated.
Operations
Provisioning & Registration
| Operation | API | Description |
|---|---|---|
| Register Device | POST /api/v1/orgs/{orgId}/devices | Register a device and link it to an Org. Requires deviceId and hwModel; orgId is supplied in the URL path. deviceName is optional — see Constraints. |
| Get Auth Info | GET /api/v1/devices/{deviceId}/auth | Download the credential .bin file for local activation. |
| List All Devices | GET /api/v1/devices | Paginated list of devices the caller has permission to view. |
| List Devices Under Org | GET /api/v1/orgs/{orgId}/devices | List devices belonging to a specific Org. |
| Update Device | PATCH /api/v1/devices/{deviceId} | Update the device name or move the device to another Org. |
| Update Device Status | POST /api/v1/devices/{deviceId}:{status} | Activate, deactivate, or reactivate a device. |
| Delete Device | DELETE /api/v1/devices/{deviceId} | Soft-delete a deactivated device record — see Constraints for current retention behavior. |
Device Configuration
| Operation | API | Description |
|---|---|---|
| Get Capabilities | GET /api/v1/devices/{deviceId}/capabilities | Hardware capabilities reported by the device. |
| Get Telemetry Config | GET /api/v1/devices/{deviceId}/telemetry-configs | Current sensor sampling settings. |
| Update Telemetry Config | PATCH /api/v1/devices/{deviceId}/telemetry-configs | Enable/disable sensors or adjust sampling rates. |
| Add/Update Custom Info | PUT /api/v1/devices/{deviceId}/custom-info | Bulk upsert user-defined key-value metadata. |
| Get Custom Info | GET /api/v1/devices/{deviceId}/custom-info | Retrieve all metadata entries for the device. |
| Update Single Entry | PATCH /api/v1/devices/{deviceId}/custom-info/{key} | Modify one metadata value. |
| Delete Single Entry | DELETE /api/v1/devices/{deviceId}/custom-info/{key} | Remove one metadata entry. |
| Delete All Custom Info | DELETE /api/v1/devices/{deviceId}/custom-info | Remove all metadata from the device. |
Updating telemetry configuration is asynchronous. A 202 Accepted response means WEDA Core accepted the requested configuration; it does not confirm that the WEDA Node has applied it. Query the telemetry configuration again to verify the result.
Device Data Definitions
| Operation | API | Description |
|---|---|---|
| Get Data Source Definitions | GET /api/v1/devices/{deviceId}/data-source | Retrieve the Data Source definitions reported by the device. |
| Get Data Objects | GET /api/v1/devices/{deviceId}/data-objects | Retrieve the device's Data Object definitions. |
| Get Data Object by ID | GET /api/v1/devices/{deviceId}/data-objects/{dataObjectId} | Retrieve one Data Object definition. |
These APIs return device data definitions. To retrieve current values or historical data, use the Data Engine APIs.
Constraints
Registration
- A WEDA Node
deviceIdmust contain exactly 12 lowercase letters or digits, with no separators (e.g.cc827f50f406) hwModelis the hardware model string as shown in WEDA Node ActivatordeviceNameis optional at registration. If omitted, WEDA Core auto-generates it as{hwModel}-{deviceId}- Maximum length: 128 characters
- Allowed characters:
a-z,A-Z,0-9,-,_ - Whitespace and other special characters are not allowed
- Must be unique within the same Org; comparison is case-insensitive
- A device can belong to only one Org at a time
Deletion
- A device must be
Deactivatedbefore it can be deleted DELETE /api/v1/devices/{deviceId}is currently a soft delete: the device record no longer appears in queries, but its data is retained. Registering and activating the same device again restores its prior data- Historical telemetry stored by the Data Engine is retained regardless of deletion
- v1.2: deleting a device will also remove its stored telemetry configuration
- v1.3: device deletion will become a hard delete, to align with Cyber Resilience Act (CRA) requirements
Deactivation
- A deactivated device remains linked to its Org
- Containers already running on the device are not stopped — they continue running unaffected
- The device cannot connect to WEDA Core, so it stops sending telemetry and cannot immediately receive new deployments
- Any deployment issued while deactivated is queued and delivered automatically once the device reconnects after reactivation
- Deactivation does not delete the device, its configuration, or its historical telemetry
Scenario
A system integrator onboards the first edge device at a factory site and tags it with asset metadata:
Once Activated, the device begins reporting telemetry. Custom metadata (location, assetTag) helps users identify and search for the device without changing its core registration fields.
Related
- Device must belong to an Org before it can be used: Organization Management
- How queued changes reach a reconnecting device: Device state synchronization
- Retrieving telemetry data and working with data objects: Data Engine
- Deploying containers to devices: Container Management
- Postman walkthrough: Register Your Device