Platforms
Product Lines
Platforms Safecrete Safewall Mine Operating System (Coming Soon)
© 2026 IndustryOS
On this page

Connecting Devices

Overview

IndustryOS IoT supports multiple protocols for device connectivity, allowing you to connect virtually any IoT device to the platform. This guide covers the primary protocols and how to use them to send telemetry data and attributes.

Supported Protocols

IndustryOS supports the following device communication protocols:

  • MQTT - Lightweight publish-subscribe messaging protocol, ideal for most IoT devices
  • HTTP/HTTPS - Request-response protocol, suitable for devices with intermittent connectivity
  • CoAP - Constrained Application Protocol for resource-constrained devices
  • LwM2M - Lightweight M2M protocol for device management

Each protocol has its own API and authentication methods, but they all share the same data model and key concepts.

Device Authentication

Before connecting a device, you need to create it in IndustryOS and obtain credentials. The platform supports several authentication methods:

Access Token Authentication

The simplest authentication method uses an access token:

  1. Navigate to Entities → Devices
  2. Create a new device or open an existing one
  3. In the device details, find the Access Token in the credentials section
  4. Copy the token to use in your device firmware

X.509 Certificate Authentication

For enhanced security, use certificate-based authentication:

  1. Generate X.509 certificates for your device
  2. Upload the certificate to the device credentials
  3. Configure your device to use TLS with the certificate

See Authentication and Security for detailed configuration.

MQTT Protocol

MQTT is a lightweight publish-subscribe messaging protocol, making it the most suitable for IoT devices.

MQTT Basics

  • QoS Levels: IndustryOS supports QoS 0 (at most once) and QoS 1 (at least once)
  • Port: 1883 (TCP) or 8883 (TLS/SSL)
  • Clean Session: Recommended for most use cases

MQTT Connection

Connect to the MQTT broker using your device access token as the username:

1
2
3
4
5
6
7

# Using mosquitto_pub client
mosquitto_pub -d -q 1 \
  -h "YOUR_SERVER_HOST" \
  -p "1883" \
  -t "v1/devices/me/telemetry" \
  -u "YOUR_ACCESS_TOKEN" \
  -m '{"temperature":25}'

Connection Return Codes:

  • 0x00 - Successfully connected
  • 0x04 - Connection refused, bad username or password
  • 0x05 - Connection refused, not authorised

Publishing Telemetry via MQTT

Publish telemetry to the topic:

1

v1/devices/me/telemetry

Simple format (server-side timestamp):

1

{"temperature":25, "humidity":65}

With client-side timestamp:

1
2
3
4
5
6
7

{
  "ts": 1451649600512,
  "values": {
    "temperature": 25,
    "humidity": 65
  }
}

Publishing Attributes via MQTT

Publish client-side attributes to the topic:

1

v1/devices/me/attributes

Example:

1
2
3
4

{
  "firmwareVersion": "1.2.3",
  "serialNumber": "SN-12345"
}

Requesting Shared Attributes via MQTT

To request shared attributes, subscribe to:

1

v1/devices/me/attributes/response/+

Then publish a request to:

1

v1/devices/me/attributes/request/$request_id

With payload:

1
2
3
4

{
  "clientKeys": "attribute1,attribute2",
  "sharedKeys": "shared1,shared2"
}

Subscribing to Attribute Updates via MQTT

To receive shared attribute updates, subscribe to:

1

v1/devices/me/attributes

You’ll receive notifications when server-side components update shared attributes.

RPC via MQTT

Server-side RPC (receive commands):

Subscribe to:

1

v1/devices/me/rpc/request/+

Respond by publishing to:

1

v1/devices/me/rpc/response/$request_id

Client-side RPC (send commands):

Publish to:

1

v1/devices/me/rpc/request/$request_id

Subscribe to responses:

1

v1/devices/me/rpc/response/+

HTTP/HTTPS Protocol

HTTP is a request-response protocol suitable for devices with intermittent connectivity.

HTTP Authentication

Include your access token as a path parameter:

1

http(s)://YOUR_SERVER_HOST/api/v1/$ACCESS_TOKEN/...

Error Codes:

  • 400 - Bad Request (invalid URL, parameters, or body)
  • 401 - Unauthorised (invalid access token)
  • 404 - Not Found (resource not found)

Publishing Telemetry via HTTP

Send POST request to:

1

http(s)://YOUR_SERVER_HOST/api/v1/$ACCESS_TOKEN/telemetry

Example using curl:

1
2
3
4

curl -v -X POST \
  --data '{"temperature":42,"humidity":73}' \
  https://YOUR_SERVER_HOST/api/v1/$ACCESS_TOKEN/telemetry \
  --header "Content-Type:application/json"

With timestamp:

1
2
3
4
5
6
7

{
  "ts": 1451649600512,
  "values": {
    "temperature": 42,
    "humidity": 73
  }
}

Publishing Attributes via HTTP

Send POST request to:

1

http(s)://YOUR_SERVER_HOST/api/v1/$ACCESS_TOKEN/attributes

Example:

1
2
3
4

curl -v -X POST \
  --data '{"firmwareVersion":"1.2.3"}' \
  https://YOUR_SERVER_HOST/api/v1/$ACCESS_TOKEN/attributes \
  --header "Content-Type:application/json"

Requesting Attributes via HTTP

Send GET request to:

1

http(s)://YOUR_SERVER_HOST/api/v1/$ACCESS_TOKEN/attributes?clientKeys=key1,key2&sharedKeys=key3,key4

Example:

1
2

curl -v -X GET \
  "https://YOUR_SERVER_HOST/api/v1/$ACCESS_TOKEN/attributes?clientKeys=firmwareVersion&sharedKeys=targetTemp"

