mqtt-sub_handler 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cc152d507d338bd439708e9506b55c434f4ebeb4
-  data.tar.gz: 7b9ce380c5ceda9d935d0defe51794723295376d
+  metadata.gz: aaf64955622e7422caca9dab6565f9ae9c80d11c
+  data.tar.gz: 804a85d87e0e22ac033342b96490d7e833143986
 SHA512:
-  metadata.gz: a03ca9562da63543356deedfbba1117c877f5ebc80dac1da5883fbdb4e6a57e2eb17e28bb6bd554f999c9c97170a2dffe7a39a973ba79b0663fb9f09c2be4628
-  data.tar.gz: aa8c44e52e0a2ff8893fa721f23be336770b7248bbcbd678d220b82d3a93e4cfb1d8f9795e79424f446f346eadb0a90b2b6339035b132e793da661ea5a3b5604
+  metadata.gz: 6876a2eb48079b48c30e3cdd8d9156c3fb57f11c63f63b1c1eadde490f96b2a9d41aafe9fd76dacd154866789692d8656701c41322decbf1f8b0930747481ff9
+  data.tar.gz: 3ab96f2b0af4d2f3bc0ce230f9d5f3d9bae4ba90447c4966c3d4b2d9fdf7af21164cb0ac3124805956d3c026f5948e82466fafc688f205c74c44a98554def34d

data/README.md

@@ -0,0 +1,74 @@
+
+**Important note:**
+*Right now, I (Xasin) am still in the process of figuring out how to properly set up gems.
+This is my first one, and it has only recently (11.02.18) been published.*
+
+*I'm working on documenting the code, so if you can't figure out how to get it running, come back in a few days or make an issue explaining your problem!*
+
+---
+
+# A topic-based, asynchronous MQTT handler
+That's right, finally there's a *mostly* stable, connection-loss resistant MQTT handler out there that runs fully asynchronously.
+What's even nicer is that you can attach (and detach!) callbacks to *any* topic you want - including wildcards!
+Any topic can have as many callbacks as you want too, so don't worry about that!
+
+## That's great, but how to get it started?
+The main code is simple:
+```ruby
+require 'mqtt/sub_handler'
+
+myClient = MQTT::Client.new(ADDRESS_OR_PARAMETERS); # See the "mqtt" gem for possible options!
+mqttSubHandler = MQTT::SubHandler.new(myClient);    # Create a handler with a mqtt class
+
+mqttSubHandler = MQTT::SubHandler.new('mqtts://Password:Username@Address') # Or use a string!
+mqttSubHandler = MQTT.Eclipse(); # Or use the quick shortcut to 'iot.eclipse.org' for testing!
+```
+### Subscribing
+
+```ruby
+mySub = mqttSubHandler.subscribe_to "Any/Topic/You/Want" do |data, [topicMatch]|
+	puts "I got some data: #{data}";
+end
+# Yup, it's that simple. The callback will be stored, and will run whenever data is received.
+
+# You need to get rid of your subscription?
+# Sure thing!
+
+mqttSubHandler.unregister_subscription(mySub); # That'll remove the callback, and unsubscribe!
+# Don't worry about breaking other subscriptions. The code checks if any other callbacks are attached to the topic in question!
+```
+
+#### Wildcard subscriptions
+Wildcard subscriptions are also accepted with this code, and, may I say, are quite useful too!
+```ruby
+mqttSubHandler.subscribe_to "A/Wildcard/+/Topic/+" do |data, topicList|
+	puts "I got some data: #{data}"
+	puts "The first + was: #{topicList[0]}"
+	puts "The second one was: #{topicList[1]}"
+end
+```
+Note: This also works with the "#" wildcard. Every following topic "branch" becomes a new array element!
+
+### Publishing
+```ruby
+# Pushing gets easy, too:
+mqttSubHandler.publish_to "Any/Topic/You/Want", theData, [qos: 1, retain: false]
+# Right now, the code ONLY SUPPORTS QOS 0, AND WILL BLOCK!
+# This is courtesy of the MQTT-Gem though, and nothing I can fix for now.
+```
+
+## But ... Wait?
+Yep, you can wait for data, too!
+
+```ruby
+mqttSubHandler.wait_for "The/Waiting/Topic", [timeout: seconds or nil] do |data, [topicMatch]|
+	# Confirm and process data here. The rest of the code will wait!
+	# Return true when you found what you need, or set an optional timeout, and the main code will continue after that.
+end
+```
+
+The same goes for the end of the code, if you have nothing else to run but want to keep listening:
+```ruby
+mqttSubHandler.lockAndListen();
+# This here also traps SIGINT, so you get a clean exit!
+```

