tef-furcoms 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c612206f7e17733552bcca965b3e2684a5ba17c9
-  data.tar.gz: 6bde1a400cb7e6f6fedbe93f50a0ae0550830e1e
+  metadata.gz: 2d1cff2d52f453c7c95ed031309ad6d24c397f84
+  data.tar.gz: d61410a2fe3d4618b8619a658505e56804c6e732
 SHA512:
-  metadata.gz: bc921df1642b8f5ac7cea97fae3080f40c107621c9ae70a7e51fb42a21e14416a67ff64a2e3899d594da5e6721f688e3e2a1322875c6488d293d8b2280b8becd
-  data.tar.gz: 6a1508a0ec5f87fb9c51e43344987f707faa767caebb3095967eba446fe80d3a8dc539a5da8ee9ab0fa9f74d36cf736c1bd5d0200429dc7673ce34905d6babf1
+  metadata.gz: 26ca8a0c9c65b4069bcd93a93a351c9a18453ebea0ef2f58fdd8d1c8537507eac7499c56e91e6d246f0bdb720df1e8f8d5d9aa4bd111fde50bb757cc9ce30fd2
+  data.tar.gz: 15d07676bf346fc3f096cd681425b9a44948fec6726d5e3cf6aaf0efadc48b8df5b98f850c001704ede71dc5dec35e792e962a4496f477630e82383bdefefd9b

data/README.md

@@ -1,6 +1,50 @@
 
 # TheElectricFursuit FurComs
 
-This... Is a stub for now. Stay tuned for documentation!
-OR!
-Head to github.com/Xasin/system-synth-suit/Ruby/VoiceControl and see how this works.
+This gem is the link between a FurComs hardware bus and your ruby code!
+It provides a standardized interface for sending and receiving messages, using
+a large variety of channels to connect to a FurComs bus.
+
+In its current state, it provides the following options:
+- A direct FurComs connection via a USB to UART adapter.  
+  This does not provide arbitration, but is perfect for testing, as
+  well as read-only access.
+- Two MQTT Briding classes to connect a Serial FurComs connection
+  to a broker, and to access the FurComs bus via MQTT.
+
+In upcoming versions there will be other options available, such as
+using a STM32 as translator to the computer, providing true arbitration.
+
+### Quickstart:
+
+Let's give a short and sweet example. Here, we will try to connect to a FurComs bus using a USB to UART adapter connected to `/dev/ttyACM0` and send and receive a few messages.
+
+```Ruby
+require 'tef/furcoms.rb'
+
+coms_interface = TEF::FurComs::Serial.new('/dev/ttyACM0');
+
+coms_interface.on_message /^Topic_Regexp(\d)/ do |data, topic|
+	puts "Got some data on #{topic}!"
+end
+
+coms_interface.send_message 'Topic_Regexp1234', 'Henlo yes!'
+```
+
+And that's all you need!
+
+If you want to use MQTT you'll need to do the following instead:
+```Ruby
+require 'mqtt/sub_handler.rb' # Comes from the mqtt-sub_handler gem, which is not a dependency of this FurComs gem!
+
+require 'tef/furcoms.rb'
+
+mqtt = MQTT::SubHandler.new('your.broker.address');
+
+coms_interface = TEF::FurComs::SerialToMQTT.new('/dev/ttyACM0', mqtt, 'FurComs/MyTopic/');
+# Leaving out the topic will instead use 'FurComs/DEVNAME', in this case FurComs/ttyACM0
+
+coms_over_mqtt = TEF::FurComs::MQTT.new(mqtt, 'FurComs/MyTopic/');
+```
+
+The SerialToMQTT and MQTT classes have the same interface functions as the Serial class, and can be used interchangeably!

data/lib/tef/furcoms.rb

@@ -1,3 +1,3 @@
 
-require_relative 'furcoms/SerialToMQTT.rb'
-require_relative 'furcoms/MQTT.rb'
+require_relative 'furcoms/serial_to_mqtt.rb'
+require_relative 'furcoms/mqtt.rb'

