--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Sniffing-workflow	Wed Aug 30 03:03:04 2023 +0000
@@ -0,0 +1,63 @@
+Workflow for SIM sniffing with SIMtrace3
+========================================
+
+To sniff ME-to-SIM communication with SIMtrace3, follow this workflow:
+
+* Assemble the hardware as described in the Sniffing-hw-setup article, and
+  program the serial flash chip on the Icestick board with our sniffer FPGA
+  image.  You will need to use iceprog utility from IceStorm suite for the
+  latter part.
+
+* Make sure that the ME is still able to talk to the SIM going through the
+  additional plumbing.  Only the parts up to sim-fpc-pasv matter here: the
+  mv-sniffer adapter and the Icestick board can be disconnected and unpowered,
+  yet the ME should still see the SIM inserted into the socket on the
+  sim-fpc-pasv board.
+
+* When you are ready to start sniffing, complete all hw connections per the
+  desired hw setup you are following and plug the Icestick board into your PC
+  or laptop.  With our sniffer FPGA image, the initial LED pattern should be:
+  with the Icestick oriented horizontally, upper and lower red LEDs on, left
+  and right red LEDs off, center green LED off.
+
+* Run simtrace3-sniff-rx as follows:
+
+  simtrace3-sniff-rx /dev/ttyUSBx logfile
+
+  The /dev/ttyUSBx device needs to be the one corresponding to FT2232H Channel B
+  on the Icestick board, and you need to specify the name of the log file to be
+  written.
+
+* Power on the phone, or otherwise cause the ME to bring up its SIM interface.
+  Once the ME applies power to its SIM interface and raises its RST output, the
+  green LED should light on the Icestick, and you should see an stdout message
+  from simtrace3-sniff-rx that reads "SIM RST is high".
+
+* When you power off the phone or cause the modem to shut down its SIM interface
+  with AT+CFUN=0, the green LED will go out and simtrace3-sniff-rx will print
+  "SIM RST is low" on stdout.  You can kill the process now, or you can kill it
+  earlier once you've captured enough - but you do need to start each sniffing
+  session from the beginning.
+
+When you run simtrace3-sniff-rx with a logfile argument as recommended above,
+there will be very little output on stdout - just SIM RST transition messages
+indicating start and end of SIM interface sessions - while all other output gets
+written to the log file.
+
+The main output of simtrace3-sniff-rx - written to the log file if specified or
+to stdout otherwise - is very low-level and very voluminuous.  Each line
+corresponds to just one character in the ISO 7816-3 sense passing across the
+SIM interface, and is logged as the raw 16-bit value received from the FPGA, as
+described in the Sniffer-FPGA-design document.  This low-level logging format
+makes it possible to troubleshoot phone-to-SIM compatibility problems at the
+lowest level: microsecond timestamps allow you to see how long the SIM takes to
+respond with each byte, and you can see all procedure bytes below the level of
+APDU exchanges.  Did the card ask for data transfer in one swoop or one byte at
+a time?  Did it use any stalling bytes, and how many?  All of these lowest-level
+details might matter when trying to solve the mystery of why vintage phone model
+ABC seemingly-inexplicably refuses to work with SIM card model XYZ!
+
+There will also be a higher-level decoding program, tentatively named
+simtrace3-sniff-dec.  This program will read log files written by
+simtrace3-sniff-rx and decode them into slightly-higher-level elements as in
+ATR, PPS exchanges, command headers, data transfers and status bytes.