ThingsBot

Manage ThingsBoard devices, dashboards, telemetry, and users via the ThingsBoard REST API.

Security Scan

The skill's requests and instructions are consistent with a ThingsBoard management tool: it only needs curl/jq and ThingsBoard credentials and contains no installers or unrelated secrets.

Purpose & Capability

Name/description match required binaries (curl, jq) and environment variables (TB_URL, TB_USERNAME, TB_PASSWORD). All declared requirements are appropriate for a REST-API-based ThingsBoard administration skill.

Instruction Scope

SKILL.md stays within ThingsBoard admin scope (login, devices, telemetry, dashboards, users). It instructs storing server info in credentials.json (a sample file is included). Two items to note: (1) SKILL.md references TB_REFRESH_TOKEN for token refresh but TB_REFRESH_TOKEN is not declared in requires.env (minor inconsistency); (2) many commands are administrative and destructive (DELETE endpoints, making dashboards public) — appropriate for the purpose but they require you to supply properly scoped credentials to avoid unintended changes.

Install Mechanism

Instruction-only skill with no install spec and no code files. This is low-risk: nothing is downloaded or written by an installer.

Credentials

Declared env vars (TB_URL, TB_USERNAME, TB_PASSWORD) are proportionate to the stated functionality. No unrelated credentials or high-privilege services are requested. The included credentials.json contains sample/local credentials — treat as example only and replace with appropriate credentials.

Persistence & Privilege

always is false and the skill does not request system config paths or global changes. disable-model-invocation is false (normal), so the agent could call the skill autonomously if allowed by policy — this is expected for functional skills.

Assessment

This skill is coherent for managing ThingsBoard via its REST API, but take these precautions before installing: - Do not provide production/admin credentials to the skill unless you trust the environment and the skill source; create a limited user with only the permissions needed (read/list vs. create/delete) where possible. - Replace the included sample credentials.json with your own config (the provided file contains example local credentials only). - Note the SKILL.md references a TB_REFRESH_TOKEN variable not declared in the requirements — expect to obtain/store refresh tokens at runtime if you need refresh functionality. - Understand that many example commands are destructive (DELETE, making dashboards public); verify commands before running and confirm TB_URL points to the intended server. - Because this is instruction-only (no installer), review the SKILL.md before use; it runs curl commands leveraging whatever credentials you provide. If you want stricter control, run the commands manually or provide a low-privilege account to the skill.

ThingsBoard Skill

Manage ThingsBoard IoT platform resources including devices, dashboards, telemetry data, and users.

Setup

1. Configure your ThingsBoard server in credentials.json:

   [
     {
       "name": "Server Thingsboard",
       "url": "http://localhost:8080",
       "account": [
         {
           "sysadmin": {
             "email": "[e-mail]",
             "password": "sysadmin"
           }
         },
         {
           "tenant": {
             "email": "[e-mail]",
             "password": "tenant"
           }
         }
       ]
     }
   ]
   

2. Set environment variables:

   export TB_URL="http://localhost:8080"
   export TB_USERNAME="[e-mail]"
   export TB_PASSWORD="tenant"
   

3. Get authentication token:

   export TB_TOKEN=$(curl -s -X POST "$TB_URL/api/auth/login" \
     -H "Content-Type: application/json" \
     -d "{\"username\":\"$TB_USERNAME\",\"password\":\"$TB_PASSWORD\"}" | jq -r '.token')
   

Usage

All commands use curl to interact with the ThingsBoard REST API.

Authentication

Login and get token:

curl -s -X POST "$TB_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"$TB_USERNAME\",\"password\":\"$TB_PASSWORD\"}" | jq -r '.token'

Refresh token (when expired):

curl -s -X POST "$TB_URL/api/auth/token" \
  -H "Content-Type: application/json" \
  -d "{\"refreshToken\":\"$TB_REFRESH_TOKEN\"}" | jq -r '.token'

Get current user info:

curl -s "$TB_URL/api/auth/user" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq

Device Management

List all tenant devices:

curl -s "$TB_URL/api/tenant/devices?pageSize=100&page=0" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq '.data[] | {name, id: .id.id, type}'

Get device by ID:

curl -s "$TB_URL/api/device/{deviceId}" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq

Get device credentials:

curl -s "$TB_URL/api/device/{deviceId}/credentials" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq

Telemetry & Attributes

Get telemetry keys:

curl -s "$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/keys/timeseries" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq

Get latest telemetry:

curl -s "$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/values/timeseries?keys=temperature,humidity" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq

Get timeseries data with time range:

START_TS=$(($(date +%s)*1000 - 3600000))  # 1 hour ago
END_TS=$(($(date +%s)*1000))              # now
curl -s "$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/values/timeseries?keys=temperature&startTs=$START_TS&endTs=$END_TS&limit=100" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq

