Remote Commands

Use remote commands to request an action on a connected WEDA Node or SubNode. Available actions come from the target device's command catalog; a command supported by one device is not automatically available on another.

Before you start:

• Target: Confirm the Device ID and Org. Use the ID whose catalog declares the command. For a SubNode, Org permissions are resolved through its owning WEDA Node; this does not make the parent Node's commands available on every SubNode. Custom Devices do not use this command workflow.
• Connection and software: The device must be reachable and provide the required capability model and command definition. A v1.2.0 Cloud instance alone does not establish device support. An offline command request is rejected with 409, rather than queued for reconnection.
• Authentication: Use a user access token with the required role in the device's Org.
• Interface: In v1.2.0, use these REST APIs from your application or API client. WEDA Console does not provide the command controls described here.
• Examples: Replace https://weda.example.com/central/weda and {deviceId} with your environment and target ID. The examples describe requests to send; they are not evidence that an action has been executed.

Operation	Required Org role
Reboot, Data Resync and ordinary custom commands	Use Admin access in the device's Org; a custom command also checks its declared permission requirement.
Shut down, including system.shutdown through the generic invoke API	Admin.
Read command history	An authenticated identity with access to the device's Org.

Reboot or Shut Down a Device

Choose the action before issuing a request:

Action	API	What to expect
Reboot	Reboot a Device, POST /api/v1/devices/{deviceId}/commands:reboot	The device becomes unreachable while restarting. Verify its reconnection separately.
Shut down	Shut Down a Device, POST /api/v1/devices/{deviceId}/commands:shutdown	The device powers off and remains unavailable until powered on again.

1. Confirm that the target declares system.reboot or system.shutdown and that the action will not interrupt work that must continue. These power commands require compatible Linux device software; they cannot recover a fully unresponsive operating system.

2. Submit the chosen action. For a reboot:

   POST https://weda.example.com/central/weda/api/v1/devices/{deviceId}/commands:reboot
   Authorization: Bearer {userAccessToken}
   Content-Type: application/json
   
   {
     "delaySeconds": 5,
     "timeoutSeconds": 30,
     "cmdNote": "Scheduled maintenance reboot"
   }

   For shutdown, use the commands:shutdown endpoint with the same body fields and a note describing the shutdown.

3. After 202 Accepted, save the returned reqSeqId and find it in command history as described below.

4. For reboot and shutdown, follow pending → result. A result with data.status: 0 means the device accepted the power command. Check reconnection after reboot, or the intended power state after shutdown, to verify its physical effect.

Note: Delay and timeout

timeoutSeconds defaults to 30 and must be 15-86400 seconds. delaySeconds defaults to 5 and must be between 0 and timeoutSeconds - 10. Out-of-range values are rejected with 422, not silently adjusted.

Caution: Plan how to restore access

Reboot interrupts connectivity and running work. Shutdown leaves the device off; this API does not provide Wake-on-LAN or a way to power it back on. Ensure that the intended recovery or on-site power-on procedure is available before shutting down a remote device.

Check the result: The saved request has a result outcome, and a separate device check confirms the intended restart or power state. 202 and a successful result flag do not establish physical completion on their own.

Data Resync

Data Resync is a manual command that asks the device to upload a time range of locally recorded readings. It does not detect missing periods automatically or turn recording on retroactively.

Confirm these prerequisites:

• The device software supports Data Resync.
• Recording was enabled for the relevant sensors during the requested period, and the data remains in the device's local buffer.
• The device is connected, and its clock is synchronized. The API validates the window against Cloud time, while recordings use the device's timestamps.
• The requested readings are numeric. The v1.2.0 resync flow does not replay string, JSON or image data.

1. Choose a UTC window with startedAt < endedAt. The start is inclusive and the end is exclusive. The start must be within the last 7 days, and the end must not be in the future.

