mqtt 0.0.5 → 0.0.7

data/README

@@ -1,16 +1,18 @@
 ruby-mqtt
 =========
 
-Pure Ruby gem that implements the MQTT (Message Queue Telemetry Transport) protocol, a lightweight protocol for publish/subscribe messaging.
+Pure Ruby gem that implements the MQTT (Message Queue Telemetry Transport) protocol,
+a lightweight protocol for publish/subscribe messaging.
 
 
 Installing
 ----------
 
-You may get the latest stable version from Rubyforge. Source gems are also available.
+You may get the latest stable version from Rubygems:
 
     $ gem install mqtt
 
+
 Synopsis
 --------
 
@@ -18,37 +20,22 @@ Synopsis
     require 'mqtt'
     
     # Publish example
-    mqtt = MQTT::Client.new('mqtt.example.com')
-    mqtt.connect do |c|
-      c.publish('topic','message')
+    MQTT::Client.connect('test.mosquitto.org') do |c|
+      c.publish('topic', 'message')
     end
     
     # Subscribe example
-    mqtt = MQTT::Client.new('mqtt.example.com')
-    client.connect do
-      client.subscribe('test')
-      loop do
-        topic,message = client.get
+    MQTT::Client.connect('test.mosquitto.org') do |c|
+      c.get('test') do |topic,message|
         puts "#{topic}: #{message}"
       end
     end
 
 
-TODO
-----
+Limitations
+-----------
 
-* Implement Will and Testament
-* Process acknowledgement packets / Implement QOS 1 in client
-* More validations of data/parameters
-* More error checking and exception throwing
-  - Check that packet data is valid - don't blindly read values
-  - Subscribe and Unsubscribe packets should always have QOS of 1
-* More examples
-* Integration tests
-* Refactor to add callbacks that are called from seperate thread
-* Implement QOS Level 2 in client
-* Prevent proxy from connecting to itself
-* Add support for binding socket to specific local address
+ * Only QOS 0 currently supported
 
 
 Resources
@@ -56,7 +43,7 @@ Resources
 
 * MQTT Homepage: http://www.mqtt.org/
 * GitHub Project: http://github.com/njh/ruby-mqtt
-* Documentation: http://rdoc.info/github/njh/ruby-mqtt/master/frames
+* API Documentation: http://rubydoc.info/gems/mqtt/frames
 
 
 Contact

data/lib/mqtt.rb

@@ -17,7 +17,7 @@ module MQTT
 
   class ProtocolException < MQTT::Exception
   end
-  
+
   class NotConnectedException < MQTT::Exception
   end
 

data/lib/mqtt/client.rb

@@ -16,23 +16,67 @@ class MQTT::Client
   # Timeout between select polls (in seconds)
   SELECT_TIMEOUT = 0.5
 
+  # Default attribute values
+  ATTR_DEFAULTS = {
+    :remote_host => MQTT::DEFAULT_HOST,
+    :remote_port => MQTT::DEFAULT_PORT,
+    :keep_alive => 15,
+    :clean_session => true,
+    :client_id => nil,
+    :ack_timeout => 5,
+    :username => nil,
+    :password => nil
+  }
+
+  # Create and connect a new MQTT Client
+  # Accepts the same arguments as creating a new client.
+  # If a block is given, then it will be executed before disconnecting again.
+  #
+  # Example:
+  #  MQTT::Client.connect('myserver.example.com') do |client|
+  #    # do stuff here
+  #  end
+  #
+  def self.connect(*args, &block)
+    client = MQTT::Client.new(*args)
+    client.connect(&block)
+    return client
+  end
+
   # Create a new MQTT Client instance
-  def initialize(remote_host=MQTT::DEFAULT_HOST, remote_port=MQTT::DEFAULT_PORT)
-    @remote_host = remote_host
-    @remote_port = remote_port
-    @keep_alive = 10
-    @clean_session = true
-    @client_id = nil
+  #
+  # Examples:
+  #  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)
+  #
+  def initialize(*args)
+    if args.count == 0
+      args = {}
+    elsif args.count == 1 and args[0].is_a?(Hash)
+      args = args[0]
+    elsif args.count == 1
+      args = {:remote_host => args[0]}
+    elsif args.count == 2
+      args = {:remote_host => args[0], :remote_port => args[1]}
+    else
+      raise ArgumentError, "Unsupported number of arguments"
+    end
+
+    # Merge arguments with default values for attributes
+    ATTR_DEFAULTS.merge(args).each_pair do |k,v|
+      instance_variable_set("@#{k}", v)
+    end
+
+    # Initialise private instance variables
     @message_id = 0
