This code repository contains current versions of FreeCalypso SIM card
manipulation utilities fc-simtool and fc-uicc-tool; the old versions which were
previously maintained in the freecalypso-hwlab Hg repository are now deprecated
and no longer maintained.

The present utilities operate on SIM cards that are inserted into a smart card
"reader" device attached to the user's host computer (PC or laptop), *without*
going through any kind of phone or other GSM device.  Whichever smart card
"reader" hardware you are going to use, it needs to be supported by pcsc-lite
software: our tools link with libpcsclite and thus require this library and its
header files to be installed in order to compile; actually running the programs
and getting them to work further requires pcscd and appropriate pcsc-lite back
end drivers.  The Mother uses HID Omnikey 3121 and 6121 CCIDs (USB-interfaced),
with pcsc-lite and its ccid back end installed under Slackware 14.2.

fc-simtool is the utility of primary interest.  It speaks the classic GSM 11.11
SIM protocol to the card (as opposed to the unwanted-innovation UICC protocol),
and it is intended to be useful to end users of regular operator-issued SIM
cards without admin privileges.  High-level user-friendly commands include
manipulating PINs and phonebooks; low-level commands allow you to SELECT any
arbitrary file (MF/DF/EF) and to perform READ and UPDATE commands on any EF
(BINARY or RECORD as appropriate) as the card will allow, given your access
level.  We (FreeCalypso core team) are also doing some experiments with
programmable SIM cards, hoping to some day be able to issue our own SIMs, but
this work is currently very experimental and not ready for consumption.

fc-uicc-tool is currently a very minimal tool for a few narrow use cases.  It
implements a small subset of fc-simtool commands (basic low-level ones), but
speaking the new UICC protocol to the card - as well as new SELECT by AID
commands that are only possible with this new protocol, granting access to ADFs
for USIM and ISIM.  The tool's only useful functions right now are (1) testing
whether or not a given card has USIM/ISIM functionality present, and (2)
manually exploring the file system under ADF.USIM or ADF.ISIM which cannot be
accessed in any other way.  fc-uicc-tool does NOT currently replicate any of
the high-level end-user-oriented functionality of fc-simtool!