MQ Telemetry - WebSphere MQ v7.5

MQ Telemetry - WebSphere MQ v7.5

+
Search Tips | Advanced Search

WebSphere MQ Telemetry

How to read railroad diagrams
WebSphere MQ Control commands
Use control commands
Use control commands on Windows systems
Use control commands on UNIX and Linux systems
The control commands
addmqinf
amqmdain
amqmfsck (file system check)
crtmqcvx
crtmqenv
crtmqinst
crtmqm
dltmqinst
dltmqm
dmpmqaut
dmpmqcfg
dmpmqlog
dspmq
dspmqaut
dspmqcsv
dspmqfls
dspmqinf
dspmqinst
dspmqrte
dspmqspl
dspmqtrc
dspmqtrn
dspmqver
endmqcsv
endmqlsr
endmqdnm
endmqm
endmqsvc (end IBM WebSphere MQ service)
endmqtrc
migmbbrk
MQExplorer (launch WebSphere MQ Explorer)
mqrc (MQ return code)
rcdmqimg
rcrmqobj
rmvmqinf
rsvmqtrn
runmqchi
runmqchl
runmqdlq
runmqdnm
runmqlsr
runmqras
runmqsc

WebSphere MQ Telemetry comprises a telemetry (MQXR) service that is part of a queue manager, telemetry clients that you can write yourself, or use one of the clients that are provided, and command line and explorer administrative interfaces. Telemetry refers to collecting data from and administering a wide range of remote devices. With WebSphere MQ Telemetry you can integrate the collection of data and control of devices with web applications.
MQTT support was previously available with either WebSphere Message Broker or WebSphere MQ Version 7.0.1, where WebSphere MQ Telemetry was a separate feature. Because WebSphere MQ Telemetry is a component of WebSphere MQ Version 7.1 and later, upgrading is essentially uninstalling WebSphere MQ Telemetry version 7.0.1 and installing WebSphere MQ Version 7.1. WebSphere MQ Telemetry can either be installed with the main product, or installed after version 7.1 or later is already installed. For migration information, see Migrating WebSphere MQ Telemetry from version 7.0.1 to version 7.5 or Migration of telemetry applications from using WebSphere Message Broker version 6 to use WebSphere MQ Telemetry and WebSphere Message Broker version 7.0 .
Included in WebSphere MQ Telemetry are the following components:

Installer

WebSphere MQ Telemetry is installed using either a GUI or command-line installer.
The Java components of the SDK are installed as WebSphere Eclipse Platform features. The C components of the SDK are supplied as compressed files.

Telemetry channels

Use telemetry channels to manage the connection of MQTT clients to WebSphere MQ. Telemetry channels use new WebSphere MQ objects, such as the SYSTEM.MQTT.TRANSMIT.QUEUE, to interact with WebSphere MQ.

Telemetry (MQXR) service

MQTT clients use the SYSTEM.MQXR.SERVICE telemetry service to connect to telemetry channels.

WebSphere MQ Explorer support for WebSphere MQ Telemetry

WebSphere MQ Telemetry can be administered using WebSphere MQ Explorer.

Client Software Development Kit (SDK)

The client SDK has four parts:

MQTT v3 client libraries for Java SE and Java ME. Use the Java libraries to write Java clients for devices that support Java SE or Java ME.
MQTT v3 libraries for C. Use the C libraries to write C clients for a number of platforms.
WebSphere MQ Telemetry daemon for devices, which is an advanced client written in C that runs on a number of platforms.
MQTT v3 protocol. The MQTT v3 protocol is published and licensed for reuse. Use the protocol, and reference MQTT client implementations, to write MQTT clients for different platforms and languages.

Documentation

WebSphere MQ Telemetry documentation is included in the standard WebSphere MQ information center from Version 7.1. SDK documentation for Java and C clients is provided in the information center, and as Javadoc and HTML.

Telemetry concepts

You collect information from the environment all around you to decide what to do. As a consumer, you check what you have in store, before deciding about what food to buy. You want to know how long a journey is going to take if you leave now, before booking a connection. You check your symptoms, before deciding whether to visit the doctor. You check when a bus is going to arrive, before deciding whether to wait. The information for those decisions comes directly from meters and devices, from the written word on paper or from a screen, and from you. Where ever you are, and when ever you need to, you collect information, bring it together, analyze it, and act upon it.
If the sources of information are widely dispersed or inaccessible, it becomes difficult and costly to collect the most accurate information. If there are many changes you want to make, or it is difficult to make the changes, then the changes do not get made, or are made when they are less effective.
What if the costs of collecting information from, and controlling, widely dispersed devices is greatly reduced by connecting the devices with digital technology to the internet? The information can be analyzed using the resources of the internet and the enterprise. You have more opportunities to make informed decisions and act upon them.
Technological trends, and environmental and economic pressures, are driving these changes to happen:

The cost of connecting and controlling sensors and actuators is reducing, due to standardization and connection to low cost digital processors.
The internet, and internet technologies, are increasingly used to connect devices. In some countries, mobile phones exceed personal computers in the number of connections to internet applications. Other devices are surely following.
The internet, and internet technologies, make it much easier for an application to get data. Easy access to data is driving the use of data analytics to turn data from sensors into information that is useful in many more solutions.
Intelligent use of resources is often a quicker and cheaper way of reducing carbon emissions and costs. The alternatives: finding new resources, or developing new technologies to use existing resources, might be the long-term solution. In the short term developing new technologies, or finding new resources, is often riskier, slower, and more costly, than improving existing solutions.

Example

An example shows how these trends create new opportunities to interact with the environment intelligently.
The International Convention for the Safety of Life at Sea (SOLAS) requires Automatic Identification System (AIS) to be deployed on many ships. It is required on merchant ships over 300 tons and passenger ships. AIS is primarily a collision avoidance system for coastal shipping. It is used by marine authorities to monitor and control coastal waters.
Enthusiasts around the world are deploying low-cost AIS tracking stations and placing coastal shipping information onto the internet. Other enthusiasts are writing applications that combine information from AIS with other information from the internet. The results are put on Web sites, and published using Twitter and SMS.
In one application, information from AIS stations near Southampton is combined with ship ownership and geographical information. The application feeds live information about ferry arrivals and departures to Twitter, red-ferries . Regular commuters using the ferries between Southampton and the Isle of Wight subscribe to the news feed using Twitter or SMS. If the feed shows their ferry is running late, commuters can delay their departure and catch the ferry when it docks later than its scheduled arrival time.

Telemetry concepts and scenarios for monitoring and control

Telemetry is the automated sensing, measurement of data, and control of remote devices. The emphasis is on the transmission of data from devices to a central control point. Telemetry also includes sending configuration and control information to devices.
WebSphere MQ Telemetry connects small devices by using the MQTT protocol, and connects the devices to other applications by using WebSphere MQ. WebSphere MQ Telemetry bridges a gap between devices and the internet making it easier to build "smart solutions". Smart solutions unlock the wealth of information available on the internet, and in enterprise applications, for applications that monitor and control devices.

Telemetry: Smart Electricity

MQTT message containing energy usage data sent to service provider.
WebSphere MQ Telemetry sends CONTROL COMMANDS based on analysis of energy usage data.

Telemetry: Smart Health Services

WebSphere MQ Telemetry sends Health Data to your Hospital & Doctor.
MQTT message alerts or feedback can be sent based on analysis of Health Data.

Telemetry: One in a Crowd

A simple card transaction is sent to the bank's server.
WebSphere MQ Telemetry identifies the one person from the thousands, alerting the customer that their card has been used.
WebSphere MQ Telemetry can use the simplest input of information, and locate that individual.

Telemetry scenario: Home patient monitoring

In the collaboration between IBM and a healthcare provider on a cardiac patient care system, an implanted cardioverter defibrillator communicates with a hospital. Data about the patient and the implanted device are transferred using RF telemetry to the MQTT device in the home of a patient.
Typically the transfer takes place nightly to a transmitter located at the bedside. The transmitter transfers the data securely over the phone system to the hospital, where the data is analyzed.
The system reduces the number of visits a patient must make to a physician. It detects when the patient or device needs attention, and in the event of an emergency, it alerts the on-call physician.
The collaboration between IBM and the healthcare provider has characteristics that are common to a number of telemetry scenarios:

Invisibility

The device requires no user intervention other than supplying power, a telephone line, and being in proximity to the device for part of the day. Its operation is reliable and simple to use.
To remove the need for the patient to set up the device, the device supplier preconfigures the device. The patient only must plug it in. Elimination of configuration by the patient simplifies the operation of the device and reduces the chance the device is configured wrongly.
The MQTT client is embedded as part of the device. The device developer embeds the MQTT client implementation in the device and the developer, or supplier, configures the MQTT client as part of the preconfiguration.
The MQTT client is shipped as Java SE andJava ME jar file,, which the developer includes in their Java application. For non-Java environments, such as this one, the device developer can implement a client in a different language using the published MQTT formats and protocol. Alternatively, the developer can use one of the C clients shipped as shared libraries for Windows, Linux and ARM platforms.

Uneven connectivity

Communication between the defibrillator and the hospital has uneven network characteristics. Two different networks are used to solve the different problems of collecting data from the patient, and sending the data to the hospital. Between the patent and the MQTT device, a short-range low-power RF network is used. The transmitter connects to the hospital using a VPN TCP/IP connection over a low-bandwidth phone-line.
It is often impractical to find a way to connect every device directly to an Internet Protocol network. Using two networks, connected by a hub, is a common solution. The MQTT device is a simple hub, storing information from the patient, and forwarding it to the hospital.

Security

The physician must be able to trust the authenticity of the patient data, and the patient wants the privacy of their data to be respected.
In some scenarios it is sufficient to encrypt the connection, using VPN or SSL. In other scenarios, it is desirable to keep the data secure even after it has been stored.
Sometimes the telemetry device is not secure. It might be in a shared dwelling, for example. The user of the device must be authenticated to make sure that the data is from the correct patient. The device itself can be authenticated to the server using SSL, and the server authenticated to the device.
The telemetry channel between the device and the queue manager supports JAAS for user authentication and SSL for communication encryption, and device authentication. Access to a publication is controlled by the object authority manager in WebSphere MQ.
The identifier used to authenticate the user can be mapped to a different identifier, such as a common patient identity. A common identifier simplifies configuring authorization to publication topics in WebSphere MQ.

