onkyo_eiscp_ruby 0.0.3 → 1.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: be075bcd7a1830e7614b8384d610ea59d0b7160f
-  data.tar.gz: 40cea299c77c937a786f387cfbf4c11e8696632c
+  metadata.gz: ab3d51dea59ba8c99a8782be06c6508cd3b37163
+  data.tar.gz: aa346aaa381eda5418f7d7233b475d9f54e04b51
 SHA512:
-  metadata.gz: 5066d43a66350cb39e84ddbae87038d4ba04057f2dd884eee1852c3dd108ed4a44842878157dfb854e7802d3e771cbe5789a70af936af0e338a36264e92332d6
-  data.tar.gz: 6c2c8bb4ba7d3b7e9fee332d448a054cf97480194192252965b363b7efaa8d8b095ae76d2f68ab6f064fbf68ec2bac75c63b2ba53a26e891b055c0751f776cc4
+  metadata.gz: 0c75784e4c01fe2ad2031933f5ea5f6204ccf81b543985a93dd2d301dac5e714aff529508d0fc3545013b7723fb84043f0405903e4444b8ca61635dab0ccdde4
+  data.tar.gz: 07aba89079c12e05b5eac6d4d475f7818568744d16d9c3196e714efff07b21f8c86308afdd8a6953a9b97045a26a146ca9dbac18f58e03a216368cc78ffdb293

data/README.md

