Frequently Asked Questions

Common questions about WAYSCloud IoT Platform.

General Questions

Can I use the same API key for multiple devices?

Yes. All devices under the same customer account use the same API key for device registration and management. However, each device receives unique MQTT credentials (username/password) for broker authentication.

Example:

• API key: wayscloud_iot_prod_abc123 - Used to register devices via API
• Device 1 MQTT: sensor-001 / mqtt_password_xyz
• Device 2 MQTT: sensor-002 / mqtt_password_abc

---

What if I lose the MQTT password?

The MQTT password is shown only once during device registration. If you lose it, you have two options:

Option 1: Reset via Dashboard

1. Go to Dashboard → IoT Devices
2. Select the device
3. Click "Reset MQTT Password"
4. New password will be generated and shown once

Option 2: Re-register via API

# Delete device
DELETE /v1/iot/devices/{device_id}

# Register again
POST /v1/iot/devices

warning

Resetting the password will immediately disconnect the device until updated with new credentials.

---

How many devices can I connect?

Device limits depend on your subscription plan:

Plan	Max Devices	Messages/Month	Bandwidth
Starter	10	100,000	1 GB
Professional	1,000	10,000,000	100 GB
Enterprise	Unlimited	Custom	Custom

Check your current quota:

GET /v1/iot/quota

---

Do you support MQTT v5.0?

Yes. The EMQX broker supports both MQTT v3.1.1 and v5.0.

Python example (MQTT v5.0):

import paho.mqtt.client as mqtt

client = mqtt.Client(
    client_id="sensor-001",
    protocol=mqtt.MQTTv5
)

Node.js example:

const client = mqtt.connect('mqtt://mqtt.wayscloud.services', {
  protocolVersion: 5  // MQTT v5.0
});

---

Connection & Authentication

Can I use WebSocket from a browser?

Yes. Use MQTT over WebSocket for browser-based applications:

Ports:

