View source for Broker connection in SparkplugCmd utility

[[Category:Sparkplug]] [[Category:SparkplugCmd Utility]] [[Category:Tools and Online Services]] 
{{Sparkplug trademarks disclaimer}}

The primary means of specifying the broker connection in the SparkplugCmd is the ''resourceDescriptor'' arguments to commands such as [[Using SparkplugCmd Utility as Sparkplug host application#Command: consumer|'''consumer''']] or [[Using SparkplugCmd Utility as Sparkplug Edge Node#Command: edgeNode|'''edgeNode''']]. The ''resourceDescriptor'' is an URL of the broker, and it defaults to "mqtt://localhost", which specifies a non-authenticated TCP connection to the MQTT broker residing on the local machine, using port 1883. For further information on the URL syntax in ''resourceDescriptor'', and the configurable parameters of the MQTT channel, see [[OpcLabs.MqttNet communication package]].

= Authentication =
The username and password can be specified in the MQTT broker URL. Note that the username and password are transferred in plain text on the wire, unless encryption is used (e.g., using TLS or WSS).

== Examples ==
Example URL with authentication: <code>mqtt://admin:password@localhost</code>

Subscribing to Sparkplug payloads, with authentication:
 consumer mqtt://ro:readonly@test.mosquitto.org:1884 
 subscribePayload

Sparkplug edge node publishing with authentication:
 edgeNode mqtt://wo:writeonly@test.mosquitto.org:1884 
 start

= MQTT 5 =
The MQTT protocol version can be specified in the broker URL using the "version" query parameter. Possible values are 310, 311, and 500, which correspond to MQTT 3.1, MQTT 3.1.1, and MQTT 5.0, respectively. The default is MQTT 3.1.1.

== Examples ==
Example URL: <code>mqtt://localhost?version=500</code>

= TLS =
The TLS protocol can be specified in the broker URL using the "mqtts", "ssl" or "tls" scheme (the schemes are equivalent). Default port is 8883. TLS can be combined with username/password authentication.

SparkplugCmd uses a [[Certificate security plugin]] with console interaction turned on by default. This means that when an unknown remote certificate is provided by the broker, SparkplugCmd will ask the interactive user whether the certificate should be accepted or not.

== Examples ==
Example URL: <code>mqtts://localhost</code>

Subscribing to Sparkplug payloads, with TLS:
 consumer mqtts://test.mosquitto.org
 subscribePayload

= WebSocket =
The WebSocket protocol can be specified in the broker URL using the "ws" scheme. Note: Use the "wss" scheme for WebSocket Secure. Default port for "ws" is 80, and for "wss" is 443.

== Examples ==
Example URL: <code>ws://localhost:8080/mqtt</code>

Subscribing to Sparkplug payloads, over WebSocket:
 consumer ws://test.mosquitto.org:8080
 subscribePayload


= See also =
* [[OpcLabs.MqttNet communication package]]
* [[Using SparkplugCmd Utility as Sparkplug Edge Node]]
* [[Using SparkplugCmd Utility as Sparkplug host application]]