mqtt_pipe 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 69a8164675982ac052fefb772507fd26f96eac61
-  data.tar.gz: 6d001fffc5f2007191349ff736d4c3309e716813
+  metadata.gz: f579008e0f69a4f8dd375038f2b611d39e82ec07
+  data.tar.gz: 4b54e9845ad534d37b6f954028f5c6d9e3bcd83b
 SHA512:
-  metadata.gz: 7e530f0ca6aa01fd40858e35993b038b9daa552ef7eb510bff04c9dde3b7b9150b6201bef7d5131183e1bfe369c2fa527348c90e94af38cd0d948b57e576ce79
-  data.tar.gz: 908eb4630804e017663dd91d2cfc299433fcbcc9f026a6284e023b0cb95ca3f1856fc297a34b5d50470c0b57f805fb369d6a66484d51fb4d71da35ccfdc36151
+  metadata.gz: 1ded3c38efb21c73ecb8ac1cb2455cb1dc206e7e6273101fd26672e1c914143748e37862f39e311a79aed4a2fe3b7a2879f48586029d9ac2c96b271f8bd31e68
+  data.tar.gz: 249ded44ccac0db4e6f66372f242b99ea9d4c205fc245fe62c4b0233328ceebcfa9536450542dbf72a8af750754fdbf6a38bb648431b792ca24c4c18cf9df50b

data/README.md

@@ -1,6 +1,13 @@
 # MQTTPipe
 
