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.