data/lib/mqtt/sub_handler.rb

@@ -4,17 +4,34 @@ require 'mqtt'
 
 require 'mqtt/subscription_classes'
 
+# @author Xasin
 module MQTT
+# A shortcut-function to quickly connect to the public Eclipse MQTT Broker.
+# @return [MQTT::SubHandler] Sub-Handler connected to `iot.eclipse.org`
 def self.Eclipse()
 	@EclipseMQTT ||= SubHandler.new('iot.eclipse.org');
 	return @EclipseMQTT;
 end
 
+
 class SubHandler
+	# Split a Topic into a Topic-Array
+	# @param topicName [String] The string topic which to split
+	# @return [Array<String>] A list of individual topic-branches
+	# @note This function is mainly used for background processing.
 	def self.getTopicSplit(topicName)
 		return topicName.scan(/[^\/]+/);
 	end
 
+	# Match a topic string to a topic pattern
+	# @param receivedTopicString [String] The string (as
+	#  returned by MQTT.get) to compare
+	# @param topicPattern [Array<String>] The Topic-Array (as
+	#  returned by .getTopicSplit) to compare against
+	# @return [nil, Array<String>] Nil if no match was found.
+	#  An Array of matched wildcard topic branches (can be empty) when
+	#  successfully matched
+	# @note (see .getTopicSplit)
 	def self.getTopicMatch(receivedTopicString, topicPattern)
 		receivedTopicList = getTopicSplit receivedTopicString;
 
@@ -40,6 +57,7 @@ class SubHandler
 		return nil;
 	end
 
+	# Call all existing callbacks whose topic-list matches `topic`
 	def call_interested(topic, data)
 		topicHasReceivers = false;
 		@callbackList.each do |h|
@@ -54,6 +72,7 @@ class SubHandler
 	end
 	private :call_interested
 
+	# Handle sending a subscription-message to the server
 	def raw_subscribe_to(topic, qos: 1)
 		begin
 			@conChangeMutex.lock
@@ -71,48 +90,82 @@ class SubHandler
 	end
 	private :raw_subscribe_to
 
+	# @!group Custom subscription handling
+
+	# Unregister a subscription. Removes it from the callback list and
+	# unsubscribes from the topic if no other subscriptions for it are present.
+	# @param subObject [MQTT::Subscriptions::Subscription]
+	#  The subscription-object to remove
+	# @return void
 	def unregister_subscription(subObject)
-		raise ArgumentError, "Object is not a subscription!" unless subObject.is_a? MQTT::Subscription
+		raise ArgumentError, "Object is not a subscription!" unless subObject.is_a? MQTT::Subscriptions::Subscription
 		return unless @callbackList.include? subObject;
 
 		@callbackList.delete(subObject);
 	end
+	# Register a custom subscription, and send a subscription message to the server.
+	# @param subObject [MQTT::Subscriptions::Subscription]
+	#  An instance of a MQTT Subscription object
+	# @return void
 	def register_subscription(subObject)
-		raise ArgumentError, "Object is not a subscription!" unless subObject.is_a? MQTT::Subscription
+		raise ArgumentError, "Object is not a subscription!" unless subObject.is_a? MQTT::Subscriptions::Subscription
 		return if @callbackList.include? subObject;
 
 		@callbackList << subObject;
 		raw_subscribe_to(subObject.topic, qos: subObject.qos);
 	end
 
+	# @!group Subscribing
+
+	# Synchronously wait for data.
+	# It waits for a message on `topic`, optionally letting a block
+	# check the data for validity, and optionally aborting after a timeout
+	# @param topic [String] The MQTT-Topic to wait for
+	# @param timeout [nil, Integer] The optional timeout after which to abort
+	# @param qos [nil, Integer] The QoS for this subscription
+	# @return [Boolean] True if the block returned true, False if the code timed-out
+	# @yieldparam data [String] The data received via MQTT
+	# @yieldparam topicList [Array<String>] The wildcard topic branches matched.
+	# @yieldreturn [Boolean] Whether or not the data was sufficient, and capture should be stopped.
 	def wait_for(topic, qos: 1, timeout: nil)
-		subObject = MQTT::WaitpointSubscription.new(topic, qos);
+		unless block_given? then
+			raise ArgumentError, "A block for data-processing needs to be passed!"
+		end
+
+		subObject = MQTT::Subscriptions::WaitpointSubscription.new(topic, qos);
 		register_subscription(subObject);
 