Subscribing to Attribute Updates via HTTP

Long polling for attribute updates:

1

http(s)://YOUR_SERVER_HOST/api/v1/$ACCESS_TOKEN/attributes/updates?timeout=20000

Example:

1
2

curl -v -X GET \
  "https://YOUR_SERVER_HOST/api/v1/$ACCESS_TOKEN/attributes/updates?timeout=20000"

RPC via HTTP

Server-side RPC (receive commands):

Long polling for RPC requests:

1
2

curl -v -X GET \
  "https://YOUR_SERVER_HOST/api/v1/$ACCESS_TOKEN/rpc?timeout=20000"

Respond to RPC:

1
2
3
4

curl -v -X POST \
  -d @response.json \
  https://YOUR_SERVER_HOST/api/v1/$ACCESS_TOKEN/rpc/$REQUEST_ID \
  --header "Content-Type:application/json"

Client-side RPC (send commands):

1
2
3
4

curl -v -X POST \
  -d '{"method":"getTime","params":{}}' \
  https://YOUR_SERVER_HOST/api/v1/$ACCESS_TOKEN/rpc \
  --header "Content-Type:application/json"

CoAP Protocol

CoAP (Constrained Application Protocol) is designed for resource-constrained devices and low-power networks.

CoAP Connection

CoAP uses UDP on port 5683 (or 5684 for DTLS). Authentication uses the access token as a URI parameter.

Publishing Telemetry via CoAP

1
2
3
4
5

# Using coap-client
coap-client -m post \
  coap://YOUR_SERVER_HOST/api/v1/$ACCESS_TOKEN/telemetry \
  -t json \
  -e '{"temperature":25}'

Data Format

All protocols support the same key-value data format:

Simple Key-Value

1
2
3
4
5
6

{
  "stringKey": "value1",
  "booleanKey": true,
  "doubleKey": 42.0,
  "longKey": 73
}

Nested JSON

1
2
3
4
5
6
7
8

{
  "temperature": 25.5,
  "location": {
    "latitude": 51.5074,
    "longitude": -0.1278
  },
  "sensors": [1, 2, 3]
}

Array Format

1
2
3
4

[
  {"key1": "value1"},
  {"key2": true}
]

Client Libraries

Popular MQTT client libraries:

  • Python: paho-mqtt, asyncio-mqtt
  • JavaScript/Node.js: mqtt.js
  • Java: Eclipse Paho
  • C/C++: Eclipse Paho C, mosquitto
  • Arduino: PubSubClient
  • ESP32/ESP8266: PubSubClient, AsyncMqttClient

HTTP client libraries are available in virtually every programming language.

Connection Examples

Python MQTT Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

import paho.mqtt.client as mqtt
import json
import time

ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"
THINGSBOARD_HOST = "YOUR_SERVER_HOST"

client = mqtt.Client()
client.username_pw_set(ACCESS_TOKEN)
client.connect(THINGSBOARD_HOST, 1883, 60)

# Publish telemetry
telemetry = {"temperature": 25.5, "humidity": 65}
client.publish('v1/devices/me/telemetry', json.dumps(telemetry))

client.loop_start()
time.sleep(1)
client.loop_stop()
client.disconnect()

Arduino MQTT Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

#include <WiFi.h>
#include <PubSubClient.h>

const char* ssid = "YOUR_WIFI_SSID";
const char* password = "YOUR_WIFI_PASSWORD";
const char* mqtt_server = "YOUR_SERVER_HOST";
const char* token = "YOUR_ACCESS_TOKEN";

WiFiClient espClient;
PubSubClient client(espClient);

void setup() {
  Serial.begin(115200);
  WiFi.begin(ssid, password);
  
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  
  client.setServer(mqtt_server, 1883);
}

void loop() {
  if (!client.connected()) {
    client.connect("ESP32Client", token, NULL);
  }
  
  float temperature = 25.5;
  String payload = "{\"temperature\":" + String(temperature) + "}";
  client.publish("v1/devices/me/telemetry", payload.c_str());
  
  delay(5000);
}

Device Provisioning

For automated device onboarding at scale, see Device Provisioning.

Best Practices

Protocol Selection

  • Use MQTT for: Real-time applications, bi-directional communication, low-bandwidth scenarios
  • Use HTTP for: Simple polling, infrequent updates, request-response patterns
  • Use CoAP for: Extremely constrained devices, battery-powered sensors

Connection Management

  • Implement automatic reconnection logic
  • Use exponential backoff for retry attempts
  • Handle network interruptions gracefully
  • Monitor connection status

Data Transmission

  • Batch multiple telemetry points when possible
  • Use appropriate QoS levels for MQTT
  • Implement local buffering for offline scenarios
  • Compress data for bandwidth-constrained networks

Security

  • Always use TLS/SSL in production
  • Rotate access tokens periodically
  • Use certificate-based authentication for sensitive deployments
  • See Authentication and Security for details

Performance

  • Limit telemetry frequency to actual data changes
  • Use appropriate sampling rates
  • Avoid sending duplicate or unchanged values
  • Configure proper timeout values

Troubleshooting

Connection Issues

  1. Verify credentials: Ensure access token is correct
  2. Check network: Confirm device can reach the server
  3. Review firewall: Ensure ports are open (1883, 8883, 80, 443)
  4. Test connectivity: Use command-line tools (curl, mosquitto_pub)

Data Not Appearing

  1. Check device status: Verify device is active in UI
  2. Review payload format: Ensure JSON is valid
  3. Check timestamps: Verify timestamp values are reasonable
  4. Monitor logs: Check device and server logs

Authentication Failures

  1. Verify token: Copy token directly from device credentials
  2. Check device state: Ensure device is not disabled
  3. Review permissions: Confirm device has necessary access

Next Steps