README.rdoc in launchpad-0.0.2 vs README.rdoc in launchpad-0.1.0

@@ -1,24 +1,71 @@
 = launchpad
 
-This gem provides an interface to access novation's launchpad programmatically. LEDs can be lighted and button presses can be evaluated using launchpad's MIDI input/output.
+This gem provides an interface to access novation's launchpad programmatically. LEDs can be lighted and button presses can be responded to. Internally, launchpad's MIDI input/output is used to accomplish this.
 
-This is the first version, nothing sophisticated, but you can access the launchpad already. In and out. The API might change quite a bit during the next releases, so don't rely on it, this is work in progress. If you need anything or think the interface could be improved in any way, please contact me.
+The interfaces should be rather stable now, so experiment with them and comment on their usability. This still is work in progress. If you need anything or think the interfaces could be improved in any way, please contact me.
 
-Sometimes, the launchpad won't react to anything. Don't despair, just dis- and reconnect the thing. It seems that some (unexpected) MIDI signals make it hickup.
+Sometimes, the launchpad won't react to anything or react to/light up the wrong LEDs. Don't despair, just dis- and reconnect the thing. It seems that some (unexpected) MIDI signals make it hickup.
 
 
 == Requirements
 
-* Jan Krutisch's portmidi gem
-* Roger B. Dannenberg's portmidi library
+* Roger B. Dannenberg's {portmidi library}[http://sourceforge.net/projects/portmedia/]
+* Jan Krutisch's {portmidi gem}[http://github.com/halfbyte/portmidi]
 
 
+== Installation
+
+The gem is hosted on Gemcutter[http://gemcutter.org/], so in order to use it, you're gonna install the gemcutter gem (for details, see their site):
+
+  gem install gemcutter
+  gem tumble
+
+After that, it's a simple gem install:
+
+  gem install launchpad
+
+
+== Usage
+
+There are two main entry points:
+
+* require 'launchpad/device', providing Launchpad::Device, which handles all the basic input/output stuff
+* require 'launchpad/interaction' or just 'launchpad', additionally providing Launchpad::Interaction, which lets you respond to actions (button presses/releases)
+
+This is a simple example (only requiring the device for output) that switches on all LEDs (for testing), resets the launchpad again and then lights the grid button at position 4/4 (from top left).
+
+  require 'rubygems'
+  require 'launchpad/device'
+  
+  device = Launchpad::Device.new
+  device.test_leds
+  sleep 1
+  device.reset
+  sleep 1
+  device.change :grid, :x => 4, :y => 4, :red => :high, :green => :low
+
+This is an interaction example lighting all grid buttons in red when pressed and keeping them lit.
+
+  require 'rubygems'
+  require 'launchpad'
+  
+  interaction = Launchpad::Interaction.new
+  interaction.response_to(:grid, :down) do |interaction, action|
+    interaction.device.change(:grid, action.merge(:red => :high))
+  end
+  
+  interaction.start
+
+
+For more details, see the examples. examples/color_picker.rb is the most complex example with interaction.
+
+
 == Near future plans
 
-* dedicated interaction with control buttons (top and right row)
-* listeners for presses on single buttons/button areas
-* double buffering (already there but has some glitches)
+* close devices properly as soon as halfbyte's pulled my changes to portmidi
+* interaction responses for presses on single grid buttons/button areas
+* double buffering
 * bitmap rendering
 
 
 == Copyright