mqtt 0.0.7 → 0.0.8

data/NEWS

@@ -1,6 +1,30 @@
 Ruby MQTT NEWS
 ==============
 
+Ruby MQTT Version 0.0.8 (2011-02-04)
+------------------------------------
+
+* Implemented Last Will and Testament feature.
+* Renamed dup attribute to duplicate to avoid method name clash.
+* Made the random client_id generator a public class method.
+
+
+Ruby MQTT Version 0.0.7 (2011-01-19)
+------------------------------------
+
+* You can now pass a topic and block to client.get
+* Added MQTT::Client.connect class method.
+
+
+Ruby MQTT Version 0.0.5 (2011-01-18)
+------------------------------------
+
+* Implemented setting username and password (MQTT 3.1)
+* Renamed clean_start to clean_session
+* Started using autoload to load classes
+* Modernised Gem building mechanisms
+
+
 Ruby MQTT Version 0.0.4 (2009-02-22)
 ------------------------------------
 

data/README

@@ -26,6 +26,7 @@ Synopsis
     
     # 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

data/lib/mqtt/client.rb

@@ -8,6 +8,10 @@ class MQTT::Client
   attr_accessor :ack_timeout   # Number of seconds to wait for acknowledgement packets
   attr_accessor :username      # Username to authenticate to the broker with
   attr_accessor :password      # Password to authenticate to the broker with
+  attr_accessor :will_topic    # The topic that the Will message is published to
+  attr_accessor :will_payload  # Contents of message that is sent by broker when client disconnect
+  attr_accessor :will_qos      # The QoS level of the will message sent by the broker
+  attr_accessor :will_retain   # If the Will message should be retain by the broker after it is sent
 
   # OLD deprecated clean_start
   alias :clean_start :clean_session
@@ -25,7 +29,11 @@ class MQTT::Client
     :client_id => nil,
     :ack_timeout => 5,
     :username => nil,
-    :password => nil
+    :password => nil,
+    :will_topic => nil,
+    :will_payload => nil,
+    :will_qos => 0,
+    :will_retain => false
   }
 
   # Create and connect a new MQTT Client
@@ -43,6 +51,24 @@ class MQTT::Client
     return client
   end
 
+  # Generate a random client identifier
+  # (using the characters 0-9 and a-z)
+  def self.generate_client_id(prefix='ruby_', length=16)
+    str = prefix.dup
+    length.times do
+      num = rand(36)
+      if (num<10)
+        # Number
+        num += 48
+      else
+        # Letter
+        num += 87
+      end
+      str += num.chr
+    end
+    return str
+  end
+
   # Create a new MQTT Client instance
   #
   # Examples:
@@ -79,13 +105,20 @@ class MQTT::Client
     @write_semaphore = Mutex.new
   end
 
+  def set_will(topic, payload, retain=false, qos=0)
+    self.will_topic = topic
+    self.will_payload = payload
+    self.will_retain = retain
+    self.will_qos = qos
+  end
+
   # Connect to the MQTT broker
   # If a block is given, then yield to that block and then disconnect again.
   def connect(clientid=nil)
     if !clientid.nil?
       @client_id = clientid
     elsif @clientid.nil?
-      @client_id = random_letters(16)
+      @client_id = MQTT::Client.generate_client_id
       @clean_session = true
     end
 
@@ -99,7 +132,11 @@ class MQTT::Client
         :keep_alive => @keep_alive,
         :client_id => @client_id,
         :username => @username,
-        :password => @password
+        :password => @password,
+        :will_topic => @will_topic,
+        :will_payload => @will_payload,
+        :will_qos => @will_qos,
+        :will_retain => @will_retain
       )
 
       # Send packet
@@ -284,21 +321,4 @@ private
     end
   end
 
-  # Generate a string of random letters (0-9,a-z)
-  def random_letters(count)
-    str = ''
-    count.times do
-      num = rand(36)
-      if (num<10)
-        # Number
-        num += 48
-      else
-        # Letter
-        num += 87
-      end
-      str += num.chr
-    end
-    return str
-  end
-
 end

data/lib/mqtt/packet.rb

@@ -3,12 +3,19 @@ module MQTT
   # Class representing a MQTT Packet
   # Performs binary encoding and decoding of headers
   class MQTT::Packet