2. Call Recover Buffered Device Data. Replace both illustrative timestamps below before sending, using a window that meets those rules and exists in the device's recordings:

   POST https://weda.example.com/central/weda/api/v1/devices/{deviceId}/commands:resync
   Authorization: Bearer {userAccessToken}
   Content-Type: application/json
   
   {
     "startedAt": "2026-10-24T00:00:00Z",
     "endedAt": "2026-10-24T01:00:00Z",
     "timeoutSeconds": 1800,
     "cmdNote": "Recover the selected recorded period"
   }

3. Save reqSeqId from 202 Accepted. The initial data.resultData echoes the accepted range, recovery horizon and timeout; it is not an upload-completion result.

4. Follow that request through command history. Inspect the device's progress and final data.resultData, then query the corresponding DataStreams over the requested period to verify the Cloud values.

Note: Recovery window and timeout

The seven-day API horizon does not guarantee that seven days of recordings exist on the device. If the start is too old, 422 Command.HorizonExceeded includes the requested range, effective horizon and a suggested range. Review that suggestion rather than treating the window as automatically adjusted.

Resync is long-running: timeoutSeconds must be 1800-86400 seconds. When omitted, the server default is 1800 seconds. The ordinary 30-second command default is not the resync default.

Caution: Resync replays the whole window

The device uploads the whole requested window, without gap detection. Replayed values overwrite existing Cloud values with the same timestamp. Repeating the request is another replay; do not assume automatic resume, duplicate suppression or a command result that proves durable storage of every reading.

Check the result: Review any reported counts or gaps and verify the actual historical values. totalSamples can include empty samples, and dataGaps reports sensor read errors rather than every recording hole; neither alone proves complete recovery.

Invoke Custom Commands

commands:invoke is the Cloud API for calling a custom command implemented by your WEDA SubNode application. You define the command name, parameters and execution handler with the SubNode SDK; your Cloud application calls that command using the SubNode's Device ID.

For a command targeting a SubNode:

Your Cloud application -> WEDA commands:invoke -> WEDA Node -> SubNode command handler
Your Cloud application <- Command history / result         <- SubNode response

• Develop the command: Start with WEDA SubNode SDK in Developer Resources. The SDK application implements the action and returns its result; WEDA Node carries commands and responses between that application and Cloud.
• Use a concrete example: The public Custom Command Handler Example (SDK v1.2 RC) demonstrates command definitions, handlers, validation and results, including sensor.read. Its simulator demonstrates local dispatch. For Cloud invocation, connect the application through WEDA Node and confirm that the target's catalog declares the command.
• Invoke it from Cloud: Use the REST request below after the SubNode is connected and has published its command definitions. The SDK example's device-message envelope is different from the public REST body; use deviceCommand and parameters as shown here.

The same invoke API also calls supported WEDA Node / System Agent commands, such as GPIO operations. In each case, the keyword and parameters must match the target device's catalog.

1. Read the command definitions. Use Get Sensor and Command Definitions:

   GET https://weda.example.com/central/weda/api/v1/devices/{deviceId}/capabilities/schema?type=commands
   Authorization: Bearer {userAccessToken}

   Inspect the returned DTDL definitions, including referenced or inherited definitions, to identify the parameter shape and declared commands:

   • If the device's capability report includes a reported.commands list, use each entry's name as the request keyword and match its dtmi to the definition's @id.
   • Some WEDA Node images declare commands in the DTDL definitions without a separate commands list. DTDL command names use underscores where the request keyword uses dots: for example, gpio_list maps to gpio.list. Do not send the Interface's @id as deviceCommand.

   Do not assume an example command is supported by your target.

2. Prepare the command-specific parameters. For your own SubNode, use the parameters defined by its SDK command handler. Built-in hardware commands are another use of the same API; compatible Advantech GPIO device images can expose commands such as:

   Keyword	Purpose
   gpio.list	List available pins and their reported direction and state.
   di.get / do.get	Read supported digital input or output states.
   do.set	Request writes to supported digital outputs.

