Adding a basic MQTT connection

note

Basic MQTT connections are not yet available in self-hosted ThingPark Enterprise.

Basic MQTT connections provide a direct bidirectional connection between the Network Server (NS) and third-party Application Servers (AS) using MQTT protocol: uplink messages are published into MQTT topics, and downlink messages are received from an MQTT topic.

Device payloads are exchanged in an encoded format without the support of payload drivers.

To learn more about basic MQTT connections and the NS-AS Tunnel Interface, see the Tunnel Interface data-plane API.

---

1. Select Connections, and click ADD CONNECTION on the Connections page, or from Dashboard, go to the CONNECTIONS widget, and click.

2. Click the Basic MQTT type of connection.

3. Enter your connection information:

   • Name

   • Domains (optional): If the permission segregation based on domains has been enabled by an administrator, you may associate your connection with domains to restrict its visibility. Domain-specific connections are visible only to authorized users whose domain restrictions match. To learn more, see About domains.

     • If no domains are set, the connection is cross-domain and visible to all users. However, users having domain restrictions have read-only access to cross-domain connections.
     • If your user account has domain restrictions, the associated domains must match your domain restrictions without any domain prefix (only full domains can be assigned to resources).

   • Additional information (optional): Any useful information, administrative for instance, that is related to the connection.

4. In the MQTT broker field, select the type of MQTT broker to use:

   • ThingPark-hosted: Uses the ThingPark-managed MQTT broker. MQTT topics are automatically assigned and displayed as read-only in the connection dashboard after creation. Skip to step 6.

     note

     The ThingPark-hosted MQTT broker is only available on ThingPark SaaS, and only if enabled by the operator.

   • External: Connect to your own MQTT broker. Continue with step 5.

     note

     If the ThingPark-hosted MQTT broker has not been enabled by the operator, the MQTT broker field is not shown and the form always uses the External mode.

5. Configure the external MQTT broker connection:

   • Hostname: Hostname or IP address of the MQTT broker, optionally followed by a port. Example: myhostname:8883, broker.example.com, 192.168.1.10:1883.

   • Protocol: Security and authentication method used to connect to the MQTT broker:

     Protocol	Description
     TLS with username/password authentication (default)	Encrypted connection using login credentials.
     TLS with client certificate authentication	Encrypted connection using mutual TLS (client certificate).
     TLS with username/password + client certificate authentication	Encrypted connection using both login credentials and client certificate.
     TCP with username/password authentication	Unencrypted connection using login credentials only.

   • Client ID: Unique identifier for this MQTT client connection on the broker. If another client connects with the same Client ID, the previous connection may be disconnected.

   • MQTT username (for password-based protocols): Username used to authenticate with the MQTT broker.

   • MQTT password (for password-based protocols): Password used to authenticate with the MQTT broker.

   • CA certificate (optional, for TLS protocols): CA certificate in PEM format used to verify the MQTT broker's server certificate during the TLS handshake.

   • Certificate (for mutual TLS protocols): Client certificate in PEM format used for TLS client authentication.

   • Private key (for mutual TLS protocols): Private key in PEM format associated with the client certificate.

   • Uplink topic: MQTT topic used to publish uplink messages. The topic must not contain MQTT wildcards (+ or #). The following variables are dynamically replaced by the device's actual values when a message is published:

     • {DevEUI}: replaced with the device EUI.
     • {DeviceTopicPath}: replaced with the device topic path.

     Default value: mqtt/things/{DevEUI}/uplink

   • Downlink topic: MQTT topic used to subscribe to downlink messages. The topic may contain MQTT wildcards (+ and #). If not set, downlink messages cannot be sent to associated devices.

     Default value: mqtt/things/+/downlink

   • QoS (if available): MQTT Quality of Service level used for message delivery:

     • At most once (QoS 0) (default): Messages are sent once without acknowledgment. Lowest overhead, but messages may be lost.
     • At least once (QoS 1): Messages are acknowledged and retransmitted if necessary. Ensures delivery, but messages may be received more than once.
     note

     This field is only shown if QoS 1 has been enabled by the operator.

6. Configure the message format:

   • Message format: The type of encoding used to report device data to your application. Use the message format supported by the application server:

     • ThingPark (JSON). Example:

       {
         "DevEUI":"78A8952D2E2992C5",
         "FPort":2,
         "LrrRSSI":-60.000000
       }

     • ThingPark (JSON untyped): JSON document where all values, including numeric values, are reported as strings. Example:

       {
         "DevEUI":"78A8952D2E2992C5",
         "FPort":"2",
         "LrrRSSI":"-60.000000"
       }

     • ThingPark (XML)

7. Click ADD.