mqtt 0.3.1 → 0.4.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    Y2MwODVmNmViNWEyM2ViM2NkMDk1ODIzNzg3ZGJiM2EyYTdlZTJlMw==
+  data.tar.gz: !binary |-
+    OWI1ZGM5Yzk4OWZiZDBkMDY5ZDM5NTllMWQ3YzRhYTk3NThmNDY3Ng==
+SHA512:
+  metadata.gz: !binary |-
+    NDg1ZTMxZTdkNjM2ZDk2ZmU0ZGRiYzcyNWI0ZDk1MWI1MGU3OTRmMmI3Yzkx
+    NmRiYzQ0NmE3NDlhNDQ1MDExNmY2OGM2NzNjYWNlMTAwODc0NDRiNzM3MDU1
+    YWYxYTYyNDdmZTUxNjI2YjM2ODU2ZTgxMGVhNjM1NjAwOWViY2I=
+  data.tar.gz: !binary |-
+    YzkwNjYyYzYxODgyYzZjZWU2MGZhMzQ0YWZhNWM3MTVhNzdjNTFjMjEzYWFj
+    OGMzN2NlYjNmYTdjYzVmODNhZDZmZGIzMDg4ZjBjYmY5MzljNzRlODljMjI0
+    NTI3OGRmZDhhODA0NDA2NDI5ZTBlYzhjZWE3MWJhNGQwYzE4OWQ=

data/NEWS.md

@@ -1,6 +1,19 @@
 Ruby MQTT NEWS
 ==============
 
+Ruby MQTT Version 0.4.0 (2016-06-27)
+------------------------------------
+
+* Added puback handling for QoS level 1
+* Low-level MQTT-SN packet parsing support
+* Allow certs to be set directly instead of just by file
+* Allow keyphrase for certs to be passed through
+* Put 'disconnect' inside an 'ensure' block
+* Fix for error on publish with frozen payload
+* Fix for packets always getting id 1
+* Improvements to tests
+
+
 Ruby MQTT Version 0.3.1 (2014-10-10)
 ------------------------------------
 

data/README.md

@@ -5,6 +5,8 @@ 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
 -----------------
@@ -31,22 +33,23 @@ Alternatively, to use a development snapshot from GitHub using [Bundler]:
 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
+~~~ ruby
+require 'rubygems'
+require 'mqtt'
 
+# Publish example
+MQTT::Client.connect('test.mosquitto.org') do |c|
+  c.publish('test', '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
@@ -56,42 +59,52 @@ Library Overview
 
 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 ... )
+~~~ ruby
+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
-    )
+~~~ ruby
+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()
+~~~ ruby
+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()
+~~~ ruby
+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
-    
+~~~ ruby
+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.
 
 
@@ -99,7 +112,9 @@ For more information, see and list of attributes for the [MQTT::Client] class an
 
 To send a message to a topic, use the ```publish``` method:
 
-    client.publish(topic, payload, retain=false)
+~~~ ruby
+client.publish(topic, payload, retain=false)
+~~~
 
 The method will return once the message has been sent to the MQTT server.
 