-    attr_reader :dup         # Duplicate delivery flag
+    attr_reader :duplicate   # Duplicate delivery flag
     attr_reader :retain      # Retain flag
     attr_reader :qos         # Quality of Service level
     attr_reader :body_length # The length of the parsed packet body
 
-    # Deprecate this: Read in a packet from a socket
+    DEFAULTS = {
+      :duplicate => false,
+      :qos => 0,
+      :retain => false,
+      :body_length => nil
+    }
+
+    # Read in a packet from a socket
     def self.read(socket)
       # Read in the packet header and work out the class
       header = read_byte(socket)
@@ -17,7 +24,7 @@ module MQTT
 
       # Create a new packet object
       packet = packet_class.new(
-        :dup => ((header & 0x08) >> 3),
+        :duplicate => ((header & 0x08) >> 3),
         :qos => ((header & 0x06) >> 1),
         :retain => ((header & 0x01) >> 0)
       )
@@ -60,7 +67,7 @@ module MQTT
 
       # Create a new packet object
       packet = packet_class.new(
-        :dup => ((buffer[0] & 0x08) >> 3) == 0x01,
+        :duplicate => ((buffer[0] & 0x08) >> 3) == 0x01,
         :qos => ((buffer[0] & 0x06) >> 1),
         :retain => ((buffer[0] & 0x01) >> 0) == 0x01
       )
@@ -91,12 +98,7 @@ module MQTT
 
     # Create a new empty packet
     def initialize(args={})
-      update_attributes({
-        :dup => false,
-        :qos => 0,
-        :retain => false,
-        :body_length => nil
-      }.merge(args))
+      update_attributes(DEFAULTS.merge(args))
     end
 
     def update_attributes(attr={})
@@ -115,11 +117,11 @@ module MQTT
     end
 
     # Set the dup flag (true/false)
-    def dup=(arg)
+    def duplicate=(arg)
       if arg.kind_of?(Integer)
-        @dup = (arg != 0)
+        @duplicate = (arg != 0)
       else
-        @dup = arg
+        @duplicate = arg
       end
     end
 
@@ -162,7 +164,7 @@ module MQTT
       # Encode the fixed header
       header = [
         ((type_id.to_i & 0x0F) << 4) |
-        ((dup ? 0x1 : 0x0) << 3) |
+        ((duplicate ? 0x1 : 0x0) << 3) |
         ((qos.to_i & 0x03) << 1) |
         (retain ? 0x1 : 0x0)
       ]
@@ -249,13 +251,15 @@ module MQTT
       attr_accessor :message_id
       attr_accessor :payload
 
-      # Create a new Publish packet
-      def initialize(args={})
-        super({
+      DEFAULTS = {
           :topic => nil,
           :message_id => 0,
           :payload => ''
-        }.merge(args))
+      }
+
+      # Create a new Publish packet
+      def initialize(args={})
+        super(DEFAULTS.merge(args))
       end
 
       # Get serialisation of packet's body
@@ -297,21 +301,23 @@ module MQTT
       alias :clean_start :clean_session
       alias :clean_start= :clean_session=
 
+      DEFAULTS = {
+        :protocol_name => 'MQIsdp',
+        :protocol_version => 0x03,
+        :client_id => nil,
+        :clean_session => true,
+        :keep_alive => 15,
+        :will_topic => nil,
+        :will_qos => 0,
+        :will_retain => false,
+        :will_payload => '',
+        :username => nil,
+        :password => nil,
+      }
+
       # Create a new Client Connect packet
       def initialize(args={})
-        super({
-          :protocol_name => 'MQIsdp',
-          :protocol_version => 0x03,
-          :client_id => nil,
-          :clean_session => true,
-          :keep_alive => 10,
-          :will_topic => nil,
-          :will_qos => 0,
-          :will_retain => false,
-          :will_payload => '',
-          :username => nil,
-          :password => nil,
-        }.merge(args))
+        super(DEFAULTS.merge(args))
       end
 
       # Get serialisation of packet's body
@@ -372,12 +378,11 @@ module MQTT
     # Class representing an MQTT Connect Acknowledgment Packet
     class Connack < MQTT::Packet
       attr_accessor :return_code
+      DEFAULTS = {:return_code => 0x00}
 
       # Create a new Client Connect packet
       def initialize(args={})
-        super({
-          :return_code => 0x00
-        }.merge(args))
+        super(DEFAULTS.merge(args))
       end
 
       # Get a string message corresponding to a return code
