IOTMP (Internet of Things Message Protocol) is the protocol of the Thinger.io device libraries. A device opens one connection to the server and keeps it open; over it, the platform calls the device and the device calls the platform, in both directions and at any time. Messages are binary and use the PSON encoding, so they stay small on constrained boards and networks.

The full specification of IOTMP and PSON, with the message formats, the encoding rules and wire examples, is published at iotmp.io. This page covers how Thinger.io uses the protocol and what you need to connect a device.

IOTMP specificationMessage types, framing, PSON encoding, streaming and security of the protocol.

What Thinger.io uses it for

Feature	Direction	What happens on the connection
Device resources	Platform to device	The platform asks the device for its list of device resources and calls them: reads a sensor, switches a relay. The console, the REST API, dashboards, other devices and AI agents all go through it.
Real-time streams	Device to platform	While a dashboard or another client listens to a device resource, the device sends its value at an interval or when it changes. Nothing is sent when no one listens.
Data Buckets	Device to platform	The device writes data to a Data Bucket.
Properties	Device to platform	The device reads and writes its properties.
Endpoints	Device to platform	The device calls an endpoint, with or without data.
Device-to-device calls	Device to platform to device	The device calls a device resource of another connected device of the same account.
Remote tools	Platform to device	Terminal, file explorer and logs of the devices whose library supports them.

Because the connection stays open, the platform also knows whether each device is online: it changes when the connection opens or closes, and it fires the device_state_change event (see Events).

Connect a device

To connect, a device needs the server address, a port, and its credentials. The libraries set the port for you; you set the server only on a private instance.

Server

YOUR_SERVER is the host of your account: iot.thinger.io on the free Cloud account, or your own domain on a private instance. The device libraries connect to the Thinger.io Cloud by default. Each library page explains how to set another server.

Ports

The server accepts IOTMP on these ports:

Port	Transport	Used by
25206	TLS	IOTMP as specified at iotmp.io: the ESP-IDF component, the Zephyr module and the Linux client.
25204	TCP without encryption	The same clients, with TLS turned off. Use it only for development or on a trusted network.
443	WebSocket over HTTPS, at wss://YOUR_SERVER/iotmp	The Linux client with the WebSocket transport, for networks that only allow web traffic.
25202	TLS	IOTMP legacy: the Arduino library.
25200	TCP without encryption	IOTMP legacy: the Arduino library on boards without TLS, or with TLS turned off.

Ports 25200 and 25202 carry IOTMP legacy, the earlier version of the protocol that the Arduino library speaks; the other ports carry IOTMP as specified at iotmp.io. You do not choose between them: each library uses its own ports. If a device cannot connect, check that the network allows outgoing connections to its port.

Over WebSocket, the client requests the subprotocol iotmp in the handshake and sends each IOTMP message in one binary WebSocket message.

On a private instance, the administrator can change these ports in the server settings of each host.

TLS

Use TLS in production. The libraries check the server certificate: against the certificate of the Thinger.io Cloud servers, against the Let's Encrypt root certificate on a private instance, or against the certificate you configure. For a private instance with a self-signed certificate, each library has an option to skip the check; see its page.

Device credentials

The device authenticates with three values: your username, the device ID and the device credentials. It sends them in its first message, CONNECT, and the server answers before anything else happens.

• The device must exist in your account as an IOTMP Device (type Generic in the API), created in Devices or with the REST API. See Devices.
• If the values do not match, the server rejects the connection and closes it. The libraries report it: the Arduino library, for example, prints Auth Failed! with THINGER_SERIAL_DEBUG.
• Thinger.io authenticates IOTMP devices with device credentials only.

Connection lifecycle

An IOTMP connection, from the first message to a reconnection.

1. Connect. The device opens the connection (TLS, TCP or WebSocket) and sends CONNECT with its credentials. The server answers OK, and the device is online; or it answers with an error and closes the connection.
2. Requests. Both sides send requests and wait for their answers. The platform lists the device resources with DESCRIBE and calls them with RUN; it starts and stops a stream with START_STREAM and STOP_STREAM, and the device sends the values in STREAM_DATA. The device uses RUN to write to a Data Bucket, read or write a property, or call an endpoint or another device.
3. Keepalive. When the device has nothing else to send, it sends KEEP_ALIVE, and the server echoes it. The libraries do it every 60 seconds. If the server receives nothing from the device for longer than its keepalive interval, plus a margin, it closes the connection and the device goes offline.
4. Reconnect. When the connection drops, the device libraries connect again on their own after a few seconds. A device that sends DISCONNECT, or closes the connection, goes offline at once.

The message names, their fields, the recommended timeouts and the reconnection back-off are defined in the specification.

Libraries that implement IOTMP

Library	Runs on	Ports	Guide
Arduino library (IOTMP legacy)	ESP32, ESP8266 and Arduino boards	25202, 25200	Arduino, Arduino library reference
ESP-IDF component	ESP32 with ESP-IDF	25206, 25204	ESP-IDF
Zephyr module	Boards running Zephyr RTOS	25206, 25204	Zephyr
Linux client	Linux computers and gateways	25206, 25204, 443	Linux

Devices that cannot use these libraries connect over MQTT or HTTP instead; see Connect a device to compare the options.

To write your own client, follow the specification at iotmp.io, connect to port 25206 (or WebSocket on 443) and authenticate with the device credentials of an IOTMP device. Once connected, your device resources appear in the console like those of any other device, and you can call them over HTTP with the REST API.