Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Build Status


Pure Ruby gem that implements the MQTT protocol, a lightweight protocol for publish/subscribe messaging.

Also includes a class for parsing and generating MQTT-SN packets.

Table of Contents


You may get the latest stable version from Rubygems:

$ gem install mqtt

Alternatively, to use a development snapshot from GitHub using Bundler, add this to your Gemfile:

    gem 'mqtt', :github => 'njh/ruby-mqtt'

Quick Start

require 'mqtt'

# Publish example
MQTT::Client.connect('') do |c|
  c.publish('test', 'message')

# Subscribe example
MQTT::Client.connect('') do |c|
  # If you pass a block to the get method, then it will loop
  c.get('test') do |topic,message|
    puts "#{topic}: #{message}"

Library Overview


A new client connection can be created by passing either a MQTT URI, a host and port or by passing a hash of attributes.

client = MQTT::Client.connect('mqtt://')
client = MQTT::Client.connect('mqtts://')
client = MQTT::Client.connect('')
client = MQTT::Client.connect('', 18830)
client = MQTT::Client.connect(:host => '', :port => 1883 ... )

TLS/SSL is not enabled by default, to enabled it, pass :ssl => true:

client = MQTT::Client.connect(
  :host => '',
  :port => 8883,
  :ssl => true

Alternatively you can create a new Client object and then configure it by setting attributes. This example shows setting up client certificate based authentication:

client = = ''
client.ssl = true
client.cert_file = path_to('client.pem')
client.key_file  = path_to('client.key')
client.ca_file   = path_to('root-ca.pem')

The connection can either be made without the use of a block:

client = MQTT::Client.connect('')
# perform operations

Or, if using a block, with an implicit disconnection at the end of the block.

MQTT::Client.connect('') do |client|
  # perform operations

For more information, see and list of attributes for the MQTT::Client class and the MQTT::Client.connect method.


To send a message to a topic, use the publish method:

client.publish(topic, payload, retain=false)

The method will return once the message has been sent to the MQTT server.

For more information see the MQTT::Client#publish method.


You can send a subscription request to the MQTT server using the subscribe method. One or more Topic Filters may be passed in:

client.subscribe( 'topic1' )
client.subscribe( 'topic1', 'topic2' )
client.subscribe( 'foo/#' )

For more information see the MQTT::Client#subscribe method.

Receiving Messages

To receive a message, use the get method. This method will block until a message is available. The topic is the name of the topic the message was sent to. The message is a string:

topic,message = client.get

Alternatively, you can give the get method a block, which will be called for every message received and loop forever:

client.get do |topic,message|
  # Block is executed for every message received

For more information see the MQTT::Client#get method.

Parsing and serialising of packets

The parsing and serialising of MQTT and MQTT-SN packets is a separate lower-level API. You can use it to build your own clients and servers, without using any of the rest of the code in this gem.

# Parse a string containing a binary packet into an object
packet_obj = MQTT::Packet.parse(binary_packet)
# Write a PUBACK packet to an IO handle
ios << MQTT::Packet::Puback(:id => 20)
# Write an MQTT-SN Publish packet with QoS -1 to a UDP socket
socket =
socket.connect('localhost', MQTT::SN::DEFAULT_PORT)
socket <<
  :topic_id => 'TT',
  :topic_id_type => :short,
  :data => "The time is: #{}",
  :qos => -1


  • QoS 2 is not currently supported by client
  • Automatic re-connects to the server are not supported
  • No local persistence for packets



The mqtt ruby gem is licensed under the terms of the MIT license. See the file LICENSE for details.



Pure Ruby gem that implements the MQTT protocol, a lightweight protocol for publish/subscribe messaging.