data/lib/tef/furcoms/base.rb

@@ -0,0 +1,78 @@
+
+
+# TheElectricFursuits Ruby namespace.
+# @see https://github.com/TheElectricFursuits/
+module TEF
+	# Module for all classes related to the FurComs communication bus.
+	# @see https://github.com/TheElectricFursuits/tef-FurComs
+	module FurComs
+		# Base class for a FurComs bus.
+		#
+		# This base class represents a single, bidirectional connection
+		# point to a FurComs bus. It provides function prototypes for sending
+		# and receiving messages that shall be overloaded by actual implementations.
+		#
+		# @author The System (Neira)
+		#
+		# @see Serial
+		# @see MQTT
+		class Base
+			# Initialize an empty base class.
+			#
+			# Note that this class cannot be used for communication!
+			def initialize()
+				@message_procs = [];
+			end
+
+			# Send a message to the FurComs bus.
+			#
+			# This will send a message onto topic, using the given
+			# priority and chip_id (defaulting both to 0).
+			#
+			# @param topic [String] Topic to send the message onto
+			# @param message [String] Binary string of data to send, expected
+			#   to be ASCII-8 encoded, can contain any character (including null)
+			def send_message(topic, message, priority: 0, chip_id: 0) end
+
+			# Add a message callback.
+			#
+			# Calling this function with a block will add a callback to received
+			# messages. Any new message that is received will be passed to the
+			# callback.
+			# @param topic_filter [String, RegExp] Optional topic filter to use,
+			#   either a String (for exact match) or Regexp
+			# @yieldparam data [String] Raw data received from the FurComs bus.
+			#   ASCII-8 encoded, may contain any binary character.
+			# @yieldparam topic [String] Topic string that this message was received on.
+			def on_message(topic_filter = nil, &block)
+				o_msg = { topic: topic_filter, block: block };
+				@message_procs << o_msg;
+
+				o_msg
+			end
+
+			# @private
+			# Internal function used merely to cleanly hand out received data
+			# to message callbacks.
+			private def handout_data(topic, data)
+				x_logd("Data received on #{topic}: #{data}")
+
+				@message_procs.each do |callback|
+					begin
+						if (filter = callback[:topic])
+							if filter.is_a? String
+								next unless topic == filter
+							elsif filter.is_a? RegExp
+								next unless filter.match(topic)
+							end
+						end
+
+						callback[:block].call(data, topic)
+					rescue => e
+						x_logf("Error in callback #{callback[:block]}: #{e}");
+					end
+				end
+			end
+		end
+	end
+end

data/lib/tef/furcoms/mqtt.rb

@@ -0,0 +1,60 @@
+
+require_relative 'base.rb'
+
+require 'xasin_logger'
+
+module TEF
+	module FurComs
+		# FurComs MQTT wrapper
+		#
+		# This class will connect to a MQTT Broker, and use it as a bridge
+		# to a FurComs hardware connection.
+		# This allows multiple different systems to access different busses remotely,
+		# and has the added benefit of allowing Read/Write restrictions using
+		# the MQTT built-in authentication.
+		class MQTT < Base
+			include XasLogger::Mix
+
+			# Initialize a new FurComs MQTT Bridge.
+			#
+			# This will subscribe to the topic: topic + 'Received/#', and will
+			# being relaying messages to the attached callbacks immediately.
+			# Messages it wants to send will be sent to topic + 'Send/#{msg_topic}'
+			#
+			# If no MQTT to FurComs is attached to the bus, the message will be lost!
+			#
+			# @param mqtt The MQTT handler. Must support subscribe_to and publish_to.
+			#   A fitting gem would be mqtt-sub_handler.
+			# @param topic [String] Topic base. Must end with /
+			def initialize(mqtt, topic = 'FurComs/ttyACM0/')
+				super();
+
+				@mqtt = mqtt;
+				@mqtt_topic = topic;
+
+				@mqtt.subscribe_to topic + 'Received/#' do |data, msg_topic|
+					msg_topic = msg_topic.join('/')
+					next unless msg_topic =~ /^[\w\s\/]*$/
+
+					handout_data(msg_topic, data);
+				end
+
+				init_x_log(@mqtt_topic)
+			end
+
+			# (see Base#send_message)
+			def send_message(topic, data, priority: 0, chip_id: 0)
+				unless topic =~ /^[\w\s\/]*$/
+					raise ArgumentError, 'Topic includes invalid characters!'
+				end
+				if (topic.length + data.length) > 250
+					raise ArgumentError, 'Message packet length exceeded!'
+				end
+
+				x_logd("Sending '#{topic}': '#{data}'")
+
+				@mqtt.publish_to @mqtt_topic + "Send/#{topic}", data
+			end
+		end
+	end
+end

