onkyo_eiscp_ruby 0.0.2 → 2.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a4b06cd590c97b2221cbb2aea133003a16d59c0ad917c48e3cba7ee0758e9c88
+  data.tar.gz: a0eae4abe4ec00ea74db045b4218b6e7adc86f4aefa839e9faa53eee0d135598
+SHA512:
+  metadata.gz: 7b2274ea6e68eb2405c32aa4db290621a49bddfdb4b8550d76da52013981691c783b9b03088e6fde4f845ab18a5d858a3bf145cf4a7d60e2ae4531bb4fcecfa4
+  data.tar.gz: bd9fa98a349f0eee2dfb80f7c46c8f8ae5ba0a624f6563bd43983cc2d9cf531f0a57095f2db0eb5d7b68232b97bdbda25f1585930b858c4177af0c5a3d2a96f0

data/README.md

@@ -1,41 +1,225 @@
 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.
-* Mock reciever (currently only responds to discovery)
+**This code is not really still under development and using it might still make you sick.**
+
+**The python version linked below sees much more activity.**
+
+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
 
-Usage
-________________
+**Protocol information from http://michael.elsdoerfer.name/onkyo/ISCP-V1.21_2011.xls
 
-	# require the library
+What's missing?
+---------------
+* Command validation
 
-	require 'eiscp'
+* 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
+-----------------
+* require the library
+
+		require 'eiscp'
+
+* 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 off 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 Receiver on the LAN
+
+```ruby		
+		receiver = EISCP::Receiver.new
+```
+
+* Or create one manually by IP address or hostname
+
+```ruby		
+		receiver = EISCP::Receiver.new('10.0.0.132')
+```
+
+* When you create a `Receiver` object with a callback block it will
+  connect and call your block on each message received.:
+
+```ruby
+		receiver = EISCP::Receiver.new do |msg|
+		  puts msg.command
+		  puts msg.value
+		end
+```
+
+* Receivers created without a block will not connect automatically. You can use
+  the `connect` method to create a socket and connect to the receiver.
+
+```ruby
+		receiver.connect
+```
+
+* You can also set or change the callback block later. This will kill the 
+  existing callback thread, recreate the socket if necessary and start
+  a new callback thread using the provided block:
+
+```ruby		
+		receiver.connect do |msg|
+		  puts "Received: #{msg.command_name}:#{msg.value_name}"
+		end
+```
+
+* You can also disconnect, which will close the socket and kill the connection
+  thread:
+
+```ruby
+		receiver.disconnect
+```
+
+* Get information about the Receiver:
 	
-	# Discover local receivers
-	EISCP.discover
-	
-	
-	# Open a TCP connection to monitor solicited updates
-	eiscp = EISCP.new('10.0.0.1')
-	eiscp.connect
-
-	# You can also pass a block and operate on received packet strings:
-	eiscp.connect do |data|
-	  puts EISCPPacket.parse(data).iscp_message
-	end
-
-	# Turn on the receiver
-	iscp_message = ISCPMessage.new("PWR", "01")
-	eiscp_packet = EISCPPacket.new(iscp_message.message)
-	eiscp.send(eiscp_packet.to_s)
-	
+```ruby		
+		receiver.model => "TX-NR609"
+		receiver.host  => "10.0.0.111"
+		receiver.port  => 60128
+		receiver.mac_address => "001122334455"
+		receiver.area => "DX"
+```
+
+* Receivers now have a `@state` hash that contains a mapping of commands and
+  values received. You can use this see the Receiver's last known state without
+  querying. Use the `#update_state` method to run every 'QSTN' command in the
+  Dictionary and update the state hash, but do note that it will take a few
+  seconds to finish:
+
+```ruby
+		receiver.update_state
+		receiver.state["MVL"] => "22"
+		receiver.human_readable_state["master-volume"] => 34
+```
+		
+
+* You can use `CommandMethods` to easily send a message and return the reply as
+  a Message object. Once `Receiver#connect`is called, 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.
+
+
+Using the Binaries
+------------------
+
+* Discover local receivers
+
+	`$ onkyo.rb -d`
+		
+* Send a human-readable command
+
+	`$ onkyo.rb system-power on  # uses Parser.parse`
+
+* Or send a raw command
+
+	`$ onkyo.rb PWRQSTN   # Also tries to use Parser.parse`
+
+* Monitor the first discovered receiver to see status updates
+
+	`$ onkyo.rb -m`
+
+* Start the mock server (only responds to 'ECNQSTN')
+
+	`$ onkyo-server.rb`
+
+* Turn off the first receiver discovered:
+
+	`$ onkyo.rb system-power off`
+
+* List all known commands and values:
+
+	`$ onkyo.rb -L`
+
+* List all known commands known to work with discovered models:
+
+	`$ onkyo.rb -l`
+
+Contributing
+------------
 