Connectivity

The connection between the MQTT device and the hospital uses dial-up, and works with a bandwidth as low as 300 baud.
To operate effectively at 300 baud, the MQTT protocol adds only a few extra bytes to a message in addition to TCP/IP headers.
The MQTT protocol provides single transmission "fire and forget" messaging, which keeps latencies low. It can also use multiple transmissions to guarantee "at least once" and "exactly once" delivery if guaranteed delivery is more important than response time. To guarantee delivery, messages are stored at the device until they have been delivered successfully. If a device is connected wirelessly, guaranteed delivery is especially useful.

Scalability

Telemetry devices are typically deployed in large numbers, from tens of thousands to millions.
Connecting many devices to a system places large demands on a solution. There are business demands such as the cost of the devices and their software, and the administration demands of managing licenses, devices, and users. Technical demands include the load on the network, and on servers.
Opening connections uses more server resource than maintaining the open connections. But in a scenario such as this that uses phone lines, the expense of connections means that connections are left open no longer than required. The data transfers are largely of a batched nature. The connections can be scheduled throughout the night to avoid a sudden peak of connections at bedtime.
On the client, the scalability of clients is helped by the minimal client configuration required. The MQTT client is embedded in the device. There is no requirement for a configuration or MQTT client license acceptance step to be built into the deployment of devices to patients.
On the server, WebSphere MQ Telemetry has an initial target of 50,000 open connections per queue manager.
The connections are managed using WebSphere MQ Explorer. The Explorer filters the connections to be displayed to a manageable number. With an appropriately chosen scheme of allocating identifiers to clients, you might filter connections based on geography, or alphabetically by patient name.

Telemetry scenario: Home energy monitoring and control

Smart meters collect more detail about energy consumption than traditional meters.
Smart meters are often coupled with a local telemetry network to monitor and control individual appliances in a home. Some are also connected remotely for monitoring and control at a distance.
The remote connection could be set up by an individual, by a power utility, or by a central control point. The remote control point can read power usage and provide usage data. It can provide data to influence usage such as continuous pricing and weather information. It can limit load to improve overall power generation efficiency.
Smart meters are beginning to deployed widely. The UK government, for instance, is in consultation about deployment of smart meters to every UK home by 2020.
Home metering scenarios have a number of common characteristics:

Invisibility

Unless the user wants to be involved in saving energy by using the meter, the meter must not require user intervention. It must not reduce the reliability of the energy supply to individual appliances.
An MQTT client can be embedded in the software deployed with the meter, and does not require separate installation or configuration.

Uneven connectivity

The communication between appliances and the smart meter demands different standards of connectivity than between the meter and the remote connection point.
The connection from the smart meter to appliances must be highly available and conform to network standards for a home area network.
The remote network is likely to use various physical connections. Some of them, such as cellular, have a high transmission cost, and can be intermittent. The MQTT v3 specification is aimed at remote connections, and connections between local adapters and the smart meter.
Connection between power outlets and applicances, and the meter, use a home area network, such as Zigbee. MQTT for sensor networks (MQTT-S), is designed to work with Zigbee and other low bandwidth network protocols. WebSphere MQ Telemetry does not support MQTT-S directly. It requires a gateway to connect MQTT-S to MQTT v3.
Like home patient monitoring, solutions for home energy monitoring and control require multiple networks, connected using the smart meter as a hub.

Security

There are a number of security issues associated with smart meters. These issues include non-repudiation of transactions, authorization of any control actions that are initiated, and privacy of power consumption data.
To ensure privacy, data transferred between the meter and the remote control point by MQTT can be encrypted using SSL. To ensure authorization of control actions, the MQTT connection between the meter and the remote control point can be mutually authenticated using SSL.

Connectivity

The physical nature of the remote network can vary considerably. It might use an existing broadband connection, or use a mobile network with high call costs, and intermittent availability. For high cost, intermittent, connections MQTT is an efficient and reliable protocol

Scalability

Eventually power companies, or central control points, plan to deploy tens of millions of smart meters. Initially, the numbers of meters per deployment are in the tens to hundreds of thousands. This number is comparable to the initial MQTT target of 50,000 open client connections per queue manager.
A critical aspect of the architecture for home energy monitoring and control is to use the smart meter as a network concentrator. Each appliance adapter is a separate sensor. By connecting them to a local hub using MQTT, the hub can concentrate the data flows onto a single TCP/IP session with the central control point, and also store messages for a short period to overcome session outages.
Remote connections must be left open in home energy scenarios for two reasons. First, because opening connections takes a long time relative to sending requests. The time to open many connections to send load-limitation requests in a short interval is too long. Second, to receive load-limitation requests from the power company, the connection must first be opened by the client. With MQTT, connections are always initiated by the client, and to receive load-limitation requests from the power company, the connection must be left open.
If the rate of opening connections is critical, or the server initiates time-critical requests, the solution is typically to maintain many open connections.

Telemetry scenarios: Radio Frequency Identification (RFID)

RFID is the use of an embedded RFID tag to identify and track an object wirelessly. RFID tags can be read up to a range of several meters, and out of the line of sight of the RFID reader. Passive tags are activated by an RFID reader. Active tags transmit without external activation. Active tags must have a power source. Passive tags can include a power source to increase their range.
RFID is used in many applications, and the types of scenarios vary enormously. RFID scenarios, and home patient monitoring and home energy monitoring and control scenarios, have some similarities and differences.

Invisibility

In many scenarios, the RFID reader is deployed in large numbers and must work without user intervention. The reader includes an embedded MQTT client to communicate with a central control point.
For example, in a distribution warehouse, a reader uses a motion sensor to detect a pallet. It activates the RFID tags of items on the pallet and sends data and requests to central applications. The data is used to update the location of stock. The requests control what happens to the pallet next, such as moving it to a particular bay. Airlines, and airport baggage systems, are using RFID in this way.
In some RFID scenarios, the reader has a standard computing environment, such as Java ME. In these cases, the MQTT client might be deployed in a distinct configuration step, after manufacture.

Uneven connectivity

The RFID readers might be separated from the local control device that contains an MQTT client, or each reader might embed an MQTT client. Typically, geographical or communications factors indicate the choice of topology.

Security

Privacy and authenticity are security concerns in the attachment of RFID tags. RFID tags are unobtrusive and can be covertly monitored, spoofed, or tampered with.
Solution of RFID security issues increases the opportunity for deployment of new RFID solutions. Although the security exposure is in the RFID tag, and the local reader, using central information processing suggests approaches for countering different threats. For example, tag tampering might be detected by dynamically correlating stock levels against deliveries and dispatches.

Connectivity

RFID applications typically involved both batched store and forward of information gathered from RFID readers and immediate queries. In the distribution warehouse scenario, the RFID reader is connected all the time. When a tag is read, it is published along with information about the reader. The warehousing application publishes the response back to the reader.
In the warehousing application the network is typically reliable, and the immediate requests might use "fire and forget" messages for low latency performance. The batched store and forward data might use "exactly once" messaging to minimize administration costs associated with loosing data.

Scalability

If the RFID application requires immediate responses, in the order of a second or two, then the RFID readers must stay connected.

Telemetry scenarios: Environment sensing

Environment sensing uses telemetry to collect information about river water levels and quality, atmospheric pollutants, and other environmental data.
Sensors are frequently located in remote places, without access to wired communication. Wireless bandwidth is expensive and reliability can be low. Typically, a number of environment sensors in a small geographical area are connected to a local monitoring device in a safe location. The local connections might be wired or wireless.

Invisibility

The sensor devices are likely to be less accessible, lower powered, and deployed in greater numbers, than the central monitoring device. The sensors are sometimes "dumb", and the local monitoring device includes adapters to transform and store sensor data. The monitoring device is likely to incorporate a general-purpose computer that supports Java SE or ME. Invisibility is unlikely to be a major requirement when configuring the MQTT client.

Uneven connectivity

The capabilities of sensors, and cost and bandwidth of remote connection, typically results in a local monitoring hub connected to a central server.

Security

Unless the solution is being used in a military or defensive scenario, security is not a major requirement.

Connectivity

Many uses do not require continuous monitoring or immediate availability of data. Exception data, such as a flood level alert, does need to be forwarded immediately. Sensor data is aggregated at the local monitor to reduce connection and communication costs, and then transferred using scheduled connections. Exception data is forwarded as soon as it is detected at the monitor.

Scalability

Sensors are concentrated around local hubs, and sensor data is aggregated into packets that are transmitted according to a schedule. Both these factors reduce the load on the central server that would be imposed by using directly connected sensors.

Telemetry scenarios: Mobile applications

Mobile applications are applications that run on wireless devices. The devices are either generic application platforms or custom devices.
General platforms include handheld devices such as phones and personal data assistants, and portable devices such as notebook computers. Custom devices use special purpose hardware tailored to specific applications. A device to record "signed-for" parcel delivery is an example of a custom mobile device. Applications on custom mobile devices are often built on a generic software platform.

Invisibility

The deployment of custom mobile applications is managed, and can include configuration of the MQTT client application. Invisibility is unlikely to be a major requirement when configuring the MQTT client.

Uneven connectivity

Unlike the local hub topology of the preceding scenarios, mobile clients connect remotely. The client application layer connects directly to an application at the central hub.

Security

With little physical security, the mobile device, and the mobile user must be authenticated. SSL is used to confirm the identity of the device, and JAAS to authenticate the user.

Connectivity

If the mobile application depends on wireless coverage, it must be able to operate offline, and to deal efficiently with an interrupted connection. In this environment, the goal is to stay connected, but the application must be able to store and forward messages. Often the messages are orders, or delivery confirmations, and have important business value. They need to be stored and forwarded reliably.

Scalability

Scalability is not a major issue. The numbers of application clients are likely to not to exceed the thousands, or tens of thousands, in custom mobile application scenarios.

Connecting telemetry devices to a queue manager

Telemetry devices connect to a queue manager using an MQTT v3 client. The MQTT v3 client uses TCP/IP to connect to a TCP/IP listener called the telemetry (MQXR) service.
As an alternative to connecting telemetry devices directly to the telemetry service, you can connect the devices to the WebSphere MQ Telemetry daemon for devices. The daemon is itself an MQTT v3 client. It pools the device connections, and makes a single connection to the telemetry (MQXR) service. You can connect daemons in a hierarchy, increasing the number of devices that can be indirectly connected to WebSphere MQ by many orders of magnitude.