-    @ack_timeout = 5
     @last_pingreq = Time.now
     @last_pingresp = Time.now
     @socket = nil
     @read_queue = Queue.new
     @read_thread = nil
     @write_semaphore = Mutex.new
-    @username = nil
-    @password = nil
   end
 
   # Connect to the MQTT broker
@@ -40,7 +84,7 @@ class MQTT::Client
   def connect(clientid=nil)
     if !clientid.nil?
       @client_id = clientid
-    elsif clientid.nil?
+    elsif @clientid.nil?
       @client_id = random_letters(16)
       @clean_session = true
     end
@@ -140,17 +184,31 @@ class MQTT::Client
   end
 
   # Return the next message recieved from the MQTT broker.
-  # This method blocks until a message is available.
+  # An optional topic can be given to subscribe to.
   #
-  # The method returns the topic and message as an array:
+  # The method either returns the topic and message as an array:
   #   topic,message = client.get
   #
-  def get
-    # Wait for a packet to be available
-    packet = @read_queue.pop
-    topic = packet.topic
-    payload = packet.payload
-    return topic,payload
+  # Or can be used with a block to keep processing messages:
+  #   client.get('test') do |topic,payload|
+  #     # Do stuff here
+  #   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
+        yield(packet.topic, packet.payload)
+      end
+    else
+      # Wait for one packet to be available
+      packet = @read_queue.pop
+      return packet.topic, packet.payload
+    end
   end
 
   # Send a unsubscribe message for one or more topics on the MQTT broker

data/lib/mqtt/version.rb

@@ -1,3 +1,3 @@
 module MQTT
-  VERSION = "0.0.5"
+  VERSION = "0.0.7"
 end

data/spec/mqtt_client_spec.rb

@@ -9,45 +9,98 @@ describe MQTT::Client do
     @client = MQTT::Client.new
     @socket = StringIO.new
   end
-  
+
+  describe "initializing a client" do
+    it "with no arguments, it should use the defaults" do
+      @client = MQTT::Client.new
+      @client.remote_host.should == 'localhost'
+      @client.remote_port.should == 1883
+      @client.keep_alive.should == 15
+    end
+
+    it "with a single string argument, it should use it has the host" do
+      @client = MQTT::Client.new('otherhost.mqtt.org')
+      @client.remote_host.should == 'otherhost.mqtt.org'
+      @client.remote_port.should == 1883
+      @client.keep_alive.should == 15
+    end
+
+    it "with two arguments, it should use it as the host and port" do
+      @client = MQTT::Client.new('otherhost.mqtt.org', 1000)
+      @client.remote_host.should == 'otherhost.mqtt.org'
+      @client.remote_port.should == 1000
+      @client.keep_alive.should == 15
+    end
+
+    it "with names arguments, it should use those as arguments" do
+      @client = MQTT::Client.new(:remote_host => 'otherhost.mqtt.org', :remote_port => 1000)
+      @client.remote_host.should == 'otherhost.mqtt.org'
+      @client.remote_port.should == 1000
+      @client.keep_alive.should == 15
+    end
+
+    it "with a hash, it should use those as arguments" do
+      @client = MQTT::Client.new({:remote_host => 'otherhost.mqtt.org', :remote_port => 1000})
+      @client.remote_host.should == 'otherhost.mqtt.org'
+      @client.remote_port.should == 1000
+      @client.keep_alive.should == 15
+    end
+
+    it "with a hash containing just a keep alive setting" do
+      @client = MQTT::Client.new(:keep_alive => 60)
+      @client.remote_host.should == 'localhost'
+      @client.remote_port.should == 1883
+      @client.keep_alive.should == 60
+    end
+
+    it "with three arguments" do
+      lambda {
+        @client = MQTT::Client.new(1, 2, 3)
+      }.should raise_error(
+        'Unsupported number of arguments'
+      )
+    end
+  end
+
+
   describe "when calling the 'connect' method" do
     before(:each) do
       TCPSocket.stubs(:new).returns(@socket)
       Thread.stubs(:new)
       @client.stubs(:receive_connack)
     end
