Dedicated and BYOC Connection Guide ​

This page introduces the protocols and ports used for connecting to the Dedicated and BYOC deployments and provides a troubleshooting guide for connection issues.

Protocols and Ports Q&A ​

The following table lists the protocols and ports used for connecting to the Dedicated and BYOC deployments.

What are MQTT over TCP and WebSocket? ​

The standard MQTT is a lightweight publish and subscribe messaging protocol for asynchronous data communication. It is built on the TCP/IP stack and can scale in unreliable network environments. Therefore, it is suitable for scenarios where device hardware storage space or network bandwidth is limited.

WebSocket protocol is a new network protocol based on TCP, which enables the creation of a persistent connection between a browser and a server through a single handshake. Since there is no need for repeated handshakes between the browser and server, bi-directional data exchange between the two becomes much simpler. Specifically, WebSocket in MQTT refers to establishing a connection using WebSocket first and then communicating over the WebSocket channel using the MQTT protocol, i.e. MQTT over WebSocket, which is mainly used for connections in the browser environment.

Both standard MQTT over TCP and WebSocket are unencrypted, so there can be safety risks.

The MQTT over TCP port is 1883, which corresponds to the mqtt. The WebSocket port is 8083, which corresponds to the ws.

How to Use MQTT over TCP and WebSocket Ports? ​

You can view the sample code for testing and connecting by using SDK Demos at Client Connection Guidelines.

What are MQTT over TLS/SSL and WebSocket over TLS/SSL？ ​

MQTT over TLS/SSL and WebSocket over TLS/SSL means to add TLS/SSL encryption to MQTT or WebSocket protocol communication. In this way, the communication is secured from eavesdropping and tampering.

The MQTT over TLS/SSL port is 8883, which corresponds to the 'mqtts'. The WebSocket over TLS/SSL port is 8084, which corresponds to the 'wss'.

How to Use MQTT over TLS/SSL and WebSocket over TLS/SSL Ports in a Standard Plan? ​

For the Standard plan, you can connect directly through port 15xxx (mqtts) and port 8084 (wss) on the deployment overview.

The standard plan uses one-way TLS. EMQX provides and maintains server-side CA. Some clients may need a server-side CA for verification, please download here.

How to Use MQTT over TLS/SSL and WebSocket over TLS/SSL Ports in a Professional Plan? ​

The Professional plan supports customized one-way/two-way TLS/SSL. You need to enable it via Configure TLS/SSL.

How to Use MQTT over TLS/SSL and WebSocket over TLS/SSL Ports in a BYOC Deployment? ​

The BYOC deployment supports customized one-way TLS/SSL certificates which configured during creating the deployment. You can connect directly through port 8883 (mqtts) and port 8084 (wss) on the deployment overview.

How to Write Client's Code for TLS/SSL Connection? ​

You can check sample code (TLS-related sample code) to write client's code.

Python
Java
GO
Node.js
ESP 32
ESP 8266
Android
swift

Connection Troubleshooting Guide ​

If you encounter problems when connecting to a deployment, follow the steps in this guide based on your deployment plan (Professional or Standard) for troubleshooting and self-diagnosis.

Dedicated - Standard Plan ​

If you encounter problems connecting to the EMQX Cloud Standard plan, self-diagnose and troubleshoot using the following steps:

1. Check the connection address. Ensure you are using the correct domain name provided by the Standard plan for connection. The Standard plan supports using a domain name as the connection address and supports CNAME pointing of EMQX Cloud's domain name to your own domain name for custom domain name configuration.
2. Confirm the connection port. The Standard plan by default opens the 15xxx (MQTT), 15xxx (MQTTS), 8083 (WebSocket), and 8084 (WSS) ports. The roles of different ports are as follows:
   • MQTT and WebSocket ports: These ports support plaintext transmission without encryption during transmission, suitable for scenarios where data encryption is not required, such as internal network communication or development environments.
   • MQTTS and WSS ports: These ports support secure transmission using TLS/SSL encryption, providing higher security, suitable for scenarios requiring encrypted communication, such as production environments or sensitive data transmission.
3. Test network connectivity. Use the telnet command to test the network connectivity between your server and the Standard plan. For example, you can run the following command to test connection to the Standard plan's MQTT port: telnet <Basic Edition deployment's domain name> 15xxx. Replace <Basic Edition deployment's domain name> with your actual deployment address.
4. Verify authentication information. EMQX Cloud Standard plan does not support anonymous authentication. Please ensure that you have correctly configured the MQTT client's username and password in the EMQX Cloud console and have made the correct configuration during the client connection.
5. Test using the MQTTX client. We recommend using MQTTX as a MQTT client testing tool. It's a free and easy-to-use cross-platform MQTT 5.0 client. You can use it to verify if the inability to connect is due to issues with the client code. For detailed instructions, see: MQTTX Documentation.

Dedicated - Professional Plan ​

If you encounter problems connecting to the Professional plan, self-diagnose and troubleshoot using the following steps:

1. Check the connection address. Ensure you are using the correct IP address provided by the Professional plan for connection. Note that the Professional plan supports direct connection using IP addresses and encrypted connection through custom TLS/SSL configuration. If you need a domain name as the connection address, you can point the Professional plan's connection IP address to your own domain name.

2. Confirm the connection port. The Professional plan by default opens the 1883 (MQTT) and 8083 (WebSocket) ports. You can open the secure 8883 (MQTTS) and 8084 (WSS) ports through TLS/SSL configuration. The roles of different ports are as follows:

   • MQTT and WebSocket ports: These ports support plaintext transmission without encryption during transmission, suitable for scenarios where data encryption is not required, such as internal network communication or development environments.
   • MQTTS and WSS ports: These ports support secure transmission using TLS/SSL encryption, providing higher security, suitable for scenarios requiring encrypted communication, such as production environments or sensitive data transmission.

3. Test network connectivity. Use the telnet command to test the network connectivity between your server and the Professional plan.

   For example, you can run the following command to test connection to the Professional plan's MQTT port: telnet <Professional Edition deployment's IP address> 1883; or if you enabled TLS/SSL, test connection to the MQTTS port: telnet <Professional Edition deployment's IP address> 8883.

   Replace <Professional Edition deployment's IP address> with your actual deployment address.

4. Verify authentication information. EMQX Cloud Professional plan also does not support anonymous authentication. Please ensure that you have correctly configured the MQTT client's username and password in the EMQX Cloud console and have made the correct configuration during the client connection.

5. Test using the MQTTX client. We recommend using MQTTX as a MQTT client testing tool. It's a free and easy-to-use cross-platform MQTT 5.0 client. You can use it to verify if the inability to connect is due to issues with the client code. For detailed instructions, see: MQTTX Documentation.

Get Help via Support Ticket ​

If all the above steps are correct but the issue persists, please submit a support ticket through our ticket system. Provide the following detailed information to expedite issue resolution:

• Deployment name and ID (found on the "Deployment Management" page in the console)
• Deployment type (e.g., Serverless Plan, Standard, Professional, etc.)
• Specific client type and version
• Client connection example code (provide your programming language, e.g., Python, JavaScript, and the relevant connection code with sensitive information redacted)
• Client error logs or specific error messages (please provide detailed error descriptions or screenshots, if possible)