A subdevice is a device that reaches the platform through another device, its gateway. The gateway publishes MQTT messages on behalf of the equipment behind it, and a product turns each message into data of the right subdevice. Each subdevice has its own connection state, properties, Data Buckets and dashboards, as if it were connected directly.

When to use it

• An MQTT gateway forwards the data of many sensors, PLCs or meters, and you want one device per sensor instead of one device for the whole gateway.
• You need to know which equipment behind a gateway stopped reporting.

Use an MQTT device for the gateway itself, and a virtual device for a device that is computed on the platform.

How subdevices connect

1. The gateway connects as an MQTT device and publishes each reading on a topic that includes the ID of the equipment, such as gateway/sensor_01/telemetry.
2. A product, with the subdevices assigned to it, has a flow or API resource that listens to those topics and takes the device ID from the topic or the payload.
3. When a message arrives for a subdevice, it shows as connected and its data goes to the product's Data Buckets and properties. If messages stop, it shows as disconnected after its timeout.

The product decides how to read the topics and payloads: see Flows and API resources.

Create a subdevice

Create subdevices with the API, the CLI or an agent; the console's Add Device form does not offer this type. You can also let the product create them on their first message with Auto Provision.

API

POST/v1/users/{user}/devicesAPI reference

curl -X POST "https://YOUR_SERVER/v1/users/YOUR_USER/devices" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"device": "YOUR_DEVICE", "type": "Subdevice", "protocol": "MQTT", "parent": "my_gateway", "product": "YOUR_PRODUCT"}'

YOUR_SERVER is iot.thinger.io on the free Cloud account, or your own domain. YOUR_TOKEN is an access token of your account. parent names the gateway device and protocol the protocol it uses; subdevices have no device credentials.

CLI

thinger device create YOUR_DEVICE -t Subdevice -p YOUR_PRODUCT

The CLI cannot set the gateway or the protocol. Use the API if you need them.

AI

Ask your AI agent

Create a subdevice called YOUR_DEVICE behind my gateway my_gateway, using MQTT, and assign it to the product YOUR_PRODUCT.

List and remove subdevices

Subdevices appear in Devices with the rest of your devices, and thinger device list shows their type as Subdevice. Delete one like any other device:

Console

Open the device, go to Settings and delete it.

API

DELETE/v1/users/{user}/devices/{device}API reference

curl -X DELETE "https://YOUR_SERVER/v1/users/YOUR_USER/devices/YOUR_DEVICE" \
  -H "Authorization: Bearer YOUR_TOKEN"

CLI

thinger device delete YOUR_DEVICE

AI

Ask your AI agent

Delete the subdevice YOUR_DEVICE from my Thinger.io account.

Limits

• Subdevices connect only through MQTT topics handled by a product. The device libraries and the Linux client do not create subdevices.
• The gateway of a subdevice is not shown in the console or returned by the API: name subdevices so that their gateway is clear, or keep it in a property.
• A subdevice has no Terminal or Explorer, and no device resources other than those of its product.
• Subdevices count as devices of your account: see Plans and limits.

Related pages

MQTTConnect an MQTT client to the Thinger.io broker, publish and subscribe to topics, and store the messages in a Data Bucket.Provisioning at scaleCompare the three ways to add devices to Thinger.io - by hand, with Auto Provision when they first connect, and with claims that hand them to other accounts.Virtual devicesCreate devices without hardware whose device resources are computed on the platform, such as a weather station that reads a public weather API.