@@ -110,9 +125,11 @@ 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/#' )
+~~~ ruby
+client.subscribe( 'topic1' )
+client.subscribe( 'topic1', 'topic2' )
+client.subscribe( 'foo/#' )
+~~~
 
 For more information see the [MQTT::Client#subscribe] method.
 
@@ -121,23 +138,52 @@ 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
+~~~ ruby
+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
+~~~ ruby
+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.
+
+~~~ ruby
+# 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
+ * QoS 2 is not currently supported by client
  * Automatic re-connects to the server are not supported
+ * No local persistence for packets
 
 
 Resources
@@ -146,6 +192,7 @@ 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-SN Protocol Specification v1.2: http://mqtt.org/new/wp-content/uploads/2009/06/MQTT-SN_spec_v1.2.pdf
 * MQTT Homepage: http://www.mqtt.org/
 * GitHub Project: http://github.com/njh/ruby-mqtt
 
@@ -153,7 +200,7 @@ Resources
 License
 -------
 
-The ruby-mqtt gem is licensed under the terms of the MIT license.
+The mqtt ruby gem is licensed under the terms of the MIT license.
 See the file LICENSE for details.
 
 
@@ -162,11 +209,14 @@ Contact
 
 * Author:    Nicholas J Humfrey
 * Email:     njh@aelius.com
+* Twitter:   [@njh]
 * Home Page: http://www.aelius.com/njh/
 
 
 
+[@njh]:           http://twitter.com/njh
 [MQTT]:           http://www.mqtt.org/
+[MQTT-SN]:        http://mqtt.org/2013/12/mqtt-for-sensor-networks-mqtt-sn
 [Rubygems]:       http://rubygems.org/
 [Bundler]:        http://bundler.io/
 [MQTT URI]:       https://github.com/mqtt/mqtt.github.io/wiki/URI-Scheme

data/lib/mqtt.rb

@@ -21,7 +21,7 @@ module MQTT
   DEFAULT_SSL_PORT = 8883
 
   # Super-class for other MQTT related exceptions
-  class Exception < Exception
+  class Exception < ::Exception
   end
 
   # A ProtocolException will be raised if there is a
@@ -39,4 +39,17 @@ module MQTT
   autoload :Packet,   'mqtt/packet'
   autoload :Proxy,    'mqtt/proxy'
 
+  # MQTT-SN
+  module SN
+
+    # Default port number for unencrypted connections
+    DEFAULT_PORT = 1883
+
+    # A ProtocolException will be raised if there is a
+    # problem with data received from a remote host
+    class ProtocolException < MQTT::Exception
+    end
+
+    autoload :Packet,   'mqtt/sn/packet'
+  end
 end

data/lib/mqtt/client.rb

@@ -53,7 +53,7 @@ class MQTT::Client
   # If the Will message should be retain by the server after it is sent
   attr_accessor :will_retain
 
-  #Last ping response time
+  # Last ping response time
   attr_reader :last_ping_response
 
 
@@ -174,13 +174,14 @@ class MQTT::Client
     end
 
     # Initialise private instance variables
-    @packet_id = 0
-    @last_pingreq = Time.now
+    @last_ping_request = Time.now
     @last_ping_response = Time.now
     @socket = nil
     @read_queue = Queue.new
+    @pubacks = {}
     @read_thread = nil
     @write_semaphore = Mutex.new
+    @pubacks_semaphore = Mutex.new
   end
 
   # Get the OpenSSL context, that is used if SSL/TLS is enabled
@@ -190,12 +191,24 @@ class MQTT::Client
 
   # Set a path to a file containing a PEM-format client certificate
   def cert_file=(path)
-    ssl_context.cert = OpenSSL::X509::Certificate.new(File.open(path))
+    self.cert = File.read(path)
+  end
+
+  # PEM-format client certificate
+  def cert=(cert)
+    ssl_context.cert = OpenSSL::X509::Certificate.new(cert)
   end
 
   # Set a path to a file containing a PEM-format client private key
-  def key_file=(path)
-    ssl_context.key = OpenSSL::PKey::RSA.new(File.open(path))
+  def key_file=(*args)
+    path, passphrase = args.flatten
+    ssl_context.key = OpenSSL::PKey::RSA.new(File.open(path), passphrase)
+  end
+
+  # Set to a PEM-format client private key
+  def key=(*args)
+    cert, passphrase = args.flatten
+    ssl_context.key = OpenSSL::PKey::RSA.new(cert, passphrase)
   end
 
   # Set a path to a file containing a PEM-format CA certificate and enable peer verification
@@ -287,8 +300,11 @@ class MQTT::Client
 
     # If a block is given, then yield and disconnect
     if block_given?
-      yield(self)
-      disconnect
+      begin
+        yield(self)
+      ensure
+        disconnect
+      end
     end
   end
 
@@ -315,23 +331,13 @@ class MQTT::Client
     (not @socket.nil?) and (not @socket.closed?)
   end
 
-  # Send a MQTT ping message to indicate that the MQTT client is alive.
-  #
-  # Note that you will not normally need to call this method
-  # as it is called automatically
-  def ping
-    packet = MQTT::Packet::Pingreq.new
-    send_packet(packet)
-    @last_pingreq = Time.now
-  end
-
   # 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,
+      :id => next_packet_id,
       :qos => qos,
       :retain => retain,
       :topic => topic,
@@ -339,14 +345,28 @@ class MQTT::Client
     )
 
     # Send the packet
-    send_packet(packet)
+    res = send_packet(packet)
+
+    if packet.qos > 0
+      Timeout.timeout(@ack_timeout) do
+        while connected? do
+          @pubacks_semaphore.synchronize do
+            return res if @pubacks.delete(packet.id)
+          end
+          # FIXME: make threads communicate with each other, instead of polling
+          # (using a pipe and select ?)
+          sleep 0.01
+        end
+      end
+      return -1
+    end
   end
 
   # 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
