Skip to content

CoAP Device API & HTTP Device API. Updated docs #2549

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
stitenko wants to merge 1 commit into
base: master
Choose a base branch
from
Open

CoAP Device API & HTTP Device API. Updated docs #2549

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion _data/host-constant.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
hostLabel: localhost
hostName: localhost
mqttHostName: localhost
coapHostName: coap.thingsboard.cloud
coapHostName: localhost
httpsUrl: https://thingsboard.cloud
lwm2mHostName: lwm2m.thingsboard.cloud
apiHostName: YOUR_SERVER_HOSTNAME
Expand Down
196 changes: 109 additions & 87 deletions _includes/docs/reference/coap-api.md
View file
Open in desktop

Large diffs are not rendered by default.

449 changes: 217 additions & 232 deletions _includes/docs/reference/http-api.md
View file
Open in desktop

Large diffs are not rendered by default.

50 changes: 26 additions & 24 deletions _includes/docs/reference/mqtt-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,10 +79,10 @@ mosquitto_pub -d -q 1 -h "{{mqttHostName}}" -p "1883" -t "v1/devices/me/telemetr
{: .copy-code}

{% endif %}
{% if docsPrefix == nil or docsPrefix == "pe/" or docsPrefix == "edge/" or docsPrefix == "pe/edge" %}
{% if docsPrefix == nil or docsPrefix == "pe/" or docsPrefix == "edge/" or docsPrefix == "pe/edge/" %}

> ⚠️ **Don't forget to replace:**
> &#8194;&#8226;&#8194;<code>{{HOST_NAME}}</code> with your ThingsBoard{% if docsPrefix == "edge/" or docsPrefix == "pe/edge" %} Edge{% endif %} hostname or IP address.
> &#8194;&#8226;&#8194;<code>{{HOST_NAME}}</code> with your ThingsBoard{% if docsPrefix == "edge/" or docsPrefix == "pe/edge/" %} Edge{% endif %} hostname or IP address.
> &#8194;&#8226;&#8194;<code>$ACCESS_TOKEN</code> with your device&#39;s access token.