-		if block_given? then
-			begin
-			Timeout::timeout(timeout) do
-				loop do
-					return_data = subObject.waitpoint.wait()[1];
-					if yield(return_data[0], return_data[1]) then
-						unregister_subscription(subObject);
-						return true;
-					end
+		begin
+		Timeout::timeout(timeout) do
+			loop do
+				return_data = subObject.waitpoint.wait()[1];
+				if yield(return_data[0], return_data[1]) then
+					return true;
 				end
 			end
-			rescue Timeout::Error
-				return false;
-			end
-		else
-			return_data = subObject.waitpoint.wait(timeout);
 		end
-
-		unregister_subscription(subObject);
-		return return_data;
+		rescue Timeout::Error
+			return false;
+		ensure
+			unregister_subscription(subObject);
+		end
 	end
+
+	# Track data changes for a topic in the background.
+	# With no callback given, the returned object can be used to get the last
+	# received raw data string.
+	# With a callback given, the callback will be called whenever a change in data
+	# is detected.
+	# @param topic [String] The MQTT-Topic to track for data. Can be a Wildcard.
+	# @param qos [nil, Integer] The QoS to use for the subscription
+	# @yieldparam data [String] The new (changed) data received from MQTT.
+	# @yieldreturn [void]
+	# @return [MQTT::Subscriptions::ValueTrackerSubscription]
+	#  The tracker-object. Can be used to unsubscribe.
+	#  More importantly, `tracker.value` can be used to fetch the last received data.
 	def track(topic, qos: 1, &callback)
 		unless(@trackerHash.has_key? topic)
-			subObject = MQTT::ValueTrackerSubscription.new(topic, qos);
+			subObject = MQTT::Subscriptions::ValueTrackerSubscription.new(topic, qos);
 			register_subscription(subObject);
 
 			@trackerHash[topic] = subObject;
@@ -123,15 +176,33 @@ class SubHandler
 		return @trackerHash[topic];
 	end
 	alias on_change track
+
+	# Attach a callback to a MQTT Topic or wildcard.
+	# The callback will be saved, and asynchronously executed whenever a message
+	# from a matching topic (including wildcards) is received.
+	# @param topic [String] The MQTT-Topic to subscribe to. Can be a Wildcard.
+	# @param qos [nil, Integer] The QoS for the subscription. Currently not used!
+	# @yieldparam data [String] The raw MQTT data received from the MQTT server
+	# @yieldparam topicList [Array<String>] An array of topic-branches corresponding to wildcard matches.
+	#  Can be empty if no wildcard was used!
+	# @yieldreturn [void]
+	# @return [MQTT::Subscriptions::CallbackSubscription] The Subscription-Object corresponding to this callback.
+	#  Mainly used by the .unregister_subscription function to unsubscribe.
 	def subscribe_to(topic, qos: 1, &callback)
-		subObject = MQTT::CallbackSubscription.new(topic, qos, callback);
+		subObject = MQTT::Subscriptions::CallbackSubscription.new(topic, qos, callback);
 		register_subscription(subObject);
 
 		return subObject;
 	end
 	alias subscribeTo subscribe_to
 
+	# @!endgroup
 