@@ -422,12 +427,11 @@ module MQTT
     # Class representing an MQTT Publish Acknowledgment packet
     class Puback < MQTT::Packet
       attr_accessor :message_id
+      DEFAULTS = {:message_id => 0}
 
       # Create a new Publish Acknowledgment packet
       def initialize(args={})
-        super({
-          :message_id => 0
-        }.merge(args))
+        super(DEFAULTS.merge(args))
       end
 
       # Get serialisation of packet's body
@@ -448,12 +452,11 @@ module MQTT
     # Class representing an MQTT Publish Received packet
     class Pubrec < MQTT::Packet
       attr_accessor :message_id
+      DEFAULTS = {:message_id => 0}
 
       # Create a new Publish Recieved packet
       def initialize(args={})
-        super({
-          :message_id => 0
-        }.merge(args))
+        super(DEFAULTS.merge(args))
       end
 
       # Get serialisation of packet's body
@@ -474,12 +477,11 @@ module MQTT
     # Class representing an MQTT Publish Release packet
     class Pubrel < MQTT::Packet
       attr_accessor :message_id
+      DEFAULTS = {:message_id => 0}
 
       # Create a new Publish Release packet
       def initialize(args={})
-        super({
-          :message_id => 0
-        }.merge(args))
+        super(DEFAULTS.merge(args))
       end
 
       # Get serialisation of packet's body
@@ -500,12 +502,11 @@ module MQTT
     # Class representing an MQTT Publish Complete packet
     class Pubcomp < MQTT::Packet
       attr_accessor :message_id
+      DEFAULTS = {:message_id => 0}
 
       # Create a new Publish Complete packet
       def initialize(args={})
-        super({
-          :message_id => 0
-        }.merge(args))
+        super(DEFAULTS.merge(args))
       end
 
       # Get serialisation of packet's body
@@ -527,14 +528,13 @@ module MQTT
     class Subscribe < MQTT::Packet
       attr_accessor :message_id
       attr_reader :topics
+      DEFAULTS = {:message_id => 0}
 
       # Create a new Subscribe packet
       def initialize(args={})
-        super({
-          :topics => [],
-          :message_id => 0
-        }.merge(args))
-        self.qos = 1 # Force a QOS of 1
+        super(DEFAULTS.merge(args))
+        @topics ||= []
+        @qos = 1 # Force a QOS of 1
       end
 
       # Set one or more topics for the Subscrible packet
@@ -609,13 +609,12 @@ module MQTT
     class Suback < MQTT::Packet
       attr_accessor :message_id
       attr_reader :granted_qos
+      DEFAULTS = {:message_id => 0}
 
       # Create a new Subscribe Acknowledgment packet
       def initialize(args={})
-        super({
-          :granted_qos => [],
-          :message_id => 0
-        }.merge(args))
+        super(DEFAULTS.merge(args))
+        @granted_qos ||= []
       end
 
       def granted_qos=(value)
@@ -649,14 +648,13 @@ module MQTT
     class Unsubscribe < MQTT::Packet
       attr_reader :topics
       attr_accessor :message_id
+      DEFAULTS = {:message_id => 0}
 
       # Create a new Unsubscribe packet
       def initialize(args={})
-        super({
-          :topics => [],
-          :message_id => 0
-        }.merge(args))
-        self.qos = 1 # Force a QOS of 1
+        super(DEFAULTS.merge(args))
+        @topics ||= []
+        @qos = 1 # Force a QOS of 1
       end
 
       def topics=(value)
@@ -690,12 +688,11 @@ module MQTT
     # Class representing an MQTT Unsubscribe Acknowledgment packet
     class Unsuback < MQTT::Packet
       attr_accessor :message_id
+      DEFAULTS = {:message_id => 0}
 
       # Create a new Unsubscribe Acknowledgment packet
       def initialize(args={})
-        super({
-          :message_id => 0
-        }.merge(args))
+        super(DEFAULTS.merge(args))
       end
 
       # Get serialisation of packet's body

data/lib/mqtt/version.rb

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

data/spec/mqtt_client_spec.rb

@@ -62,7 +62,6 @@ describe MQTT::Client do
     end
   end
 
-
   describe "when calling the 'connect' method" do
     before(:each) do
       TCPSocket.stubs(:new).returns(@socket)
@@ -125,6 +124,39 @@ describe MQTT::Client do
       @client.connect
       @client.clean_session.should be_true
     end