Get attribute keys:

# Client scope
curl -s "$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/keys/attributes/CLIENT_SCOPE" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq

# Shared scope
curl -s "$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/keys/attributes/SHARED_SCOPE" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq

# Server scope
curl -s "$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/keys/attributes/SERVER_SCOPE" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq

Get attributes by scope:

curl -s "$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/values/attributes/CLIENT_SCOPE?keys=attribute1,attribute2" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq

Save device attributes:

curl -s -X POST "$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/attributes/SERVER_SCOPE" \
  -H "X-Authorization: Bearer $TB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"attribute1":"value1","attribute2":"value2"}' | jq

Delete timeseries keys:

curl -s -X DELETE "$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/timeseries/delete?keys=oldKey1,oldKey2&deleteAllDataForKeys=true" \
  -H "X-Authorization: Bearer $TB_TOKEN"

Dashboard Management

List all dashboards:

curl -s "$TB_URL/api/tenant/dashboards?pageSize=100&page=0" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq '.data[] | {name, id: .id.id}'

Get dashboard info:

curl -s "$TB_URL/api/dashboard/{dashboardId}" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq

Make dashboard public:

curl -s -X POST "$TB_URL/api/customer/public/dashboard/{dashboardId}" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq

Get public dashboard info (no auth required):

curl -s "$TB_URL/api/dashboard/info/{publicDashboardId}" | jq

Remove public access:

curl -s -X DELETE "$TB_URL/api/customer/public/dashboard/{dashboardId}" \
  -H "X-Authorization: Bearer $TB_TOKEN"

User Management

List tenant users:

curl -s "$TB_URL/api/tenant/users?pageSize=100&page=0" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq '.data[] | {email, firstName, lastName, id: .id.id}'

List customers:

curl -s "$TB_URL/api/customers?pageSize=100&page=0" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq '.data[] | {title, id: .id.id}'

Get customer users:

curl -s "$TB_URL/api/customer/{customerId}/users?pageSize=100&page=0" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq '.data[]'

Assets

List all assets:

curl -s "$TB_URL/api/tenant/assets?pageSize=100&page=0" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq '.data[] | {name, type, id: .id.id}'

Get asset by ID:

curl -s "$TB_URL/api/asset/{assetId}" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq

Notes

• Authentication: JWT tokens expire after a configured period (default: 2 hours). Re-authenticate when you receive 401 errors.
• Device/Dashboard IDs: Entity IDs are in the format {entityType: "DEVICE", id: "uuid"}. Use the id field for API calls.
• Pagination: Most list endpoints support pageSize and page parameters (default: 100 items per page, max: 1000).
• Attribute Scopes:
  • CLIENT_SCOPE: Client-side attributes (set by devices)
  • SHARED_SCOPE: Shared between server and devices
  • SERVER_SCOPE: Server-side only (not visible to devices)
• Timestamps: Use milliseconds since epoch for startTs and endTs parameters.
• Rate Limits: Check your ThingsBoard server configuration for API rate limits.
• HTTPS: For production, use HTTPS URLs (e.g., https://demo.thingsboard.io).

Examples

# Complete workflow: Login, list devices, get telemetry
export TB_URL="http://localhost:8080"
export TB_USERNAME="[e-mail]"
export TB_PASSWORD="tenant"

# Get token
export TB_TOKEN=$(curl -s -X POST "$TB_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"$TB_USERNAME\",\"password\":\"$TB_PASSWORD\"}" | jq -r '.token')

# List all devices
curl -s "$TB_URL/api/tenant/devices?pageSize=10&page=0" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq '.data[] | {name, type, id: .id.id}'

# Get first device ID
DEVICE_ID=$(curl -s "$TB_URL/api/tenant/devices?pageSize=1&page=0" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq -r '.data[0].id.id')

# Get telemetry keys for device
curl -s "$TB_URL/api/plugins/telemetry/DEVICE/$DEVICE_ID/keys/timeseries" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq

# Get latest telemetry values
curl -s "$TB_URL/api/plugins/telemetry/DEVICE/$DEVICE_ID/values/timeseries?keys=temperature,humidity" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq

# Get historical data (last hour)
START_TS=$(($(date +%s)*1000 - 3600000))
END_TS=$(($(date +%s)*1000))
curl -s "$TB_URL/api/plugins/telemetry/DEVICE/$DEVICE_ID/values/timeseries?keys=temperature&startTs=$START_TS&endTs=$END_TS&limit=100" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq

# List dashboards and make first one public
DASHBOARD_ID=$(curl -s "$TB_URL/api/tenant/dashboards?pageSize=1&page=0" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq -r '.data[0].id.id')

curl -s -X POST "$TB_URL/api/customer/public/dashboard/$DASHBOARD_ID" \
  -H "X-Authorization: Bearer $TB_TOKEN" | jq