Custom Device Integration

Use a Custom Device to bring data from an external device or application into WEDA Cloud without installing WEDA Node. This walkthrough sends one temperature value through HTTP, maps it to a DataStream, and checks the received value.

Note: HTTP data input requires Client Credentials

Prepare a Client Credential for your Custom Device integration. HTTP ingestion requires an M2M token with audience custom-device-api and scope http-server-data.write; a user access token cannot replace it. Device, DataStream, Data Source and Data Parser management use your authorized user access instead.

Follow Client Credentials for credential creation and token acquisition. Create the Custom Device first so you can include its returned Device ID in the credential configuration. MQTT uses separate device Broker credentials.

In v1.2.0, the credential's deviceIds list is recorded in the token but is not enforced as a device-access restriction.

Understand the Integration Flow

Keep the management and data-input credentials separate:

Operation	Authentication path
Create or manage the device, DataStreams, Data Source and Data Parser	Platform authentication using your user access token and the required Org permissions.
Submit data through HTTP ingestion	Client Credential token with audience custom-device-api and scope http-server-data.write. A user token cannot replace it.
Connect through MQTT	Device Broker credentials, using the MQTT-specific setup.

For this example, prepare:

• An Org you are authorized to manage and its orgId.
• A user access token for management and verification requests.
• An HTTP client and an integration environment that can protect the client secret and M2M token.
• A numeric temperature payload: {"temperature":23.5}.

The examples use https://weda.example.com/central/weda as the WEDA base URL. Replace the origin and tenant path with your environment. Replace route placeholders and example DataStream IDs with the values returned by your requests.

Caution: Keep the integration secret out of public clients

Store the client secret in the sending device or backend integration environment. Exclude client secrets and access tokens from publicly served frontend code, screenshots and shared request exports.

Create a Custom Device

Use the organization-scoped device API with a name and omit deviceId. The presence of deviceId selects the WEDA Node registration path instead. Do not supply the Activator's hardware model for a Custom Device.

POST https://weda.example.com/central/weda/api/v1/orgs/{orgId}/devices
Authorization: Bearer {userAccessToken}
Content-Type: application/json

{
  "deviceName": "FactoryA_External01"
}

1. Choose a name using 1-128 English letters, digits, hyphens or underscores.
2. Submit the request to the intended Org.
3. Save the returned deviceId for the credential, configuration and input requests below.
4. Read the device in the same Org and confirm that its type is CustomDevice.

Check the result: Creation returns 201 Created, and the device is associated with the intended Org. Creation alone does not configure or activate its data input.

Note: Device names share one Org scope

Names must be unique in the Org, ignoring letter case. A WEDA Node and a Custom Device cannot use names that differ only by letter case.

See Register a Device to an Organization and Get Device in Organization.

Configure the Data Source and Parser

HTTP payload: {"temperature":23.5}
  -> Data Source: HTTP-Server
  -> Data Parser: channel 1, $.temperature
  -> Output DataStream: temperature, double

The Data Source selects the input connector. The Data Parser selects values from the incoming JSON and maps them to existing output DataStreams. For this example, one Custom Device has one Data Source and one Data Parser.

1. Create the Output DataStream

Create the required DataStreams yourself before configuring their parser mappings. Creating a Custom Device does not automatically create the output streams for your payload.

POST https://weda.example.com/central/weda/api/v1/orgs/{orgId}/devices/{deviceId}/data-streams
Authorization: Bearer {userAccessToken}
Content-Type: application/json

{
  "dataStreamName": "temperature",
  "displayName": "External temperature",
  "dataType": "double",
  "recordToDataLake": true
}

Check the result: The API returns 201 Created. Save the returned dataStreamId. A new DataStream has no source mapping yet; the next steps connect the incoming value to that ID.

See Create a DataStream for supported data types and field limits. This example uses a scalar double; data-pack and blob inputs require their own stream types and mappings.

2. Configure the HTTP Data Source

Create or replace the device's Data Source with the exact connector value HTTP-Server:

PUT https://weda.example.com/central/weda/api/v1/orgs/{orgId}/devices/{deviceId}/data-source
Authorization: Bearer {userAccessToken}
Content-Type: application/json

{
  "name": "External temperature HTTP input",
  "connectorType": "HTTP-Server"
}

Check the result: A new source returns 201 Created; replacing an existing source returns 200 OK. Read the same resource with GET and confirm its connector before continuing.

Note: Choose the connector before configuring input

The connector type cannot be changed after it has been set. HTTP ingestion requires an HTTP Data Source. Use the MQTT-specific Broker setup when your integration publishes over MQTT.

3. Map the Payload to the DataStream

Create or replace the Data Parser. Replace the example UUID below with your returned dataStreamId:

PUT https://weda.example.com/central/weda/api/v1/orgs/{orgId}/devices/{deviceId}/data-source/data-parser
Authorization: Bearer {userAccessToken}
Content-Type: application/json

{
  "name": "External temperature parser",
  "configs": [
    {
      "channel": 1,
      "dataPacks": [
        {
          "valueObjJsonPath": "$.temperature",
          "dataStreamId": "00000000-0000-0000-0000-000000000001"
        }
      ]
    }
  ]
}