+
+    context "with a last will and testament set" do
+      before(:each) do
+        @client.set_will('topic', 'hello', retain=false, qos=1)
+      end
+
+      it "should have set the Will's topic" do
+        @client.will_topic.should == 'topic'
+      end
+
+      it "should have set the Will's payload" do
+        @client.will_payload.should == 'hello'
+      end
+
+      it "should have set the Will's retain flag to true" do
+        @client.will_retain.should be_false
+      end
+
+      it "should have set the Will's retain QOS value to 1" do
+        @client.will_qos.should == 1
+      end
+
+      it "should include the will in the CONNECT message" do
+        @client.connect('myclient')
+        @socket.string.should ==
+          "\x10\x24"+
+          "\x00\x06MQIsdp"+
+          "\x03\x0e\x00\x0f"+
+          "\x00\x08myclient"+
+          "\x00\x05topic\x00\x05hello"
+      end
+    end
+
   end
 
   describe "when calling the 'receive_connack' method" do
@@ -350,7 +382,44 @@ describe MQTT::Client do
       MQTT::Packet.stubs(:read).raises(MQTT::Exception)
       @client.send(:receive_packet)
     end
+  end
 
+  describe "generating a client identifier" do
+    context "with default parameters" do
+      before :all do
+        @client_id = MQTT::Client.generate_client_id
+      end
+
+      it "should be less or equal to 23 characters long" do
+        @client_id.length.should <= 23
+      end
+
+      it "should have a prefix of ruby_" do
+        @client_id.should match(/^ruby_/)
+      end
+
+      it "should end in 16 characters of lowercase letters and numbers" do
+        @client_id.should match(/_[a-z0-9]{16}$/)
+      end
+    end
+
+    context "with an alternative prefix" do
+      before :all do
+        @client_id = MQTT::Client.generate_client_id('test_')
+      end
+
+      it "should be less or equal to 23 characters long" do
+        @client_id.length.should <= 23
+      end
+
+      it "should have a prefix of test_" do
+        @client_id.should match(/^test_/)
+      end
+
+      it "should end in 16 characters of lowercase letters and numbers" do
+        @client_id.should match(/_[a-z0-9]{16}$/)
+      end
+    end
   end
 
 end

data/spec/mqtt_packet_spec.rb

@@ -7,8 +7,8 @@ describe MQTT::Packet do
 
   describe "when creating a new packet" do
     it "should allow you to set the packet dup flag as a hash parameter" do
-      packet = MQTT::Packet.new( :dup => true )
-      packet.dup.should be_true
+      packet = MQTT::Packet.new( :duplicate => true )
+      packet.duplicate.should be_true
     end
 
     it "should allow you to set the packet QOS level as a hash parameter" do
@@ -25,7 +25,7 @@ describe MQTT::Packet do
   describe "when setting packet parameters" do
     before(:each) do
       @packet = MQTT::Packet.new(
-        :dup => false,
+        :duplicate => false,
         :qos => 0,
         :retain => false
       )
@@ -37,13 +37,13 @@ describe MQTT::Packet do
     end
 
     it "should let you change the dup flag of a packet" do
-      @packet.dup = true
-      @packet.dup.should be_true
+      @packet.duplicate = true
+      @packet.duplicate.should be_true
     end
 
     it "should let you change the dup flag of a packet using an integer" do
-      @packet.dup = 1
-      @packet.dup.should be_true
+      @packet.duplicate = 1
+      @packet.duplicate.should be_true
     end
 
     it "should let you change the retain flag of a packet" do
@@ -121,7 +121,7 @@ describe MQTT::Packet::Publish do
     end
 
     it "should output the correct bytes for a packet with QOS 2 and dup flag set" do
-      packet = MQTT::Packet::Publish.new( :qos => 2, :dup => true, :message_id => 5, :topic => 'c/d', :payload => 'hello world' )
+      packet = MQTT::Packet::Publish.new( :qos => 2, :duplicate => true, :message_id => 5, :topic => 'c/d', :payload => 'hello world' )
       packet.to_s.should == "\x3C\x12\x00\x03c/d\x00\x05hello world"
     end
 
@@ -152,7 +152,7 @@ describe MQTT::Packet::Publish do
     end
 
     it "should set the DUP flag correctly" do
-      @packet.dup.should be_false
+      @packet.duplicate.should be_false
     end
 
     it "should set the topic name correctly" do