data/lib/tef/furcoms/{Serial.rb → serial.rb}

@@ -1,29 +1,47 @@
 
-require_relative 'Base.rb'
+require_relative 'base.rb'
 
 require 'serialport'
 require 'xasin_logger'
 
 module TEF
 	module FurComs
+		# USB-To-Serial FurComs Bridge.
+		#
+		# This class will handle connecting to a FurComs bus using a standard
+		# USB-To-UART adapter, such as an FTDI-Chip, in order to send and
+		# receive messages.
+		#
+		# @note This class provides limited FurComs compatibility. Arbitration
+		#  handling is not possible, which may cause frequent collisions in busy
+		#  bus conditions. It is recommended to use a STM32 processor
+		#  that provides translation between FurComs and the computer.
 		class Serial < Base
 			include XasLogger::Mix
 
-			def initialize(port)
+			# Initialize a Serial bridge class.
+			#
+			# This will open the given Serial port and begin reading/writing
+			# onto the FurComs bus.
+			# @note This class can not provide full arbitration handling. This may
+			#   cause issues in busy bus conditions!
+			# @todo Add graceful handling of controller disconnect/reconnect.
+			def initialize(port = '/dev/ttyACM0', baudrate = 115_200)
 				super();
 
 				@port = SerialPort.new(port);
-				@port.baud = 115200;
+				@port.baud = baudrate;
 				@port.sync = true;
 
 				start_thread();
 
 				init_x_log("FurComs #{port}")
-				x_logi("Ready!");
+				x_logi('Ready!');
 			end
 
 			private def decode_data_string(data)
-				return if(data.length() < 9)
+				return if data.length() < 9
+
 				payload = data[8..-1]
 				topic, _sep, payload = payload.partition("\0")
 
@@ -40,11 +58,12 @@ module TEF
 					c = 0;
 
 					loop do
-						c = @port.getbyte
-						if c == 0
+						c = @port.getbyte # Blocks until byte is available on bus.
+
+						if c.zero? # 0x00 Indicates STOP
 							decode_data_string rx_buffer
 							rx_buffer = ''
-						elsif had_esc
+						elsif had_esc # ESC had been received, decode next byte.
 							case c
 							when 0xDC
 								rx_buffer += "\0"
@@ -52,9 +71,9 @@ module TEF
 								rx_buffer += "\xDB"
 							end
 							had_esc = false
-						elsif c == 0xDB
+						elsif c == 0xDB # SLIP ESC
 							had_esc = true
-						else
+						else # No special treatment needed, add byte.
 							rx_buffer += c.chr
 						end
 					end
@@ -65,7 +84,7 @@ module TEF
 
 			private def slip_encode_data(data_str)
 				data_str.bytes.map do |b|
-					if b == 0
+					if b.zero?
 						[0xDB, 0xDC]
 					elsif b == 0xDB
 						[0xDB, 0xDD]
@@ -75,6 +94,17 @@ module TEF
 				end.flatten
 			end
 
+			# @private
+			# Internal function to append/prepend the neccessary framing
+			# to be a FurComs message.
+			# This framing is:
+			# - 0x00 START
+			# - priority and chip_id fields
+			# - 0xFF latency
+			# - 24-bit arbitration collission map.
+			# - 0xFF latency
+			# - Modified SLIP-Encoded message data
+			# - 0x00 STOP
 			private def generate_furcom_message(priority, chip_id, data_str)
 				priority = ([[-60, priority].max, 60].min + 64) * 2 + 1;
 				chip_id = 0x1 | 0x100 | ((chip_id & 0xEF) << 9) | ((chip_id >> 6) & 0xEF);
