# HG changeset patch # User Mychaela Falconia # Date 1616372674 0 # Node ID ccaa1319740c873b1133acafe85df722d70f157a # Parent ef501e258036509f8567d17ce421235e827d7c44 doc/SIM-manipulation article written diff -r ef501e258036 -r ccaa1319740c CHANGES --- a/CHANGES Fri Mar 19 06:17:58 2021 +0000 +++ b/CHANGES Mon Mar 22 00:24:34 2021 +0000 @@ -2,7 +2,8 @@ * New fc-simint host program and its associated simagent target back end work together with fc-simtool (separate FC SIM tools package), allowing the latter - to operate on SIM cards inside Calypso phones and development boards. + to operate on SIM cards inside Calypso phones and development boards. See + the new doc/SIM-manipulation article for the details. Changes from fc-host-tools-r13 to fc-host-tools-r14: diff -r ef501e258036 -r ccaa1319740c doc/SIM-manipulation --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/SIM-manipulation Mon Mar 22 00:24:34 2021 +0000 @@ -0,0 +1,119 @@ +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.