Using fc-simint and fc-simtool to manipulate SIM cards inside Calypso devices
=============================================================================

Starting with fc-host-tools-r15, our FreeCalypso host tools package includes a
new utility called fc-simint that works together with fc-simtool and other SIM
card manipulation tools maintained in the separate FC SIM tools package.

fc-simint is not a standalone program - instead it is a front end to the
hardware-agnostic fc-simtool main program.  Therefore, fc-simint cannot be used
unless you install FC SIM tools (fc-simtool and its accessories) on the same
host machine where you are going to run fc-simint.  As of this writing, our FC
SIM tools package has not yet reached the stage of first tarball release, hence
you will need to get it from the Hg repository:

https://www.freecalypso.org/hg/fc-sim-tools/

FC SIM tools can be used by themselves (without FC host tools) if the objective
is to operate on a SIM card using a dedicated smart card reader/programmer
device.  However, if the SIM card to be operated on sits inside a Calypso phone
or development board and you would like to poke at it without physically moving
it back and forth between that Calypso device and another card reader, then
fc-simint from the present package and fc-simtool from FC SIM tools work
together to accomplish this feat.

Once you have both FC host tools and FC SIM tools fully and properly installed,
you are ready to run fc-simint.  fc-simint works in exactly the same manner as
fc-loadtool (operates on the Calypso device, in this case the SIM interface
rather than the flash, while the regular firmware is shut down), and it needs
to be invoked in exactly the same way: simply change fc-loadtool to fc-simint.
Some examples:

SIM card in a Mot C139/140 phone:   fc-simint -h compal -c 1004 /dev/ttyUSBx
SIM card in a Pirelli DP-L10 phone: fc-simint -h pirelli /dev/ttyUSBx
SIM card in a FreeCalypso board:    fc-simint -h fcfam /dev/ttyUSBx

If your USB-serial chip and the associated Linux kernel driver support
non-standard high baud rates, you can add a -B812500 option to the above command
lines to speed up the UART communication between fc-simint/fc-simtool on your
host machine and simagent on the Calypso.  This speed-up option should always be
safe with Pirelli DP-L10 and with FreeCalypso hardware (official FT2232x adapter
boards), but the headset jack serial cables used with Mot C1xx phones are more
iffy.

The phone's regular firmware needs to be shut down, and you need to execute the
Calypso device's boot path.  (For very advanced users, target boot control
options work exactly the same way as in fc-loadtool.)  fc-simint will feed
simagent.srec to the Calypso boot ROM, simagent will run on the Calypso device,
and then fc-simint will command simagent to bring up the SIM interface.
fc-simint will retrieve the SIM card's ATR from simagent, it will turn on speed
enhancement if the SIM supports it, and then all further control is passed to
fc-simtool.

Once the control is passed to fc-simtool, you will see a simtool> prompt -
please refer to fc-simtool documentation in the FC SIM tools package for the
available commands such as manipulating SIM PINs and phonebooks.  Once you are
done poking at the SIM card, type "exit" at the simtool> prompt - when operating
in Calypso target mode, fc-simtool will issue a poweroff command to simagent
just like fc-loadtool, causing most Calypso devices to power off cleanly, or
causing the Pirelli DP-L10 phone to boot back into its regular firmware.

Using fc-simtool batch mode via fc-simint
=========================================

If your fc-simint invokation line has any additional arguments after the
/dev/ttyXXX Calypso target pathname, these arguments are passed to fc-simtool,
causing it to operate in its batch mode instead of the default interactive
shell.  However, given the logistics of operating on a Calypso device with its
regular firmware shut down, this batch mode of operation is expected to be
useful only in very unusual scenarios.

Using fc-uicc-tool
==================

There are two main tools in the FC SIM tools package: fc-simtool speaks the
classic GSM 11.11 SIM protocol to the card, whereas fc-uicc-tool speaks the
"enemy" UICC protocol.  All currently existing Calypso phone and modem firmwares
(both our own FreeCalypso and historical proprietary ones) speak only the
classic GSM 11.11 SIM protocol, hence if you are using a given SIM in a Calypso
phone or modem board, the expectation is that the card needs to support the
classic GSM SIM application.  For this reason, fc-simtool is the tool of primary
interest in this mode of usage, and it is the tool which fc-simint invokes by
default.  In contrast, fc-uicc-tool is meant to be used primarily in lab
exploration settings, with the card under investigation inserted into a
dedicated smart card reader/programmer, not involving Calypso GSM devices or
fc-simint.

However, if you have a special contrived use case where you would like to run
fc-uicc-tool on a SIM card that sits in a Calypso phone or other GSM device, you
can do so by adding a -T uicc option to your fc-simint invokation line.  This
option will make fc-simint pass the control to fc-uicc-tool instead of
fc-simtool.

Other fc-simint options
=======================

fc-simint supports all command line options documented in the Loadtools-usage
article that are relevant to its operation.  There are just two more options
that haven't been documented already:

-n

	This option suppresses SIM speed enhancement.  By default fc-simint
	looks at the ATR TA1 byte to see if the SIM supports F=512 D=8 speed
	enhancement (the only speed enhancement mode endorsed by the original
	GSM SIM specs and supported by Calypso hardware), and requests this
	speed enhancement mode if it is supported.  -n option suppresses the
	latter action, forcing the default slow speed mode (F=372 D=1)
	regardless of ATR-indicated SIM capabilities.

-v volt

	The volt argument needs to be "1.8" or "3.0" ("3" is also accepted as an
	alias for 3.0), selecting the voltage mode in which the SIM should be
	powered up.  3.0 V mode (not 3.3 V!) is class B per the specs, 1.8 V
	mode is class C.  Class A is 5.0 V, but the Iota ABB chip in our Calypso
	target devices (the chip responsible for SIM voltage supply and level
	shifting) is new enough to not support that original class any more.
	In the absence of a -v option, fc-simint currently uses 3.0 V mode by
	default.