Device Onboarding Guide

Step-by-step guide for connecting your IoT devices to WAYSCloud IoT Platform.

Overview: Getting Started

Register account → Get API key
Register IoT device → Get MQTT credentials
Device connects to MQTT broker → Authentication
Device can send/receive messages

Step 1: Register an IoT Device

You can register devices via the Web Dashboard or programmatically via API.

Method 1: Via Web Dashboard (Recommended)

Dashboard URL: https://dashboard.wayscloud.services

Log in with your Keycloak SSO credentials
Navigate to IoT Devices → Add Device
Fill in the registration form:
- Device ID: Unique identifier (e.g., serial number, MAC address)
- Name: Human-readable name (e.g., "Warehouse Sensor #1")
- Description: Device description
- Metadata: Additional info (location, model, firmware version)
Click Register

Response (shown once):

{
  "device_id": "sensor-001",
  "mqtt_username": "sensor-001",
  "mqtt_password": "mqtt_a7f3e9c4b1d6",
  "mqtt_host": "mqtt.wayscloud.services",
  "mqtt_port": 1883,
  "mqtt_port_tls": 8883,
  "mqtt_port_ws": 8083,
  "mqtt_port_wss": 8084
}

Important

MQTT password is shown ONLY ONCE during registration. Save it securely immediately.

Method 2: Via API (For Automation)

Endpoint: POST https://api.wayscloud.services/v1/iot/devices

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request:

{
  "device_id": "sensor-001",
  "name": "Temperature Sensor #1",
  "description": "Main warehouse temperature sensor",
  "device_type": "DHT22",
  "metadata": {
    "location": "warehouse-a",
    "model": "DHT22",
    "firmware": "v1.2.3"
  }
}

Response (201 Created):

{
  "id": "abc123-def456-ghi789",
  "customer_id": "cust-uuid",
  "device_id": "sensor-001",
  "name": "Temperature Sensor #1",
  "mqtt_username": "sensor-001",
  "mqtt_password": "mqtt_a7f3e9c4b1d6",
  "is_active": true,
  "created_at": "2025-11-05T12:00:00Z"
}

Step 2: Connect Device to MQTT

Connection Details

Host: mqtt.wayscloud.services

Ports:
  1883  - MQTT over TCP (plain)
  8883  - MQTT over TLS/SSL (recommended)
  8083  - MQTT over WebSocket
  8084  - MQTT over WebSocket Secure (WSS)

Protocol: MQTT v3.1.1 / v5.0
Username: <device_id>
Password: <mqtt_password>
Client ID: <device_id>

Python Example (paho-mqtt)

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

# MQTT credentials from registration
MQTT_HOST = "mqtt.wayscloud.services"
MQTT_PORT = 1883
MQTT_USERNAME = "sensor-001"
MQTT_PASSWORD = "mqtt_a7f3e9c4b1d6"
CLIENT_ID = "sensor-001"

def on_connect(client, userdata, flags, rc):
    if rc == 0:
        print("Connected to MQTT broker")
        # Subscribe to command topic
        client.subscribe(f"devices/{CLIENT_ID}/commands/#")
    else:
        print(f"Connection failed with code {rc}")

def on_message(client, userdata, msg):
    print(f"Received: {msg.topic} - {msg.payload.decode()}")

# Create MQTT client
client = mqtt.Client(client_id=CLIENT_ID, protocol=mqtt.MQTTv311)
client.username_pw_set(MQTT_USERNAME, MQTT_PASSWORD)

# Set Last Will and Testament
client.will_set(
    topic=f"devices/{CLIENT_ID}/status",
    payload=json.dumps({"status": "offline"}),
    qos=1,
    retain=True
)

# Set callbacks
client.on_connect = on_connect
client.on_message = on_message

# Connect to broker
client.connect(MQTT_HOST, MQTT_PORT, keepalive=60)

# Start network loop
client.loop_start()

# Publish telemetry
while True:
    payload = {
        "temperature": 22.5,
        "humidity": 45.2,
        "timestamp": time.time()
    }

    topic = f"devices/{CLIENT_ID}/telemetry"
    client.publish(topic, json.dumps(payload), qos=1)
    print(f"Published to {topic}")

    time.sleep(10)

Node.js Example (mqtt.js)

const mqtt = require('mqtt');

