diff --git a/README b/README
new file mode 100644
index 0000000..41978b6
--- /dev/null
+++ b/README
@@ -0,0 +1,31 @@
+This utility allows to :
+
+ * Program customizable SIMs. Two modes are possible:
+
+  - one where you specify every parameter manually :
+
+./pySim.py -n 26C3 -c 49 -x 262 -y 42 -i <IMSI> -s <ICCID>
+
+
+  - one where they are generated from some minimal set :
+
+./pySim.py -n 26C3 -c 49 -x 262 -y 42 -z <random_string_of_choice> -j <card_num>
+
+    With <random_string_of_choice> and <card_num>, the soft will generate
+    'predictable' IMSI and ICCID, so make sure you choose them so as not to
+    conflict with anyone. (for eg. your name as <random_string_of_choice> and
+    0 1 2 ... for <card num>).
+
+  You also need to enter some parameters to select the device :
+   -t TYPE : type of card (supersim, magicsim, fakemagicsim or try 'auto')
+   -d DEV  : Serial port device (default /dev/ttyUSB0)
+   -b BAUD : Baudrate (default 9600)
+
+ * Interact with SIMs from a python interactive shell (ipython for eg :)
+
+import pySim
+sl = pySim.SerialSimLink(device='/dev/ttyUSB0', baudrate=9600)
+print sl.read_binary(['3f00', '7f20', '6f07']) # Print IMSI
+print sl.run_gsm('00112233445566778899aabbccddeeff') # Run A3/A8
+
+