• channel: The input request selects this block with ?channel=1.
• valueObjJsonPath: Selects temperature from the raw JSON payload.
• dataStreamId: Routes the extracted value to the DataStream you created.
• dataPacks: The contract's mapping array also handles basic values such as this number. Its name does not require you to change this example's stream type to data-pack.

This example omits timePath, so ingestion uses the server's receive time. To use a payload timestamp, configure timePath for a Unix millisecond number or ISO 8601 string. An existing field with an invalid timestamp value causes 400; a missing configured field falls back to server time.

Check the result: A new parser returns 201 Created; replacement returns 200 OK. GET the same parser resource and confirm channel 1, $.temperature and the correct output ID.

Note: Mapping and replacement rules

Each DataStream ID can appear only once across the parser's channels and mappings. PUT replaces the source or parser resource; read the existing configuration before replacing it. PATCH updates an existing resource and returns 404 if it has not been created.

Activate and Verify Data Input

1. Prepare the HTTP Sender's Credential

In Client Credentials:

1. Create a credential using your user access token, with scope http-server-data.write and this Custom Device's ID in deviceIds.
2. Retain the returned client ID and secret in the integration environment.
3. Request an M2M token from Identity using the client_credentials grant. Read access_token from the response.
4. Use that token as {m2mAccessToken} in the HTTP input request below. Its audience must be custom-device-api.

Use your user access token for the activation and readback requests. Do not reuse the M2M token as a replacement for management access.

2. Activate the Device

After preparing the source and parser, activate through the device-management API:

POST https://weda.example.com/central/weda/api/v1/devices/{deviceId}:activate
Authorization: Bearer {userAccessToken}

Check the result: The API returns 200 OK. Read the device in its Org and confirm Activated. HTTP input requires this state; an inactive device returns 409 Conflict when you attempt to submit data.

See Deactivate or Reactivate a Device.

3. Send One Test Value

Send the payload using the Client Credential token:

POST https://weda.example.com/central/weda/api/v1/devices/{deviceId}/data-source/http-server/data?channel=1
Authorization: Bearer {m2mAccessToken}
Content-Type: application/json

{
  "temperature": 23.5
}

Check the result: The endpoint returns 201 Created. Continue with readback to confirm that the expected DataStream received the value.

4. Read the Result

GET https://weda.example.com/central/weda/api/v1/orgs/{orgId}/devices/{deviceId}/data-streams/{dataStreamId}/values/latest
Authorization: Bearer {userAccessToken}

Confirm that the result belongs to the saved dataStreamId, contains the numeric value 23.5, and has a timestamp corresponding to your test. Query promptly after sending: this endpoint reads within the configured latest-value retention period (60 minutes by default).

Check the result: The complete path works: an authenticated sender's payload is parsed into the intended DataStream, and the value can be read back. See Get the Latest DataStream Value.

Custom Device heartbeat connectivity is not applicable. Use activation status, input responses and received data to verify this integration.

If the test fails:

What you see	What to check
HTTP input is denied while management requests work	Use the M2M token with audience custom-device-api and scope http-server-data.write. A user token is not a substitute.
HTTP input returns 409	The device exists but cannot accept input yet. Confirm that it is Activated, its Data Source connector is HTTP-Server, a Data Parser is saved, and the request's channel exists in that parser.
GET returns a source or parser whose ID is all zeros, or PATCH returns 404	The source or parser has not been created yet. Create it with PUT first. A 404 from GET means the device itself was not found in this Org.
The value does not arrive in the expected stream	Check the input channel, JSONPath, output DataStream ID and data type. Read back the saved parser configuration.
HTTP input returns 400	Check that the payload is valid JSON and contains a value at each valueObjJsonPath configured for that channel; a path that does not resolve is rejected. If timePath is configured and present, send a Unix millisecond number or ISO 8601 string. Keep the payload within the configured size limit.
Latest-value lookup returns 204 No Content	Check whether the mapped stream received data in the latest-value retention window (60 minutes by default). Send a fresh test and query the exact saved IDs.

Manage the Custom Device Lifecycle

Use your user access token for device management. The Custom Device created through the Org API above is the target of these requests.

Task	Request	What to check
Inspect the device	GET /api/v1/orgs/{orgId}/devices/{deviceId}	Confirm its Org, name, type and status.
Rename it	PATCH /api/v1/orgs/{orgId}/devices/{deviceId} with deviceName	Use the same name-format and Org-uniqueness rules as creation.
Pause input	POST /api/v1/devices/{deviceId}:deactivate	Confirm Deactivated. HTTP input requires Activated and is rejected while inactive.
Resume input	POST /api/v1/devices/{deviceId}:activate	Confirm Activated, then repeat the input/readback test.
Remove the device	DELETE /api/v1/devices/{deviceId}	204 No Content indicates permanent deletion.

Prefix these paths with your WEDA base URL. For a rename, deviceId, hwModel and orgId must not appear in the PATCH body. Choose connectorType before setup; changing it is not a supported source update.

Caution: Custom Device deletion is permanent

Confirm the target Device ID and stop the sender before deleting it. The current API permits Custom Device deletion from any lifecycle status. This differs from WEDA Node deletion, which requires Deactivated status. Its MQTT and NATS device credentials are revoked. Review the integration's Client Credentials separately rather than assuming device deletion invalidates its issued M2M tokens.

See Rename a Device in an Organization and Delete a Device. Manage credential metadata and deletion through the Client Credentials guide.