doc: Add images, add introduction, add usage system

6 files changed, 77 insertions, 8 deletions

diff --git a/docs/chapters/installation.xml b/docs/chapters/installation.xml
index fd659ce..3476da8 100644
--- a/docs/chapters/installation.xml
+++ b/docs/chapters/installation.xml
@@ -4,7 +4,9 @@
     <para><application>SIMtrace</application> will need a patched version of
     <application>wireshark</application> and the <command>simtrace</command>
     host utility to fully operate. The installation might be possible from
-    binary packages or will require building from source.</para>
+    binary packages or will require building from source. The following
+    sections provide some hints how to achieve this on the various Linux
+    distributions</para>
 
     <section id="install_ubuntu_natty">
         <title>Installation Ubuntu Natty</title>
diff --git a/docs/chapters/introduction.xml b/docs/chapters/introduction.xml
index 885d7c4..73ac9a5 100644
--- a/docs/chapters/introduction.xml
+++ b/docs/chapters/introduction.xml
@@ -2,7 +2,43 @@
 <chapter id="chapter_introduction">
     <title>Introduction</title>
     <section id="intro_overview">
+        <title>History</title>
+        <para>SIMtrace was created out of necessity. Harald Welte wanted
+        to see the communication between a GSM Mobile Station (or
+        what we call a cellphone) and the SIM. He was not able to
+        find an existing solution, or the existing ones had mayor
+        drawbacks that made using them very time consuming and slow.
+        The Atmel AT91SAM7 came to the rescue. This microcontroller
+        has hardware support for the  ISO7816 T0/T1 Smart Card
+        specification. Using this hardware with the clock coming from
+        the normal connection we are able to read bytes coming from
+        and going to the SIM.
+        The next step in the project was taken by Kevin Redon
+        that started to modify an existing AT91SAM7 design, started
+        to use the Free Software KiCAD CAD Software. In 2011 the project
+        went from having Schematics to having routed circuits, prototypes
+        and the final product. The first production run was in August.</para>
+    </section>
+    <section id="intro_picture">
         <title>Overview</title>
-        <para></para>
+        <para>The setup of SIMtrace consists out of a Hardware and a
+        Software part. The SIM card needs to be put into the SIMtrace
+        Hardware, the flex cable needs to be connected to the SIMtrace
+        Hardware and the SIM end needs to be placed in the SIM socket
+        of the phone. The SIMtrace hardware can be seen as a USB device
+        from the host, the SIMtrace software will try to find this device
+        and claim it. The SIMtrace software will receive packets from the
+        SIMtrace hardware and can forward them using the GSMTAP protocol
+        to the IANA assigned GSMTAP port (4729). A modified version of Wireshark
+        can be used to analyze the data.</para>
+
+         <figure><title>Schematic Overview</title>
+         <mediaobject>
+           <imageobject>
+             <imagedata fileref="images/setup_overview.png" width="6cm"/>
+           </imageobject>
+           <textobject><phrase>SIMtrace being connected</phrase></textobject>
+         </mediaobject>
+         </figure>
     </section>
 </chapter>
diff --git a/docs/chapters/using.xml b/docs/chapters/using.xml
index f0afd30..baca423 100644
--- a/docs/chapters/using.xml
+++ b/docs/chapters/using.xml
@@ -2,19 +2,50 @@
 <chapter id="chapter_using">
     <title>Sniffing your SIM</title>
 
+    <section id="hw_setup">
+        <title>Connecting your device</title>
+        <para>You will need to put your SIM into the SIMtrace hardware, connect
+        one of the four flex cables to the SIMtrace hardware, put the other side
+        into the SIM socket of your phone. Use USB to connect the SIMtrace hardware
+        to the PC. On your PC you should be able to see the USB device now.</para>
+
+        <figure><title>Connecting the SIMtrace Hardware</title>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="images/simtrace_hw_setup.png" width="15cm"/>
+          </imageobject>
+          <textobject><phrase>SIMtrace being connected</phrase></textobject>
+        </mediaobject>
+        </figure>
+    </section>
+
     <section id="launching_simtrace">
         <title>Launching SIMtrace</title>
-        <para></para>
         <screen>
-$ <command>simtrace</command>
+$ <command>./simtrace</command>
+simtrace - GSM SIM and smartcard tracing
+(C) 2010 by Harald Welte &lt;laforge@gnumonks.org&gt;
         </screen>
+        <para>Launching the <command>simtrace</command> will try to find
+        the SIMtrace hardware and then try to claim the USB device. The
+        application will send the received data encapsulated in the GSMTAP
+        format on localhost and the IANA assigned GSMTAP port.</para>
     </section>
 
     <section id="launching_wireshark">
         <title>Launching Wireshark</title>
-        <para></para>
-        <screen>
-$ <command>wireshark</command>
-        </screen>
+        <para>The <command>wireshark</command> application will start a GUI
+        and given the right permissions you should be able listen to the
+        localhost interface and filter for the GSMTAP port on 4729. You should
+        be able to see the decoded messages like in the figure below.</para>
+
+         <figure><title>GSMTAP in Wireshark</title>
+         <mediaobject>
+           <imageobject>
+             <imagedata fileref="images/wireshark-sim.png" width="16cm"/>
+           </imageobject>
+           <textobject><phrase>SIMtrace sending data</phrase></textobject>
+         </mediaobject>
+         </figure>
     </section>
 </chapter>
diff --git a/docs/images/setup_overview.png b/docs/images/setup_overview.png
new file mode 100644
index 0000000..2e511eb
--- /dev/null
+++ b/docs/images/setup_overview.png
diff --git a/docs/images/simtrace_hw_setup.png b/docs/images/simtrace_hw_setup.png
new file mode 100644
index 0000000..b73ae3a
--- /dev/null
+++ b/docs/images/simtrace_hw_setup.png
diff --git a/docs/images/wireshark-sim.png b/docs/images/wireshark-sim.png
new file mode 100644
index 0000000..e05f5b6
--- /dev/null
+++ b/docs/images/wireshark-sim.png