The MQTT client initiates a TCP/IP connection using the MqttClient.connect method. Like WebSphere MQ clients, an MQTT client must be connected to the queue manager to send and receive messages. The connection is made at the server using a TCP/IP listener, installed with WebSphere MQ Telemetry, called the telemetry (MQXR) service. Each queue manager runs a maximum of one telemetry (MQXR) service.
The telemetry (MQXR) service uses the remote socket address set by each client in the MqttClient.connect method to allocate the connection to a telemetry channel. A socket address is the combination of TCP/IP host name and port number. Multiple clients that use the same remote socket address are connected to the same telemetry channel by the telemetry (MQXR) service.
If there are multiple queue managers on a server, split the telemetry channels between the queue managers. Allocate the remote socket addresses between the queue managers. Define each telemetry channel with a unique remote socket address. Two telemetry channels must not use the same socket address.
If the same remote socket address is configured for telemetry channels on multiple queue managers, the first telemetry channel to connect, wins. Subsequent channels connecting on the same address fail, and create a first-failure data capture (FDC) file.
If there are multiple network adapters on the server, split the remote socket addresses between telemetry channels. The allocation of socket addresses is entirely arbitrary, as long as any specific socket address is configured on only one telemetry channel.
Configure WebSphere MQ to connect MQTT clients using the wizards provided in the WebSphere MQ Telemetry supplement for WebSphere MQ Explorer. Alternatively, follow the instructions in Configuring a queue manager for telemetry on Linux and AIX and Configuring a queue manager for telemetry on Windows to configure telemetry manually.

Telemetry connection protocols

WebSphere MQ Telemetry supports TCP/IP IPv4 and IPv6, and SSL.

Telemetry (MQXR) service

The telemetry (MQXR) service is a TCP/IP listener, that is managed as a WebSphere MQ service. Create the service using a WebSphere MQ Explorer wizard, or with a runmqsc command.
The WebSphere MQ Telemetry (MQXR) service is called SYSTEM.MQXR.SERVICE .
The Telemetry sample configuration wizard, provided in the WebSphere MQ Telemetry supplement for WebSphere MQ Explorer, creates the telemetry service and a sample telemetry channel; see Verifying the installation of WebSphere MQ Telemetry by using WebSphere MQ Explorer . Create the sample configuration from the command line; see Verifying the installation of WebSphere MQ Telemetry using the command line .
The telemetry (MQXR) service starts and stops automatically with the queue manager. Control the service using the services folder in WebSphere MQ Explorer. To see the service, you must click the icon to stop the Explorer filtering out SYSTEM objects from the display. an example of how to create the service manually on AIX and Linux. installMQXRService_win.mqsc shows how to create the service manually in Windows.

Telemetry channels

Create telemetry channels to create connections with different properties, such as JAAS or SSL authentication, or to manage groups of clients.
Create Telemetry channels using the New Telemetry Channel wizard, supplied in the WebSphere MQ Telemetry supplement for WebSphere MQ Explorer. Configure a channel, using the wizard, to accept connections from MQTT clients on a particular TCP/IP port. Since Version 7.1, you can configure WebSphere MQ Telemetry using the command line program, runmqsc.
Create multiple telemetry channels, on different ports, to make large numbers of client connections easier to manage, by splitting the clients into groups. Each telemetry channel has a different name.
You can configure telemetry channels with different security attributes to create different types of connection. Create multiple channels to accept client connections on different TCP/IP addresses. Use SSL to encrypt messages and authenticate the telemetry channel and client

MQTT protocol

The MQ Telemetry Transport (MQTT) v3 protocol is designed for exchanging messages between small devices on low bandwidth, or expensive connections, and to send messages reliably. It uses TCP/IP.
The MQTT protocol is published. Version 3 of the protocol uses publish/subscribe, and supports three qualities of service: "fire and forget", "at least once", and "exactly once".
The small size of the protocol headers, and the byte array message payload, keeps messages small. The headers comprise a 2 byte fixed header, and up to 12 bytes of additional variable headers. The protocol uses 12 byte variable headers to subscribe and connect, and only 2 byte variable headers for most publications.
With three qualities of service, you can trade off between low-latency and reliability. "Fire and forget" uses no persistent device storage, and only one transmission to send or receive a publication. "At least once", and "exactly once" require persistent storage on the device to maintain the protocol state and save a message until it is acknowledged.
The protocol is one of a family of MQTT protocols that are used in other products, such as Lotus Expeditor.

MQTT clients

An MQTT client app is responsible for collecting information from the telemetry device, connecting to the server, and publishing the information to the server. It can also subscribe to topics, receive publications, and control the telemetry device.
Unlike WebSphere MQ client applications, MQTT client apps are not WebSphere MQ applications. They do not specify a queue manager to connect to. They are not limited to using specific WebSphere MQ programming interfaces. Instead, MQTT clients implement the MQTT version 3 protocol. You can write your own client library to interface to the MQTT protocol in the programming language, and on the platform, of your choice.
To simplify writing MQTT client apps, use the C, Java, and JavaScript client libraries that encapsulate the MQTT protocol for a number of platforms. For links to client API documentation for the MQTT version 3.1 protocol, see MQTT client programming reference . If you incorporate these libraries in your MQTT apps, a fully functional MQTT client can be as short as 15 lines of code.
Two copies of the com.ibm.micro.client.mqttv3.jar JAR file are installed. One copy has a version number as part of the file name. For example: com.ibm.micro.client.mqttv3_3.0.2.0-20100723.jar. Use the versioned copy in OSGi applications. The content of the JAR files is the same.
The MQTT client app is always responsible for initiating a connection with a telemetry channel. After it is connected, either the MQTT client app or a WebSphere MQ application can start an exchange of messages.
MQTT client apps and WebSphere MQ applications publish and subscribe to the same set of topics. A WebSphere MQ application can also send a message directly to an MQTT client app without the client app first creating a subscription.
MQTT client apps are connected to WebSphere MQ using a telemetry channel. The telemetry channel acts as a bridge between the different types of message used by MQTT and WebSphere MQ. It creates publications and subscriptions in the queue manager on behalf of the MQTT client app. The telemetry channel sends publications that match the subscriptions of an MQTT client app from the queue manager to the MQTT client app.

Send a message to an MQTT client

WebSphere MQ applications can send MQTT v3 clients messages by publishing to subscriptions created by clients, or by sending messages directly. MQTT clients can send messages to one another by publishing to topics subscribed to by other clients.

An MQTT client subscribes to a publication, which it receives from WebSphere MQ

Do the task, Publishing a message to the MQTT client utility from WebSphere MQ Explorer to send a publication from WebSphere MQ to an MQTT client.
The standard way for an MQTT v3 client to receive messages is for it to create a subscription to a topic, or set of topics. In the example code snippet, Figure 1 , the MQTT client subscribes using the topic string "MQTT Examples". A WebSphere MQ C application, Figure 2 , publishes to the topic using the topic string "MQTT Examples". In the code snippet Figure 3 , the MQTT client receives the publication in the callback method, messageArrived.
For further information about how to configure WebSphere MQ to send publications in response to subscriptions from MQTT clients, see Publishing a message in response to an MQTT client subscription .

A WebSphere MQ application sends a message directly to an MQTT client

Do the task, Sending a message to an MQTT client using WebSphere MQ Explorer to send a message directly from WebSphere MQ to an MQTT client.
A message sent in this way to an MQTT client is called an unsolicited message. MQTT v3 clients receive unsolicited messages as publications with a topic name set. The telemetry (MQXR) service sets the topic name to the remote queue name.
You cannot send unsolicited messages to the WebSphere MQ daemon for devices: the daemon might shut down if it receives an unsolicited message. An MQTT v3 client cannot send an unsolicited message to another MQTT v3 client, nor to a WebSphere MQ queue.
For further information about how to configure WebSphere MQ to send messages directly to MQTT clients, see Sending a message to a client directly .

An MQTT client publishes a message

An MQTT v3 client can publish a message that is received by another MQTT v3 client, but it cannot send an unsolicited message. The code snippet, Figure 4 shows how an MQTT v3 client, written in Java™, publishes a message.
The typical pattern for sending a message to one specific MQTT v3 client, is for each client to create a subscription to its own ClientIdentifier. Do the task, Publish a message to a specific MQTT v3 client , to publish a message from one MQTT client to another MQTT client using ClientIdentifier as a topic string.

Example code snippets

The code snippet in Figure 1 shows how an MQTT client written in Java creates a subscription. It also needs a callback method, messageArrived to receive publications for the subscription. The code snippet is extracted from the task, Creating a subscriber for MQ Telemetry Transport using Java .
MQTT v3 client subscriber
 
String    clientId = String.format("%-23.23s", 
                     System.getProperty("user.name") + "_" + 
                     (UUID.randomUUID().toString())).trim()).replace('-', '_');

MqttClient  client = new MqttClient("localhost", clientId);
String topicString = "MQTT Examples";
int            QoS = 1;
client.subscribe(topicString, QoS);
The code snippet in Figure 2 shows how an WebSphere MQ application written in C sends a publication. The code snippet is extracted from the task, Create a publisher to a variable topic
WebSphere MQ publisher
 
/* Define and set variables to.defaults */
/* Omitted lines declaring variables    */
char * topicName   = ""
char * topicString = "MQTT Examples"
char * publication = "Hello world!";
do {
  MQCONN(qMgrName, &Hconn, &CompCode, &Reason);
  if (CompCode != MQCC_OK) break;
  td.ObjectType = MQOT_TOPIC;    /* Object is a topic             */
  td.Version = MQOD_VERSION_4;   /* Descriptor needs to be V4     */
  strncpy(td.ObjectName, topicName,  MQ_TOPIC_NAME_LENGTH);
  td.ObjectString.VSPtr = topicString;
  td.ObjectString.VSLength = (MQLONG)strlen(topicString);
  MQOPEN(Hconn, &td, MQOO_OUTPUT | MQOO_FAIL_IF_QUIESCING, &Hobj, &CompCode, &Reason);
  if (CompCode != MQCC_OK) break;
  pmo.Options = MQPMO_FAIL_IF_QUIESCING | MQPMO_RETAIN;
  MQPUT(Hconn, Hobj, &md, &pmo, (MQLONG)strlen(publication)+1, publication, &CompCode, &Reason);
  if (CompCode != MQCC_OK) break;
  MQCLOSE(Hconn, &Hobj, MQCO_NONE, &CompCode, &Reason);
  if (CompCode != MQCC_OK) break;
  MQDISC(&Hconn, &CompCode, &Reason);
} while (0);
When the publication arrives, the MQTT client calls the messageArrived method of the MQTT application client MqttCallback class. The code snippet is extracted from the task, Creating a subscriber for MQ Telemetry Transport using Java .
Figure 3. messageArrived method
 
