FreeCalypso > hg > freecalypso-tools
view doc/SIM-manipulation @ 998:fb7442e3d430
CHANGES: mention flash write protection support
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Mon, 04 Dec 2023 02:17:54 +0000 |
parents | ccaa1319740c |
children |
line wrap: on
line source
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.