mqtt 0.2.0 → 0.3.0

data/NEWS.md

@@ -1,15 +1,35 @@
 Ruby MQTT NEWS
 ==============
 
+Ruby MQTT Version 0.3.0 (2014-08-26)
+------------------------------------
+
+* Added support for MQTT protocol version 3.1.1
+* Renamed a number of methods/attributes:
+  - Renamed ```:granted_qos``` to ```:return_codes```
+  - Renamed ```:remote_port``` to ```:port```
+  - Renamed ```:remote_host``` to ```:host```
+  - Renamed ```:message_id``` to ```:id```
+  - Renamed ```:protocol_version``` to ```:protocol_level```
+  - Renamed ```MQTT_SERVER``` environment variable to ```MQTT_SERVER```
+* Added more checks to ensure that the 3.1.1 protocol specs are adhered to
+* Added a Library Overview section to the README
+* Added links to the protocol specification to README
+* Improvements to the YARD API documentation
+* Don't display payload in inspect if it contains non-visible ASCII characters
+* Upgraded to rspec 3
+* Various minor bug fixes and corrections
+
+
 Ruby MQTT Version 0.2.0 (2014-04-02)
 ------------------------------------
 
 * Added SSL/TLS support
 * Added support for passing connection details using a URI
-* Added support for using the MQTT_BROKER environment variable
+* Added support for using the ```MQTT_BROKER``` environment variable
 * Allow passing array of topics to Client#unsubscribe
 * Allow more combinations of arguments to be passed to a new Client
-* No longer defaults to ‘localhost’ if there is no broker configured
+* No longer defaults to ‘localhost’ if there is no server configured
 * Fixed more 'unused variable' warnings
 * Documentation improvements
 * Ruby 1.8 fixes

data/README.md