+* Open an issue describing bug or feature
+* Fork repo
+* Create a branch
+* Send pull request

data/VERSION

@@ -1 +1 @@
-0.0.2
+2.1.1

data/bin/mock_receiver.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+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

@@ -1,18 +1,20 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'eiscp'
 require 'optparse'
 require 'ostruct'
 
+# This object parses ARGV and returns an @option hash
+#
 class Options
-  DEFAULT_OPTIONS = { verbose: true, all: false }
+  DEFAULT_OPTIONS = { verbose: true, all: false }.freeze
   USAGE = ' Usage: onkyo_rb [options]'
 
   def self.parse(args)
     @options = OpenStruct.new
 
     options = OptionParser.new do |opts|
-
       opts.banner = USAGE
 
       opts.on '-d', '--discover', 'Find Onkyo Receivers on the local broadcast domain' do |d|
@@ -35,33 +37,91 @@ 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
+    puts options if @options.nil? && ARGV == []
 
     if @options.discover
-      EISCP.discover.each do |receiver|
-        puts  EISCPPacket.parse(receiver[0]).to_s
-      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.new(EISCP.discover[0][1])
-      eiscp.connect
+    if @options.monitor
+      begin
+        rec = EISCP::Receiver.new do |reply|
+          puts "#{Time.now} #{rec.host} "\
+               "#{reply.zone}: "\
+               "#{reply.command_description || reply.command} "\
+               "-> #{reply.value_description || reply.value}"
+        end
+        rec.thread.join
+      rescue Interrupt
+        raise 'Exiting...'
+      rescue Exception => e
+        puts 'bummer...'
+        puts e
+      end
+    end
+
+    if @options.list
+      models =  []
+      modelsets = []
+      EISCP::Receiver.discover.each do |rec|
+        models << rec.model
+      end
+      models.each do |model|
+        EISCP::Dictionary.modelsets.each do |modelset, list|
+          modelsets << modelset unless list.select { |x| x.match model }.empty?
+        end
+      end
+      EISCP::Dictionary.zones.each do |zone|
+        EISCP::Dictionary.commands[zone].each do |command, command_hash|
+          puts 'Command - Description'
+          puts "\n"
+          puts "  '#{Dictionary.command_to_name(command)}' - "\
+            "#{Dictionary.description_from_command(command)}"
+          puts "\n"
+          puts '    Value - Description>'
+          puts "\n"
+          command_hash[:values].each do |_value, attr_hash|
+            if modelsets.include? attr_hash[:models]
+              puts "      '#{attr_hash[:name]}' - "\
+                " #{attr_hash[:description]}"
+            end
+          end
+          puts "\n"
+        end
+      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.command_to_name(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 == []
@@ -69,16 +129,18 @@ class Options
       exit 0
     end
   end
-
 end
 
+include EISCP
 
 @options = Options.parse(ARGV)
 
-
-eiscp = EISCP.new(EISCP.discover[0][1])
-eiscp.send_recv(EISCPPacket.new(ISCPMessage.new(ARGV[0], ARGV[1]).message).to_s)
-
-
-
-
+receiver = EISCP::Receiver.discover[0]
+receiver.connect
+begin
+  command = EISCP::Parser.parse(ARGV.join(' '))
+rescue StandardError
+  raise "Couldn't parse command"
+end
+reply = receiver.send_recv(command)
+puts "#{Time.now}: Response from #{receiver.host}: #{reply.zone.capitalize}   #{reply.command_description || reply.command} -> #{reply.value_description || reply.value}"

data/bin/onkyo_server.rb

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'eiscp/mock_receiver'
+
+puts 'Starting server on 60128...'
+
+EISCP::MockReceiver.new