@@ -85,12 +115,13 @@ module TEF
 				out_data
 			end
 
+			# (see Base#send_message)
 			def send_message(topic, message, priority: 0, chip_id: 0)
 				unless topic =~ /^[\w\s\/]*$/
-					raise ArgumentError, "Topic includes invalid characters!"
+					raise ArgumentError, 'Topic includes invalid characters!'
 				end
 				if (topic.length + message.length) > 250
-					raise ArgumentError, "Message packet length exceeded!"
+					raise ArgumentError, 'Message packet length exceeded!'
 				end
 
 				x_logd("Sending '#{topic}': '#{message}'")
@@ -98,7 +129,7 @@ module TEF
 				escaped_str = slip_encode_data "#{topic}\0#{message}"
 				out_data = generate_furcom_message priority, chip_id, escaped_str;
 
-				@port.write(out_data.pack("C2S<C*"))
+				@port.write(out_data.pack('C2S<C*'))
 
 				@port.flush
 			end

data/lib/tef/furcoms/serial_to_mqtt.rb

@@ -0,0 +1,58 @@
+
+require_relative 'serial.rb'
+
+module TEF
+	module FurComs
+		# FurComs SerialToMQTT Bridge.
+		#
+		# This class will extend {FurComs::Serial} with a few internal functions
+		# to bridge the FurComs bus connection to MQTT.
+		#
+		# @note This class suffers from the same restrictions as the {Serial} class.
+		#   Use a different PC to FurComs connection if possible!
+		#
+		# @see Serial
+		class SerialToMQTT < Serial
+			# Initialize a Serial To MQTT bridge instance.
+			#
+			# This will open the given Serial port and begin reading/writing
+			# onto the FurComs bus.
+			# It will additionally subscribe to the MQTT 'topic',
+			# or 'FurComs/#{topic}/Send/#' using the /dev/DEVICE part of the port
+			# argument if topic is left nil.
+			# Any message received on this topic will be sent as FurComs messages.
+			#
+			# Received messages are first handed out to internal callbacks,
+			# and will then be sent off to 'FurComs/#{topic}/Received/#{msg_topic}'
+			#
+			# @note This class can not provide full arbitration handling. This may
+			#   cause issues in busy bus conditions!
+			# @param port [String] Device port to use for the FurComs connection
+			# @param mqtt MQTT Handler class. Must support subscribe_to
+			#  and publish_to
+			# @param topic [nil, String] MQTT topic to use for receiving and sending.
+			#  must end with a '/'
+			def initialize(port, mqtt, topic = nil)
+				super(port);
+
+				@mqtt = mqtt;
+				@mqtt_topic = topic || "FurComs/#{port.sub('/dev/', '')}/";
+
+				@mqtt.subscribe_to @mqtt_topic + 'Send/#' do |data, msg_topic|
+					msg_topic = msg_topic.join('/')
+
+					next if data.length + msg_topic.length > 250
+					next unless msg_topic =~ /^[\w\s\/]*$/
+
+					send_message msg_topic, data
+				end
+			end
+
+			private def handout_data(topic, data)
+				super(topic, data);
+
+				@mqtt.publish_to @mqtt_topic + "Received/#{topic}", data
+			end
+		end
+	end
+end

metadata

@@ -1,46 +1,46 @@
 --- !ruby/object:Gem::Specification
 name: tef-furcoms
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - TheSystem
-- Xasin
+- Neira
 autorequire: 
 bindir: bin
 cert_chain: []
 date: 2020-05-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: serialport
+  name: mqtt-sub_handler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '0.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '0.1'
 - !ruby/object:Gem::Dependency
-  name: xasin-logger
+  name: serialport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '1.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '1.3'
 - !ruby/object:Gem::Dependency