@@ -1,19 +1,35 @@
+[![Build Status](https://travis-ci.org/njh/ruby-mqtt.svg)](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.
+
+
+Table of Contents
+-----------------
+* [Installation](#installation)
+* [Quick Start](#quick-start)
+* [Library Overview](#library-overview)
+* [Resources](#resources)
+* [License](#license)
+* [Contact](#contact)
 
 
-Installing
-----------
+Installation
+------------
 
-You may get the latest stable version from Rubygems:
+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'
@@ -32,18 +48,106 @@ Synopsis
     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
@@ -59,3 +163,18 @@ Contact
 * 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
+

data/lib/mqtt.rb

@@ -14,22 +14,22 @@ end
 
 module MQTT
 
-  # Default port number for unencrypted connections 
+  # Default port number for unencrypted connections
   DEFAULT_PORT = 1883
-  
-  # Default port number for TLS/SSL encrypted connections 
+
+  # Default port number for TLS/SSL encrypted connections
   DEFAULT_SSL_PORT = 8883
 
   # Super-class for other MQTT related exceptions
   class Exception < Exception
   end
 
-  # A ProtocolException will be raised if there is a 
+  # A ProtocolException will be raised if there is a
   # problem with data received from a remote host
   class ProtocolException < MQTT::Exception
   end
 
-  # A NotConnectedException will be raised when trying to 
+  # A NotConnectedException will be raised when trying to
   # perform a function but no connection has been
   # established
   class NotConnectedException < MQTT::Exception

data/lib/mqtt/client.rb

@@ -2,52 +2,55 @@ autoload :OpenSSL, 'openssl'
 autoload :URI, 'uri'
 
 
-# Client class for talking to an MQTT broker
+# Client class for talking to an MQTT server
 class MQTT::Client
-  # Hostname of the remote broker
-  attr_accessor :remote_host
+  # Hostname of the remote server
+  attr_accessor :host
 
-  # Port number of the remote broker
-  attr_accessor :remote_port
+  # Port number of the remote server
+  attr_accessor :port
+
+  # The version number of the MQTT protocol to use (default 3.1.0)
+  attr_accessor :version
 
   # Set to true to enable SSL/TLS encrypted communication
   #
   # Set to a symbol to use a specific variant of SSL/TLS.
-  # Allowed values include: 
-  # 
+  # Allowed values include:
+  #
   # @example Using TLS 1.0
   #    client = Client.new('mqtt.example.com', :ssl => :TLSv1)
   # @see OpenSSL::SSL::SSLContext::METHODS
   attr_accessor :ssl
 
-  # Time (in seconds) between pings to remote broker
+  # Time (in seconds) between pings to remote server (default is 15 seconds)
   attr_accessor :keep_alive
 
-  # Set the 'Clean Session' flag when connecting?
+  # Set the 'Clean Session' flag when connecting? (default is true)
   attr_accessor :clean_session
 
   # Client Identifier
   attr_accessor :client_id
 
-  # Number of seconds to wait for acknowledgement packets
+  # Number of seconds to wait for acknowledgement packets (default is 5 seconds)
   attr_accessor :ack_timeout
 
-  # Username to authenticate to the broker with
+  # Username to authenticate to the server with
   attr_accessor :username
 
-  # Password to authenticate to the broker with
+  # Password to authenticate to the server with
   attr_accessor :password
 
   # The topic that the Will message is published to
   attr_accessor :will_topic
 
-  # Contents of message that is sent by broker when client disconnect
+  # Contents of message that is sent by server when client disconnect
   attr_accessor :will_payload
 
-  # The QoS level of the will message sent by the broker
+  # The QoS level of the will message sent by the server
   attr_accessor :will_qos
 
-  # If the Will message should be retain by the broker after it is sent
+  # If the Will message should be retain by the server after it is sent
   attr_accessor :will_retain
 
 
@@ -56,8 +59,9 @@ class MQTT::Client
 
   # Default attribute values
   ATTR_DEFAULTS = {
-    :remote_host => nil,
-    :remote_port => nil,
+    :host => nil,
+    :port => nil,
+    :version => '3.1.0',
     :keep_alive => 15,
     :clean_session => true,
     :client_id => nil,
@@ -89,7 +93,7 @@ class MQTT::Client
 
   # Generate a random client identifier
   # (using the characters 0-9 and a-z)
-  def self.generate_client_id(prefix='ruby_', length=16)
+  def self.generate_client_id(prefix='ruby', length=16)
     str = prefix.dup
     length.times do
       num = rand(36)
@@ -113,7 +117,7 @@ class MQTT::Client
   # - a Hash containing attributes to be set on the new instance
   #
   # If no arguments are given then the method will look for a URI
-  # in the MQTT_BROKER environment variable.
+  # in the MQTT_SERVER environment variable.
   #
   # Examples:
   #  client = MQTT::Client.new
@@ -121,8 +125,8 @@ class MQTT::Client
   #  client = MQTT::Client.new('mqtt://user:pass@myserver.example.com')
   #  client = MQTT::Client.new('myserver.example.com')
   #  client = MQTT::Client.new('myserver.example.com', 18830)
-  #  client = MQTT::Client.new(:remote_host => 'myserver.example.com')
-  #  client = MQTT::Client.new(:remote_host => 'myserver.example.com', :keep_alive => 30)
+  #  client = MQTT::Client.new(:host => 'myserver.example.com')
+  #  client = MQTT::Client.new(:host => 'myserver.example.com', :keep_alive => 30)
   #
   def initialize(*args)
     if args.last.is_a?(Hash)
@@ -132,8 +136,8 @@ class MQTT::Client
     end
 
     if args.length == 0
-      if ENV['MQTT_BROKER']
-        attr.merge!(parse_uri(ENV['MQTT_BROKER']))
+      if ENV['MQTT_SERVER']
+        attr.merge!(parse_uri(ENV['MQTT_SERVER']))
       end
     end
 
@@ -144,12 +148,12 @@ class MQTT::Client
         when %r|^mqtts?://|
           attr.merge!(parse_uri(args[0]))
         else
-          attr.merge!(:remote_host => args[0])
+          attr.merge!(:host => args[0])
       end
     end
 
     if args.length >= 2
-      attr.merge!(:remote_port => args[1])
+      attr.merge!(:port => args[1]) unless args[1].nil?
     end
 
     if args.length >= 3
@@ -162,12 +166,12 @@ class MQTT::Client
     end
 
     # Set a default port number
-    if @remote_port.nil?
-      @remote_port = @ssl ? MQTT::DEFAULT_SSL_PORT : MQTT::DEFAULT_PORT
+    if @port.nil?
+      @port = @ssl ? MQTT::DEFAULT_SSL_PORT : MQTT::DEFAULT_PORT
     end
 
     # Initialise private instance variables
-    @message_id = 0
+    @packet_id = 0
     @last_pingreq = Time.now
     @last_pingresp = Time.now
     @socket = nil
@@ -201,8 +205,8 @@ class MQTT::Client
 
   # Set the Will for the client
   #
-  # The will is a message that will be delivered by the broker when the client dies.
-  # The Will must be set before establishing a connection to the broker
+  # The will is a message that will be delivered by the server when the client dies.
+  # The Will must be set before establishing a connection to the server
   def set_will(topic, payload, retain=false, qos=0)
     self.will_topic = topic
     self.will_payload = payload
@@ -210,7 +214,7 @@ class MQTT::Client
     self.will_qos = qos
   end
 
-  # Connect to the MQTT broker
+  # Connect to the MQTT server
   # If a block is given, then yield to that block and then disconnect again.
   def connect(clientid=nil)
     unless clientid.nil?
@@ -219,19 +223,22 @@ class MQTT::Client
 
     if @client_id.nil? or @client_id.empty?
       if @clean_session
-        @client_id = MQTT::Client.generate_client_id
+        if @version == '3.1.0'
+          # Empty client id is not allowed for version 3.1.0
+          @client_id = MQTT::Client.generate_client_id
+        end
       else
         raise 'Must provide a client_id if clean_session is set to false'
       end
     end
 
-    if @remote_host.nil?
-      raise 'No MQTT broker host set when attempting to connect'
+    if @host.nil?
+      raise 'No MQTT server host set when attempting to connect'
     end
 
     if not connected?
       # Create network socket
-      tcp_socket = TCPSocket.new(@remote_host, @remote_port)
+      tcp_socket = TCPSocket.new(@host, @port)
 
       if @ssl
         # Set the protocol version
@@ -246,8 +253,9 @@ class MQTT::Client
         @socket = tcp_socket
       end
 
-      # Protocol name and version
+      # Construct a connect packet
       packet = MQTT::Packet::Connect.new(
+        :version => @version,
         :clean_session => @clean_session,
         :keep_alive => @keep_alive,
         :client_id => @client_id,
@@ -281,8 +289,8 @@ class MQTT::Client
     end
   end
 
-  # Disconnect from the MQTT broker.
-  # If you don't want to say goodbye to the broker, set send_msg to false.
+  # Disconnect from the MQTT server.
+  # If you don't want to say goodbye to the server, set send_msg to false.
   def disconnect(send_msg=true)
     # Stop reading packets from the socket first
     @read_thread.kill if @read_thread and @read_thread.alive?
@@ -299,7 +307,7 @@ class MQTT::Client
     end
   end
 
-  # Checks whether the client is connected to the broker.
+  # Checks whether the client is connected to the server.
   def connected?
     (not @socket.nil?) and (not @socket.closed?)
   end
@@ -314,21 +322,24 @@ class MQTT::Client
     @last_pingreq = Time.now
   end
 
-  # Publish a message on a particular topic to the MQTT broker.
-  def publish(topic, payload, retain=false, qos=0)
+  # Publish a message on a particular topic to the MQTT server.
+  def publish(topic, payload='', retain=false, qos=0)
+    raise ArgumentError.new("Topic name cannot be nil") if topic.nil?
+    raise ArgumentError.new("Topic name cannot be empty") if topic.empty?
+
     packet = MQTT::Packet::Publish.new(
+      :id => @packet_id.next,
       :qos => qos,
       :retain => retain,
       :topic => topic,
-      :payload => payload,
-      :message_id => @message_id.next
+      :payload => payload
     )
 
     # Send the packet
     send_packet(packet)
   end
 
-  # Send a subscribe message for one or more topics on the MQTT broker.
+  # Send a subscribe message for one or more topics on the MQTT server.
   # The topics parameter should be one of the following:
   # * String: subscribe to one topic with QOS 0
   # * Array: subscribe to multiple topics with QOS 0
@@ -342,13 +353,13 @@ class MQTT::Client
   #
   def subscribe(*topics)
     packet = MQTT::Packet::Subscribe.new(
-      :topics => topics,
-      :message_id => @message_id.next
+      :id => @packet_id.next,
+      :topics => topics
     )
     send_packet(packet)
   end
 
-  # Return the next message received from the MQTT broker.
+  # Return the next message received from the MQTT server.
   # An optional topic can be given to subscribe to.
   #
   # The method either returns the topic and message as an array:
@@ -376,7 +387,7 @@ class MQTT::Client
     end
   end
 
-  # Return the next packet object received from the MQTT broker.
+  # Return the next packet object received from the MQTT server.
   # An optional topic can be given to subscribe to.
   #
   # The method either returns a single packet:
@@ -414,7 +425,7 @@ class MQTT::Client
     @read_queue.length
   end
 
-  # Send a unsubscribe message for one or more topics on the MQTT broker
+  # Send a unsubscribe message for one or more topics on the MQTT server
   def unsubscribe(*topics)
     if topics.is_a?(Enumerable) and topics.count == 1
       topics = topics.first
@@ -422,14 +433,14 @@ class MQTT::Client
 
     packet = MQTT::Packet::Unsubscribe.new(
       :topics => topics,
-      :message_id => @message_id.next
+      :id => @packet_id.next
     )
     send_packet(packet)
   end
 
 private
 
-  # Try to read a packet from the broker
+  # Try to read a packet from the server
   # Also sends keep-alive ping packets.
   def receive_packet
     begin
@@ -470,7 +481,9 @@ private
     Timeout.timeout(@ack_timeout) do
       packet = MQTT::Packet.read(@socket)
       if packet.class != MQTT::Packet::Connack
-        raise MQTT::ProtocolException.new("Response wan't a connection acknowledgement: #{packet.class}")
+        raise MQTT::ProtocolException.new(
+          "Response wasn't a connection acknowledgement: #{packet.class}"
+        )
       end
 
       # Check the return code
@@ -480,7 +493,7 @@ private
     end
   end
 
-  # Send a packet to broker
+  # Send a packet to server
   def send_packet(data)
     # Throw exception if we aren't connected
     raise MQTT::NotConnectedException if not connected?
@@ -503,12 +516,36 @@ private
     end
 
     {
-      :remote_host => uri.host,
-      :remote_port => uri.port || nil,
+      :host => uri.host,
+      :port => uri.port || nil,
       :username => uri.user,
       :password => uri.password,
       :ssl => ssl
     }
   end
 
+
+  # ---- Deprecated attributes and methods  ---- #
+  public
+
+  # @deprecated Please use {#host} instead
+  def remote_host
+    host
+  end
+
+  # @deprecated Please use {#host=} instead
+  def remote_host=(args)
+    self.host = args
+  end
+
+  # @deprecated Please use {#port} instead
+  def remote_port
+    port
+  end
+
+  # @deprecated Please use {#port=} instead
+  def remote_port=(args)
+    self.port = args
+  end
+
 end