```bash
Expand All @@ -91,7 +91,7 @@ mosquitto_pub -d -q 1 -h "{{HOST_NAME}}" -p "1883" -t "v1/devices/me/telemetry"
{: .copy-code}

**Example**
In this example, <code>{{HOST_NAME}}</code> refers to your <code>local</code> ThingsBoard {% if docsPrefix == "edge/" or docsPrefix == "pe/edge" %}Edge {% endif %}installation, and <code>$ACCESS_TOKEN</code> is set to <code>ABC123</code>.
In this example, <code>{{HOST_NAME}}</code> refers to your <code>local</code> ThingsBoard {% if docsPrefix == "edge/" or docsPrefix == "pe/edge/" %}Edge {% endif %}installation, and <code>$ACCESS_TOKEN</code> is set to <code>ABC123</code>.

```bash
mosquitto_pub -d -q 1 -h "localhost" -p "1883" -t "v1/devices/me/telemetry" -u "ABC123" -m {"temperature":25}
Expand Down Expand Up @@ -279,7 +279,7 @@ v1/devices/me/attributes
```
{: .copy-code}

<br><b><font size="3">Examples</font></b>
<b><font size="3">Examples</font></b>
Below are the examples of how to publish client-side device attributes.

> ⚠️ Don&#39;t forget to replace {% unless docsPrefix contains "paas/" %}
Expand All @@ -298,9 +298,9 @@ Telemetry data:

Execute the command:

{% if docsPrefix == null or docsPrefix == "pe/" %}
{% if docsPrefix == nil or docsPrefix == "pe/" or docsPrefix == "edge/" or docsPrefix == "pe/edge/" %}
```shell
mosquitto_pub -d -h "$THINGSBOARD_HOST_NAME" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN" -m "{"attribute1": "value1", "attribute2": true}"
mosquitto_pub -d -h "{{HOST_NAME}}" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN" -m "{"attribute1": "value1", "attribute2": true}"
```
{: .copy-code}
{% else %}
Expand Down Expand Up @@ -358,23 +358,14 @@ v1/devices/me/attributes/response/+
The following example is written in javascript and is based on mqtt.js.
Pure command-line examples are not available because subscribe and publish need to happen in the same mqtt session.

{% if docsPrefix == nil or docsPrefix == "pe/" %}
**1.** Save the [mqtt-js-attributes-request.js](/docs/pe/reference/resources/mqtt-js-attributes-request.js){:target="_blank" download="mqtt-js-attributes-request.js"} file to your PC.

> ⚠️ In this example, the hostname refers to a **local ThingsBoard installation**.
> If your ThingsBoard instance is deployed on a different host, make sure to replace <code>localhost</code> with the appropriate hostname or IP address.
**1.** Save the [mqtt-js-attributes-request.js](/docs/{{docsPrefix}}reference/resources/mqtt-js-attributes-request.js){:target="_blank" download="mqtt-js-attributes-request.js"} file to your PC.

{% endif %}
{% if docsPrefix contains 'paas/' %}
**1.** Save the [mqtt-js-attributes-request.js](/docs/paas/reference/resources/mqtt-js-attributes-request.js){:target="_blank" download="mqtt-js-attributes-request.js"} file to your PC.
{% endif %}
{% if docsPrefix == "edge/" or docsPrefix == "pe/edge/" %}
**1.** Save the [mqtt-js-attributes-request.js](/docs/edge/reference/resources/mqtt-js-attributes-request.js){:target="_blank" download="mqtt-js-attributes-request.js"} file to your PC.
{% unless docsPrefix contains 'paas/' %}

> ⚠️ In this example, the hostname refers to a **local ThingsBoard Edge installation**.
> If your ThingsBoard Edge instance is deployed on a different host, make sure to replace <code>localhost</code> with the appropriate hostname or IP address.
> ⚠️ In this example, the hostname refers to a **local ThingsBoard{% if docsPrefix == "edge/" or docsPrefix == "pe/edge/" %} Edge{% endif %} installation**.
> If your ThingsBoard{% if docsPrefix == "edge/" or docsPrefix == "pe/edge/" %} Edge{% endif %} instance is deployed on a different host, make sure to replace <code>localhost</code> with the appropriate hostname or IP address.

{% endif %}
{% endunless %}

{% capture tabspec %}mqtt-attributes-request
A,The content of the "mqtt-js-attributes-request.js" file:,javascript,resources/mqtt-js-attributes-request.js,/docs/reference/resources/mqtt-js-attributes-request.js{% endcapture %}
Expand Down Expand Up @@ -666,7 +657,8 @@ These limits help control load and ensure stable operation when multiple devices

## Claiming devices

Please see the corresponding article to get more information about the [Claiming devices](/docs/{{docsPrefix}}user-guide/claiming-devices){:target="_blank"} feature.
The Device Claiming feature allows end users to securely associate a device with their account after the device has been deployed and connected to ThingsBoard.
For a detailed explanation of the device claiming workflow and supported scenarios, refer to the {% if docsPrefix == nil or docsPrefix == "pe/" or docsPrefix contains "paas/" %}[Claiming devices](/docs/{{docsPrefix}}user-guide/claiming-devices){:target="_blank"}{% endif %}{% if docsPrefix == "edge/" or docsPrefix == "pe/edge/" %}[Claiming devices](/docs/user-guide/claiming-devices){:target="_blank"}{% endif %} documentation.

In order to initiate claiming device, send PUBLISH message to the following topic:

Expand All @@ -691,9 +683,11 @@ In case the **durationMs** is not specified, the system parameter **device.claim

## Device provisioning

Please see the corresponding article to get more information about the [Device provisioning](/docs/{{docsPrefix}}user-guide/device-provisioning){:target="_blank"} feature.
Device provisioning allows devices to be registered dynamically without manual creation in the ThingsBoard UI.
For a detailed explanation of the provisioning process and supported scenarios, refer to the {% if docsPrefix == nil or docsPrefix == "pe/" or docsPrefix contains "paas/" %}[Device provisioning](/docs/{{docsPrefix}}user-guide/device-provisioning){:target="_blank"}{% endif %}{% if docsPrefix == "edge/" or docsPrefix == "pe/edge/" %}[Device provisioning](/docs/user-guide/device-provisioning){:target="_blank"}{% endif %} documentation.

In order to initiate device provisioning, send Provisioning request to the following topic:
**Provisioning request**
To initiate device provisioning, send Provisioning request to the following topic:

```shell
/provision
Expand All @@ -702,7 +696,8 @@ In order to initiate device provisioning, send Provisioning request to the follo

Also, you should set **username** or **clientId** to *provision*.

The supported data format is:
**Request Payload**
The provisioning request must use the following JSON format:

```json
{
Expand All @@ -712,6 +707,13 @@ The supported data format is:
}
```

**Payload fields**
- **deviceName** — the name of the device to be provisioned.
- **provisionDeviceKey** — the provisioning key configured in ThingsBoard.
- **provisionDeviceSecret** — the provisioning secret associated with the provisioning key.

