+
−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.