public class CallBack implements MqttCallback {
  public void messageArrived(MqttTopic topic, MqttMessage message) {
    try {
      System.out.println("Message arrived: \"" + message.toString()
          + "\" on topic \"" + topic.toString() + "\"");
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
// ... Other callback methods 
}
The code snippet is extracted from the task, Creating your first MQ Telemetry Transport publisher application using Java .
Figure 4. MQTT v3 client publisher
      
    String          address = "localhost";
     String         clientId = String.format("%-23.23s", 
                               System.getProperty("user.name") + "_" + 
                               (UUID.randomUUID().toString())).trim()).replace('-', '_');
     MqttClient       client = new MqttClient(address, clientId);
     String      topicString = "MQTT Examples";
     MqttTopic         topic = client.getTopic(Example.topicString);
     String     publication  = "Hello world";
     MqttMessage     message = new MqttMessage(publication.getBytes());
     MqttDeliveryToken token = topic.publish(message);
Publishing a message to the MQTT client utility from WebSphere MQ Explorer

Follow the steps in this task to publish a message using WebSphere MQ Explorer, and subscribe to it with the MQTT client utility. An additional task shows you how to configure a queue manager alias rather than setting the default transmission queue to SYSTEM.MQTT.TRANSMIT.QUEUE.
The task assumes that you are familiar with WebSphere MQ and the WebSphere MQ Explorer, and that WebSphere MQ and WebSphere MQ Telemetry feature are installed.
The user creating the queue manager resources for this task must have sufficient authority to do so. For demonstration purposes, the WebSphere MQ Explorer user ID is assumed to be member of the mqm group. In the task, you create a topic in WebSphere MQ and subscribe to the topic using the MQTT client utility. When you publish to the topic using WebSphere MQ Explorer, the MQTT client receives the publication.

Procedure

Do one of the following tasks:

You have installed WebSphere MQ Telemetry, but you have not started it yet. Do the task: Start task with no telemetry (MQXR) service yet defined .
You have run WebSphere MQ telemetry before, but want to use a new queue manager to do the demonstration. Do the task: Start task with no telemetry (MQXR) service yet defined .
You want to do the task using an existing queue manager that has no telemetry resources defined. You do not want to run the Define sample configuration wizard.

Do one of the following tasks to set up telemetry:

Configuring a queue manager for telemetry on Linux and AIX
Configuring a queue manager for telemetry on Windows

Do the task: Start task with a running telemetry (MQXR) service

To do the task using an existing queue manager that already has telemetry resources defined, do the task: Start task with a running telemetry (MQXR) service .

Start task with no telemetry (MQXR) service yet defined

Create a queue manager and run the Define sample configuration to define sample telemetry resources for the queue manager. Publish a message using WebSphere MQ Explorer, and subscribe to it with the MQTT client utility.

About this task

When you set up sample telemetry resources using the Define sample configuration, the wizard sets the guest user ID permissions. Carefully consider if you want the guest user ID to be authorized in this way. guest on Windows, and nobody on Linux, are given permission to publish and subscribe to the root of the topic tree, and to put messages onto SYSTEM.MQTT.TRANSMIT.QUEUE.
The wizard also sets the default transmission queue to SYSTEM.MQTT.TRANSMIT.QUEUE, which might interfere with applications running on an existing queue manager. It is possible, but laborious, to configure telemetry and not use the default transmission queue; do the follow on task: Using a queue manager alias . In this task, you create a queue manager to avoid the possibility of interfering with any existing default transmission queue.

Procedure

Use WebSphere MQ Explorer, create and start a new queue manager.

Right-click Queue Managers folder > New > Queue manager .... Type a queue manager name > Finish.
Make up a queue manager name; for example, MQTTQMGR.

Create and start the telemetry (MQXR) service and create a sample telemetry channel.

Open the Queue Managers\QmgrName\Telemetry folder.

Click Define sample configuration... > Finish
Leave the Launch MQTT Client Utility check box checked.

Create a subscription for MQTT Example using the MQTT client utility.

Click Connect.
The Client history records a Connected event.

Type MQTT Example into the Subscription\Topic field > Subscribe.

The Client history records a Subscribed event.
Create MQTTExampleTopic in WebSphere MQ.

Right-click the Queue Managers\QmgrName\Topics folder in the WebSphere MQ Explorer > New > Topic.
Type MQTTExampleTopic as the Name > Next.
Type MQTT Example as the Topic string > Finish.
Click OK to close the acknowledgment window.

Publish Hello World! to the topic MQTT Example using WebSphere MQ Explorer.

Click the Queue Managers\QmgrName\Topics folder in the WebSphere MQ Explorer.
Right-click MQTTExampleTopic > Test publication...
Type Hello World! into the Message data field > Publish message > Switch to the MQTT Client Utility window.

The Client history records a Received event.

Start task with a running telemetry (MQXR) service

Create a telemetry channel and a topic. Authorize the user to use the topic and the telemetry transmit queue. Publish a message using WebSphere MQ Explorer, and subscribe to it with the MQTT client utility.

Before you begin

In this version of the task, a queue manager, QmgrName, is defined and running. A telemetry (MQXR) service is defined and running. The telemetry (MQXR) service might have been created manually, or by running the Define sample configuration wizard.

About this task

In this task you configure an existing queue manager to send a publication to the MQTT client utility.
Step 1 of the task sets the default transmission queue to SYSTEM.MQTT.TRANSMIT.QUEUE, which might interfere with applications running on an existing queue manager. It is possible, but laborious, to configure telemetry and not use the default transmission queue; do the follow on task: Using a queue manager alias .

Procedure

Set SYSTEM.MQTT.TRANSMIT.QUEUE as the default transmit queue.

Right-click the Queue Managers\QmgrName folder > Properties...
Click Communication in the navigator.
Click Select... > Select SYSTEM.MQTT.TRANSMIT.QUEUE > OK > OK.

Create a telemetry channel MQTTExampleChannel to connect the MQTT client utility to WebSphere MQ, and start the MQTT client utility.

Right-click the Queue Managers\QmgrName\Telemetry\Channels folder in the WebSphere MQ Explorer > New > Telemetry channel....
Type MQTTExampleChannel in the Channel name field > Next > Next.
Change the Fixed user ID on the client authorization panel to the user ID that is going to publish and subscribe to MQTTExample > Next.
Leave Launch Client Utility checked > Finish.

Create a subscription for MQTT Example using the MQTT client utility.

Click Connect.
The Client history records a Connected event.

Type MQTT Example into the Subscription\Topic field > Subscribe.

The Client history records a Subscribed event.

Create MQTTExampleTopic in WebSphere MQ.

Right-click the Queue Managers\QmgrName\Topics folder in the WebSphere MQ Explorer > New > Topic.
Type MQTTExampleTopic as the Name > Next.
Type MQTT Example as the Topic string > Finish.
Click OK to close the acknowledgment window.

If you want a user, not in the mqm group, to publish and subscribe to the MQTTExample topic, do the following:

Authorize the user to publish and subscribe to the topic MQTTExampleTopic:

setmqaut -m qMgrName -t topic -n MQTTExampleTopic -p User ID -all +pub +sub

Authorize the user to put a message onto the SYSTEM.MQTT.TRANSMIT.QUEUE:

setmqaut -m qMgrName -t q -n SYSTEM.MQTT.TRANSMIT.QUEUE -p User ID -all +put

Publish Hello World! to the topic MQTT Example using WebSphere MQ Explorer.

Click the Queue Managers\QmgrName\Topics folder in the WebSphere MQ Explorer.
Right-click MQTTExampleTopic > Test publication...
Type Hello World! into the Message data field > Publish message > Switch to the MQTT Client Utility window.

The Client history records a Received event.

Use a queue manager alias

Publish a message to the MQTT client utility using WebSphere MQ Explorer without setting the default transmission queue to SYSTEM.MQTT.TRANSMIT.QUEUE.
The task is a continuation of the previous task, and uses a queue manager alias to avoid setting the default transmission queue to SYSTEM.MQTT.TRANSMIT.QUEUE.

Before you begin

Complete either the task, Start task with no telemetry (MQXR) service yet defined or the task, Start task with a running telemetry (MQXR) service .

About this task

When an MQTT client creates a subscription, WebSphere MQ sends its response using ClientIdentifier, as the remote queue manager name. In this task, it uses the ClientIdentifier, MyClient.
If there is no transmission queue or queue manager alias called MyClient, the response is placed on the default transmission queue. By setting default transmission queue to SYSTEM.MQTT.TRANSMIT.QUEUE, the MQTT client gets the response.
You can avoid setting the default transmission queue to SYSTEM.MQTT.TRANSMIT.QUEUE by using queue manager aliases. You must set up a queue manager alias for every ClientIdentifier. Typically, there are too many clients to make it practical to use queue manager aliases. Often ClientIdentifier is unpredictable, making it impossible to configure telemetry this way.
Nonetheless, in some circumstances you might have to configure the default transmission queue to something other than SYSTEM.MQTT.TRANSMIT.QUEUE. The steps in Procedure configure a queue manager alias instead of setting the default transmission queue to SYSTEM.MQTT.TRANSMIT.QUEUE.

Procedure

Remove SYSTEM.MQTT.TRANSMIT.QUEUE as the default transmit queue.

Right-click the Queue Managers\QmgrName folder > Properties...
Click Communication in the navigator.
Remove SYSTEM.MQTT.TRANSMIT.QUEUE from the Default transmission queue field > OK.

Check that you can no longer create a subscription with the MQTT client utility:

Click Connect.
The Client history records a Connected event.

Type MQTT Example into the Subscription\Topic field > Subscribe.

The Client history records a Subscribe failed and a Connection lost event.

Create a queue manager alias for the ClientIdentifier, MyClient.

Right-click the Queue Managers\QmgrName\Queues folder > New > Remote queue definition.
Name the definition, MyClient > Next.
Type MyClient in the Remote queue manager field.
Type SYSTEM.MQTT.TRANSMIT.QUEUE in the Transmission queue field > Finish.

Connect the MQTT client utility again.

Check the Client identifier is set to MyClient.
Connect

The Client history records a Connected event.

Create a subscription for MQTT Example using the MQTT client utility.

Click Connect.
The Client history records a Connected event.

Type MQTT Example into the Subscription\Topic field > Subscribe.

The Client history records a Subscribed event.

Publish Hello World! to the topic MQTT Example using WebSphere MQ Explorer.

Click the Queue Managers\QmgrName\Topics folder in the WebSphere MQ Explorer.
Right-click MQTTExampleTopic > Test publication...
Type Hello World! into the Message data field > Publish message > Switch to the MQTT Client Utility window.

The Client history records a Received event.

Sending a message to an MQTT client using WebSphere MQ Explorer

Send a message to the MQTT client utility by putting a message onto a WebSphere MQ queue using WebSphere MQ Explorer. The task shows you how to configure a remote queue definition to send a message directly to an MQTT client. Do the task, Publishing a message to the MQTT client utility from WebSphere MQ Explorer . Leave the MQTT client utility connected.
The task demonstrates sending a message to an MQTT client using queue rather than publishing to a topic. You do not create a subscription in the client. Step 2 of the task demonstrates that the previous subscription has been deleted.

Procedure

Discard any existing subscriptions by disconnecting and reconnecting the MQTT client utility.
The subscription is discarded because, unless you change the defaults, the MQTT client utility connects with a clean session
To make it easier to do the task, type your own ClientIdentifier, rather than use the generated ClientIdentifier created by the MQTT client utility.

Click Disconnect to disconnect the MQTT client utility from the telemetry channel.
The Client History records a Disconnected event

Change the Client Identifer to MyClient.
Click Connect.

The Client History records a Connected event
Check that the MQTT client utility no longer receives publication for the MQTTExampleTopic.

Click the Queue Managers\QmgrName\Topics folder in the WebSphere MQ Explorer.
Right-click MQTTExampleTopic > Test publication...
Type Hello World! into the Message data field > Publish message > Switch to the MQTT Client Utility window.

No event is recorded in the Client history.

Create a remote queue definition for the client.
Set the ClientIdentifier, MyClient, as the remote queue manager name in the remote queue definition. Use any name you like as the remote queue name. The remote queue name is passed to an MQTT client as the topic name.

Right-click the Queue Managers\QmgrName\Queues folder > New > Remote queue definition.
Name the definition, MyClientRemoteQueue > Next.
Type MQTTExampleQueue in the Remote queue field.
Type MyClient in the Remote queue manager field.
Type SYSTEM.MQTT.TRANSMIT.QUEUE in the Transmission queue field > Finish.

Put a test message onto MyClientRemoteQueue.

Right-click MyClientRemoteQueue > Put test message...
Type Hello queue! into the Message data field > Put message > Close

The Client history records a Received event.

Remove SYSTEM.MQTT.TRANSMIT.QUEUE as the default transmit queue.

Right-click the Queue Managers\QmgrName folder > Properties...
Click Communication in the navigator.
Remove SYSTEM.MQTT.TRANSMIT.QUEUE from the Default transmission queue field > OK.

Redo step 4 .
MyClientRemoteQueue is a remote queue definition that explicitly names the transmission queue. You do not need a to define default transmission queue to send a message to MyClient.

With the default transmission queue no longer set to SYSTEM.MQTT.TRANSMIT.QUEUE, the MQTT Client Utility is unable to create a new subscription unless a queue manager alias is defined for the ClientIdentifier, MyClient. Restore the default transmission queue to SYSTEM.MQTT.TRANSMIT.QUEUE.

Publish a message to a specific MQTT v3 client

Publish a message from one MQTT v3 client to another, using ClientIdentifier as the topic name and WebSphere MQ as the publish/subscribe broker. Repeat the task using WebSphere MQ Telemetry daemon for devices as the publish/subscribe broker. Do the task, Publishing a message to the MQTT client utility from WebSphere MQ Explorer . Leave the MQTT client utility connected. The task demonstrates two things:

Subscribing to a topic in one MQTT client, and receiving a publication from another MQTT client.
Setting up "point-to-point" subscriptions by using ClientIdentifier as the topic string.

An additional task, Using the WebSphere MQ Telemetry daemon for devices as the publish/subscribe broker , uses the WebSphere MQ Telemetry daemon for devices as the publish/subscribe broker, rather than WebSphere MQ.

Procedure

Discard any existing subscriptions by disconnecting and reconnecting the MQTT client utility.
The subscription is discarded because, unless you change the defaults, the MQTT client utility connects with a clean session
To make it easier to do the task, type your own ClientIdentifier, rather than use the generated ClientIdentifier created by the MQTT client utility.

Click Disconnect to disconnect the MQTT client utility from the telemetry channel.
The Client History records a Disconnected event

Change the Client Identifer to MyClient.
Click Connect.

The Client History records a Connected event
Create a subscription to the topic, MyClient
MyClient is the ClientIdentifier of this client.

Type MyClient into the Subscription\Topic field > Subscribe.

The Client history records a Subscribed event.
Start another MQTT client utility.

Open the Queue Managers\QmgrName\Telemetry\channels folder.
Right-click the PlainText channel > Run MQTT Client Utility...
Click Connect.

The Client History records a Connected event
Publish Hello MyClient! to the topic MyClient.

Copy the subscription topic, MyClient, from the MQTT client utility running with the ClientIdentifier, MyClient.
Paste MyClient into the Publication\Topic field of each of the MQTT client utility instances.
Type Hello MyClient! into the Publication\message field.
Click Publish in both instances.

The Client history in the MQTT client utility with the ClientIdentifier, MyClient, records two Received events and one Published event. The other MQTT client utility instance records one Published event.
If only you see only one Received event check the following possible causes:

Is the default transmission queue for the queue manager set to SYSTEM.MQTT.TRANSMIT.QUEUE?
Have you created queue manager aliases or remote queue definitions referencing MyClient in doing the other exercises? In case you have a configuration problem, delete any resources that reference MyClient, such as a queue manager aliases or transmission queues. Disconnect the client utilities, stop, and restart the telemetry (MQXR) service.

What to do next

The MQTT client utility connects to the WebSphere MQ Telemetry daemon for devices rather than to a telemetry channel.

Use the WebSphere MQ Telemetry daemon for devices as the publish/subscribe broker

Use the WebSphere MQ Telemetry daemon for devices as the publish/subscribe broker instead of WebSphere MQ. Publish a message with one instance of the MQTT client utility to send to another instance, by subscribing using its ClientIdentifier as a topic string.

Before you begin

Install the daemon, if you have not done so already. .
Do not run the verification; it uses port 1883, which is already in use by the PlainText telemetry channel,

About this task

In the task, you connect the MQTT client utility to the WebSphere MQ Telemetry daemon for devices using a non-default TCP/IP port. One client subscribes using its ClientIdentifier as a topic string, and the other client publishes to ClientIdentifier, exactly in the same way as in the previous task, see Procedure .
Note: The task is documented for running the daemon on Windows. To run the daemon on Linux, modify the path and the permissions for amqtdd.

Procedure

Open a command window in the directory containing the WebSphere MQ Telemetry daemon for devices.
The directory path for Windows is, WebSphere MQ installation directory\mqxr\SDK\advanced\DeviceDaemon\windows_ia32

Run the daemon on a different TCP/IP port.

Create a file called amqtdd.cfg in the same directory as the daemon.

Add a line to the file to configure a different default port for the daemon.

port 1884

Save the file.

Start the daemon.

amqtdd

The daemon writes its console log to the command window:

20100712 123133.857 CWNAN9999I IBM WebSphere MQ Telemetry daemon for devices

...and then you can connect to the daemon. Alternatively you can install the WebSphere MQ SupportPac, IA92. The SupportPac is available from IA92: WBI Brokers - Java™ implementation of WebSphere MQ Telemetry transport .

Open the Queue Managers\QmgrName\Telemetry\channels folder.
Right-click the PlainText channel > Run MQTT Client Utility...
Change the Port to 1884.
Change the Client Identifer to MyClient.
Click Connect.

The Client History records a Connected event

Create a subscription to the topic, MyClient
MyClient is the ClientIdentifier of this client.

Type MyClient into the Subscription\Topic field > Subscribe.

The Client history records a Subscribed event.

Start another MQTT client utility.

Open the Queue Managers\QmgrName\Telemetry\channels folder.
Right-click the PlainText channel > Run MQTT Client Utility...
Change the Port to 1884.
Click Connect.

The Client History records a Connected event

Publish Hello MyClient! to the topic MyClient.

Copy the subscription topic, MyClient, from the MQTT client utility running with the ClientIdentifier, MyClient.
Paste MyClient into the Publication\Topic field of each of the MQTT client utility instances.
Type Hello MyClient! into the Publication\message field.
Click Publish in both instances.

Results

The Client history in the MQTT client utility with the ClientIdentifier, MyClient, records two Received events and one Published event. The other MQTT client utility instance records one Published event.
You can also monitor the connection and disconnection events to the WebSphere MQ Telemetry daemon for devices in the command window.

Send a message to a WebSphere MQ application from an MQTT client

A WebSphere MQ application can received a message from an MQTT v3 client by subscribing to a topic. The MQTT client connects to WebSphere MQ using telemetry channel, and sends a message to the WebSphere MQ application by publishing to the same topic.
Do the task, Publishing a message to WebSphere MQ from an MQTT client , to learn how to send a publication from an MQTT client to a subscription defined in WebSphere MQ.
If the topic is clustered, or distributed using a publish/subscribe hierarchy, the subscription can be on a different queue manager to the queue manager that the MQTT client is connected to.

Publishing a message to WebSphere MQ from an MQTT client

Create a subscription to a topic using WebSphere MQ Explorer and publish to the topic using WebSphere MQTT client utility. Do the task, Publishing a message to the MQTT client utility from WebSphere MQ Explorer . Leave the MQTT client utility connected. The task demonstrates publishing a message with an MQTT client and receiving the publication using an unmanaged durable subscription created using WebSphere MQ Explorer.

Procedure
Create a durable subscription to the topic string MQTT Example. Do either of the following procedures:

Run the command script described in Results
Do the following steps to create the queue, and subscription using WebSphere MQ Explorer.

Right-click the Queue Managers\QmgrName\Queues folder in the WebSphere MQ Explorer > New > Local queue....

Type MQTTExampleQueue as the queue name > Finish.

Right-click the Queue Managers\QmgrName\Subscriptions folder in the WebSphere MQ Explorer > New > Subscription....

Type MQTTExampleSubscription as the queue name > Next.

Click Select... > MQTTExampleTopic > OK.
You have already created the topic, MQTTExampleTopic in step 4 of Publishing a message to the MQTT client utility from WebSphere MQ Explorer .

Type MQTTExampleQueue as the destination name > Finish.
As an optional step, set the queue up for use by a different user, without mqm authority.
If you are setting up the configuration for users with less authority than mqm, you must give put and get authority to MQTTExampleQueue. Access to the topic and to the transmission queue was configured in Publishing a message to the MQTT client utility from WebSphere MQ Explorer .
Authorize a user to put and get to the queue MQTTExampleQueue:
 setmqaut -m qMgrName -t queue -n MQTTExampleQueue -p User ID -all +put +get
Publish Hello WebSphere MQ! to the topic MQTT Example using the MQTT client utility.
If you have not left the MQTT client utility connected, right-click the PlainText channel > Run MQTT Client Utility... > Connect.

Type MQTT Example into the Publication\Topic field.
Type Hello WebSphere MQ! into the Publication\Message field > Publish.

Open the Queue Managers\QmgrName\Queues folder and find MQTTExampleQueue.
The Current queue depth field is 1

Right-click MQTTExampleQueue > Browse messages... and examine the publication.
Transfer messages between the WebSphere MQ Telemetry daemon for devices and WebSphere MQ

Do this task to learn how to send commands to the WebSphere MQ Telemetry daemon for devices. The commands you write create a bridge that transfers messages from WebSphere MQ to the daemon, and messages from the daemon to WebSphere MQ.
Do the tasks Publish a message to a specific MQTT v3 client and Using the WebSphere MQ Telemetry daemon for devices as the publish/subscribe broker to become familiar with using the MQTT client utility. When you have finished the tasks, leave one instance of the MQTT client utility connected to the telemetry daemon for devices. Leave another instance connected to the telemetry channel.
The task presumes you have defined a channel to the telemetry service listening to port 1883 on address 127.0.0.1. Likewise, the default daemon listener is configured to listen to port 1884 on address 127.0.0.1. A single line in the file amqtdd.cfg, which is stored in the same directory as the daemon, amqtdd, configures the default daemon listener port.
 port 1884
In this task, you update a running daemon to create a connection bridge to the WebSphere MQ telemetry (MQXR) service, and then exchange messages with the daemon.
The update file, amqtdd.upd, is deleted by the daemon after it is used. To keep the commands you create for later use, you might want to create the commands in a different file and then transfer them to amqtdd.upd.

Procedure
Make sure that you have two instances of the MQTT client utility running. One is connected to the daemon on port 1884, and one is connected to the telemetry channel running on port 1883.
Create the file, amqtdd.upd, in the same directory as the daemon, amqtdd, with the following commands in the file.
 connection daemon1
address 127.0.0.1:1883
topic # in  import/ export/
topic # out export/ import/
try_private false
The bridge is called daemon1, and it connects to the channel configured for the telemetry (MQXR) service running at the socket address, 127.0.0.1:1883. The try_private command is optional; true is the default. Without this line, the bridge first tries to connect using a private protocol that is understood by WebSphere MQ Telemetry daemon for devices. Including try_private false in the commands avoids this step, and speeds up the time to finish a successful connection.
The line, topic # in import/ export/, instructs daemon1 to subscribe to all topics matching the topic string export/# created in the queue manager. It transfers the matching publications from the queue manager to the daemon, changing the start of the topic string from export/ to import/. The line, topic # out export/ import/, creates a subscription at the local daemon. The bridge subscribes to all topics matching the topic string export/# created in the daemon. It transfers publications from the daemon to the queue manager, changing the start of the topic string from export/ to import/.

the resulting console log.
Console log from starting connection bridge
 CWNAN0124I Starting bridge connection daemon1
CWNAN0133I Bridge connection daemon1 to 127.0.0.1:1883 now established
In each instance of the MQTT client utility, type import/# in the Subscription/Topic: input field > Subscribe.

In each instance of the MQTT client utility, type export/# in the Publication/Topic: input field.

In the MQTT client utility connected to port 1883, the telemetry channel, type From the queue manager in the Publication/Message: input field > Publish.
In the MQTT client utility connected to port 1884, the telemetry daemon, type From the daemon in the Publication/Message: input field > Publish.

The client history in each MQTT client utility shows the publication that has been transferred from one broker to the other.
MQTT publish/subscribe applications

Use topic-based publish/subscribe to write MQTT applications.
When the MQTT client is connected, publications flow in either direction between the client and server. The publications are sent from the client when information is published at the client. Publications are received at the client when a message is published to a topic that matches a subscription created by the client.
The WebSphere MQ publish/subscribe broker manages the topics and subscriptions created by MQTT clients. The topics created by MQTT clients share the same topic space as topics created by WebSphere MQ applications.
Publications that match the topic string in an MQTT client subscription are placed on SYSTEM.MQTT.TRANSMIT.QUEUE with the remote queue manager name set to the ClientIdentifier of the client. The telemetry (MQXR) service forwards the publications to the client that created the subscription. It uses ClientIdentifier, which has been set as the remote queue manager name to identify the client.
Typically, SYSTEM.MQTT.TRANSMIT.QUEUE must be defined as the default transmission queue. It is possible, but onerous, to configure MQTT not to use the default transmission queue
An MQTT client can create a persistent session. Subscriptions created in a persistent session are durable. Publications that arrive for a client with a persistent session are stored in SYSTEM.MQTT.TRANSMIT.QUEUE, and forwarded to the client when it reconnects.
An MQTT client can also publish and subscribe to retained publications; see Retained publications and MQTT clients . A subscriber to a retained publication topic receives the latest publication to the topic. The subscriber receives the retained publication when it creates a subscription, or when it reconnects to its earlier session.

Telemetry applications

Write telemetry applications using WebSphere MQ or WebSphere Message Broker message flows.
Use JMS, MQI, or other WebSphere MQ programming interfaces to program telemetry applications in WebSphere MQ.
The telemetry (MQXR) service converts between MQTT v3 messages and WebSphere MQ messages. It creates subscriptions and publications on behalf of MQTT clients, and forwards publications to MQTT clients. A publication is the payload of an MQTT v3 message. The payload comprises message headers and a byte array in jms-bytes format. The telemetry server maps the headers between an MQTT v3 message and a WebSphere MQ message
Use the Publication, MQInput, and JMSInput nodes to send and receive publications between WebSphere Message Broker and MQTT clients.
Use message flows you can integrate telemetry with Web sites using HTTP, and with other applications using WebSphere MQ and WebSphere Adapters.
WebSphere MQ Telemetry replaces the SCADA nodes in WebSphere Message Broker version 7.

Integration of WebSphere MQ Telemetry with queue managers

The MQTT client is integrated with WebSphere MQ as a publish/subscribe application. It can either publish or subscribe to topics in WebSphere MQ, creating new topics, or using existing topics. It receives publications from WebSphere MQ as a result of MQTT clients, including itself, or other WebSphere MQ applications publishing to the topics of its subscriptions. Rules are applied to decide the attributes of a publication.

Many of the attributes associated with topics, publications, subscriptions, and messages that are provided by WebSphere MQ, are not supported. MQTT client to WebSphere MQ publish/subscribe broker and WebSphere MQ to an MQTT client describe how attributes of publications are set. The settings depend on whether the publication is going to or from the WebSphere MQ publish/subscribe broker.
In WebSphere MQ publish/subscribe topics are associated with administrative topic objects. The topics created by MQTT clients are no different. When an MQTT client creates a topic string for a publication the WebSphere MQ publish/subscribe broker associates it with an administrative topic object. The broker maps the topic string in the publication to the nearest administrative topic object parent. The mapping is the same as for WebSphere MQ applications. If there is no user created topic, the publication topic is mapped to SYSTEM.BASE.TOPIC. The attributes that are applied to the publication are derived from the topic object.
When a WebSphere MQ application, or an administrator creates a subscription, the subscription is named. List subscriptions using WebSphere MQ Explorer, or by using runmqsc or PCF commands. All MQTT client subscriptions are named. They are given a name of the form: ClientIdentifier:Topic name

MQTT client to WebSphere MQ publish/subscribe broker

An MQTT client has sent a publication to WebSphere MQ. The telemetry (MQXR) service converts the publication to a WebSphere MQ message. The WebSphere MQ message contains three parts:

MQMD
RFH2
Message

MQMD properties are set to their default values, except where noted in Table 1 .

MQMD

MQMD field Type Value
Format MQCHAR8
MQFMT_RF_HEADER_2
UserIdentifier MQCHAR12
Set to one of:

MqttClient.ClientIdentifier
MqttConnectOptions.UserName
A user ID set by the WebSphere MQ administrator for the telemetry channel.

Priority MQLONG
MQPRI_PRIORITY_AS_Q_DEF (Default for WebSphere MQ, which is different to JMS that has a default of 4.)
Persistence MQLONG

QoS=0→MQPER_NOT_PERSISTENT
QoS=1→MQPER_PERSISTENT
QoS=2→MQPER_PERSISTENT

The RFH2 header does not contain an <msd> folder to define the type of the JMS message. The telemetry (MQXR) service creates the WebSphere MQ message as a default JMS message. The default JMS message-type is a jms-bytes message. An application can access additional header information as message properties
RFH2 values are set as shown in Table 2 . The Format property is set in the RFH2 fixed header and the other values are set in RFH2 folders.

RFH2

RFH2 property Type/Folder Header
Format MQCHAR8
MQFMT_NONE
ClientIdentifier mqtt/clientId
Copy MqttClient.ClientIdentifier with a length of 1...23 bytes.
QoS mqtt/qos
Copy QoS from incoming MQTT message.
Message ID mqtt/msgid
Copy Message ID from incoming MQTT message, if QoS is 1 or 2.
MQIsRetained mqps/Ret
Set if the original MQTT publication was sent with the RETAIN property set and the message is received as a retained publication.
MQTopicString mqps/Top
The topic to which the MQTT message was published.

The payload in an MQTT publication is mapped to the contents of a WebSphere MQ message:

Message contents

Message contents Type Contents
Buffer MQBYTEn
Copy of bytes from incoming MQTT message. The length can be zero.

WebSphere MQ to an MQTT client

A client has subscribed to a publication topic. A WebSphere MQ application has published to the topic, resulting in a publication being sent to the MQTT subscriber by the WebSphere MQ publish/subscribe broker. Alternatively, a WebSphere MQ application has sent an unsolicited message directly to an MQTT client. Table 4 describes how the fixed message headers are set in the message that is sent to the MQTT client. Any other data in the WebSphere MQ message header, or any other headers, are discarded. The message data in the WebSphere MQ message is sent as the message payload in the MQTT message, with no alteration. The MQTT message is sent to the MQTT client by the telemetry (MQXR) service.

MQTT fixed header properties

MQTT field Type Value
DUP boolean
Set if QoS = 1 or 2, and the message was sent to this client in a previous transmission, and the message has not been acknowledged after a time.
QoS int
The way the value of QoS in an outgoing publication from the publish/subscribe broker in WebSphere MQ is set depends on the incoming publication. It depends on whether the incoming publication was sent from an MQTT client, or from a WebSphere MQ application.

MQTT

Lower value of the QoS in the incoming publication, and in the QoS requested by the subscriber.

WebSphere MQ

Lower value of the QoS derived from the incoming publication:

MQPER_NOT_PERSISTENT→QoS=0
MQPER_PERSISTENT→QoS=2

and the QoS requested by the subscriber. If the message is sent to the client without a subscription, QoS is set by default to 2. A client can alter this value by subscribing to DEFAULT.QoS with a different QoS.

RETAIN boolean
Set if the incoming publication has the retained property set.
variable message headers are set in the MQTT message that is sent to the MQTT client.

MQTT Variable header properties

MQTT field Type Value
Topic name String
The topic string the message was published with.
Message ID String
The last 2 bytes of the MQMD.MsgId property of the publication when it is placed in SYSTEM.MQTT.TRANSMIT.QUEUE.
Payload byte[]
Direct copy of bytes from incoming publication to the publish/subscribe broker. The length can be zero.

Telemetry daemon for devices

The WebSphere MQ Telemetry daemon for devices is an advanced MQTT V3 client application. Use it to store and forward messages from other MQTT clients. It connects to WebSphere MQ like an MQTT client, but you can also connect other MQTT clients to it. You can connect it to other telemetry daemons too.
It serves four basic purposes:

Connect local MQTT clients together in a publish/subscribe network.

You might connect the sensor and an actuator of a device as separate MQTT clients to the daemon. The sensor publishes its gauge readings, and the actuator subscribes to the readings, modifying its behavior based on their values. The readings are acted on locally.

Filter which subscriptions, and which messages are published to the queue manager, and to the device.

In the previous example, a WebSphere Message Broker message flow might subscribe to the topic that the daemon publishes readings to. The flow updates a Web page and shows the state of the device.
The daemon might also forward the subscription that the actuator created to the queue manager. A WebSphere Message Broker flow publishes a message to the topic the MQTT client servicing the actuator subscribed to. The MQTT client modifies the device settings.
The message flow might start from a Web page using a WebSphere Message Broker HTTPInput node.

Concentrate multiple MQTT clients into one connection to the telemetry server.

Rather than each device connecting separately to the telemetry server, the daemon forwards publications and subscriptions on a single TCP/IP connection. The daemon reduces the number of TCP/IP connections managed by the telemetry (MQXR) service.
Individual MQTT clients connect to the daemon. The individual clients are invisible to the queue manager. The daemon makes one connection to the queue manager on behalf of all the clients that connect to it.

Store and forward messages between devices and the queue manager

The daemon takes the responsibility for protecting telemetry devices from short-lived connection failures of the connection to the queue manager.
A device might only support "fire and forget" messaging. If the connection to the queue manager is only available intermittently, or is unreliable, the device has no way to transfer information predictably or reliably.
A solution is to attach the device to the daemon using a local connection that is always available. The daemon can buffer the messages that flow to and from the queue manager in its memory. It can use a reliable quality of service to send the messages to and from the queue manager on an unreliable connection.

Note: The daemon does not have persistent storage for inflight messages. Messages are buffered in memory.

MQTT stateless and stateful sessions

MQTT clients can create a stateful session with the queue manager. When a stateful MQTT client disconnects, the queue manager maintains the subscriptions created by the client, and in-flight messages. When the client reconnects, it resolves in-flight message. It sends any messages that are queued for delivery, and receives any messages published for its subscriptions while it was disconnected.
When an MQTT client connects to a telemetry channel it either starts a new session, or resumes an old session. A new session has no outstanding messages that have not been acknowledged, no subscriptions, and no publications awaiting delivery. When a client connects, it specifies whether to start with a clean session, or to resume an existing session; see Clean sessions .
If the client resumes an existing session, it continues as if the connection had not been broken. Publications awaiting delivery are sent to the client, and any message transfers that had not been committed, are completed. When a client in a persistent session disconnects from the telemetry (MQXR) service, any subscriptions the client created remain. Publications for the subscriptions are sent to the client when it reconnects. If it reconnects without resuming the old session, the publications are discarded by the telemetry (MQXR) service.
Session state information is saved by the queue manager in the SYSTEM.MQTT.PERSISTENT.STATE queue.
The WebSphere MQ administrator can disconnect and purge a session.

When an MQTT client is not connected

When a client is not connected the queue manager can continue to receive publications on its behalf. They are forwarded to the client when it reconnects. A client can create a Last will and testament, which the queue manager publishes on behalf of the client, if the client disconnects unexpectedly.
To be notified when the client unexpectedly disconnects, you can register a last will and testament publication. It is sent by the telemetry (MQXR) service, if it detects the connection to the client has broken without the client requesting it.
A client can publish a retained publication at any time. A new subscription to a topic can request to be sent any retained publication associated with topic. If you create the last will and testament as a retained publication, you can use it to monitor the status of a client.
For example, the client publishes a retained publication, when it connects, advertising its availability. At the same time, it creates a retained last will and testament publication that announces its unavailability. In addition, just before it makes a planned disconnection, it publishes its unavailability as a retained publication. To find out whether the client is available, you would subscribe to the topic of the retained publication. You would always receive one of the three publications.
If the client is to receive messages published when it is disconnected, then reconnect the client to its previous session. Its subscriptions are active until they are deleted, or until the client creates a clean session.

Loose coupling between MQTT clients and WebSphere MQ applications

The flow of publications between MQTT clients and WebSphere MQ applications is loosely coupled. Publications might originate from either an MQTT client or a WebSphere MQ application, and in no set order. Publishers and subscribers are loosely coupled. They interact with each other indirectly through publications and subscriptions. You can also send messages directly to an MQTT client from a WebSphere MQ application.
MQTT clients and WebSphere MQ applications are loosely coupled in two senses:

Publishers and subscribers are loosely coupled by the association of a publication and a subscription with a topic. Publishers and subscribers are not normally aware of the address or identity of the other source of a publication or subscription.
MQTT clients publish, subscribe, receive publications, and process delivery acknowledgments on separate threads.

An MQTT client application does not wait until a publication has been delivered. The application passes a message to the MQTT client, and then the application continues on its own thread. A delivery-token is used to synchronize the application with the delivery of a publication; see Delivery tokens .
After passing a message to the MQTT client, the application has the choice of waiting on the delivery-token. Rather than waiting, the client can provide a callback method that is called when the publication is delivered to WebSphere MQ. It can also ignore the delivery-token.
Depending on the quality of service associated with the message, the delivery-token is returned immediately to the callback method, or possibly after some considerable time. The delivery-token might even be returned after the client has disconnected and reconnected. If the quality of service is "fire and forget", the delivery-token is returned immediately. In the other two cases, the delivery token is returned only when the client receives acknowledgment that the publication has been sent to subscribers.
Publications sent to an MQTT client as a result of a client subscription, are delivered to the messageArrived callback method. messageArrived runs on a different thread to the main application.

Sending messages directly to an MQTT client

You can send a message to a particular MQTT client in one of two ways.

A WebSphere MQ application can send a message directly to an MQTT client without a subscription
An alternative approach is to use your ClientIdentifier naming convention. Make all MQTT subscribers create subscriptions using their unique ClientIdentifier as a topic. Publish to ClientIdentifier. The publication is sent to the client that subscribed to the topic ClientIdentifier. Using this technique you can send a publication to a particular MQTT subscriber.

WebSphere MQ Telemetry security

Securing telemetry devices can be important, as the devices are likely to be portable, and used in places that cannot be carefully controlled. You can use VPN to secure the connection from the MQTT device to the telemetry (MQXR) service. WebSphere MQ Telemetry provides two other security mechanisms, SSL and JAAS.
SSL is principally used to encrypt communications between the device and the telemetry channel, and to authenticate the device is connecting to the correct server. You can also use SSL to check that the client device is permitted to connect to the server
JAAS is principally used to check that the user of the device is permitted to use a server application. JAAS can be used with LDAP to check a password using a single sign-on directory.
SSL and JAAS can be used in conjunction to provide two factor authentication. You can restrict the ciphers used by SSL to ciphers that meet FIPS standards.
With at least tens of thousands of users, it is not always practical to provide individual security profiles. Nor is it always practical to use the profiles to authorize individual users to access WebSphere MQ objects. Instead group Users into classes for authorizing publication and subscription to topics, and sending publications to clients.
Configure each telemetry channel to map clients to common client user IDs. Use a common user ID for every client that connects on a specific channel.
Authorizing groups of users does not compromise authentication of each individual. Each individual user can be authenticated, at the client or server, with their Username and Password, and then authorized at the server using a common user ID.

WebSphere MQ Telemetry globalization

The message payload in the MQTT v3 protocol is encoded as byte-array. Generally, applications handling text create the message payload in UTF-8. The telemetry channel describes the message payload as UTF-8, but does not do any code page conversions. The publication topic string must be UTF-8.
The application is responsible for converting alphabetic data to the correct code page and numeric data to the correct number encoding.
The MQTT Java client has a convenient MqttMessage.toString method. The method treats the message payload as being encoded in the local platform default character set, which is generally UTF-8. It converts the payload to a Java String. Java has a String method, getBytes that converts a string into a byte array encoded using the local platform default character set. Two MQTT Java programs exchanging text in the message payload, between platforms with the same default character set do so easily and efficiently in UTF-8.
If the default character set of one of the platforms is not UTF-8, then the applications must establish a convention for exchanging messages. For example, the publisher specifies conversion from a string to UTF-8 using the getBytes("UTF8") method. To receive the text of a message, the subscriber assumes that the message is encoded in the UTF-8 character set.
The telemetry (MQXR) service describes the encoding of all incoming publications from MQTT clients messages as being UTF-8. It sets MQMD.CodedCharSetId to UTF-8, and RFH2.CodedCharSetId to MQCCSI_INHERIT; see Integration of WebSphere MQ Telemetry with queue managers . The format of the publication is set to MQFMT_NONE, so no conversion can be performed by channels, or by MQGET.

Performance and scalability of WebSphere MQ Telemetry

Consider the following factors when managing large numbers of clients and improving scalability of WebSphere MQ Telemetry.

Capacity Planning

For information about performance reports for WebSphere MQ Telemetry, select the WebSphere MQ Telemetry Performance Evaluations report from the website WebSphere MQ Family - Performance Reports .

Connections

Costs involved with connections include

The cost of setting up a connection itself in terms of processor usage and time.
Network costs.
Memory used when keeping a connection open but not using it.

There is an extra load incurred when clients stay connected. If a connection is kept open, TCP/IP flows and MQTT messages use the network to check that the connection is still there. Additionally, memory is used in the server for each client connection that is kept open.
If you are sending messages more than one per minute, keep your connection open to avoid the cost of initiating a new connection. If you are sending messages less than one every 10 - 15 minutes, consider dropping your connection to avoid the cost of keeping it open. You might want to keep an SSL connection open, but idle, for longer periods because it is more expensive to set up.
Additionally, consider the capability of the client. If there is a store and forward facility on the client then you might batch up messages and drop the connection between sending the batches. However, if the client is disconnected, then it is not possible for the client to receive a message from the server. Therefore the purpose of your application has a bearing on the decision good.
If your system has one client sending many messages, for example file transfers, do not wait for a server response per message. Instead, send all messages and check at the end that they have all been received. Alternatively, use Quality of Service (QoS).
You can vary the QoS by message, delivering unimportant messages using QoS 0 and important messages using a QoS of 2. The message throughput can be around twice as high with a QoS of 0 than with a QoS of 2.

Naming conventions

If you are designing your application for many clients, implement an effective naming convention. In order to map each client to the correct ClientIdentifier, make the ClientIdentifier meaningful. A good naming convention makes it easier for the Administrator to work out which clients are running. A naming convention helps the administrator filter a long list of clients in WebSphere MQ Explorer, and helps with problem determination

Throughput

The length of topic names affects the number of bytes that flow across the network. When publishing or subscribing, the number of bytes in a message might be important. Therefore limit the number of characters in a topic name. When an MQTT client subscribes for a topic WebSphere MQ gives it a name of the form:

ClientIdentifier:TopicName

To view all of the subscriptions for an MQTT client, you can use the WebSphere MQ MQSC DISPLAY command:

DISPLAY SUB('ClientID1:*')

Defining resources in WebSphere MQ for use by MQTT clients

An MQTT client connects to WebSphere MQ a remote queue manager. There are two basic methods for a WebSphere MQ application to send messages to an MQTT client: set the default transmission queue to SYSTEM.MQTT.TRANSMIT.QUEUE or use queue manager aliases. Define the default transmission queue of a queue manager, if there are large numbers of MQTT clients. Using the default transmission queue setting simplifies the administration effort; see Configure distributed queuing to send messages to MQTT clients .

Improving scalability by avoiding subscriptions.

When an MQTT V3 client subscribes to a topic, a subscription is created by the telemetry (MQXR) service in WebSphere MQ. The subscription routes publications for the client onto SYSTEM.MQTT.TRANSMIT.QUEUE. The remote queue manager name in the transmission header of each publication is set to the ClientIdentifier of the MQTT client that made the subscription. If there are many clients, each making their own subscriptions, this results in many proxy subscriptions being maintained throughout the WebSphere MQ publish/subscribe cluster or hierarchy. For information about not using publish/subscribe, but using a point to point based solution instead, see Sending a message to a client directly .

Managing large numbers of clients

To support many concurrently connected clients, increase the memory available for the telemetry (MQXR) service by setting the JVM parameters -Xms and -Xmx. Follow these steps:
Find the java.properties file in the telemetry service configuration directory; see Telemetry (MQXR) service configuration directory on Windows or Telemetry service configuration directory on Linux .
Follow the directions in the file; a heap of 1 GB is sufficient for 50,000 concurrently connected clients.
 # Heap sizing options - uncomment the following lines to set the heap to 1G
#-Xmx1024m
#-Xms1024m
Add other command-line arguments to pass to the JVM running the telemetry (MQXR) service in the java.properties file; see Passing JVM parameters to the telemetry (MQXR) service .
To increase the number of open file descriptors on Linux, add the following lines to /etc/security/limits.conf/, and log in again.
 @mqm soft nofile 65000
@mqm hard nofile 65000
Each socket requires one file descriptor. The telemetry service require some additional file descriptors, so this number must be larger than the number of open sockets required.
The queue manager uses an object handle for each nondurable subscription. To support many active, nondurable subscriptions increase the maximum number of active handles in the queue manager; for example:
Alter maximum number of handles on Windows
 echo ALTER QMGR MAXHANDS(999999999) | runmqsc qMgrName
Alter maximum number of handles on Linux
 echo "ALTER QMGR MAXHANDS(999999999)" | runmqsc qMgrName
Other considerations

When planning your system requirements, consider the length of time taken to restart the system. The planned downtime might have implications for the number of messages that queue up, waiting to be processed. Configure the system so that the messages can be successfully processed in an acceptable time. Review disk storage, memory, and processing power. With some client applications, it might be possible to discard messages when the client reconnects. To discard messages, set CleanSession in the client connection parameters; see Clean sessions . Alternatively, publish and subscribe using the best effort Quality of Service, 0, in an MQTT client; see Quality of service . Use non-persistent messages when sending messages from WebSphere MQ. Messages with these qualities of service are not recovered when the system or connection restarts.

Devices supported by WebSphere MQ Telemetry

MQTT clients can run on a range of devices, from sensors and actuators, to hand held devices and vehicle systems.
MQTT clients are small, and run on devices constrained by little memory and low processing power. The MQTT protocol is reliable and has small headers, which suits networks constrained by low bandwidth, high cost, and intermittent availability.
WebSphere MQ Telemetry provides three clients, which all implement the MQTT v3 protocol:

A Java client that can run on all variations of Java from the smallest CLDC (Connected Limited Device Configuration)/MIDP (Mobile Information Device Profile) through CDC (Connected Device Configuration)/Foundation, J2SE (Java Platform, Standard Edition), and J2EE (Java Platform, Enterprise Edition). IBM jclRM customized class library is also supported.
A C reference implementation together with prebuilt native client for Windows and Linux systems. The C reference implementation enables MQTT to be ported to a wide range of devices and platforms.
The advanced client, WebSphere MQ Telemetry daemon for devices, which is written in C, and can run on any suitable Linux or Windows platform.

Some Windows systems on Intel, including Windows XP, RedHat, Ubuntu, and some Linux systems on ARM platforms such as Eurotech Viper implement versions of Linux that run the C client, but IBM does not provide service support for the platforms. You must reproduce problems with the client on a supported platform if you intend to call your IBM support centre.
The Java ME platform is generally used on small devices, such as actuators, sensors, mobile phones, and other embedded devices.
The Java SE platform is generally installed on higher end embedded devices, such as desktop computers and servers.
The MQTT reference implementation support pack can be ported to devices that might not be on one of these platforms. Source code is provided for reference implementation (plus some binary files). For further information, see IBM Support & downloads .

MQMD field	Type	Value
Format	MQCHAR8	MQFMT_RF_HEADER_2
UserIdentifier	MQCHAR12	Set to one of: MqttClient.ClientIdentifier MqttConnectOptions.UserName A user ID set by the WebSphere MQ administrator for the telemetry channel.
Priority	MQLONG	MQPRI_PRIORITY_AS_Q_DEF (Default for WebSphere MQ, which is different to JMS that has a default of 4.)
Persistence	MQLONG	QoS=0→MQPER_NOT_PERSISTENT QoS=1→MQPER_PERSISTENT QoS=2→MQPER_PERSISTENT

RFH2 property	Type/Folder	Header
Format	MQCHAR8	MQFMT_NONE
ClientIdentifier	mqtt/clientId	Copy MqttClient.ClientIdentifier with a length of 1...23 bytes.
QoS	mqtt/qos	Copy QoS from incoming MQTT message.
Message ID	mqtt/msgid	Copy Message ID from incoming MQTT message, if QoS is 1 or 2.
MQIsRetained	mqps/Ret	Set if the original MQTT publication was sent with the RETAIN property set and the message is received as a retained publication.
MQTopicString	mqps/Top	The topic to which the MQTT message was published.

Message contents	Type	Contents
Buffer	MQBYTEn	Copy of bytes from incoming MQTT message. The length can be zero.

MQTT field	Type	Value
DUP	boolean	Set if QoS = 1 or 2, and the message was sent to this client in a previous transmission, and the message has not been acknowledged after a time.
QoS	int	The way the value of QoS in an outgoing publication from the publish/subscribe broker in WebSphere MQ is set depends on the incoming publication. It depends on whether the incoming publication was sent from an MQTT client, or from a WebSphere MQ application. MQTT Lower value of the QoS in the incoming publication, and in the QoS requested by the subscriber. WebSphere MQ Lower value of the QoS derived from the incoming publication: MQPER_NOT_PERSISTENT→QoS=0 MQPER_PERSISTENT→QoS=2 and the QoS requested by the subscriber. If the message is sent to the client without a subscription, QoS is set by default to 2. A client can alter this value by subscribing to DEFAULT.QoS with a different QoS.
RETAIN	boolean	Set if the incoming publication has the retained property set.