Pure Ruby gem that implements the MQTT protocol, a lightweight protocol for publish/subscribe messaging.
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'
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
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:[email protected]')
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.
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.
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.
- Only QOS 0 currently supported
- Automatic re-connects to the server are not supported
- API Documentation: http://rubydoc.info/gems/mqtt
- Protocol Specification v3.1.1: http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html
- Protocol Specification v3.1: http://public.dhe.ibm.com/software/dw/webservices/ws-mqtt/mqtt-v3r1.html
- MQTT Homepage: http://www.mqtt.org/
- GitHub Project: http://github.com/njh/ruby-mqtt
The ruby-mqtt gem is licensed under the terms of the MIT license. See the file LICENSE for details.
- Author: Nicholas J Humfrey
- Email: [email protected]
- Home Page: http://www.aelius.com/njh/