@@ -1,21 +1,40 @@
 onkyo_eiscp_ruby
 ================
 [![Gem Version](https://badge.fury.io/rb/onkyo_eiscp_ruby.png)](http://badge.fury.io/rb/onkyo_eiscp_ruby)
+[![GitHub version](https://badge.fury.io/gh/mikerodrigues%2Fonkyo_eiscp_ruby.png)](http://badge.fury.io/gh/mikerodrigues%2Fonkyo_eiscp_ruby)
 
-A Ruby implementation of eISCP for controlling Onkyo receivers.
+*A Ruby implementation of eISCP for controlling Onkyo receivers.*
 
 **This code is still under heavy development and using it might make you sick.**
-Create ISCP messages and eISCP packets
-Automatically discover receiver's in the broadcast domain
-Send/Recieve eISCP messages
-Open a TCP socket to send commands and receive solicited and non-solicited status updates.
+
+Automatically discover receivers in the broadcast domain
+
+Send commands to receivers and parse returned messages
+
+Open a TCP socket to receive solicited and non-solicited status updates.
+
 Mock reciever (currently only responds to discovery)
 
+Human-readable commands
+
 **Inspired by https://github.com/miracle2k/onkyo-eiscp
 
 **Protocol information from http://michael.elsdoerfer.name/onkyo/ISCP-V1.21_2011.xls
 
+What's missing?
+---------------
+* Command validation
+
+* Parsing of all human readable commands (run the tests to see some commands that aren't parsable in human readable form yet.
 
+* Reasonable variants for human-readable commands (ex. `main-volume` or`volume
+` as opposed to `master-volume`)
+
+* Model compatability checking
+
+* Logging
+
+* Exhaustive testing and documentation
 
 Using the Library
 -----------------
@@ -23,53 +42,155 @@ Using the Library
 
 		require 'eiscp'
 
-* Discover local receivers
-
+* You might want to `include EISCP` if you know you won't pollute your namespace
+  with Constants under `EISCP` (`Dictionary`, `Message`, `Parser`, `Receiver`,
+  `VERSION`)
+
+* You can do most everything through the `Receiver` and `Message` objects. If you
+  want to accept user input you will probably want to use the Parser module. Be
+  sure to check out the RDocs or dig through the source code. I try to keep it
+  well commented/documented, and there's more functionality to the library than
+  is shown here:
+
+* The `Message` object is pretty self explanatory. `Message.new` is mostly used
+  internally, but you're better of using `Parser.parse` to create them. You
+  probably will want to interact with `Message` objects to get information:
+
+```ruby		
+		msg = EISCP::Message.new(command: 'PWR', value: '01')
+		msg.zone                => 'main'
+		msg.command             => "PWR"
+		msg.value               => "01"
+		msg.command_name        => "system-power"
+		msg.command_description => "System Power Command"
+		msg.value_name          => "on"
+		msg.value_description   => "sets System On"
+```
+
+* Discover local receivers (returns an `Array` of `Receiver` objects)
+
+```ruby		
 		EISCP::Receiver.discover
+```
 
-* Create Receiver object from first discovered
+* Create `Receiver` object from first discovered Receiver on the LAN
 
-		Receiver.new
+```ruby		
+		receiver = EISCP::Receiver.new
+```
 
-* Open a TCP connection to monitor solicited updates
+* Or create one manually by IP address or hostname
 
-		receiver = Receiver.new('10.0.0.1')
-		receiver.connect
+```ruby		
+		receiver = EISCP::Receiver.new('10.0.0.132')
+```
 
-* You can also pass a block and operate on received packet strings:
+* When you create a `Receiver` object, it uses the `Receiver::Connection` module to
+  make a connection and monitor incoming messages. By default, the last message
+  received can be retrieved with `receiver.last`. You can
+  pass your own block at creation time, it will have access to messages as they
+  come in. This will let you setup callbacks to run when messages are receivedL
 
-		receiver.connect do |data|
-		  puts EISCP::Receiver.parse(data).iscp_message
+```ruby
+		receiver = EISCP::Receiver.new do |msg|
+		  puts msg.command
+		  puts msg.value
 		end
+```
 
-* Turn on the receiver
+* You can also change the block later. This will kill the existing connection
+  thread (but not the socket) and start your new one:
 
-		message = EISCP::Message.parse("PWR", "01")
-		message.send(message.to_eiscp)
-
-* New 'parse' method makes creating EISCP objects more flexible.
-This parses messages from command line or raw eiscp data from the socket
-        
-		iscp_message = EISCP::Message.parse "PWR01"
-		iscp_message = EISCP::Message.parse "PWR 01"
-		iscp_message = EISCP::Message.parse "!1PWR01"
-		iscp_message = EISCP::Message.parse "!1PWR 01"
-
-* Parsing raw socket data
+```ruby		
+		receiver.update_thread do |msg|
+		  puts "Received: #{msg.command_name}:#{msg.value_name}"
+		end
+```
+
+* Get information about the Receiver:
+	
+```ruby		
+		receiver.model => "TX-NR609"
+		receiver.host  => "10.0.0.111"
+		receiver.port  => 60128
+		receiver.mac_address => "001122334455"
+		receiver.area => "DX"
+```
+
+* Get the last message received from the Receiver:
+
+```ruby		
+		receiver.last
+```
+
+* You can use `CommandMethods` to easily send a message and return the reply as
+  a Message object. A method is defined for each command listed in the
+  `Dictionary` using the `@command_name` attribute which is 'human readable'.
+  You can check the included yaml file or look at the output of 
+  `EISCP::Dictionary.commands`. Here a few examples:
+		
+```ruby		
+		# Turn on receiver
+		receiver.system_power "on"
+
+		# Query current input source
+		receiver.input_selector "query"
+		
+		# Turn the master volume up one level
+		receiver.master_volume "level-up"
+
+		# Set the master volume to 45
+		receiver.master_volume "45"
+```
+
+* Parse ISCP and human readable strings:
+
+```ruby     		
+		# Parse various ISCP strings 
+		iscp_message = EISCP::Parser.parse "PWR01"
+		iscp_message = EISCP::Parser.parse "PWR 01"
+		iscp_message = EISCP::Parser.parse "!1PWR01"
+		iscp_message = EISCP::Parser.parse "!1PWR 01"
+
+		# Parse human readable,
+		EISCP::Parser.parse("main-volume 34")
+```
+
+* `Parser.parse` is also used internally by `Receiver` to parse raw eISCP socket
+  data.
 
-		iscp_message_from_raw_eiscp = EISCP::Message.parse iscp_message.to_eiscp
 
 Using the Binaries
 ------------------
 
 * Discover local receivers
 
-		$ onkyo.rb -d
+	`$ onkyo.rb -d`
+		
+* Send a human-readable command
+
+	`$ onkyo.rb system-power on  # uses Command.parse`
+
+* Or send a raw command
 
-* Connect to the first discovered receiver to see status updates
+	`$ onkyo.rb PWRQSTN   # Also tries to use Message.parse`
 
-		$ onkyo.rb -c
+* Monitor the first discovered receiver to see status updates
+
+	`$ onkyo.rb -m`
 
 * Start the mock server (only responds to 'ECNQSTN')
 
-		$ onkyo-server.rb
+	`$ onkyo-server.rb`
+
+* Turn off the first receiver discovered:
+
+	`$ onkyo.rb system-power off`
+
+Contributing
+------------
+
+* Open an issue describing bug or feature
+* Fork repo
+* Create a branch
+* Send pull request

data/VERSION

@@ -1 +1 @@
-0.0.3
+1.0.4

data/bin/mock_receiver.rb

@@ -0,0 +1,23 @@
+require 'socket'
+require_relative './receiver'
+require_relative './message'
+
+# Mock server that only responds to ECNQSTN.
+
+module EISCP
+  # This class acts as an Onkyo Stereo. It can be used for testing
+  #
+  class MockReceiver
+    DISCOVERY_IP = '255.255.255.255'
+    ONKYO_DISCOVERY_RESPONSE =  Message.new('ECN', "TX-NR609/60128/DX/14DAE9E967C8\x19\r\n\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00")
+
+    # Create/start the server object.
+
+    def initialize
+      Socket.udp_server_loop(DISCOVERY_IP, Receiver::ONKYO_PORT) do |msg, src|
+        src.reply "ISCP\x00\x00\x00\x10\x00\x00\x00&\x01\x00\x00\x00!1ECNTX-NR609/60128/DX/14DAE9E967C8\x19\r\n\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"
+        puts msg
+      end
+    end
+  end
+end

data/bin/onkyo.rb

@@ -3,6 +3,9 @@
 require 'eiscp'
 require 'optparse'
 require 'ostruct'
+
+# This object parses ARGV and returns an @option hash
+#
 class Options
   DEFAULT_OPTIONS = { verbose: true, all: false }
   USAGE = ' Usage: onkyo_rb [options]'
@@ -34,53 +37,77 @@ class Options
         @options.list_all = l
       end
 
-      opts.on '-c', '--connect', 'Connect to the first discovered reciever and show updates' do |c|
-        @options.connect = c
+      opts.on '-m', '--monitor', 'Connect to the first discovered reciever and monitor updates' do |m|
+        @options.monitor = m 
       end
 
     end
 
     options.parse!(args)
 
-    if @options == nil && ARGV == []
-      puts options
-    end
+    if @options.nil? && ARGV == [] then puts options end
 
     if @options.discover
-      EISCP::Receiver.discover.each do |receiver|
-        puts  EISCP::Message.parse(receiver[0]).to_iscp
-      end
+      EISCP::Receiver.discover.each {|rec| puts "#{rec.host}:#{rec.port} - #{rec.model} - #{rec.mac_address}"}
       exit 0
     end
 
     if @options.help
       puts options
-      exit 0 
+      exit 0
     end
 
-    if @options.connect
-      eiscp = EISCP::Receiver.new(EISCP::Receiver.discover[0][1])
-      eiscp.connect do |data|
-        puts msg = EISCP::Receiver.parse(data).to_iscp
+    if @options.monitor
+      begin
+        rec = EISCP::Receiver.new do |reply| 
+          puts "Response:   "\
+               "#{reply.zone.capitalize}: "\
+               "#{reply.command_description || reply.command} "\
+               "-> #{reply.value_description || reply.value}"
+        end
+        rec.thread.join
+      rescue Interrupt
+        fail 'Exiting...'
+      rescue Exception => e
+        puts "bummer..."
+        puts e
       end
     end
 
+    if @options.list_all
+      EISCP::Dictionary.zones.each do |zone|
+        EISCP::Dictionary.commands[zone].each do |command, command_hash|
+          puts "Command - Description"
+          puts "\n"
+          puts "  '#{Dictionary.name_from_command(command)}' - "\
+            "#{Dictionary.description_from_command(command)}"
+          puts "\n"
+          puts "    Value - Description>"
+          puts "\n"
+          command_hash[:values].each do |value, attr_hash| 
+            puts "      '#{attr_hash[:name]}' - "\
+              " #{attr_hash[:description]}"
+          end
+          puts "\n"
+        end
+      end
+      exit 0
+    end
+
     if ARGV == []
       puts options
       exit 0
     end
   end
-
 end
 
-
 @options = Options.parse(ARGV)
 
-
-receiver = EISCP::Receiver.new(EISCP::Receiver.discover[0][1])
-message = (EISCP::Message.parse(ARGV.join(" ")).to_eiscp)
-puts receiver.send_recv message
-
-
-
-
+receiver = EISCP::Receiver.discover[0]
+begin
+  command = EISCP::Parser.parse(ARGV.join(' '))
+rescue
+  raise "Couldn't parse command"
+end
+reply = receiver.send_recv(command)
+puts "Response from #{Receiver.host}: #{reply.zone.capitalize}   #{reply.command_description || reply.command} -> #{reply.value_description || reply.value}"

data/bin/{onkyo-server.rb → onkyo_server.rb}

@@ -2,6 +2,6 @@
 
 require 'eiscp/mock_receiver'
 
-puts "Starting server on 60128..."
+puts 'Starting server on 60128...'
 
 EISCP::MockReceiver.new