mqtt 0.0.1

data/COPYING

@@ -0,0 +1,56 @@
+ruby-mqtt is copyrighted free software by Nicholas J Humfrey <njh@aelius.com>.
+You can redistribute it and/or modify it under either the terms of the GPL
+version 2 (see the file GPL), or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+	  modifications to Usenet or an equivalent medium, or by allowing
+	  the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) give non-standard binaries non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or binary form,
+     provided that you do at least ONE of the following:
+
+       a) distribute the binaries and library files of the software,
+	  together with instructions (in the manual page or equivalent)
+	  on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+	  the software.
+
+       c) give non-standard binaries non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  But some files in the distribution
+     are not written by the author, so that they are not under these terms.
+
+     For the list of those files and their copying conditions, see the
+     file LEGAL.
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.

data/NEWS

@@ -0,0 +1,5 @@
+= Ruby MQTT NEWS
+
+== Ruby MQTT Version 0.0.1 (2009-01-??)
+
+Initial Release.

data/README

@@ -0,0 +1,47 @@
+= ruby-mqtt
+
+Pure Ruby gem that implements the MQTT (Message Queue Telemetry Transport) protocol, a lightweight protocol for publish/subscribe messaging.
+
+RubyForge Project Page  http://rubyforge.org/projects/mqtt/
+
+== Installing
+
+You may get the latest stable version from Rubyforge. Source gems are also available.
+
+  $ gem install mqtt
+
+== Synopsis
+
+ require 'rubygems'
+ require 'mqtt'
+
+ mqtt = MQTT::Client.new('mqtt.example.com')
+ mqtt.connect('clientid') do |c|
+   c.publish('topic','message')
+ end
+
+== TODO
+
+* Support payloads longer than 128 bytes
+* Process acknowledgement packets
+* Create classes for each type of packet?
+* More validations of data/parameters
+* Implement exception throwing
+* Implement Will and Testament
+* Add unit tests
+* More examples
+* Refactor to add callbacks that are called from seperate thread
+* Implement QOS Level 1
+* Implement QOS Level 2
+* Add support for binding socket to specific local address
+
+== Resources
+
+http://mqtt.org
+
+== Contact
+
+Author::     Nicholas J Humfrey
+Email::      njh@aelius.com
+Home Page::  http://www.aelius.com/njh/
+License::    Distributes under the same terms as Ruby

data/Rakefile