• 8083 - WebSocket (ws://)
• 8084 - WebSocket Secure (wss://)

Example:

const mqtt = require('mqtt');

const client = mqtt.connect('wss://mqtt.wayscloud.services:8084', {
  clientId: 'browser-client-001',
  username: 'sensor-001',
  password: 'mqtt_password'
});

---

Are messages encrypted?

Messages are encrypted when using TLS/SSL:

Encrypted ports:

• 8883 - MQTT over TLS/SSL
• 8084 - WebSocket Secure (WSS)

Unencrypted ports (not recommended for production):

• 1883 - Plain MQTT
• 8083 - Plain WebSocket

Python TLS example:

import ssl

client = mqtt.Client(client_id="sensor-001")
client.username_pw_set("sensor-001", "mqtt_password")

client.tls_set(
    ca_certs=None,
    cert_reqs=ssl.CERT_REQUIRED,
    tls_version=ssl.PROTOCOL_TLS
)

client.connect("mqtt.wayscloud.services", 8883)

---

Why am I getting "Connection Refused (rc=5)"?

Error code 5 means authentication failed. Common causes:

1. Wrong username/password

   • Verify credentials match registration response
   • Check for typos or extra spaces

2. Device not registered or inactive

   • Confirm device exists: GET /v1/iot/devices/{device_id}
   • Check is_active: true

3. Password was reset

   • If you reset the password, update device configuration

---

Can I connect from behind a firewall?

If ports 1883/8883 are blocked:

Option 1: Use WebSocket

• Port 8083 (WS) or 8084 (WSS) often allowed through firewalls

Option 2: Configure firewall

• Allow outbound TCP to mqtt.wayscloud.services:1883 or :8883

Test connectivity:

# Test plain MQTT port
telnet mqtt.wayscloud.services 1883

# Test TLS port
openssl s_client -connect mqtt.wayscloud.services:8883

---

Topics & Messaging

What topics can my device publish to?

Devices can ONLY publish to their own topics:

Allowed:

devices/{device_id}/*

Examples:

devices/sensor-001/telemetry     ✓
devices/sensor-001/events        ✓
devices/sensor-001/status        ✓
devices/sensor-002/telemetry     ✗ (different device)

ACL rules enforce this restriction automatically.

---

What topics can my device subscribe to?

Devices can ONLY subscribe to their own command topics:

Allowed:

devices/{device_id}/commands/*

Examples:

devices/sensor-001/commands/#           ✓
devices/sensor-001/commands/config      ✓
devices/sensor-002/commands/reboot      ✗ (different device)
$SYS/broker/clients/connected           ✗ (system topic)

---

What is the maximum message size?

• Recommended: < 256 KB per message
• Maximum: 1 MB per message

For larger data:

1. Split into multiple messages
2. Use object storage and send URL via MQTT
3. Compress payload before sending

---

What QoS level should I use?

QoS 0 (At most once):

• Fire and forget
• No acknowledgment
• Use for: Non-critical telemetry

QoS 1 (At least once):

• Acknowledged delivery
• May receive duplicates
• Use for: Most telemetry, events, commands

QoS 2 (Exactly once):

• Guaranteed single delivery
• Slower performance
• Use for: Critical commands only

Recommendations:

• Telemetry: QoS 1
• Events: QoS 1
• Commands: QoS 1 or 2
• Status: QoS 1

---

Rate Limits & Performance

What are the rate limits?

HTTP API:

• 1,000 requests/minute per API key
• Burst: +200 requests

MQTT:

• 100 messages/second per device
• 1,000 concurrent connections per account (default)

Exceeding limits results in temporary throttling.

---

How often should devices send telemetry?

Depends on your use case:

Slow-changing data:

• Temperature/humidity: Every 60 seconds
• Battery level: Every 5 minutes

Moderate frequency:

• GPS tracking: Every 10-30 seconds
• Motion sensors: On change + heartbeat every minute

High frequency:

• Vibration monitoring: Every 1 second
• Real-time control: Sub-second (with rate limit awareness)

Optimization tip: Send on change + periodic heartbeat instead of fixed intervals.

---

Can I batch multiple readings in one message?

Yes, recommended for efficiency:

Instead of:

# 3 separate messages
client.publish("devices/sensor-001/telemetry", '{"temp": 22.5}')
client.publish("devices/sensor-001/telemetry", '{"humidity": 65}')
client.publish("devices/sensor-001/telemetry", '{"pressure": 1013}')

Do this:

# 1 message with all data
payload = {
    "temperature": 22.5,
    "humidity": 65,
    "pressure": 1013,
    "timestamp": 1699189234
}
client.publish("devices/sensor-001/telemetry", json.dumps(payload))

---

Integration & Features

Can I integrate with custom applications?

Yes, via several methods:

1. Subscribe to MQTT topics (backend application)

# Your application subscribes to all device telemetry
client.subscribe("devices/+/telemetry")

2. Webhooks (coming soon)

• Configure webhook to receive events via HTTP POST

3. Public API

• Query historical data: GET /v1/iot/usage
• Get device list: GET /v1/iot/devices

---

How do I link a GlobalSIM card to my device?

If using GlobalSIM for cellular connectivity:

Via Dashboard:

1. IoT Devices → Select device
2. Click "Link SIM Card"
3. Enter ICCID → Link

Via API:

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

{
  "sim_iccid": "89470060990123456789"
}

Dashboard will then show:

• Network operator and signal
• Data usage
• Roaming status
• Cost tracking

---

Can I see historical data in the Dashboard?

Yes, the Dashboard provides:

Real-time:

• Current device status
• Live message feed
• Active connections

Historical:

• Usage statistics (7/30/90 days)
• Message count over time
• Data usage charts
• Connection logs

Via API:

GET /v1/iot/usage?start_date=2025-10-01&end_date=2025-10-31

---

Troubleshooting

Device shows as offline but is connected

Common causes:

1. Not publishing status

   # Publish online status on connect
   client.publish(
       "devices/sensor-001/status",
       '{"status": "online"}',
       qos=1,
       retain=True
   )

2. Last Will not configured

   # Set Last Will before connecting
   client.will_set(
       "devices/sensor-001/status",
       '{"status": "offline"}',
       qos=1,
       retain=True
   )

3. Dashboard cache

   • Allow 30-60 seconds for status update
   • Refresh dashboard page

---

Messages not appearing in Dashboard

Check:

1. Topic name - Verify correct format: devices/{device_id}/telemetry
2. Payload format - Dashboard expects valid JSON
3. Permissions - Device must be active
4. Rate limits - Check if throttled

Debug with mosquitto_sub:

mosquitto_sub \
  -h mqtt.wayscloud.services \
  -p 1883 \
  -u sensor-001 \
  -P mqtt_password \
  -t "devices/sensor-001/#" \
  -v

---

How do I debug connection issues?

1. Enable verbose logging:

Python:

import logging
logging.basicConfig(level=logging.DEBUG)

client.enable_logger()

Node.js:

client.on('error', (error) => {
  console.error('MQTT Error:', error);
});

client.on('offline', () => {
  console.log('Client went offline');
});

2. Check MQTT return codes:

Code	Meaning	Solution
0	Success	Connected
1	Protocol version	Check MQTT version
2	Client ID rejected	Use unique client ID
3	Server unavailable	Check host/port
4	Bad username/password	Verify credentials
5	Not authorized	Check device is active

---

Support & Resources

Where can I get help?

Documentation:

• API docs: https://api.wayscloud.services/docs
• Dashboard: https://dashboard.wayscloud.services

Support:

• Email: support@wayscloud.services
• Community: https://community.wayscloud.services

Status:

• Platform status: https://status.wayscloud.services

---

Useful MQTT libraries

Python:

• paho-mqtt: https://pypi.org/project/paho-mqtt/

Node.js:

• mqtt.js: https://www.npmjs.com/package/mqtt

Arduino/ESP32:

• PubSubClient: https://github.com/knolleary/pubsubclient

C/C++:

• Paho MQTT C: https://github.com/eclipse/paho.mqtt.c

Java:

• Paho Java: https://github.com/eclipse/paho.mqtt.java

Go:

• paho.mqtt.golang: https://github.com/eclipse/paho.mqtt.golang

---

Next Steps

• Device Onboarding - Get started quickly
• MQTT Topics - Topic structure reference
• Examples - Complete code examples