3. Invoke your SubNode command. This Run a Device Command request calls sensor.read from the linked SDK example. Replace {deviceId} with that SubNode's Device ID, and use the device-declared configuration name and sensor name in your application. This command must be implemented and declared by your target; it is not available on every SubNode by default.

   POST https://weda.example.com/central/weda/api/v1/devices/{deviceId}/commands:invoke
   Authorization: Bearer {userAccessToken}
   Content-Type: application/json
   
   {
     "deviceCommand": "sensor.read",
     "parameters": {
       "deviceName": "MyFirstDevice",
       "sensorName": "temperature_sensor"
     },
     "timeoutSeconds": 30,
     "cmdNote": "Read a sensor through the custom SubNode command"
   }

4. After 202 Accepted, save reqSeqId, read its outcome and inspect the command-specific data.resultData. A device can reject an unsupported parameter or operation after the API has accepted the request.

Note: Catalog, parameters and permissions

The Cloud checks whether the device declares the command, but command-specific parameters are forwarded to the device. Do not treat 202 as proof that every parameter is valid or the action succeeded. Ordinary command timeouts are 15-86400 seconds, default 30; report.historical uses the longer resync rules. Invoking system.shutdown through this generic endpoint still requires Admin permission.

Caution: Output commands affect connected hardware

GPIO support depends on the device image, hardware and required drivers. A command such as do.set can actuate connected equipment. Confirm the pin mapping, direction and intended effect on a suitable test setup before issuing an output write.

Check the result: The matching command reaches its reported outcome, and the returned payload or a separate device check confirms the effect you intended. For a multi-output command, inspect each output's result rather than assuming the batch succeeded as a whole.

Check Command Results

All four command entry points return a command-result object. Save its reqSeqId, then poll List Device Command Results:

GET https://weda.example.com/central/weda/api/v1/devices/{deviceId}/commands/results?skipCount=0&maxResultCount=20
Authorization: Bearer {userAccessToken}

1. Find the item whose reqSeqId matches your saved value. Do not assume the newest item belongs to your request.

2. The response contains items and totalCount, ordered newest first by command creation time. Read additional pages if necessary. Optional startTime and endTime filters select command creation times, not a Data Resync recovery window.

3. Read data.phase together with data.status and any data.error:

   Phase	Interpretation
   pending	The request is awaiting device acknowledgement.
   ack	The device received and validated the command. Reboot and shutdown skip this phase and proceed from pending to result.
   progress	A long-running command is reporting progress.
   result	A final result is available. Check the result flag, error and command-specific payload.

4. Follow the request to result or a reported failure/timeout. For a successful reboot or shutdown result, also perform the separate physical-state check.

Field	How to use it
data.status	0 means success/received and 1 means failure. A 0 while pending or in progress is not proof of completed execution.
data.error.code	The execution failure reason, for example notSupported, permissionDenied, executionFailed or timedOut. This is distinct from an HTTP rejection's title.
data.resultData	Command-specific progress or result information. Interpret it using that command's definition.
data.createdAt	When the command was accepted.
data.executedAt / data.completedAt	Device-reported execution times; they can be null before the device reports them.

Note: Timeout does not prove that nothing happened

A timeout is reported as data.status: 1 with data.error.code: timedOut. It means no confirming outcome arrived within the wait window, not proof that the physical action never occurred. Check the device before submitting another request. A new POST creates another command; cmdNote is a tracing note, not a duplicate-prevention key.

If the HTTP request itself is rejected, no accepted command outcome should be inferred:

Response	Next check
400 / 401	Correct the request shape or timestamps, or obtain a valid user token.
403 / 404	Check Org access, required role, target ID and whether the target published a command model.
409 Command.OfflineDevice	Restore connectivity before issuing a new request. This command was not queued.
422	Read the error to distinguish unsupported capability/command, invalid parameters and a resync horizon violation.
503	The capability or command catalog could not be read. Retry later; this alone does not mean the device lacks support.

Check the result: You have correlated the response to the exact request, interpreted its final acknowledgement or outcome, and verified the intended device or data effect. Keep the correlation ID and relevant result if your operation needs a record; command history is subject to retention and is not a permanent audit ledger.