If the provided credentials are valid, ThingsBoard automatically creates the device (if it does not already exist) and returns the device credentials, allowing the device to start communicating with the platform.

<hr>

## Firmware API
Expand Down
27 changes: 19 additions & 8 deletions _includes/docs/user-guide/ui/devices.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,14 +144,25 @@ Second way:

## Check connectivity

To verify if your device is successfully connected to ThingsBoard:
- Open the "**Device details**" window and click "**Check connectivity**".
- Select:
- [Communication protocol](/docs/{{docsPrefix}}reference/protocols/){:target="_blank"} ([MQTT](/docs/{{docsPrefix}}reference/mqtt-api){:target="_blank"}, [HTTP](/docs/{{docsPrefix}}reference/http-api){:target="_blank"}, etc.)
- Operating system
- Copy the generated command and run it in a **Terminal**.

If successful, the device status will change from "**Inactive**" to "**Active**", and telemetry data (e.g., temperature) will appear.
**Check connectivity** is a built-in feature that provides ready-to-use commands for testing device connectivity to ThingsBoard using different communication protocols. It allows you to quickly verify network access, validate credentials, and confirm that incoming telemetry is processed correctly.

Using this feature, you can publish test telemetry data (for example, a temperature value of 25) and immediately ensure that the device is able to communicate with the platform.

**To verify device connectivity:**
1. Click on device to open its details page.
2. Click **Check connectivity**.
3. Select the [communication protocol](/docs/{{docsPrefix}}reference/protocols/){:target="_blank"} ([MQTT](/docs/{{docsPrefix}}reference/mqtt-api){:target="_blank"}, [HTTP](/docs/{{docsPrefix}}reference/http-api){:target="_blank"}, etc.) and your operating system.
4. Copy the generated command and execute it in a terminal.

If the connection is successful:
- The device status changes from **Inactive** to **Active**.
- Telemetry data appears on the **Latest telemetry** tab.