-  name: mqtt-sub_handler
+  name: xasin-logger
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -75,11 +75,11 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/tef/furcoms.rb
-- lib/tef/furcoms/Base.rb
-- lib/tef/furcoms/MQTT.rb
-- lib/tef/furcoms/Serial.rb
-- lib/tef/furcoms/SerialToMQTT.rb
-homepage: 
+- lib/tef/furcoms/base.rb
+- lib/tef/furcoms/mqtt.rb
+- lib/tef/furcoms/serial.rb
+- lib/tef/furcoms/serial_to_mqtt.rb
+homepage: https://github.com/TheElectricFursuits/tef-FurComs
 licenses:
 - GPL-3.0
 metadata: {}

data/lib/tef/furcoms/Base.rb

@@ -1,48 +0,0 @@
-
-
-module TEF
-	module FurComs
-		class Message
-			attr_reader :priority
-			attr_reader :source_id
-
-			attr_reader :topic
-			attr_reader :data
-
-			def initialize()
-			end
-		end
-
-		class Base
-			def initialize()
-				@message_procs = [];
-			end
-
-			def send_message(topic, message, priority: 0, chip_id: 0) end
-
-			def on_message(topic_filter = nil, &block)
-				@message_procs << { topic: topic_filter, block: block };
-			end
-
-			private def handout_data(topic, data)
-				x_logd("Data received on #{topic}: #{data}")
-
-				@message_procs.each do |callback|
-					begin
-						if filter = callback[:topic]
-							if filter.is_a? String
-								next unless topic == filter
-							elsif filter.is_a? RegExp
-								next unless filter.match(topic)
-							end
-						end
-
-						callback[:block].call(data, topic)
-					rescue => e
-						x_logf("Error in callback #{callback[:block]}: #{e}");
-					end
-				end
-			end
-		end
-	end
-end

data/lib/tef/furcoms/MQTT.rb

@@ -1,41 +0,0 @@
-
-require_relative 'Base.rb'
-
-require 'xasin_logger'
-
-module TEF
-	module FurComs
-		class MQTT < Base
-			include XasLogger::Mix
-
-			def initialize(mqtt, topic = 'FurComs/ttyACM0/')
-				super();
-
-				@mqtt = mqtt;
-				@mqtt_topic = topic;
-
-				@mqtt.subscribe_to topic + 'Received/#' do |data, topic|
-					topic = topic.join('/')
-					next unless topic =~ /^[\w\s\/]*$/
-
-					handout_data(topic, data);
-				end
-
-				init_x_log(@mqtt_topic)
-			end
-
-			def send_message(topic, data, priority: 0, chip_id: 0)
-				unless topic =~ /^[\w\s\/]*$/
-					raise ArgumentError, "Topic includes invalid characters!"
-				end
-				if (topic.length + data.length) > 250
-					raise ArgumentError, "Message packet length exceeded!"
-				end
-
-				x_logd("Sending '#{topic}': '#{data}'")
-
-				@mqtt.publish_to @mqtt_topic + "Send/#{topic}", data
-			end
-		end
-	end
-end

data/lib/tef/furcoms/SerialToMQTT.rb

@@ -1,30 +0,0 @@
-
-require_relative 'Serial.rb'
-
-module TEF
-	module FurComs
-		class SerialToMQTT < Serial
-			def initialize(port, mqtt, topic = nil)
-				super(port);
-
-				@mqtt = mqtt;
-				@mqtt_topic = topic || "FurComs/#{port.sub('/dev/', '')}/";
-
-				@mqtt.subscribe_to @mqtt_topic + 'Send/#' do |data, topic|
-					topic = topic.join('/')
-
-					next if data.length + topic.length > 250
-					next unless topic =~ /^[\w\s\/]*$/
-
-					self.send_message topic, data
-				end
-			end
-
-			def handout_data(topic, data)
-				super(topic, data);
-
-				@mqtt.publish_to @mqtt_topic + "Received/#{topic}", data
-			end
-		end
-	end
-end