-This gem wraps the [MQTT gem](https://github.com/njh/ruby-mqtt) and adds a serializer for simple data structures.
+This gem wraps the [MQTT gem](https://github.com/njh/ruby-mqtt) and adds a serializer for simple data structures. The serializer is heavily inspired by [MessagePack](http://msgpack.org) and borrows some of their byte values when packing the data. It is however much more restricted in what data types it supports. Right now hashes are for example not supported, but this may change in the future. 
+
+The reason for the limitations is that the gem is later meant to talk to devices with much more limited hardware (think Arduino, but really the ESP8266).
+
+## TODO
+
+1. Handle disconnects gracefully
+2. Possibly add a few data types. See below for more details on that.
 
 ## Installation
 
@@ -21,10 +28,26 @@ Or install it yourself as:
 ## Usage
 
 ```ruby
-pipe = MQTTPipe.create do
+MQTTPipe.create do
   on 'hello/world/#' do |message, id|
     p message, id
   end
+  
+  open 'test.mosquitto.org', port: 1883 do
+    100.times do |i|
+      send "hello/world/#{i}", Time.now
+    end
+  end
+end
+```
+
+Everything does not need to be contained in a block:
+
+```ruby
+pipe = MQTTPipe.create
+
+pipe.on 'hello/#' do
+  # do something
 end
 
 pipe.open 'test.mosquitto.org', port: 1883 do
@@ -34,6 +57,53 @@ pipe.open 'test.mosquitto.org', port: 1883 do
 end
 ```
 
+## Protocol
+
+Taking inspiration from the excellent [MessagePack](http://msgpack.org) project each data type is represented by a byte value, or in same cases a range of values. The currently supported data types along with their byte values are:
+
+Data type                 | Byte value (in hex)
+------------------------- | -------------------
+`0..127`                  | 0x00 - 0x7F
+`Array`                   | 0x80 - 0x9F
+`String`                  | 0xA0 - 0xBF
+`Class`                   | 0xC0
+`NilClass`                | 0xC1
+`FalseClass`              | 0xC2
+`TrueClass`               | 0xC3
+`8 bit unsigned`          | 0xC4
+`6 bit signed`            | 0xC5
+`32 bit signed`           | 0xC6
+`Float`                   | 0xC7
+`Time`                    | 0xC8
+`MQTTPipe::Types::Color`  | 0xC9
+-                         | 0xCA
+-                         | 0xCB
+-                         | 0xCC
+-                         | 0xCD
+-                         | 0xCE
+-                         | 0xCF
+`-48..-1`                 | 0xD0 - 0xFF
+
+Note that the integers are split over several codes to accommodate for the various sizes that can occur. Because it is common to send small numerical values these can in most cases be represented by a single byte, instead of two.
+
+Array and string are also special cases in that their sizes are not known. They require a length value to be passed along with them, but instead of always including an extra byte for that purpose, length smaller than 32 can be encoded directly in the type byte value. An example is shown below:
+
+#### Strings with length 1..31:
+
+    'test' -> [0xA0 + 4, 0x74, 0x65, 0x73, 0x74]
+
+#### Strings with length 32..288
+    
+    'testing how really long strings are encoded'
+           -> [0xA0, 43 - 32, 0x74, 0x65, 0x73, ...]
+
+Some data types that may be supported in the future are:
+
+  - IP Addresses
+  - Hashes
+  - Strings longer than 288 characters
+  - UTF-8 encoded strings (could be a breaking change)
+
 ## Contributing
 
 1. Fork it ( https://github.com/[my-github-username]/mqtt_pipe/fork )

data/lib/mqtt_pipe/packer.rb

@@ -22,6 +22,27 @@ module MQTTPipe
     # Use the refinements made to the supported classes
     
     using Types
+    
+    
+    ##
+    # Checks whether a class or object is supported by the 
+    # packer. For arrays each item is checked recursivly
+    
+    def supports_type? type
+      if type.is_a? Class
+        type.to_packed
+      elsif type.is_a? Array
+        return type.detect{|obj| not supports_type? obj }.nil?
+      else
+        type.class.to_packed
+      end
+      return true
+    rescue NoMethodError
+      return false
+    end
+    
+    alias_method :supports?, :supports_type?
+    
         
     ##
     # Packs the arguments acording to their type.
@@ -58,6 +79,7 @@ module MQTTPipe
       return result
     end
     
+    
     ##
     # A simple helper method to read a given number of bytes
     # +from+ IO object and format them +as+ anything 
@@ -70,6 +92,7 @@ module MQTTPipe
       raw.unpack(as).first
     end
     
+    
     private
     
     def unpack_single raw

data/lib/mqtt_pipe/version.rb

@@ -1,3 +1,3 @@
 module MQTTPipe
-  VERSION = "0.0.2"
-end
+  VERSION = "0.0.3"
+end 

data/spec/packer_spec.rb

@@ -3,6 +3,41 @@ require 'mqtt_pipe'
 describe MQTTPipe::Packer do
   let(:klass) { MQTTPipe::Packer }
   
+  describe '#supports_type?' do
+    it 'expects one argument' do
+      expect{klass.supports_type?}.to raise_error ArgumentError
+    end
+    
+    context 'When the type is supported' do
+      it 'returns true for integers' do
+        expect(klass.supports_type? Integer).to be true
+        expect(klass.supports_type? Fixnum).to be true
+        expect(klass.supports_type? 42).to be true
+      end
+      
+      it 'returns true for strings' do
+        expect(klass.supports_type? String).to be true
+        expect(klass.supports_type? 'string').to be true
+      end
+      
+      it 'returns true for arrays containing supported types' do
+        expect(klass.supports_type? Array).to be true
+        expect(klass.supports_type? [42, 'string']).to be true
+      end
+    end
+    
+    context 'When the type is not supported' do
+      it 'returns false for arbitrary classes/objects' do
+        expect(klass.supports_type? Regexp).to be false
+        expect(klass.supports_type? /regexp/).to be false
+      end
+      
+      it 'returns false for arrays containing unsupported objects' do
+        expect(klass.supports_type? [42, /regexp/]).to be false
+      end
+    end
+  end
+  
   describe '#pack/#[]' do
     describe 'Array' do
       it 'serializes empty arrays to nil' do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mqtt_pipe
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Sebastian Lindberg