mqtt-rails 1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '07387e175ea1e3133f15fb9bce534aab019799ebb6472bbe7d48479cb67b9405'
+  data.tar.gz: '0438ddc874e70a232032e23a461081e798d4528191fb821523abd8f5d9a586fb'
+SHA512:
+  metadata.gz: d83640e2f6fff6190fe3ab6232d1ab2fc6a6401c4d05cadb17cc6ad9304ea40cf7d80911ae018ddc749cba5436d8566d4278fe755651bd6d239dba6b2eaf44e3
+  data.tar.gz: f70787d2ebfa9bb889c7ec8b50103cc0b429e6cf1b736c9aee3290e6d0b0786e96d448cf8fa59896466051915f4ae32f72ee69614d0118dca73c2e9f0a862fd9

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+.idea/
+.rubocop.yml
+
+*.gem
+*.log

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.2.3
+before_install: gem install bundler -v 1.11.2

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at p-goudet@ruby-dev.jp. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in MqttRailsRuby.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,210 @@
+Eclipse Public License - v 1.0
+
+THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC
+LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM
+CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.
+
+   1. DEFINITIONS
+
+   "Contribution" means:
+
+a) in the case of the initial Contributor, the initial code and documentation
+distributed under this Agreement, and
+
+      b) in the case of each subsequent Contributor:
+
+         i) changes to the Program, and
+
+         ii) additions to the Program;
+
+where such changes and/or additions to the Program originate from and are
+distributed by that particular Contributor. A Contribution 'originates' from
+a Contributor if it was added to the Program by such Contributor itself or
+anyone acting on such Contributor's behalf. Contributions do not include additions
+to the Program which: (i) are separate modules of software distributed in
+conjunction with the Program under their own license agreement, and (ii) are
+not derivative works of the Program.
+
+   "Contributor" means any person or entity that distributes the Program.
+
+"Licensed Patents" mean patent claims licensable by a Contributor which are
+necessarily infringed by the use or sale of its Contribution alone or when
+combined with the Program.
+
+"Program" means the Contributions distributed in accordance with this Agreement.
+
+"Recipient" means anyone who receives the Program under this Agreement, including
+all Contributors.
+
+   2. GRANT OF RIGHTS
+
+a) Subject to the terms of this Agreement, each Contributor hereby grants
+Recipient a non-exclusive, worldwide, royalty-free copyright license to reproduce,
+prepare derivative works of, publicly display, publicly perform, distribute
+and sublicense the Contribution of such Contributor, if any, and such derivative
+works, in source code and object code form.
+
+b) Subject to the terms of this Agreement, each Contributor hereby grants
+Recipient a non-exclusive, worldwide, royalty-free patent license under Licensed
+Patents to make, use, sell, offer to sell, import and otherwise transfer the
+Contribution of such Contributor, if any, in source code and object code form.
+This patent license shall apply to the combination of the Contribution and
+the Program if, at the time the Contribution is added by the Contributor,
+such addition of the Contribution causes such combination to be covered by
+the Licensed Patents. The patent license shall not apply to any other combinations
+which include the Contribution. No hardware per se is licensed hereunder.
+
+c) Recipient understands that although each Contributor grants the licenses
+to its Contributions set forth herein, no assurances are provided by any Contributor
+that the Program does not infringe the patent or other intellectual property
+rights of any other entity. Each Contributor disclaims any liability to Recipient
+for claims brought by any other entity based on infringement of intellectual
+property rights or otherwise. As a condition to exercising the rights and
+licenses granted hereunder, each Recipient hereby assumes sole responsibility
+to secure any other intellectual property rights needed, if any. For example,
+if a third party patent license is required to allow Recipient to distribute
+the Program, it is Recipient's responsibility to acquire that license before
+distributing the Program.
+
+d) Each Contributor represents that to its knowledge it has sufficient copyright
+rights in its Contribution, if any, to grant the copyright license set forth
+in this Agreement.
+
+   3. REQUIREMENTS
+
+A Contributor may choose to distribute the Program in object code form under
+its own license agreement, provided that:
+
+      a) it complies with the terms and conditions of this Agreement; and
+
+      b) its license agreement:
+
+i) effectively disclaims on behalf of all Contributors all warranties and
+conditions, express and implied, including warranties or conditions of title
+and non-infringement, and implied warranties or conditions of merchantability
+and fitness for a particular purpose;
+
+ii) effectively excludes on behalf of all Contributors all liability for damages,
+including direct, indirect, special, incidental and consequential damages,
+such as lost profits;
+
+iii) states that any provisions which differ from this Agreement are offered
+by that Contributor alone and not by any other party; and
+
+iv) states that source code for the Program is available from such Contributor,
+and informs licensees how to obtain it in a reasonable manner on or through
+a medium customarily used for software exchange.
+
+   When the Program is made available in source code form:
+
+      a) it must be made available under this Agreement; and
+
+b) a copy of this Agreement must be included with each copy of the Program.
+
+Contributors may not remove or alter any copyright notices contained within
+the Program.
+
+Each Contributor must identify itself as the originator of its Contribution,
+if any, in a manner that reasonably allows subsequent Recipients to identify
+the originator of the Contribution.
+
+   4. COMMERCIAL DISTRIBUTION
+
+Commercial distributors of software may accept certain responsibilities with
+respect to end users, business partners and the like. While this license is
+intended to facilitate the commercial use of the Program, the Contributor
+who includes the Program in a commercial product offering should do so in
+a manner which does not create potential liability for other Contributors.
+Therefore, if a Contributor includes the Program in a commercial product offering,
+such Contributor ("Commercial Contributor") hereby agrees to defend and indemnify
+every other Contributor ("Indemnified Contributor") against any losses, damages
+and costs (collectively "Losses") arising from claims, lawsuits and other
+legal actions brought by a third party against the Indemnified Contributor
+to the extent caused by the acts or omissions of such Commercial Contributor
+in connection with its distribution of the Program in a commercial product
+offering. The obligations in this section do not apply to any claims or Losses
+relating to any actual or alleged intellectual property infringement. In order
+to qualify, an Indemnified Contributor must: a) promptly notify the Commercial
+Contributor in writing of such claim, and b) allow the Commercial Contributor
+to control, and cooperate with the Commercial Contributor in, the defense
+and any related settlement negotiations. The Indemnified Contributor may participate
+in any such claim at its own expense.
+
+For example, a Contributor might include the Program in a commercial product
+offering, Product X. That Contributor is then a Commercial Contributor. If
+that Commercial Contributor then makes performance claims, or offers warranties
+related to Product X, those performance claims and warranties are such Commercial
+Contributor's responsibility alone. Under this section, the Commercial Contributor
+would have to defend claims against the other Contributors related to those
+performance claims and warranties, and if a court requires any other Contributor
+to pay any damages as a result, the Commercial Contributor must pay those
+damages.
+
+   5. NO WARRANTY
+
+EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON
+AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS
+OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF
+TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+Each Recipient is solely responsible for determining the appropriateness of
+using and distributing the Program and assumes all risks associated with its
+exercise of rights under this Agreement, including but not limited to the
+risks and costs of program errors, compliance with applicable laws, damage
+to or loss of data, programs or equipment, and unavailability or interruption
+of operations.
+
+   6. DISCLAIMER OF LIABILITY
+
+EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY
+CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION
+LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
+WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS
+GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+   7. GENERAL
+
+If any provision of this Agreement is invalid or unenforceable under applicable
+law, it shall not affect the validity or enforceability of the remainder of
+the terms of this Agreement, and without further action by the parties hereto,
+such provision shall be reformed to the minimum extent necessary to make such
+provision valid and enforceable.
+
+If Recipient institutes patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Program itself
+(excluding combinations of the Program with other software or hardware) infringes
+such Recipient's patent(s), then such Recipient's rights granted under Section
+2(b) shall terminate as of the date such litigation is filed.
+
+All Recipient's rights under this Agreement shall terminate if it fails to
+comply with any of the material terms or conditions of this Agreement and
+does not cure such failure in a reasonable period of time after becoming aware
+of such noncompliance. If all Recipient's rights under this Agreement terminate,
+Recipient agrees to cease use and distribution of the Program as soon as reasonably
+practicable. However, Recipient's obligations under this Agreement and any
+licenses granted by Recipient relating to the Program shall continue and survive.
+
+Everyone is permitted to copy and distribute copies of this Agreement, but
+in order to avoid inconsistency the Agreement is copyrighted and may only
+be modified in the following manner. The Agreement Steward reserves the right
+to publish new versions (including revisions) of this Agreement from time
+to time. No one other than the Agreement Steward has the right to modify this
+Agreement. The Eclipse Foundation is the initial Agreement Steward. The Eclipse
+Foundation may assign the responsibility to serve as the Agreement Steward
+to a suitable separate entity. Each new version of the Agreement will be given
+a distinguishing version number. The Program (including Contributions) may
+always be distributed subject to the version of the Agreement under which
+it was received. In addition, after a new version of the Agreement is published,
+Contributor may elect to distribute the Program (including its Contributions)
+under the new version. Except as expressly stated in Sections 2(a) and 2(b)
+above, Recipient receives no rights or licenses to the intellectual property
+of any Contributor under this Agreement, whether expressly, by implication,
+estoppel or otherwise. All rights in the Program not expressly granted under
+this Agreement are reserved.
+
+This Agreement is governed by the laws of the State of New York and the intellectual
+property laws of the United States of America. No party to this Agreement
+will bring a legal action under this Agreement more than one year after the
+cause of action arose. Each party waives its rights to a jury trial in any
+resulting litigation.