{% capture difference %}
For guidance on connecting devices based on your technology stack, see the available [connection guides](/docs/guides/#AnchorIDGettingStartedGuides){:target="_blank"}.<br>
For advanced protocols and API options, refer to the [ThingsBoard API reference](/docs/{{docsPrefix}}reference/protocols/){:target="_blank"}.
{% endcapture %}
{% include templates/info-banner.md content=difference %}

{% include images-gallery.html imageCollection="check-connectivity" %}

Expand Down
16 changes: 8 additions & 8 deletions _includes/templates/api/coap/claiming-devices-access-token.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
Send POST request to the following URL:

{% if docsPrefix == null or docsPrefix == "pe/"%}
{% if docsPrefix == nil or docsPrefix == "pe/" or docsPrefix == "edge/" or docsPrefix == "pe/edge/" %}

```shell
coap://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/claim
coap://{{HOST_NAME}}/api/v1/$ACCESS_TOKEN/claim
```
{: .copy-code}

Where
- **$THINGSBOARD_HOST_NAME** is your localhost, or the platform address;
- **$ACCESS_TOKEN** is device access token.

{% endif %}
{% if docsPrefix == "paas/" or docsPrefix == "paas/eu/"%}

```shell
coap://{{coapHostName}}/api/v1/$ACCESS_TOKEN/claim
```
{: .copy-code}

Where **$ACCESS_TOKEN** is device access token.
{% endif %}

{% endif %}
> ⚠️ Don&#39;t forget to replace {% unless docsPrefix contains "paas/" %}
&#8194;&#8226;&#8194;<code>{{HOST_NAME}}</code> with your ThingsBoard{% if docsPrefix == "edge/" or docsPrefix == "pe/edge/" %} Edge{% endif %} hostname or IP address.
&#8194;&#8226;&#8194;{% endunless %}<code>$ACCESS_TOKEN</code> with your device&#39;s access token.
8 changes: 5 additions & 3 deletions _includes/templates/api/coap/claiming-devices-certificate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,17 @@
Send POST request to the following URL:

{% if docsPrefix == null or docsPrefix == "pe/"%}
{% if docsPrefix == nil or docsPrefix == "pe/" or docsPrefix == "edge/" or docsPrefix == "pe/edge/" %}

```shell
coap://$THINGSBOARD_HOST_NAME/api/v1/claim
coap://{{HOST_NAME}}/api/v1/claim
```
{: .copy-code}

Where **$THINGSBOARD_HOST_NAME** is your localhost, or the platform address.
> ⚠️ Don&#39;t forget to replace <code>{{HOST_NAME}}</code> with your ThingsBoard{% if docsPrefix == "edge/" or docsPrefix == "pe/edge/" %} Edge{% endif %} hostname or IP address.

{% endif %}
{% if docsPrefix == "paas/" or docsPrefix == "paas/eu/"%}

```shell
coap://{{coapHostName}}/api/v1/claim
```
Expand Down
48 changes: 22 additions & 26 deletions _includes/templates/api/coap/client-side-rpc-access-token.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,71 +1,67 @@
Send POST request to the following URL:

{% if docsPrefix == null or docsPrefix == "pe/"%}
{% if docsPrefix == nil or docsPrefix == "pe/" or docsPrefix == "edge/" or docsPrefix == "pe/edge/" %}
```shell
coap://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc
coap://{{HOST_NAME}}/api/v1/$ACCESS_TOKEN/rpc
```
{: .copy-code}

Where
- **$THINGSBOARD_HOST_NAME** is your localhost, or the platform address;
- **$ACCESS_TOKEN** is device access token.

{% endif %}
{% if docsPrefix == "paas/" or docsPrefix == "paas/eu/"%}
{% if docsPrefix contains "paas/" %}

```shell
coap://{{coapHostName}}/api/v1/$ACCESS_TOKEN/rpc
```
{: .copy-code}

Where **$ACCESS_TOKEN** is device access token.

{% endif %}

> Where {% unless docsPrefix contains "paas/" %}
&#8194;&#8226;&#8194;<code>{{HOST_NAME}}</code> is your ThingsBoard{% if docsPrefix == "edge/" or docsPrefix == "pe/edge/" %} Edge{% endif %} hostname or IP address.
&#8194;&#8226;&#8194;{% endunless %}<code>$ACCESS_TOKEN</code> is your device&#39;s access token.

Both request and response body should be valid JSON documents. The content of the documents is specific to the rule node that will handle your request.

<br>
**Let's look at an example**:

- Add two nodes to the Rule Chain: "**script**" and "**rpc call reply**";
**Example**

- In the {% if docsPrefix == "edge/" or docsPrefix == "pe/edge/" %}**Edge** {% endif %}**Root Rule Chain** add two nodes: [script](/docs/user-guide/rule-engine-2-0/nodes/transformation/script){:target="_blank"} and [rpc call reply](/docs/user-guide/rule-engine-2-0/nodes/action/rpc-call-reply){:target="_blank"}.
- In the **script** node enter the function:

```shell
return {msg: {time:String(new Date())}, metadata: metadata, msgType: msgType};
```
{: .copy-code}

- Save the "[rpc-client-request.json](/docs/reference/resources/rpc-client-request.json)" file to your PC;
- Save the [rpc-client-request.json](/docs/reference/resources/rpc-client-request.json){:target="_blank" download="rpc-client-request.json"} file to your PC;
- Now, send request to the server using the command below:

{% if docsPrefix == null or docsPrefix == "pe/" %}
- Now, send request to the server using the command below. Don't forget to replace <code>$THINGSBOARD_HOST_NAME</code> with your host and <code>$ACCESS_TOKEN</code> with your device's access token:
{% if docsPrefix == nil or docsPrefix == "pe/" or docsPrefix == "edge/" or docsPrefix == "pe/edge/" %}

```shell
cat rpc-client-request.json | coap post coap://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc
cat rpc-client-request.json | coap post coap://{{HOST_NAME}}/api/v1/$ACCESS_TOKEN/rpc
```
{: .copy-code}

{% endif %}
{% if docsPrefix == "paas/" or docsPrefix == "paas/eu/"%}
- Now, send request to the server using the command below. Don't forget to replace <code>$ACCESS_TOKEN</code> with your device's access token:
{% if docsPrefix contains "paas/" %}

```shell
cat rpc-client-request.json | coap post coap://{{coapHostName}}/api/v1/$ACCESS_TOKEN/rpc
```
{: .copy-code}
{% endif %}
{% if docsPrefix == "edge/" %}
- Now, send request to the server using the command below. Don't forget to replace <code>$THINGSBOARD_EDGE_HOST_NAME</code> with your host and <code>$ACCESS_TOKEN</code> with your device's access token:

```shell
cat rpc-client-request.json | coap post coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc
```
{: .copy-code}
{% endif %}
> ⚠️ Replace {% unless docsPrefix contains "paas/" %}
&#8194;&#8226;&#8194;<code>{{HOST_NAME}}</code> with your ThingsBoard{% if docsPrefix == "edge/" or docsPrefix == "pe/edge/" %} Edge{% endif %} hostname or IP address.
&#8194;&#8226;&#8194;{% endunless %}<code>$ACCESS_TOKEN</code> with your device&#39;s access token.

- You should receive a response from the server:

```shell
{"time":"2016 11 21 12:54:44.287"}
```

{% include images-gallery.html imageCollection="client-side-rpc" %}
{% if docsPrefix == nil or docsPrefix == "pe/" or docsPrefix == "paas/" or docsPrefix == "paas/eu/" %}
{% include images-gallery.html imageCollection="client-side-rpc" %}
{% endif %}
40 changes: 19 additions & 21 deletions _includes/templates/api/coap/client-side-rpc-certificate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,17 @@
Send POST request to the following URL:

{% if docsPrefix == null or docsPrefix == "pe/"%}
{% if docsPrefix == nil or docsPrefix == "pe/" or docsPrefix == "edge/" or docsPrefix == "pe/edge/" %}

```shell
coap://$THINGSBOARD_HOST_NAME/api/v1/rpc
coap://{{HOST_NAME}}/api/v1/rpc
```
{: .copy-code}

Where **$THINGSBOARD_HOST_NAME** is your localhost, or the platform address.
> ⚠️ Where <code>{{HOST_NAME}}</code> is your ThingsBoard{% if docsPrefix == "edge/" or docsPrefix == "pe/edge/" %} Edge{% endif %} hostname or IP address.

{% endif %}
{% if docsPrefix == "paas/" or docsPrefix == "paas/eu/"%}
{% if docsPrefix contains "paas/" %}

```shell
coap://{{coapHostName}}/api/v1/rpc
```
Expand All @@ -20,42 +22,36 @@ coap://{{coapHostName}}/api/v1/rpc
Both request and response body should be valid JSON documents. The content of the documents is specific to the rule node that will handle your request.

<br>
**Let's look at an example**:

- Add two nodes to the Rule Chain: "**script**" and "**rpc call reply**";
**Example**

- In the {% if docsPrefix == "edge/" or docsPrefix == "pe/edge/" %}**Edge** {% endif %}**Root Rule Chain** add two nodes: [script](/docs/user-guide/rule-engine-2-0/nodes/transformation/script){:target="_blank"} and [rpc call reply](/docs/user-guide/rule-engine-2-0/nodes/action/rpc-call-reply){:target="_blank"}.
- In the **script** node enter the function:

```shell
return {msg: {time:String(new Date())}, metadata: metadata, msgType: msgType};
```
{: .copy-code}

- Save the "[rpc-client-request.json](/docs/reference/resources/rpc-client-request.json)" file to your PC;
- Save the [rpc-client-request.json](/docs/reference/resources/rpc-client-request.json){:target="_blank" download="rpc-client-request.json"} file to your PC;
- Now, send request to the server using the command below:

{% if docsPrefix == null or docsPrefix == "pe/" %}
- Now, send request to the server using the command below. Don't forget to replace <code>$THINGSBOARD_HOST_NAME</code> with your host:
{% if docsPrefix == nil or docsPrefix == "pe/" or docsPrefix == "edge/" or docsPrefix == "pe/edge/" %}

```shell
cat rpc-client-request.json | coap post coap://$THINGSBOARD_HOST_NAME/api/v1/rpc
cat rpc-client-request.json | coap post coap://{{HOST_NAME}}/api/v1/rpc
```
{: .copy-code}

> ⚠️ Replace <code>{{HOST_NAME}}</code> with your ThingsBoard{% if docsPrefix == "edge/" or docsPrefix == "pe/edge/" %} Edge{% endif %} hostname or IP address.

{% endif %}
{% if docsPrefix == "paas/" or docsPrefix == "paas/eu/"%}
- Now, send request to the server using the command below:
{% if docsPrefix contains "paas/" %}

```shell
cat rpc-client-request.json | coap post coap://{{coapHostName}}/api/v1/rpc
```
{: .copy-code}
{% endif %}
{% if docsPrefix == "edge/" %}
- Now, send request to the server using the command below. Don't forget to replace <code>$THINGSBOARD_EDGE_HOST_NAME</code> with your host:

```shell
cat rpc-client-request.json | coap post coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/rpc
```
{: .copy-code}
{% endif %}

- You should receive a response from the server:
Expand All @@ -64,4 +60,6 @@ cat rpc-client-request.json | coap post coap://$THINGSBOARD_EDGE_HOST_NAME/api/v
{"time":"2016 11 21 12:54:44.287"}
```

{% include images-gallery.html imageCollection="client-side-rpc-certificate" %}
{% if docsPrefix == nil or docsPrefix == "pe/" or docsPrefix == "paas/" or docsPrefix == "paas/eu/" %}
{% include images-gallery.html imageCollection="client-side-rpc-certificate" %}
{% endif %}
Loading