MQTT Connector Configuration

Configuration example:

"connector": [ {
  "id": "mqttConnector",
  "connectorType": "mqtt",
  "properties": {
    "mqttBrokerUri": "tcp://localhost:1883",
    "mqttClientId": "demo01",
    "username": "sv-lab-demo",
    "password": "changeit"
  }
} ]

Topic filters

Although you can use standard MQTT topic filters, SV provides extended syntax for easier use in model. MQTT topic is hierarchical with levels separated by slash (/). When subscribing to topic, you can use wildcards to receive messages from several topics at once. There are two types of wildcards - plush sign (+) for single level and hash sign (#) for multiple levels (can be used only at the end of topic). When message arrives, the receiver gets the full name of the topic without these wildcards. The parts of full name corresponding to wildcards are typically IDs of devices or simply some "parameters". For example you can subscribe to topic car/+/parts/+/status to get status of all parts in all cars as they are announced by themselves. The real topics then look like car/f3f7485/parts/engine/status or car/hdj875fjs/parts/window. It can be very helpful to have these parts of topic names available in models as parameters.

To do so easily, SV provides its own named "version" of wildcards - {xxx} where xxx is some name under which the wildcard value will be available in model. You can rewrite the example above as car/{carId}/parts/{partName}/status and the messages received from the topic will have two additional "parameters" carId and partName. Named wildcard for multiple levels has just hash appended: {xxx#}.

Note

Note that standard MQTT wildcards will also create parameters in messages, they just by named by numbers in order they were specified in topic.

Mapping wildcards into messages also allows automatic construction of target topic when sending the messages. Normally, you would need to specify full name of the topic in endpoint in order to send the message. With wildcards, you can specify topic with wildcards and provide the real values as part of the model - additional parameters of the message. It also works automatically in forward mode - parameters are extracted from incoming topic and substituted into target topic. So when you define virtual topic as virtual/car/{id} and real topic as car/{id}, it will "copy" ID from incoming topic to outgoing one so message received as virtual/car/12345 will be sent to car/12345.

MQTT connector configuration properties

The mandatory properties are bold, other properties are optional.

Property	Default Value	Description
mqttBrokerUri		(string) Broker URI, like `tcp://localhost:1883` or `ssl://localhost:8883`
mqttClientId		(string) Client ID
username		(string) Credentials required by broker
password		(string) Credentials required by broker
connectionTimeout	30	(integer) How many seconds will connector attempt to connect to the remote party when initiating connection
mqttKeepaliveInterval	60	(integer) Maximum interval in seconds between two messages sent or received by client, used to detect dead connections
mqttReconnectInterval	5000	(integer) If connection to server is lost, how often to try to reestablish it, in milliseconds

clientKeyStore (1)		(byte[]) Serialized Java keystore with client's private key for SSL connection to broker.
clientKeyStorePassword (1)		(string) Password for client's keystore.
clientPrivateKeyPassword (1)		(string) Password for private key stored in client's keystore.
trustStore (2)		(byte[]) Serialized Java truststore with private key for validation broker's certificate.
trustStorePassword (2)		(string) Password for Java truststore.

Notes:

[1] Key store is used when using mutual SSL authentication on broker.
[2] Trust store is used for SSL connection to broker.

MQTT endpoint configuration properties

In each endpoint you can configure either request, response or both. Since MQTT is one-way, not request-response, the endpoint request/response mapping just affects how endpoint behaves in different service modes.

FORWARD_TO_REAL_SERVICE mode:
SV will listen on virtual request topic and send the received messages to real request topic.
SV will also listen on real response topic and send the received messages to virtual response topic.
In both cases it will learn the messages.
SIMULATE_SERVICE mode:
SV will listen on virtual request topic and pass received messages to simulator.
Any messages generated by simulator will be sent to virtual response topic.
INVOKE_REAL_SERVICE mode:
SV will send messages generated by simulator to real request topic.
SV will listen for messages from real service on real response topic.

As can be seen, the REQUEST topics work from client to real service and RESPONSE topics work in reverse. This way you can simulate service which sends messages to some topic(s) and receives them on another topic(s).

There is no correlation between request and response topics or messages so you can have separate endpoints with request and response configuration, especially when you need different content type for request and response messages.

Note

It is important to set name of endpoint as the endpoint is directly bound to operation. There is one to one mapping between endpoint and operation so the endpoint name must match the operation name. During learning, the operation will be named according to endpoint from which the message came. During simulation and invocation, operation name is used to determined where to send the message - SV uses the endpoint named after the operation.

Mandatory properties are bold. Other properties are optional.

Property	Description
displayName (1)	(string) The endpoint name used in operation definition in service interface
mqttVirtualRequestTopic (2)	(string) The JNDI name of topic for receiving requests from clients
mqttVirtualResponseTopic (2)	(string) The topic where clients receive responses. Optional, the client can provide response topic with `replyTo` header
mqttRealRequestTopic (2)	(string) The topic where service receives requests. Optional, the client can provide a topic with `replyTo` header for solicit response in invocation mode
mqttRealResponseTopic (2)	(string) The topic to receive responses from service
contentType	(string) Content type of message sent on endpoint, one of application/xml`,`application/json`,`text/plain`and`application/octet-stream`

Notes:

[1] The display name is mandatory when there are more than one operation in service interface.
[2] You can specify QoS directly in opic using the topic:qos syntax where qos is quality of service, default is 0.