@@ -0,0 +1,112 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+require 'spec/rake/verify_rcov'
+
+
+NAME = "mqtt"
+VERS = "0.0.1"
+CLEAN.include ['pkg', 'rdoc']
+
+spec = Gem::Specification.new do |s|
+  s.name              = NAME
+  s.version           = VERS
+  s.author            = "Nicholas J Humfrey"
+  s.email             = "njh@aelius.com"
+  s.homepage          = "http://mqtt.rubyforge.org"
+  s.platform          = Gem::Platform::RUBY
+  s.summary           = "Implementation of the MQTT (Message Queue Telemetry Transport) protocol" 
+  s.rubyforge_project = "mqtt" 
+  s.description       = "Pure Ruby gem that implements the MQTT (Message Queue Telemetry Transport) protocol, a lightweight protocol for publish/subscribe messaging."
+  s.files             = FileList["Rakefile", "lib/*.rb", "lib/mqtt/*.rb", "examples/*"]
+  s.require_path      = "lib"
+  
+  # rdoc
+  s.has_rdoc          = true
+  s.extra_rdoc_files  = ["README", "NEWS", "COPYING"]
+  
+  # Build Dependencies
+  #s.add_dependency 'rake'     '~> 0.8'
+  #s.add_dependency 'rspec',   '~> 1.1'
+  #s.add_dependency 'rcov',    '~> 0.8'
+  #s.add_dependency 'mocha',   '~> 0.9'
+end
+
+desc "Default: test the gem."
+task :default => [:check_syntax, :rdoc]
+
+task :build_package => [:repackage]
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = false
+  pkg.need_tar = true
+  pkg.gem_spec = spec
+end
+
+desc "Run :package and install the resulting .gem"
+task :install => :package do
+  sh %{sudo gem install --local pkg/#{NAME}-#{VERS}.gem}
+end
+
+desc "Run :clean and uninstall the .gem"
+task :uninstall => :clean do
+  sh %{sudo gem uninstall #{NAME}}
+end
+
+
+
+## Testing
+desc "Run all the specification tests"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_files = FileList['spec/*_spec.rb']
+  t.spec_opts  = ["--colour"]
+end
+  
+desc "Check the syntax of all ruby files"
+task :check_syntax do
+  `find . -name "*.rb" |xargs -n1 ruby -c |grep -v "Syntax OK"`
+  puts "* Done"
+end
+
+namespace :spec do
+  desc "Generate RCov report"
+  Spec::Rake::SpecTask.new(:rcov) do |t|
+    t.spec_files  = FileList['spec/*_spec.rb']
+    t.rcov        = true
+    t.rcov_dir    = 'coverage'
+    t.rcov_opts   = ['--text-report', '--exclude', "spec/"] 
+  end
+  
+  desc "Generate specdoc"
+  Spec::Rake::SpecTask.new(:doc) do |t|
+    t.spec_files  = FileList['spec/*_spec.rb']
+    t.spec_opts   = ["--format", "specdoc"]
+   end
+ 
+  namespace :doc do
+    desc "Generate html specdoc"
+    Spec::Rake::SpecTask.new(:html) do |t|
+      t.spec_files    = FileList['spec/*_spec.rb']
+      t.spec_opts     = ["--format", "html:rspec_report.html", "--diff"]
+    end
+  end
+end
+
+
+
+## Documentation
+desc "Generate documentation for the library"
+Rake::RDocTask.new("rdoc") { |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = "mqtt Documentation"
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.main = "README"
+  rdoc.rdoc_files.include("README", "NEWS", "COPYING", "lib/*.rb", "lib/mqtt/*.rb")
+}
+
+desc "Upload rdoc to rubyforge"
+task :upload_rdoc => [:rdoc] do
+  sh %{/usr/bin/scp -r -p rdoc/* mqtt.rubyforge.org:/var/www/gforge-projects/mqtt}
+end

data/examples/simple_get.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.dirname(__FILE__)+'/../lib'
+
+require 'mqtt'
+
+
+client = MQTT::Client.new('mqtt.example.com')
+client.connect('simple_get')
+
+client.subscribe('$SYS/#')
+
+loop do
+  topic,message = client.get
+  puts "#{topic}: #{message}"
+end
+
+client.disconnect

data/examples/simple_publish.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.dirname(__FILE__)+'/../lib'
+
+require 'mqtt'
+
+client = MQTT::Client.new('mqtt.example.com')
+client.connect('simple_publish_example') do |c|
+
+  c.publish('test', "The time is: #{Time.now}")
+
+end

data/lib/mqtt/client.rb

@@ -0,0 +1,238 @@
+#!/usr/bin/env ruby
+
+require 'mqtt'
+require 'mqtt/packet'
+require 'thread'
+require 'socket'
+
+
+module MQTT
+
+  # Client class for talking to an MQTT broker
+  class Client
+    attr_reader :remote_host    # Hostname of the remote broker
+    attr_reader :remote_port    # Port number of the remote broker
+    attr_accessor :keep_alive   # Time between pings to remote broker
+    attr_accessor :clean_start  # Set the 'Clean Start' flag when connecting?
+    
+    # Timeout between select polls (in seconds)
+    SELECT_TIMEOUT = 0.5
+
+    # Create a new MQTT Client instance 
+    def initialize(remote_host='localhost', remote_port=1883)
+      @remote_host = remote_host
+      @remote_port = remote_port
+      @message_id = 0
+      @keep_alive = 10
+      @clean_start = true
+      @last_pingreq = Time.now
+      @last_pingresp = Time.now
+      @socket = nil
+      @read_queue = Queue.new
+      @read_thread = nil
+      @write_semaphore = Mutex.new
+    end
+    
+    # Connect to the MQTT broker
+    # If a block is given, then yield to that block and then disconnect again.
+    def connect(clientid)
+      if not connected?
+        # Create network socket
+        @socket = TCPSocket.new(@remote_host,@remote_port)
+        
+        # Start packet reading thread
+        @read_thread = Thread.new(Thread.current) do |parent|
+          Thread.current[:parent] = parent
+          loop { receive_packet } 
+        end
+
+        # Protocol name and version
+        packet = MQTT::Packet.new(:type => :connect)
+        packet.add_string('MQIsdp')
+        packet.add_bytes(0x03)
+        
+        # Connect flags
+        connect_flags = 0x00
+        connect_flags ||= 0x02 if @clean_start
+        # FIXME: implement Will and Testament
+        packet.add_bytes(connect_flags)
+        
+        # Keep Alive timer: 10 seconds
+        packet.add_short(@keep_alive)
+        
+        # Add the client identifier
+        packet.add_string(clientid)
+        
+        # Send packet
+        send_packet(packet)
+      end
+      
+      # If a block is given, then yield and disconnect
+      if block_given?
+        yield(self)
+        disconnect
+      end
+    end
+    
+    # Disconnect from the MQTT broker.
+    # If you don't want to say goodbye to the broker, set send_msg to false.
+    def disconnect(send_msg=true)
+      if connected?
+        if send_msg
+          packet = MQTT::Packet.new(:type => :disconnect)
+          send_packet(packet)
+        end
+        @read_thread.kill unless @read_thread.nil?
+        @read_thread = nil
+        @socket.close unless @socket.nil?
+        @socket = nil
+      end
+    end
+    
+    # Checks whether the client is connected to the broker. 
+    def connected?
+      not @socket.nil?
+    end
+  
+    # Send a MQTT ping message to indicate that the MQTT client is alive.
+    def ping
+      packet = MQTT::Packet.new(:type => :pingreq)
+      send_packet(packet)
+      @last_pingreq = Time.now
+    end
+
+    # Publish a message on a particular topic to the MQTT broker.
+    def publish(topic, payload, retain=false, qos=0)
+      packet = MQTT::Packet.new(
+        :type => :publish,
+        :qos => qos,
+        :retain => retain
+      )
+      
+      # Add the topic name
+      packet.add_string(topic)
+      
+      # Add Message ID for qos1 and qos2
+      unless qos == 0
+        packet.add_short(@message_id.next)
+      end
+      
+      # Add the packet payload
+      packet.add_data(payload)
+      
+      # Send the packet
+      send_packet(packet)
+    end
+    
+    # Send a subscribe message for one or more topics on the MQTT broker.
+    # 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
+    #
+    # For example:
+    #   client.subscribe( 'a/b' )
+    #   client.subscribe( 'a/b', 'c/d' )
+    #   client.subscribe( ['a/b',0], ['c/d',1] )
+    #   client.subscribe( 'a/b' => 0, 'c/d' => 1 )
+    #
+    def subscribe(*topics)
+      array = []
+      topics.each do |item|
+        if item.is_a?(Hash)
+          # Convert hash into an ordered array of arrays
+          array += item.sort
+        elsif item.is_a?(Array)
+          # Already in [topic,qos] format 
+          array.push item
+        else
+          # Default to QOS 0
+          array.push [item.to_s,0]
+        end
+      end
+      
+      # Create the packet
+      packet = MQTT::Packet.new(:type => :subscribe, :qos => 1)
+      packet.add_short(@message_id.next)
+      array.each do |item|
+        packet.add_string(item[0])
+        packet.add_bytes(item[1])
+      end
+      send_packet(packet)
+    end
+    
+    # Return the next message recieved from the MQTT broker.
+    # This method blocks until a message is available.
+    #
+    # The method 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
+      
+      # Parse the variable header
+      topic = packet.shift_string
+      msg_id = packet.shift_short unless (packet.qos == 0)
+      return topic,packet.body
+    end
+    
+    # Send a unsubscribe message for one or more topics on the MQTT broker
+    def unsubscribe(*topics)
+      packet = MQTT::Packet.new(:type => :unsubscribe, :qos => 1)
+      topics.each { |topic| packet.add_string(topic) }
+      send_packet(packet)
+    end
+  
+  private
+  
+    # Try to read a packet from the broker
+    # Also sends keep-alive ping packets.
+    def receive_packet
+      begin
+        # Poll socket - is there data waiting?
+        result = IO.select([@socket], nil, nil, SELECT_TIMEOUT)
+        unless result.nil?
+          # Yes - read in the packet
+          packet = MQTT::Packet.read(@socket)
+          if packet.type == :publish
+            # Add to queue
+            @read_queue.push(packet)
+          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 Time.now > @last_pingreq + @keep_alive
+          ping
+        end
+        
+        # FIXME: check we received a ping response recently?
+
+      # Pass exceptions up to parent thread
+      rescue Exception => exp
+        unless @socket.nil?
+          @socket.close 
+          @socket = nil
+        end
+        Thread.current[:parent].raise(exp)
+      end
+    end
+  
+    # Send a packet to broker
+    def send_packet(data)
+      # Throw exception if we aren't connected
+      raise MQTT::NotConnectedException if not connected?
+    
+      # Only allow one thread to write to socket at a time
+      @write_semaphore.synchronize do
+        @socket.write(data)
+      end
+    end
+    
+  end
+
+end

data/lib/mqtt/packet.rb

@@ -0,0 +1,160 @@
+#!/usr/bin/env ruby
+
+require 'mqtt'
+
+module MQTT
+
+  # Class representing a MQTT Packet
+  # Performs binary encoding and decoding of headers
+  class Packet #:nodoc: all
+    attr_reader :type      # The packet type
+    attr_reader :dup       # Duplicate delivery flag
+    attr_reader :retain    # Retain flag
+    attr_reader :qos       # Quality of Service level
+    attr_reader :body      # Packet's body (everything after fixed header)
+  
+    # Read in a packet from a socket
+    def self.read(sock)
+      header = sock.read(2)
+      raise MQTT::ProtocolException if header.nil?
+      byte1,byte2 = header.unpack('C*')
+
+      # FIXME: support decoding of multi-byte length header
+
+      packet = MQTT::Packet.new(
+        :type => ((byte1 & 0xF0) >> 4),
+        :dup => ((byte1 & 0x08) >> 3),
+        :qos => ((byte1 & 0x06) >> 1),
+        :retain => ((byte1 & 0x01) >> 0)
+      )
+      packet.body = sock.read(byte2)
+
+      return packet
+    end
+
+    # Create a new empty packet
+    def initialize(args={})
+      self.type = args[:type] || :invalid
+      self.dup = args[:dup] || false
+      self.qos = args[:qos] || 0
+      self.retain = args[:retain] || false
+      self.body = args[:body] || ''
+    end
+    
+    def type=(arg)
+      if arg.kind_of?(Integer)
+        # Convert type identifier to symbol
+        @type = MQTT::PACKET_TYPES[arg]
+      else
+        @type = arg.to_sym
+        # FIXME: raise exception if packet type is invalid?
+      end
+    end
+
+    # Return the identifer for this packet type
+    def type_id
+      raise "No packet type set for this packet" if @type.nil?
+      index = MQTT::PACKET_TYPES.index(@type)
+      raise "Invalid packet type: #{@type}" if index.nil?
+      return index
+    end
+    
+    def dup=(arg)
+      if arg.kind_of?(Integer)
+        @dup = (arg != 0 ? true : false)
+      else
+        @dup = arg
+      end
+    end
+    
+    def retain=(arg)
+      if arg.kind_of?(Integer)
+        @retain = (arg != 0 ? true : false)
+      else
+        @retain = arg
+      end
+    end
+    
+    def qos=(arg)
+      @qos = arg.to_i
+    end
+    
+    def body=(arg)
+      @body = arg.to_s
+    end
+
+
+
+
+    
+    # Add an array of bytes to the end of the packet's body
+    def add_bytes(*bytes)
+      @body += bytes.pack('C*')
+    end
+
+    # Add a 16-bit unsigned integer to the end of the packet's body
+    def add_short(val)
+      @body += [val.to_i].pack('n')
+    end
+    
+    # Add some raw data to the end of the packet's body
+    def add_data(data)
+      data = data.to_s unless data.is_a?(String)
+      @body += data
+    end
+
+    # Add a string to the end of the packet's body
+    # (preceded by the length of the string)
+    def add_string(str)
+      str = str.to_s unless str.is_a?(String)
+      add_short(str.size)
+      add_data(str)
+    end
+
+
+    # Remove a 16-bit unsigned integer from the front on the body
+    def shift_short
+      bytes = @body.slice!(0..1)
+      bytes.unpack('n').first
+    end
+    
+    # Remove n bytes from the front on the body
+    def shift_bytes(bytes)
+      @body.slice!(0...bytes).unpack('C*')
+    end
+    
+    # Remove n bytes from the front on the body
+    def shift_data(bytes)
+      @body.slice!(0...bytes)
+    end
+    
+    # Remove string from the front on the body
+    def shift_string
+      len = shift_short
+      shift_data(len)
+    end
+
+    
+    # Serialise the packet
+    def to_s
+      # Encode the 2-byte fixed header
+      header = [
+        ((type_id.to_i & 0x0F) << 4) |
+        ((dup ? 0x1 : 0x0) << 3) |
+        ((qos.to_i & 0x03) << 1) |
+        (retain ? 0x1 : 0x0),
+        (@body.length & 0x7F)
+      ]
+      # FIXME: support multi-byte length header
+      header.pack('C*') + @body
+    end
+    
+    def inspect
+      format("#<MQTT::Packet:0x%01x ", object_id)+
+      "type=#{@type}, dup=#{@dup}, retain=#{@retain}, "+
+      "qos=#{@qos}, body.size=#{@body.size}>"
+    end
+    
+  end
+  
+end

data/lib/mqtt.rb

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+
+require 'mqtt/client'
+
+# Pure-ruby implementation of the MQTT protocol
+module MQTT
+
+  PACKET_TYPES = [
+    nil,
+    :connect,      # Client request to connect to Broker
+    :connack,      # Connect Acknowledgment
+    :publish,      # Publish message
+    :puback,       # Publish Acknowledgment
+    :pubrec,       # Publish Received (assured delivery part 1)
+    :pubrel,       # Publish Release (assured delivery part 2)
+    :pubcomp,      # Publish Complete (assured delivery part 3)
+    :subscribe,    # Client Subscribe request
+    :suback,       # Subscribe Acknowledgment
+    :unsubscribe,  # Client Unsubscribe request
+    :unsuback,     # Unsubscribe Acknowledgment
+    :pingreq,      # PING Request
+    :pingresp,     # PING Response
+    :disconnect,   # Client is Disconnecting
+    nil
+  ]
+  
+  class Exception < Exception
+  
+  end
+
+  class ProtocolException < MQTT::Exception
+  
+  end
+  
+  class NotConnectedException < MQTT::Exception
+  
+  end
+
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification 
+name: mqtt
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Nicholas J Humfrey
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-02-01 00:00:00 +00:00
+default_executable: 
+dependencies: []
+
+description: Pure Ruby gem that implements the MQTT (Message Queue Telemetry Transport) protocol, a lightweight protocol for publish/subscribe messaging.
+email: njh@aelius.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- NEWS
+- COPYING
+files: 
+- Rakefile
+- lib/mqtt.rb
+- lib/mqtt/client.rb
+- lib/mqtt/packet.rb
+- examples/simple_get.rb
+- examples/simple_publish.rb
+- README
+- NEWS
+- COPYING
+has_rdoc: true
+homepage: http://mqtt.rubyforge.org
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: mqtt
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: Implementation of the MQTT (Message Queue Telemetry Transport) protocol
+test_files: []
+