+	# Publish a message to topic.
+	# @param topic [String] The topic to push to.
+	# @param data [String] The data to be transmitted.
+	# @param qos [nil, Numeric] QoS for the publish. Currently not fully supported by the mqtt gem.
+	# @param retain [nil, Boolean] retain-flag for the publish.
 	def publish_to(topic, data, qos: 1, retain: false)
 		raise ArgumentError, "Wrong symbol in topic: #{topic}" if topic =~ /[#\+]/
 
@@ -186,6 +257,9 @@ class SubHandler
 	end
 	private :mqtt_resub_thread
 
+	# Pause the main thread and wait for messages.
+	# This is mainly useful when the code has set everything up, but doesn't just want to end.
+	# "INT" is trapped, ensuring a smooth exit on Ctrl-C
 	def lockAndListen()
 		Signal.trap("INT") {
 			exit 0
@@ -213,8 +287,14 @@ class SubHandler
 			end
 		end
 	end
-
-	def initialize(mqttClient, autoListen: true)
+	private :flush_pubqueue
+
+	# Initialize a new MQTT::SubHandler
+	# The handler immediately connects to the server, and begins receciving and sending.
+	# @param mqttClient [String, MQTT::Client] Either a URI to connect to, or a MQTT::Client
+	#  The URI can be of the form "mqtts://Password@User:URL:port"
+	#  The MQTT client instance can be fully configured, as specified by the MQTT Gem. It must **not** already be connected!
+	def initialize(mqttClient)
 		@callbackList = Array.new();
 		if mqttClient.is_a? String then
 			@mqtt = MQTT::Client.new(mqttClient);

data/lib/mqtt/subscription_classes.rb

@@ -2,74 +2,77 @@
 require 'mqtt/Waitpoint.rb'
 
 module MQTT
-	class Subscription
-		attr_reader :topic
-		attr_reader :qos
-		attr_reader :topic_split
-
-		def initialize(topic, qos)
-			@topic 		 = topic;
-			@topic_split = SubHandler.getTopicSplit(topic);
+	module Subscriptions
+		# @abstract Basis for custom MQTT::Subcription objects
+		class Subscription
+			attr_reader :topic
+			attr_reader :qos
+			attr_reader :topic_split
+
+			def initialize(topic, qos)
+				@topic 		 = topic;
+				@topic_split = SubHandler.getTopicSplit(topic);
+
+				@qos 			= 0;
+			end
 
-			@qos 			= 0;
+			def offer(topicList, data) end
 		end
 
-		def offer(topicList, data) end
-	end
+		class CallbackSubscription < Subscription
+			def initialize(topic, qos, callback)
+				super(topic, qos);
 
-	class CallbackSubscription < Subscription
-		def initialize(topic, qos, callback)
-			super(topic, qos);
-
-			@callback  	= callback;
-		end
-		def offer(topicList, data)
-			@callback.call(data, topicList);
+				@callback  	= callback;
+			end
+			def offer(topicList, data)
+				@callback.call(data, topicList);
+			end
 		end
-	end
 
-	class WaitpointSubscription < Subscription
-		attr_reader :waitpoint
+		class WaitpointSubscription < Subscription
+			attr_reader :waitpoint
 
-		def initialize(topic, qos)
-			super(topic, qos);
+			def initialize(topic, qos)
+				super(topic, qos);
 
-			@waitpoint 	 = Xasin::Waitpoint.new();
-		end
+				@waitpoint 	 = Xasin::Waitpoint.new();
+			end
 
-		def offer(topicList, data)
-			@waitpoint.fire([topicList, data]);
+			def offer(topicList, data)
+				@waitpoint.fire([data, topicList]);
+			end
 		end
-	end
 
-	class ValueTrackerSubscription < Subscription
-		attr_reader :value
+		class ValueTrackerSubscription < Subscription
+			attr_reader :value
 
-		def initialize(topic, qos = 1)
-			raise ArgumentError, "Tracking of topic wildcards is prohibited! Topic: #{topic}" if topic =~ /[#\+]/
-			super(topic, qos);
+			def initialize(topic, qos = 1)
+				raise ArgumentError, "Tracking of topic wildcards is prohibited! Topic: #{topic}" if topic =~ /[#\+]/
+				super(topic, qos);
 
-			@value = nil;
+				@value = nil;
 
-			@callbackList = Array.new();
-		end
+				@callbackList = Array.new();
+			end
 
-		def offer(topicList, data)
-			return if data == @value;
+			def offer(topicList, data)
+				return if data == @value;
 
-			@callbackList.each do |cb|
-				cb.call(data, @value);
+				@callbackList.each do |cb|
+					cb.call(data, @value);
+				end
+				@value = data;
 			end
-			@value = data;
-		end
 
-		def attach(callback)
-			@callbackList << callback;
-			callback.call(@value, nil) if(@value);
-			return callback;
-		end
-		def detach(callback)
-			@callbackList.delete callback;
+			def attach(callback)
+				@callbackList << callback;
+				callback.call(@value, nil) if(@value);
+				return callback;
+			end
+			def detach(callback)
+				@callbackList.delete callback;
+			end
 		end
 	end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mqtt-sub_handler
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Xasin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-10 00:00:00.000000000 Z
+date: 2018-02-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mqtt
@@ -24,12 +24,14 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.5.0
-description: A gem to use when the normal ruby mqtt doesn't hit the spot.
+description: Asynchronous handling of callbacks that can be attached to individual
+  topics, based on the mqtt gem.
 email: 
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - lib/mqtt/Waitpoint.rb
 - lib/mqtt/sub_handler.rb
 - lib/mqtt/subscription_classes.rb