Device Access Troubleshooting Checklist

Page Guide

Use CasesSuitable for access issues such as devices not coming online, data not being reported, commands not being delivered, protocol parsing errors, and rules not being triggered.

How to UseTroubleshoot in the order of "Product → Device → Network → Authentication → Payload → Platform logs → Business chain".

Acceptance CriteriaThe device is online, its running status refreshes, device logs are recorded, and commands delivered by the platform are received by the device.

Related ObjectsApplies to MQTT, HTTP, CoAP, TCP, Modbus, gateway sub-device, and video device access.

1. First determine which layer the problem stops at: network unreachable, authentication failure, device offline, data not displayed, commands not received, or rules and alerts not triggered.
2. Change only one variable at a time, and record the device number, product ID, request time, Topic/API, payload content, and backend logs.
3. Reproduce the minimal link with MQTTX, Postman, or curl first, then go back to the real device to troubleshoot firmware, network, and protocol implementation.

1. Troubleshooting Order

Do not modify code at the very beginning. The vast majority of access issues come from an unpublished product, inconsistent authentication fields, a mistyped device number, mismatched Thing Model identifiers, or closed ports.

2. Product Checks

Check Item	Normal State	Impact of Abnormality
Product status	Published	Device authentication or creation fails when unpublished
Transport protocol	Matches the device access method	Selecting HTTP for an MQTT device causes an authentication chain mismatch
Communication protocol	Matches the device payload format	Payloads cannot be parsed correctly into the Thing Model
Authentication method	Matches the device-side implementation	Simple and encrypted authentication cannot be mixed
Device authorization	The device carries the authorization code	Authentication fails when authorization is enabled but the device does not carry the code
Thing Model identifiers	Exactly match the device-side id	Data is received successfully but not displayed

3. Device Checks

Check Item	Normal State	Troubleshooting Suggestion
Device number	Exactly the same on the platform and the device	Watch case sensitivity, special characters, and length requirements
Device disabled	Off	A disabled device cannot connect
Owning product	Matches the product in the authentication parameters	Do not confuse the product ID with the product number
Device shadow	Selected according to the business	Turn it off during early integration to avoid interference from offline commands
Device logs	Contain online, reporting, and delivery records	When there are no logs, check authentication and network first

4. Network And Ports

Protocol	Common Port	Verification Method
MQTT	1883	Connect with MQTTX and view clients in the EMQX console
MQTT WebSocket	8083	Connect from a browser or a WebSocket tool
HTTP	Backend service port or gateway port	Call the API with Postman/curl
CoAP	The CoAP port in the deployment configuration	Send messages with a CoAP debugging tool
TCP	TCP service listening port	telnet/nc or device logs
GB28181/SIP	5061, etc.	Device registration logs and SIP service logs
Streaming media	30000-30100, etc.	Live streaming, playback, and ZLM logs

If local connections work but external devices cannot connect, check the cloud server security groups, firewall, NAT, port mapping, and reverse proxy first.

5. Authentication Issues

MQTT

Simple authentication format:

clientId = S & deviceNumber & productId & userId
username = mqttAccount
password = mqttPassword

When device authorization is enabled:

password = mqttPassword & deviceAuthorizationCode

Common mistakes:

• Treating the product number as the product ID.
• A wrong user ID, causing unexpected device ownership.
• Not appending the authorization code after device authorization is enabled.
• An incorrect expiry time format for encrypted authentication.

HTTP/CoAP/TCP

Key checks:

• Whether the device number, product ID, authentication account, and authentication password match the product.
• Whether the request path, request method, and Content-Type are correct.
• Whether the device-side time drift is too large.
• Whether a gateway or proxy rewrites the request body.

6. Payload Issues

Thing Model Reporting

The standard platform report usually uses an array:

[
  {
    "id": "temperature",
    "value": "26.5",
    "remark": "Device report"
  }
]

Key checks:

1. Whether id exactly matches the Thing Model identifier.
2. Whether value matches the data type.
3. Whether arrays, objects, and object arrays are expanded according to the platform convention.
4. Whether booleans and enums use the agreed keys and values.
5. Whether the payload encoding is UTF-8.

Gateway Sub-devices

Key checks:

1. Whether the gateway product and sub-product relationship is configured.
2. Whether sub-device addresses are unique.
3. Whether sub-devices have been imported or auto-creation is allowed.
4. Whether the data ownership field is correct when multiple sub-devices report at the same time.
5. Whether the logic for sub-devices going offline together with the gateway meets expectations.

Modbus

Key checks:

1. Whether the serial parameters or TCP address are correct.
2. Whether the slave address, register address, and function code are correct.
3. Whether the data type, byte order, scaling factor, and decimal places are correct.
4. Whether the cloud polling task is enabled.
5. Whether the Modbus-related cache in Redis needs to be cleared after configuration changes.

7. Platform Logs

Log Location	Purpose
Device Details > Device Logs	View online, reporting, delivery, and exception records
EMQX console	View client connections, subscriptions, and authentication results
Backend logs	View API, protocol parsing, database, and cache exceptions
Rule engine logs	View whether rules are triggered and whether scripts report errors
ZLM/recording service logs	View video stream, playback, Hook, and recording exceptions

When troubleshooting, record the device number, product ID, request time, and requestId at the same time so the issue can be located in the backend logs.

8. FAQ

Symptom	Check First	Common Handling
Device stays offline	Network ports, product publication, authentication parameters, device disabled status	Connect with a debugging tool first, then replace with real device parameters
Device online but no data	Reporting Topic/API, Thing Model identifiers, data types, product publication status	Verify one property with a minimal JSON payload
Command delivery fails	Device subscribed Topic, device online status, Thing Model read-write property, user permissions	Print the delivered message on the device side
Auto-registration fails	Device number, product ID, user ID, authorization code, tenant ownership	Create the device manually first, then compare the authentication parameters
Rules or alerts not triggered	Whether running status refreshes, rule variable binding, condition types, alert enabled status	Confirm data is stored first, then check the business rules

9. Related Docs

• MQTT Device Access
• HTTP Device Access
• CoAP Device Access
• TCP Device Access
• Modbus RTU Access
• Modbus TCP Access
• Gateway And Sub-devices
• Video Device Access