-    
+
     it "should create a TCP Socket if not connected" do
       TCPSocket.expects(:new).once.returns(@socket)
       @client.connect('myclient')
     end
-    
+
     it "should not create a new TCP Socket if connected" do
       @client.stubs(:connected?).returns(true)
       TCPSocket.expects(:new).never
       @client.connect('myclient')
     end
-    
+
     it "should start the reader thread if not connected" do
       Thread.expects(:new).once
       @client.connect('myclient')
     end
-    
+
     it "should write a valid CONNECT packet to the socket if not connected" do
       @client.connect('myclient')
-      @socket.string.should == "\020\026\x00\x06MQIsdp\x03\x02\x00\x0a\x00\x08myclient"
+      @socket.string.should == "\020\026\x00\x06MQIsdp\x03\x02\x00\x0f\x00\x08myclient"
     end
-    
+
     it "should try and read an acknowledgement packet to the socket if not connected" do
       @client.expects(:receive_connack).once
       @client.connect('myclient')
     end
-    
+
     it "should disconnect after connecting, if a block is given" do
       @client.expects(:disconnect).once
       @client.connect('myclient') { nil }
     end
-    
+
     it "should not disconnect after connecting, if no block is given" do
       @client.expects(:disconnect).never
       @client.connect('myclient')
@@ -60,8 +113,8 @@ describe MQTT::Client do
       @socket.string.should ==
         "\x10\x2A"+
         "\x00\x06MQIsdp"+
-        "\x03\xC2\x00\x0a\x00"+
-        "\x08myclient"+
+        "\x03\xC2\x00\x0f"+
+        "\x00\x08myclient"+
         "\x00\x08username"+
         "\x00\x08password"
     end
@@ -79,74 +132,74 @@ describe MQTT::Client do
       @client.instance_variable_set(:@socket, @socket)
       IO.stubs(:select).returns([[@socket], [], []])
     end
-    
+
     it "should not throw an exception for a successful CONNACK packet" do
       @socket.write("\x20\x02\x00\x00")
       @socket.rewind
       lambda { @client.send(:receive_connack) }.should_not raise_error
     end
-    
+
     it "should throw an exception if the packet type isn't CONNACK" do
       @socket.write("\xD0\x00")
       @socket.rewind
       lambda { @client.send(:receive_connack) }.should raise_error(MQTT::ProtocolException)
     end
-    
+
     it "should throw an exception if the CONNACK packet return code is 'unacceptable protocol version'" do
       @socket.write("\x20\x02\x00\x01")
       @socket.rewind
       lambda { @client.send(:receive_connack) }.should raise_error(MQTT::ProtocolException, /unacceptable protocol version/i)
     end
-    
+
     it "should throw an exception if the CONNACK packet return code is 'client identifier rejected'" do
       @socket.write("\x20\x02\x00\x02")
       @socket.rewind
       lambda { @client.send(:receive_connack) }.should raise_error(MQTT::ProtocolException, /client identifier rejected/i)
     end
-    
+
     it "should throw an exception if the CONNACK packet return code is 'broker unavailable'" do
       @socket.write("\x20\x02\x00\x03")
       @socket.rewind
       lambda { @client.send(:receive_connack) }.should raise_error(MQTT::ProtocolException, /broker unavailable/i)
     end
-    
+
     it "should throw an exception if the CONNACK packet return code is an unknown" do
       @socket.write("\x20\x02\x00\xAA")
       @socket.rewind
       lambda { @client.send(:receive_connack) }.should raise_error(MQTT::ProtocolException, /connection refused/i)
     end
   end
-  
+
   describe "when calling the 'disconnect' method" do
     before(:each) do
       @client.instance_variable_set(:@socket, @socket)
       @client.instance_variable_set(:@read_thread, stub_everything('Read Thread'))
     end