data/README.md

@@ -0,0 +1,323 @@
+# MQTT RAILS
+
+The following file describes the Paho Mqtt client API for the ruby programming language. It enables applications to connect to an MQTT message broker threw the [MQTT](http://mqtt.org/) protocol (versions 3.1.1). MQTT is a lightweight protocol designed for IoT/M2M. A Mqtt client can connect to a message broker in order to publish and received data contained in short messages. The messages are exchanged on topics where the client has to subscribe for receiving message.
+
+Produced by Ruby development Inc.
+## Contents
+* [Installation](#installation)
+* [Usage](#usage)
+  * [Getting started](#getting-started)
+* [Client](#client)
+  * [Initialization](#initialization)
+  * [Client's parameters](#clients-parameter)
+  * [Subscription](#subscription)
+  * [Publishing](#publishing)
+* [Connection configuration](#connection-configuration)
+  * [Unencrypted mode](#unencrypted-mode)
+  * [Encrypted mode](#encrypted-mode)
+  * [Persistence](#persistence)
+  * [Foreground and Daemon](#foreground-and-daemon)
+* [Control loops](#control-loops)
+  * [Reading loop](#reading-loop)
+  * [Writing loop](#writing-loop)
+  * [Miscellaneous loop](#miscellaneous-loop)
+* [Handlers and Callbacks](#handlers-and-callbacks)
+  * [Handlers](#handlers)
+  * [Callbacks](#callbacks)
+* [Mosquitto (message broker)](#mosquitto-message-broker)
+* [Thanks](#thanks)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mqtt-rails'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install mqtt-rails
+
+## Usage
+
+### Getting started
+The following samples files cover the main features of the client:
+```ruby
+require 'mqtt-rails'
+
+### Create a simple client with default attributes
+client = MqttRails::Client.new
+
+### Register a callback on message event to display messages
+message_counter = 0
+client.on_message do |message|
+  puts "Message recieved on topic: #{message.topic}\n>>> #{message.payload}"
+  message_counter += 1
+end
+
+### Register a callback on suback to assert the subcription
+waiting_suback = true
+client.on_suback do
+  waiting_suback = false
+  puts "Subscribed"
+end
+
+### Register a callback for puback event when receiving a puback
+waiting_puback = true
+client.on_puback do
+  waiting_puback = false
+  puts "Message Acknowledged"
+end
+
+### Connect to the eclipse test server on port 1883 (Unencrypted mode)
+client.connect('iot.eclipse.org', 1883)
+
+### Subscribe to a topic
+client.subscribe(['/paho/ruby/test', 2])
+
+### Waiting for the suback answer and excute the previously set on_suback callback
+while waiting_suback do
+  sleep 0.001
+end
+
+### Publlish a message on the topic "/paho/ruby/test" with "retain == false" and "qos == 1"
+client.publish("/paho/ruby/test", "Hello there!", false, 1)
+
+while waiting_puback do
+  sleep 0.001
+end
+
+### Waiting to assert that the message is displayed by on_message callback
+sleep 1
+
+### Calling an explicit disconnect
+client.disconnect
+```
+
+## Client
+### Initialization
+The client may be initialized without paramaeters or with a hash of parameters. The list of client's accessor is details in the next parts. A client id would be generated if not provided, a default port would be also set (8883 if ssl set, else 1883).
+```ruby
+client = MqttRails::Client.new
+# Or
+client = MqttRails::Client.new({host: "iot.eclispe.org", port: 1883, ssl: false})
+```
+
+### Client's parameters
+The client has many accessors which help to configure the client depending on user's need. The different accessors could be splited in four roles, connection setup, last will setup, time-out setup and callback setup.
+Connection setup:
+```
+* host            : The endpoint where the client would try to connect (defaut "")
+* port            : The port on the remote host where the socket would try to connect (default 1883)
+* mqtt_version    : The version of MQTT protocol used to communication (default 3.1.1)
+* clean_session   : If set to false, ask the message broker to try to restore the previous session (default true)
+* persistent      : Keep the client connected even after keep alive timer run out, automatically try to reconnect on failure (default false)
+* reconnect_limit : If persistent mode is enabled, the maximum reconnect attempt (default 3)
+* reconnect_delay : If persistent mode is enabled, the delay between to reconnection attempt in second (default 5)
+* client_id       : The identifier of the client (default nil)
+* username        : The username if the server require authentication (default nil)
+* password        : The password of the user if authentication required (default nil)
+* ssl             : Requiring the encryption for the communication (default false)
+```
+
+Last Will:
+```
+* will_topic   : The topic where to publish the last will (default nil)
+* will_payload : The message of the last will (default "")
+* will_qos     : The qos of the last will (default 0)
+* will_retain  : The retain status of the last will (default false)
+```
+
+Timers:
+```
+* keep_alive  : The reference timer after which the client should decide to keep the connection alive or not
+* ack_timeout : The timer after which a non-acknowledged packet is considered as a failure
+```
+
+The description of the callback accessor is detailed in the section dedicated to the callbacks. The client also have three read only attributes which provide information on the client state.
+```
+* registered_callback : The list of topics where callback have been registred which the associated callback
+* subscribed_topics   : The list of the topics where the client is currentely receiving publish.
+* connection_state    : The current state of the connection between the message broker and the client
+```
+
+### Subscription
+In order to read a message sent on a topic, the client should subscribe to this topic. The client enables to subscribe to several topics in the same subscribe request. The subscription could also be done by using a wild-card, see more details on [MQTT protocol specifications](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html). Each topic is subscribed with a maximum qos level, only message with a qos level lower or equal to this value would be forwarded to the client. The subscribe command accepts one or several pair, each pair is composed by the topic (or wild-card) and the maximum qos level.  
+```ruby
+### Subscribe to two topics with maximum qos associated
+client.subscribe(["/foo/bar", 1], ["/foo/foo/", 2])
+```
+
+The subscription is persistent, in case of an unexpected disconnecting, the current subscription state is saved and a new subscribe request is sent to the message broker.
+
+### Publishing
+User data could be sent to the message broker with the publish operation. A publish operation requires a topic, and payload (user data), two other parameters may be configured, retain and qos. The retain flag tell to the message broker to keep the current publish packet, see the [MQTT protocol specifications](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) for more details about retain. The qos enable different levels of control on the transmission of publish package. The MqttRails client supports the three levels of qos (0, 1 and 2), see the [MQTT protocol specifications](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) for qos level details. The default retain value is False and the qos level is 0.
+```ruby
+### Publish to the topics "/foo/bar", with qos = 1 and no retain
+client.publish("/foo/bar", "Hello Wourld!", false, 1)
+```
+
+## Connection configuration
+### Unencrypted mode
+The most simple connection way is the unencrypted mode. All data would be sent clearly to the message broker, also it might not be safe for sensitive data. The connect method may set up or override some parameters of the client, the host, the port, the keep_alive timer, the persistence mode and blocking mode.
+```ruby
+### Simply connect to the message broker with default value or pre-set value
+client.connect
+# Or
+### Connect to the message broker with all parameter
+client.connect("iot.eclipse.org", 1883, client.keep_alive, client.persistent, client.blocking)
+```
+
+### Encrypted mode
+The client supports the encrypted connection threw tls-ssl socket. In order to use encrypted mode, the ssl flag of the client should be set to True.   
+``` ruby
+### Set the encryption mode to True
+client.ssl = true
+### Configure the user SSL key and the certificate
+client.config_ssl_context(certificate_path, key_path)
+client.connect("test.mosquitto.org", 8883)
+### Or if rootCA is needed
+client.config_ssl_context(certificate_path, key_path, rootCA_path)
+client.connect("test.mosquitto.org", 8884)
+```
+
+### Persistence
+The client holds a keep_alive timer is the reference time that the connection should be held. The timer is reset every time a new valid packet is received from the message broker. The persistence flag, when set to True, enables the client to be more independent from the keep_alive timer. Just before the keep_alive run out, the client sends a ping request to tell to the message broker that the connection should be kept. The persistent mode also enables the client to automatically reconnect to the message broker after an unexpected failure.  
+When the client's persistence flag is set to False, it just simply disconnects when the keep_alive timer runs out.  
+```ruby
+### This will connect to the message broker, keep connected and automatically reconnect on failure
+client.connect('iot.eclipse.org', 1883, client.keep_alive, true, client.blocking)
+#Or
+### This only connect to the message broker, disconnect after keep_alive or on failure
+client.connect('iot.eclipse.org', 1883, client.keep_alive, false, client.blocking)
+```
+The client has two attributes `@reconnect_limit` and `@reconnect_delay` which configure the reconnection process. `@reconnection_limit` is the maximum reconnection attempt that a client could try and `@reconnection_delay` is the delay that the client waits between two reconnection attempt. Setting the `@reconnect_limit` to -1 would run the reconnection process forever. 
+
+### Foreground and Daemon
+The client could be connected to the message broker using the main thread in foreground or as a daemon in a separate thread. The default mode is daemon mode, the daemon would run in the background the read/write operation as well as the control of the timers. If the client is connected using the main thread, all control operations are left to the user, using the different control loops. There are four different loop roles is detailed in the next part.
+
+```ruby
+### Connect to the message broker executing the mqtt_loop (socket reading/writing) in the background
+client.connect('iot.eclipse.org', 1883, client.keep_alive, client.persistence, true)
+#Or
+### This only connect to the message broker, nothing more
+client.connect('iot.eclipse.org', 1883, client.keep_alive, client.persistence, false)
+```
+
+## Control loops
+/!\ The control loops should not be used in a daemon mode.  
+They are automatically run in separate thread and execute the necessary operations for reading, writing and checking the connection state.
+
+### Reading loop
+The reading loop provides access to the socket in a reading mode. Periodically, the socket would be inspected to try to find a mqtt packet. The read loop accepts a parameter, which is the number of loop's turn. The default value is five turns.  
+The default value is defined in the MqttRails module as the constant MqttRails::MAX_READ, another module constant could be modified to control the socket inspection period. The referring constant is SELECT_TIMEOUT (MqttRails::SELECT_TIMEOUT) and its default value is 0.  
+```ruby
+### Trying to read 'max_packet' packets from the client socket
+client.loop_read(max_packet)
+```
+
+### Writing loop
+The writing loop send the packets which have previously been stacked by MQTT operations. This loop also accepts a parameter, which is the maximum packets number that could be written as the MAX_WRITING constant (MqttRails::MAX_WRITING). The writing loop exit if the maximum number of packet have been sent or if the waiting packet queue is empty.
+```ruby
+### Writing 'max_packet' packets to the client socket
+client.loop_write(max_packet)
+```
+
+### Miscellaneous loop
+The misc loop performs different control operations, modifying the packets states and the connection state. The misc loop parses the different queue of packet that are waiting for an acknowledgement. If the ack_timeout of a packet had run out, the packet is re-sent. The size of the different waiting queues is defined as module constants. This loop also asserts that the connection is still available by checking the keep_alive timer.
+```ruby
+### Perfom control operations on packets queues and connection
+client.loop_misc
+```
+
+## Handlers and Callbacks
+### Handlers
+When a packet is received and inspected, an appropriate handler is called. The handler performs different control operation such as update the connection state, update the subscribed topics, and send publish control packets. Each packet has a specific handler, except the pingreq/pingresp packet. Before returning the handler executes a callback, if the user has configured one for this type of packet. The publish handler may execute sequentially two callbacks. One callback for the reception of a generic publish packet and another one, if the user has configured a callback for the topic where the publish packet has been received.  
+
+### Callbacks
+The callbacks could be defined in a three different ways, as block, as Proc or as Lambda. The callback has access to the packet which triggered it.  
+```ruby
+### Register a callback trigger on the reception of a CONNACK packet with return code 0x00
+client.on_connack = proc { puts "Successfully Connected" }
+
+### Register a callback trigger on the reception of PUBLISH packet
+client.on_message do |packet|
+  puts "New message received on topic: #{packet.topic}\n>>>#{packet.payload}"
+end
+```
+
+A callback could be configured for every specific topics. The list of topics where a callbacks have been registered could be read at any time, threw the registered_callback variable. The following example details how to manage callbacks for specific topics.  
+```ruby
+### Add a callback for every message received on /foo/bar
+specific_callback = lambda { |packet| puts "Specific callback for #{packet.topic}" }
+client.add_topic_callback("/foo/bar", specific_callback)
+# Or
+client.add_topic_callback("/foo/bar") do |packet|
+  puts "Specific callback for #{packet.topic}"
+end
+
+### To remove a callback form a topic
+client.remove_topic_callback("/foo/bar")
+```
+
+## Mosquitto (message broker)
+Mosquitto is a message broker support by Eclipse, which is quite easy-going. In order to run spec or samples files, a message broker is needed. Mosquitto enable to run locally a message broker, it could be configured with the mosquitto.conf files.
+### Install mosquitto
+#### OSX (homebrew)
+```
+$ brew install mosquitto
+```
+### Run mosquitto
+#### Default mode
+The default mode of mosquitto is unencrypted, listening on the port 1883.
+```
+ $ mosquitto
+```
+
+#### Encrypted mode
+In order to successfully pass the spec, or for testing in encrypted mode, some configurations are needed on mosquitto. Private keys and certificates should be set on both client side and server side. The [mosquitto-tls](https://mosquitto.org/man/mosquitto-tls-7.html) page might help you create all the required credentials. Once the credentials are created, the mosquitto's config files should be updated as following.
+
+```
+$ cp mosquitto.conf samples-mosquitto.conf
+$ nano mosquitto.conf
+```
+
+The following file enables the broker to support the unencrypted mode (default) on port 1883, and the encrypted mode on port 8883. Update the path variable with the file's location on your environment. 
+```
+### mosquitto.conf
+# =================================================================
+# General configuration
+# =================================================================
+.
+.
+.
+# =================================================================
+# Extra listeners
+# =================================================================
+.
+.
+listener 8883
+.
+.
+cafile   "Path to the certificate authorithy certificate file"
+certfile "Path to the server certificate file"
+keyfile  "Path to the server private keys file"
+.
+.
+.
+```
+Finally run the server with the updated configuration file.
+
+```
+$ mosquitto -c mosquitto.conf
+```
+
+See [Mosquitto message broker page](https://mosquitto.org/) for more details.
+
+## Thanks
+Special thanks to [Nicholas Humfrey](https://github.com/njh) for providing a great help with the packet serializer/deserializer.