Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Pure Ruby gem that implements the MQTT protocol, a lightweight protocol for publish/subscribe messaging.
Ruby
branch: master

Merge pull request #62 from olvap/patch-1

Update README.md
latest commit 582f28dc19
@njh authored

README.md

Build Status

ruby-mqtt

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

Installation

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 => 'https://github.com/njh/ruby-mqtt.git'

Quick Start

require 'rubygems'
require 'mqtt'

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

# Subscribe example
MQTT::Client.connect('test.mosquitto.org') 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

Connecting

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://myserver.example.com')
client = MQTT::Client.connect('mqtts://user:pass@myserver.example.com')
client = MQTT::Client.connect('myserver.example.com')
client = MQTT::Client.connect('myserver.example.com', 18830)
client = MQTT::Client.connect(:host => 'myserver.example.com', :port => 1883 ... )

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

client = MQTT::Client.connect(
  :host => 'test.mosquitto.org',
  :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 = MQTT::Client.new
client.host = 'myserver.example.com'
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')
client.connect()

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

client = MQTT::Client.connect('test.mosquitto.org')
# perform operations
client.disconnect()

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

MQTT::Client.connect('test.mosquitto.org') do |client|
  # perform operations
end

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

Publishing

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.

Subscribing

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
end

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 = UDPSocket.new
socket.connect('localhost', MQTT::SN::DEFAULT_PORT)
socket << MQTT::SN::Packet::Publish.new(
  :topic_id => 'TT',
  :topic_id_type => :short,
  :data => "The time is: #{Time.now}",
  :qos => -1
)
socket.close

Limitations

  • Only QOS 0 currently supported by client
  • Automatic re-connects to the server are not supported

Resources

License

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

Contact

Something went wrong with that request. Please try again.