-  # * Hash: subscribe to multiple topics where the key is the topic and the value is the QOS level
+  # * String: subscribe to one topic with QoS 0
+  # * Array: subscribe to multiple topics with QoS 0
+  # * Hash: subscribe to multiple topics where the key is the topic and the value is the QoS level
   #
   # For example:
   #   client.subscribe( 'a/b' )
@@ -356,7 +376,7 @@ class MQTT::Client
   #
   def subscribe(*topics)
     packet = MQTT::Packet::Subscribe.new(
-      :id => @packet_id.next,
+      :id => next_packet_id,
       :topics => topics
     )
     send_packet(packet)
@@ -374,18 +394,13 @@ class MQTT::Client
   #   end
   #
   def get(topic=nil)
-    # Subscribe to a topic, if an argument is given
-    subscribe(topic) unless topic.nil?
-
     if block_given?
-      # Loop forever!
-      loop do
-        packet = @read_queue.pop
+      get_packet(topic) do |packet|
         yield(packet.topic, packet.payload)
       end
     else
       # Wait for one packet to be available
-      packet = @read_queue.pop
+      packet = get_packet(topic)
       return packet.topic, packet.payload
     end
   end
@@ -410,11 +425,15 @@ class MQTT::Client
     if block_given?
       # Loop forever!
       loop do
-        yield(@read_queue.pop)
+        packet = @read_queue.pop
+        yield(packet)
+        puback_packet(packet) if packet.qos > 0
       end
     else
       # Wait for one packet to be available
-      return @read_queue.pop
+      packet = @read_queue.pop
+      puback_packet(packet) if packet.qos > 0
+      return packet
     end
   end
 
@@ -436,7 +455,7 @@ class MQTT::Client
 
     packet = MQTT::Packet::Unsubscribe.new(
       :topics => topics,
-      :id => @packet_id.next
+      :id => next_packet_id
     )
     send_packet(packet)
   end
@@ -452,25 +471,9 @@ private
       unless result.nil?
         # Yes - read in the packet
         packet = MQTT::Packet.read(@socket)
-        if packet.class == MQTT::Packet::Publish
-          # Add to queue
-          @read_queue.push(packet)
-        elsif packet.class == MQTT::Packet::Pingresp
-          @last_ping_response = Time.now
-        else
-          # Ignore all other packets
-          nil
-          # FIXME: implement responses for QOS 1 and 2
-        end
-      end
-
-      # Time to send a keep-alive ping request?
-      if @keep_alive > 0 and Time.now > @last_pingreq + @keep_alive
-        ping
+        handle_packet packet
       end
-
-      # FIXME: check we received a ping response recently?
-
+      keep_alive!
     # Pass exceptions up to parent thread
     rescue Exception => exp
       unless @socket.nil?
@@ -481,6 +484,40 @@ private
     end
   end
 
+  def handle_packet(packet)
+    if packet.class == MQTT::Packet::Publish
+      # Add to queue
+      @read_queue.push(packet)
+    elsif packet.class == MQTT::Packet::Pingresp
+      @last_ping_response = Time.now
+    elsif packet.class == MQTT::Packet::Puback
+      @pubacks_semaphore.synchronize do
+        @pubacks[packet.id] = packet
+      end
+    end
+    # Ignore all other packets
+    # FIXME: implement responses for QoS  2
+  end
+
+  def keep_alive!
+    if @keep_alive > 0
+      response_timeout = (@keep_alive * 1.5).ceil
+      if Time.now >= @last_ping_request + @keep_alive
+        packet = MQTT::Packet::Pingreq.new
+        send_packet(packet)
+        @last_ping_request = Time.now
+      elsif Time.now > @last_ping_response + response_timeout
+        raise MQTT::ProtocolException.new(
+          "No Ping Response received for #{response_timeout} seconds"
+        )
+      end
+    end
+  end
+
+  def puback_packet(packet)
+    send_packet(MQTT::Packet::Puback.new :id => packet.id)
+  end
+
   # Read and check a connection acknowledgement packet
   def receive_connack
     Timeout.timeout(@ack_timeout) do
@@ -500,7 +537,7 @@ private
 
   # Send a packet to server
   def send_packet(data)
-    # Throw exception if we aren't connected
+    # Raise exception if we aren't connected
     raise MQTT::NotConnectedException if not connected?
 
     # Only allow one thread to write to socket at a time
@@ -529,6 +566,9 @@ private
     }
   end
 
+  def next_packet_id
+    @last_packet_id = ( @last_packet_id || 0 ).next
+  end
 
   # ---- Deprecated attributes and methods  ---- #
   public