Need help with ruby-mqtt?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

466 Stars 118 Forks MIT License 374 Commits 26 Opened issues


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

Services available


Need anything else?

Contributors list

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:

gem 'mqtt', :git => ''

Quick Start

require 'rubygems'
require 'mqtt'

Publish example

MQTT::Client.connect('') do |c| c.publish('test', 'message') end

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}" end end

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://user:[email protected]')
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

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 ) socket.close


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


  • API Documentation:
  • Protocol Specification v3.1.1:
  • Protocol Specification v3.1:
  • MQTT-SN Protocol Specification v1.2:
  • MQTT Homepage:
  • GitHub Project:


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


We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.