Telemetry Configuration

Telemetry Configuration applies to both WEDA Nodes and SubNodes. Use the target device's supported sensor settings to control data reporting and local recording, then verify that the device applied your request.

Before you start:

• Target device: Select the WEDA Node or SubNode whose sensor telemetry you want to configure. It must have synchronized its sensor information to Cloud. Custom Device input uses its own source and parser configuration, not these telemetry endpoints.
• Permissions: Use a user access token with access to the device's Org. Updating or resetting settings requires Admin access. For a SubNode, permissions and onboarding readiness are checked against its owning WEDA Node.
• Readiness: The WEDA Node must have completed onboarding before configuration changes. An Activated or Deactivated record can accept a request, but acceptance does not prove that a disconnected device has applied it. Keep the device connected when checking the result.
• Examples: Replace https://weda.example.com/central/weda with your environment and {deviceId} with the target device's own ID. Use the WEDA Node ID for Node telemetry, or the SubNode ID for SubNode telemetry. Copy configuration names and sensor names from the discovery and configuration responses.

In WEDA Console: Select the intended Org, open Devices, select the device and inspect its Telemetry tab for received values. The tab can also turn a sensor's reporting on or off and change its reporting interval, as shown in Configure Data Reporting. Use the APIs below to discover settings, configure local recording and check apply results.

Inspect the latest Value and Last updated timestamp for the expected sensor. This WEDA Node example includes CPU and memory telemetry.

Discover Sensors and Settings

Use three checks together. A sensor list tells you what exists, a configuration schema tells you what is allowed, and the current configuration tells you what has been requested.

1. Discover supported sensors. Use List Supported Sensors:

   GET https://weda.example.com/central/weda/api/v1/devices/{deviceId}/capabilities/sensors
   Authorization: Bearer {userAccessToken}

   Each entry supplies a sensor name and its type identifier, dtmi. Use the returned sensor name rather than inventing one.

2. Read the allowed settings. Use Get Sensor and Command Definitions:

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

   Match the sensor's dtmi to the definition's @id in dtdl. Follow extends and referenced definitions when interpreting required fields, allowed values, writable settings and constraints. A type definition alone does not prove that the device has a sensor of that type.

3. Read the existing configuration. Use Get Device Telemetry Settings:

   GET https://weda.example.com/central/weda/api/v1/devices/{deviceId}/telemetry-configs
   Authorization: Bearer {userAccessToken}

   Copy the relevant entry's deviceName and sensor name. Here, deviceName identifies a device-declared configuration entry; copy it from this response rather than assuming it matches the Cloud device's display name. The request body is an array of configuration entries for the target ID.

Note: Reserved heartbeat sensor hb

WEDA Node and SubNode software for v1.2 reports a reserved sensor named hb every 60 seconds for heartbeat connectivity. It is not listed in telemetry-configs responses, and a PATCH that tries to configure it returns 400 SubNode.ReservedSensorNotConfigurable. If hb is disabled in the device's own configuration, the device's heartbeat connectivity reads Disconnected even while other telemetry arrives. Devices without hb, such as SubNode SDK 1.1 applications, use their normal telemetry for heartbeat instead; one whose sensors report less often than every 180 seconds can read Abnormal while healthy.

Note: Device software support

Sensor discovery, schema discovery and reset require device software with v1.2 capability-model support. A 422 Device.CapabilityNotSupported response means the target software cannot serve that operation; retrying the same request will not add support. A 503 indicates that capability information could not be read, so retry later. WEDA Cloud's version alone does not establish the device's support.

Check the result: You have a real sensor name, its supported settings and the exact configuration entry to update. Keep an unchanged copy of the current settings for comparison.

Configure Data Reporting

A monitoring application needs a fresh reading from one sensor every two seconds. Use the sensor's report settings to request that interval, then check the apply result and received timestamps.

In WEDA Console, for the WEDA Node shown here: In its Telemetry tab, select the sensor row's edit icon, adjust Enabled and Interval, then use the checkmark to save or the cross to cancel. Follow the configuration and apply-result checks below to verify the requested behavior.

Edit the selected sensor row. The reporting interval uses milliseconds; 2000 represents two seconds.

Using the API:

1. Substitute the deviceName and sensor name obtained above. MyFirstDevice and AI_0 below are illustrative.

2. Send only the entries and settings you intend to change, using Update Device Telemetry Settings:

   PATCH https://weda.example.com/central/weda/api/v1/devices/{deviceId}/telemetry-configs
   Authorization: Bearer {userAccessToken}
   Content-Type: application/json
   
   [
     {
       "deviceName": "MyFirstDevice",
       "sensors": [
         {
           "name": "AI_0",
           "report": {
             "enabled": true,
             "interval": 2000
           }
         }
       ]
     }
   ]

3. After 202 Accepted, read the configuration again and check its apply result as described below. Then inspect recent sensor values and timestamps in the Console or the corresponding DataStream.

Note: Partial updates and required values

• Send both enabled and interval whenever you send report, including when disabling reporting.
• Use milliseconds. Enabled intervals default to an allowed range of 1000-86400000 ms; a deployment can set different bounds, which are stated in a rejection.
• Prefer report. The older config key represents the same runtime settings; never send both for the same sensor. A desired-configuration read preserves the key you submitted.
• Omitted settings remain unchanged. Omitting the configuration entry's top-level enabled does not re-enable a previously disabled entry.
• Optional pipelines and thresholds are replaced in full when supplied. Send the complete intended pipeline or threshold object, and follow the discovered schema for supported parameters.