-  
+
     it "should not do anything if the socket is already disconnected" do
       @client.stubs(:connected?).returns(false)
       @client.disconnect(true)
       @socket.string.should == ""
     end
-  
+
     it "should write a valid DISCONNECT packet to the socket if connected and the send_msg=true an" do
       @client.stubs(:connected?).returns(true)
       @client.disconnect(true)
       @socket.string.should == "\xE0\x00"
     end
-    
+
     it "should not write anything to the socket if the send_msg=false" do
       @client.stubs(:connected?).returns(true)
       @client.disconnect(false)
       @socket.string.should be_empty
     end
-    
+
     it "should call the close method on the socket" do
       @socket.expects(:close)
       @client.disconnect
     end
   end
-  
+
   describe "when calling the 'ping' method" do
     before(:each) do
       @client.instance_variable_set(:@socket, @socket)
@@ -163,7 +216,7 @@ describe MQTT::Client do
       @client.instance_variable_get(:@last_pingreq).should_not == 0
     end
   end
-  
+
   describe "when calling the 'publish' method" do
     before(:each) do
       @client.instance_variable_set(:@socket, @socket)
@@ -173,17 +226,17 @@ describe MQTT::Client do
       @client.publish('topic','payload', false, 0)
       @socket.string.should == "\x30\x0e\x00\x05topicpayload"
     end
-    
+
     it "should write a valid PUBLISH packet to the socket with the retain flag set" do
       @client.publish('topic','payload', true, 0)
       @socket.string.should == "\x31\x0e\x00\x05topicpayload"
     end
-    
+
     it "should write a valid PUBLISH packet to the socket with the QOS set to 1" do
       @client.publish('topic','payload', false, 1)
       @socket.string.should == "\x32\x10\x00\x05topic\x00\x01payload"
     end
-    
+
     it "should write a valid PUBLISH packet to the socket with the QOS set to 2" do
       @client.publish('topic','payload', false, 2)
       @socket.string.should == "\x34\x10\x00\x05topic\x00\x01payload"
@@ -250,13 +303,13 @@ describe MQTT::Client do
       @client.unsubscribe('a/b')
       @socket.string.should == "\xa2\x07\x00\x01\x00\x03a/b"
     end
-    
+
     it "should write a valid UNSUBSCRIBE packet to the socket if given a two topic Strings" do
       @client.unsubscribe('a/b','c/d')
       @socket.string.should == "\xa2\x0c\x00\x01\x00\x03a/b\x00\x03c/d"
     end
   end
-  
+
   describe "when calling the 'receive_packet' method" do
     before(:each) do
       @client.instance_variable_set(:@socket, @socket)
@@ -278,7 +331,7 @@ describe MQTT::Client do
       @client.send(:receive_packet)
       @read_queue.size.should == 0
     end
-    
+
     it "should send a ping packet if one is due" do
       IO.expects(:select).returns(nil)
       @client.instance_variable_set(:@last_pingreq, Time.at(0))
@@ -297,7 +350,7 @@ describe MQTT::Client do
       MQTT::Packet.stubs(:read).raises(MQTT::Exception)
       @client.send(:receive_packet)
     end
-    
+
   end
-  
+
 end

data/spec/mqtt_proxy_spec.rb

@@ -4,5 +4,5 @@ require 'spec_helper'
 require 'mqtt'
 
 describe MQTT::Proxy do
-  
+
 end

data/spec/mqtt_version_spec.rb

@@ -13,11 +13,11 @@ describe MQTT do
     it "should be a string" do
       MQTT::VERSION.should be_a(String)
     end
- 
+
     it "should be in the format x.y.z" do
       MQTT::VERSION.should =~ /^\d{1,2}\.\d{1,2}\.\d{1,2}$/
     end
-  
-  end   
+
+  end
 
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: mqtt
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 17
   prerelease: false
   segments: 
   - 0
   - 0
-  - 5
-  version: 0.0.5
+  - 7
+  version: 0.0.7
 platform: ruby
 authors: 
 - Nicholas J Humfrey
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-01-17 00:00:00 +00:00
+date: 2012-01-19 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency