README.md in mqtt-0.2.0 vs README.md in mqtt-0.3.0
- old
+ new
@@ -1,22 +1,38 @@
+[](https://travis-ci.org/njh/ruby-mqtt)
+
ruby-mqtt
=========
-Pure Ruby gem that implements the MQTT protocol, a lightweight protocol for publish/subscribe messaging.
+Pure Ruby gem that implements the [MQTT] protocol, a lightweight protocol for publish/subscribe messaging.
-Installing
-----------
+Table of Contents
+-----------------
+* [Installation](#installation)
+* [Quick Start](#quick-start)
+* [Library Overview](#library-overview)
+* [Resources](#resources)
+* [License](#license)
+* [Contact](#contact)
-You may get the latest stable version from Rubygems:
+Installation
+------------
+
+You may get the latest stable version from [Rubygems]:
+
$ gem install mqtt
+Alternatively, to use a development snapshot from GitHub using [Bundler]:
-Synopsis
---------
+ 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|
@@ -30,22 +46,110 @@
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.
+
+
+
Limitations
-----------
* Only QOS 0 currently supported
+ * Automatic re-connects to the server are not supported
Resources
---------
+* 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
-* API Documentation: http://rubydoc.info/gems/mqtt/frames
License
-------
@@ -57,5 +161,20 @@
-------
* Author: Nicholas J Humfrey
* Email: njh@aelius.com
* Home Page: http://www.aelius.com/njh/
+
+
+
+[MQTT]: http://www.mqtt.org/
+[Rubygems]: http://rubygems.org/
+[Bundler]: http://bundler.io/
+[MQTT URI]: https://github.com/mqtt/mqtt.github.io/wiki/URI-Scheme
+[Topic Filters]: http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html#_Toc388534397
+
+[MQTT::Client]: http://rubydoc.info/gems/mqtt/MQTT/Client#instance_attr_details
+[MQTT::Client.connect]: http://rubydoc.info/gems/mqtt/MQTT/Client.connect
+[MQTT::Client#publish]: http://rubydoc.info/gems/mqtt/MQTT/Client:publish
+[MQTT::Client#subscribe]: http://rubydoc.info/gems/mqtt/MQTT/Client:subscribe
+[MQTT::Client#get]: http://rubydoc.info/gems/mqtt/MQTT/Client:get
+