// MQTT credentials from registration
const MQTT_HOST = 'mqtt://mqtt.wayscloud.services:1883';
const MQTT_USERNAME = 'sensor-001';
const MQTT_PASSWORD = 'mqtt_a7f3e9c4b1d6';
const CLIENT_ID = 'sensor-001';

// Connect options
const options = {
  clientId: CLIENT_ID,
  username: MQTT_USERNAME,
  password: MQTT_PASSWORD,
  clean: true,
  reconnectPeriod: 5000,
  keepalive: 60,
  protocolVersion: 4, // MQTT v3.1.1
  will: {
    topic: `devices/${CLIENT_ID}/status`,
    payload: JSON.stringify({ status: 'offline' }),
    qos: 1,
    retain: true
  }
};

// Connect to broker
const client = mqtt.connect(MQTT_HOST, options);

client.on('connect', () => {
  console.log('Connected to MQTT broker');

  // Subscribe to commands
  client.subscribe(`devices/${CLIENT_ID}/commands/#`, (err) => {
    if (!err) {
      console.log('Subscribed to commands');
    }
  });

  // Publish online status
  client.publish(
    `devices/${CLIENT_ID}/status`,
    JSON.stringify({ status: 'online' }),
    { qos: 1, retain: true }
  );
});

client.on('message', (topic, message) => {
  console.log(`Received: ${topic} - ${message.toString()}`);
});

// Publish telemetry every 10 seconds
setInterval(() => {
  const payload = {
    temperature: 22.5,
    humidity: 45.2,
    timestamp: Date.now()
  };

  const topic = `devices/${CLIENT_ID}/telemetry`;
  client.publish(topic, JSON.stringify(payload), { qos: 1 });
  console.log(`Published to ${topic}`);
}, 10000);

WebSocket Example (Browser)

// Using MQTT.js in browser
const mqtt = require('mqtt');

const MQTT_URL = 'wss://mqtt.wayscloud.services:8084';
const CLIENT_ID = 'sensor-001';
const MQTT_USERNAME = 'sensor-001';
const MQTT_PASSWORD = 'mqtt_a7f3e9c4b1d6';

const client = mqtt.connect(MQTT_URL, {
  clientId: CLIENT_ID,
  username: MQTT_USERNAME,
  password: MQTT_PASSWORD,
  clean: true,
  keepalive: 60
});

client.on('connect', () => {
  console.log('Connected via WebSocket');

  client.subscribe(`devices/${CLIENT_ID}/commands/#`);

  // Publish data
  setInterval(() => {
    const payload = {
      value: Math.random() * 100,
      timestamp: Date.now()
    };

    client.publish(
      `devices/${CLIENT_ID}/telemetry`,
      JSON.stringify(payload),
      { qos: 1 }
    );
  }, 5000);
});

Step 3: MQTT Topic Structure

Device to Platform (Publish)

devices/{device_id}/telemetry    - Time-series sensor data
devices/{device_id}/events       - Event notifications
devices/{device_id}/attributes   - Device attributes
devices/{device_id}/status       - Device status updates

Example:

Topic: devices/sensor-001/telemetry
Payload: {"temperature": 22.5, "humidity": 45.2, "timestamp": 1699189234}

devices/{device_id}/commands/reboot     - Reboot command
devices/{device_id}/commands/config     - Configuration update
devices/{device_id}/commands/firmware   - Firmware update
devices/{device_id}/commands/custom     - Custom commands

Example:

Topic: devices/sensor-001/commands/config
Payload: {"interval": 5, "threshold": 25.0}

ACL Rules

Devices can ONLY:

Publish to: devices/{device_id}/*
Subscribe to: devices/{device_id}/commands/*

Publishing to other device topics is blocked by the IoT Gateway ACL.

Step 4: Security Best Practices

Use TLS/SSL Encryption

import ssl

# Use port 8883 for TLS
MQTT_PORT = 8883

client = mqtt.Client(client_id=CLIENT_ID)
client.username_pw_set(MQTT_USERNAME, MQTT_PASSWORD)

# Enable TLS
client.tls_set(
    ca_certs=None,  # Use system CA bundle
    certfile=None,
    keyfile=None,
    cert_reqs=ssl.CERT_REQUIRED,
    tls_version=ssl.PROTOCOL_TLS,
    ciphers=None
)

client.connect(MQTT_HOST, MQTT_PORT, keepalive=60)

QoS Recommendations

QoS 0: At most once (fire and forget)
QoS 1: At least once (recommended for most use cases)
QoS 2: Exactly once (for critical commands only)

Recommendations:

Telemetry: QoS 1
Commands: QoS 1 or 2
Status updates: QoS 1

Last Will and Testament

Configure a Last Will message to notify the platform when device disconnects unexpectedly:

client.will_set(
    topic=f"devices/{CLIENT_ID}/status",
    payload='{"status": "offline", "unexpected": true}',
    qos=1,
    retain=True
)

Step 5: Monitor Device in Dashboard

Once connected, view your device in the Dashboard:

Dashboard → IoT Devices shows:

Device status (online/offline)
Last seen timestamp
Connection statistics
Message count (sent/received)
Data usage (bytes)

Dashboard → Analytics shows:

Real-time metrics
Time series charts
Top consumers
Alarms and alerts

GlobalSIM Integration

If using GlobalSIM SIM cards with your IoT devices:

Link SIM to Device

Via Dashboard:

Go to IoT Devices → Select device
Click Link SIM Card
Enter ICCID and click Link

Via API:

POST /api/v1/dashboard/iot/devices/{device_id}/sim
Content-Type: application/json

{
  "sim_iccid": "89470060990123456789"
}

Dashboard shows additional SIM info:

SIM network status (operator, country, signal strength)
Data usage (MB)
Network sessions
Roaming status
Cost estimation

Testing Tools

Test your MQTT connection with these tools:

Desktop Applications:

MQTT Explorer - Visual MQTT client
MQTTX - Cross-platform MQTT client

Command Line:

Mosquitto CLI: mosquitto_sub / mosquitto_pub

Example using mosquitto_pub:

mosquitto_pub \
  -h mqtt.wayscloud.services \
  -p 1883 \
  -u sensor-001 \
  -P mqtt_a7f3e9c4b1d6 \
  -t "devices/sensor-001/telemetry" \
  -m '{"temperature": 22.5}'

Troubleshooting

Connection Refused (rc=5)

Cause: Wrong username/password

Solution:

Verify credentials are correct
Check device is registered and active
Verify MQTT password hasn't been reset

Connection Timeout

Cause: Network issues or firewall blocking

Solution:

Ping mqtt.wayscloud.services to verify DNS
Check if port 1883/8883 is blocked by firewall
Try WebSocket (port 8083/8084) if TCP is blocked

Unauthorized Topic

Cause: Attempting to publish/subscribe to unauthorized topics

Solution:

Devices can ONLY publish to devices/{device_id}/*
Devices can ONLY subscribe to devices/{device_id}/commands/*
Check ACL rules in IoT Gateway

Next Steps

Device Management - Full API reference
MQTT Topics - Detailed topic structure
FAQ - Common questions
Examples - Complete code examples

Overview: Getting Started​

Step 1: Register an IoT Device​

Method 1: Via Web Dashboard (Recommended)​

Method 2: Via API (For Automation)​

Step 2: Connect Device to MQTT​

Connection Details​

Python Example (paho-mqtt)​

Node.js Example (mqtt.js)​

WebSocket Example (Browser)​

Step 3: MQTT Topic Structure​

Device to Platform (Publish)​

Platform to Device (Subscribe)​

Step 4: Security Best Practices​

Use TLS/SSL Encryption​

QoS Recommendations​

Last Will and Testament​

Step 5: Monitor Device in Dashboard​

GlobalSIM Integration​

Link SIM to Device​

Dashboard shows additional SIM info:​

Testing Tools​

Troubleshooting​

Connection Refused (rc=5)​

Connection Timeout​

Unauthorized Topic​

Next Steps​

Overview: Getting Started

Step 1: Register an IoT Device

Method 1: Via Web Dashboard (Recommended)

Method 2: Via API (For Automation)

Step 2: Connect Device to MQTT

Connection Details

Python Example (paho-mqtt)

Node.js Example (mqtt.js)

WebSocket Example (Browser)

Step 3: MQTT Topic Structure

Device to Platform (Publish)

Platform to Device (Subscribe)

Step 4: Security Best Practices

Use TLS/SSL Encryption

QoS Recommendations

Last Will and Testament

Step 5: Monitor Device in Dashboard

GlobalSIM Integration

Link SIM to Device

Dashboard shows additional SIM info:

Testing Tools

Troubleshooting

Connection Refused (rc=5)

Connection Timeout

Unauthorized Topic

Next Steps