@@ -182,7 +182,7 @@ describe MQTT::Packet::Publish do
     end
 
     it "should set the DUP flag correctly" do
-      @packet.dup.should be_true
+      @packet.duplicate.should be_true
     end
 
     it "should set the topic name correctly" do
@@ -243,7 +243,7 @@ describe MQTT::Packet::Connect do
   describe "when serialising a packet" do
     it "should output the correct bytes for a packet with no flags" do
       packet = MQTT::Packet::Connect.new( :client_id => 'myclient' )
-      packet.to_s.should == "\020\026\x00\x06MQIsdp\x03\x02\x00\x0a\x00\x08myclient"
+      packet.to_s.should == "\020\026\x00\x06MQIsdp\x03\x02\x00\x0f\x00\x08myclient"
     end
 
     it "should output the correct bytes for a packet with clean session turned off" do
@@ -251,7 +251,7 @@ describe MQTT::Packet::Connect do
         :client_id => 'myclient',
         :clean_session => false
       )
-      packet.to_s.should == "\020\026\x00\x06MQIsdp\x03\x00\x00\x0a\x00\x08myclient"
+      packet.to_s.should == "\020\026\x00\x06MQIsdp\x03\x00\x00\x0f\x00\x08myclient"
     end
 
     it "should throw an exception when there is no client identifier" do
@@ -274,7 +274,7 @@ describe MQTT::Packet::Connect do
       packet.to_s.should ==
         "\x10\x24"+
         "\x00\x06MQIsdp"+
-        "\x03\x0e\x00\x0a"+
+        "\x03\x0e\x00\x0f"+
         "\x00\x08myclient"+
         "\x00\x05topic\x00\x05hello"
     end
@@ -288,8 +288,8 @@ describe MQTT::Packet::Connect do
       packet.to_s.should ==
         "\x10\x2A"+
         "\x00\x06MQIsdp"+
-        "\x03\xC2\x00\x0a\x00"+
-        "\x08myclient"+
+        "\x03\xC2\x00\x0f"+
+        "\x00\x08myclient"+
         "\x00\x08username"+
         "\x00\x08password"
     end
@@ -429,8 +429,8 @@ describe MQTT::Packet::Connect do
       @packet = MQTT::Packet.parse(
         "\x10\x2A"+
         "\x00\x06MQIsdp"+
-        "\x03\xC0\x00\x0a\x00"+
-        "\x08myclient"+
+        "\x03\xC0\x00\x0a"+
+        "\x00\x08myclient"+
         "\x00\x08username"+
         "\x00\x08password"
       )

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: mqtt
 version: !ruby/object:Gem::Version 
-  hash: 17
+  hash: 15
   prerelease: false
   segments: 
   - 0
   - 0
-  - 7
-  version: 0.0.7
+  - 8
+  version: 0.0.8
 platform: ruby
 authors: 
 - Nicholas J Humfrey
@@ -15,10 +15,12 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-01-19 00:00:00 +00:00
+date: 2012-02-04 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -31,10 +33,10 @@ dependencies:
         - 7
         version: 1.0.7
   type: :development
-  name: bundler
-  prerelease: false
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -47,10 +49,10 @@ dependencies:
         - 2
         version: 0.7.2
   type: :development
-  name: yard
-  prerelease: false
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -63,10 +65,10 @@ dependencies:
         - 7
         version: 0.8.7
   type: :development
-  name: rake
-  prerelease: false
   version_requirements: *id003
 - !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -79,10 +81,10 @@ dependencies:
         - 0
         version: 2.6.0
   type: :development
-  name: rspec
-  prerelease: false
   version_requirements: *id004
 - !ruby/object:Gem::Dependency 
+  name: mocha
+  prerelease: false
   requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -95,10 +97,10 @@ dependencies:
         - 0
         version: 0.10.0
   type: :development
-  name: mocha
-  prerelease: false
   version_requirements: *id005
 - !ruby/object:Gem::Dependency 
+  name: rcov
+  prerelease: false
   requirement: &id006 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -111,8 +113,6 @@ dependencies:
         - 0
         version: 0.9.0
   type: :development
-  name: rcov
-  prerelease: false
   version_requirements: *id006
 description: Pure Ruby gem that implements the MQTT (Message Queue Telemetry Transport) protocol, a lightweight protocol for publish/subscribe messaging.
 email: njh@aelius.com