Check the result: The request is accepted, the device reports a successful application of the new settings, and fresh values support the reporting behavior you intended. A 202 response alone confirms only request acceptance.

Configure Local Recording

To prepare for a later recovery request, enable local recording on a supported sensor before the period you need to recover.

Use record to retain readings locally for later retrieval by supported device functions. Reporting and recording are separate settings:

Setting	Purpose	Effect of omitting it from PATCH
report	Configure sensor reporting.	Keep the current reporting settings.
record	Configure local recording.	Keep the current recording settings.

1. Confirm that the target WEDA Node or SubNode, its software and the sensor support local recording. For a SubNode SDK application, the recording behavior described here requires SDK v1.2.0_20261002.1 or later.

2. Enable recording at the intended interval. This example records the same sensor every 10 seconds, leaving report unchanged:

   PATCH https://weda.example.com/central/weda/api/v1/devices/{deviceId}/telemetry-configs
   Authorization: Bearer {userAccessToken}
   Content-Type: application/json
   
   [
     {
       "deviceName": "MyFirstDevice",
       "sensors": [
         {
           "name": "AI_0",
           "record": {
             "enabled": true,
             "interval": 10000
           }
         }
       ]
     }
   ]

3. Check the apply result after 202 Accepted. Local recording does not itself request an upload of earlier readings. Data Resync is a separate Remote Commands action and requires a device that declares report.historical, with recording enabled for the requested data.

To stop future recording for that sensor, submit:

PATCH https://weda.example.com/central/weda/api/v1/devices/{deviceId}/telemetry-configs
Authorization: Bearer {userAccessToken}
Content-Type: application/json

[
  {
    "deviceName": "MyFirstDevice",
    "sensors": [
      {
        "name": "AI_0",
        "record": { "enabled": false }
      }
    ]
  }
]

Note: Recording intervals

record.enabled is required whenever you send record. With enabled: true, also supply interval; the enabled-interval bounds above apply. With enabled: false, omit interval. To enable recording again, send a new interval explicitly; { "enabled": true } alone is rejected rather than restoring the old value.

Check the result: The device reports successful application of the requested recording setting. For a recovery workflow, separately verify that the device has recorded the expected period before requesting Data Resync; current Cloud values alone do not prove that a local recording exists.

Check Configuration Status

Read GET /api/v1/devices/{deviceId}/telemetry-configs again after an update. In v1.2.0, the response normally shows the desired configuration, meaning the settings last requested through the API. Before any request, or after reset, it falls back to the device's reported configuration.

Use these fields together:

Field	What it establishes
updatedAt	When the update request was saved. This does not establish device application.
status	The device-reported apply outcome: success, failed or invalid; it can be null before a result is reported.
appliedAt	The reported application time; it can be null before application is reported.
errorMessage	The device's failure explanation when an unsuccessful outcome is reported.

1. Compare the returned settings and updatedAt with your request.
2. Check for a fresh apply outcome for that change. A new PATCH retains the previous status and appliedAt until the device reports again. With synchronized device and server clocks, confirm that appliedAt is at or after this request's updatedAt. If the result is missing or older, check connectivity and query again; do not infer success from the desired values alone.
3. For failed or invalid, read errorMessage, correct the supported settings and resubmit. A successful HTTP request and a failed device apply result are different outcomes.
4. Verify the intended effect: inspect fresh received values for reporting, and the device's recording or supported retrieval result for local recording.

For a rejected HTTP request, use the response to choose your next step:

Response	What to check
400	Read the field and reason. Check discovered sensor names, required values, interval bounds, mutually exclusive parameters and schema constraints, or whether the request tried to configure the reserved hb sensor.
403 / 404	Check your token, Org, role, target ID and onboarding readiness. For a SubNode, check its owning WEDA Node.
422	The capability-based operation is unsupported by the target software. Use a compatible device/software version.
502	The returned configuration cannot be used in its expected format. Preserve the error and contact your WEDA support team.
503	Capability information is temporarily unavailable. Retry later.

Check the result: You can distinguish request acceptance, device application and evidence of the expected data behavior.

Reset Telemetry Configuration

Reset when you intend to clear the target device's desired telemetry configuration, rather than change a single setting.

1. Save the current settings and confirm the target Device ID. Reset applies to the whole target device, not a single sensor or configuration entry.

2. As an Org Admin, call Clear Requested Telemetry Settings:

   POST https://weda.example.com/central/weda/api/v1/devices/{deviceId}/telemetry-configs:reset
   Authorization: Bearer {userAccessToken}

3. After 202 Accepted, read the configuration again. With no desired configuration, GET returns the device's reported state; it does not necessarily return an empty array.

4. Check the device's behavior before submitting a replacement configuration.

Caution: Reset is not a factory reset

The operation clears desired telemetry settings. Whether the device returns to firmware defaults depends on the device software and is not guaranteed by this API. Reset is not device deletion, DataStream deletion or a request to erase historical values.

Check the result: You have cleared the desired configuration and inspected the reported settings and device behavior. Submit a new configuration only after confirming what you want to retain or change.