diff --git a/README b/README
deleted file mode 100644
index d4e4e4d..0000000
--- a/README
+++ /dev/null
@@ -1,38 +0,0 @@
-WiringPi: An implementation of most of the Arduino Wiring
-	functions for the Raspberry Pi
-
-WiringPiGem: The WiringPi library wrapped up for Ruby with some OO goodness, sanity checking and other handy additions.
-
-WiringPi GPIO:
-
-    require 'wiringpi'
-    io = WiringPi::GPIO.new
-    io.write(pin,value)
-    io.read(pin,value)
-
-    Shift out:
-
-    io.write(latch_pin, LOW)
-    io.shiftOut(data_pin, clock_pin, LSBFIRST or MSBFIRST, value)
-    io.write(latch_pin, HIGH)
-
-    Shift out an array of 1/0s (always uses LSBFIRST):
-
-    io.shiftOutArray(data_pin, clock_pin, latch_pin, [0,1,0,0,1,1,1,0])
-
-WiringPi GPIO with /sys/class/gpio:
-
-    require 'wiringpi
-    io = WiringPi::GPIO.new(WPI_MODE_SYS)
-    # read/write/shift as usual
-
-WiringPi Serial:
-
-require 'wiringpi'
-    s = WiringPi::Serial.new('/dev/ttyAMA0',9600)
-    s.serialPuts('Hello world!')
-    s.serialClose
-
-Full details at:
-	https://projects.drogon.net/raspberry-pi/wiringpi/
-
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a916266
--- /dev/null
+++ b/README.md
@@ -0,0 +1,43 @@
+# WiringPi
+WiringPi is an implementation of most of the Arduino Wiring functions for the Raspberry Pi, this gem is a wrapper for the main wiringpi library and provides a nice OO interface with a few other handy helpers.
+
+## Installation
+Install with `gem install wiringpi2` or use bundler's Gemfile
+```
+source 'https://rubygems.org'
+
+gem 'wiringpi2' # https://github.com/WiringPi/WiringPi-Ruby
+```
+then: `bundle install`
+
+## Example
+```
+#!/usr/bin/env ruby
+
+require 'bundler'
+Bundler.setup
+Bundler.require
+
+io = WiringPi::GPIO.new do |gpio|
+  gpio.pin_mode(0, WiringPi::OUTPUT)
+  gpio.pin_mode(1, WiringPi::INPUT)
+end
+
+pin_state = io.digital_read(1) # Read from pin 1
+puts pin_state
+
+io.digital_write(0, WiringPi::HIGH) # Turn pin 0 on
+io.delay(100)                       # Wait
+io.digital_write(0, WiringPi::LOW)  # Turn pin 0 off
+```
+You will need to run your scripts as root because WiringPi accesses `/dev/mem`
+
+## Reference
+
+### Pins
+For a complete run-down see the [pins page](http://wiringpi.com/pins/) of the [wiringpi website](http://wiringpi.com/).
+![alt text](http://wiringpi.com/wp-content/uploads/2013/03/gpio1.png "The main GPIO connector")
+![alt text](http://wiringpi.com/wp-content/uploads/2013/03/gpio21.png "The secondary GPIO connector")
+
+### More
+Full details on the [wiringpi website](http://wiringpi.com/).