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 freecalypso-hwlab and fc-pcsc-tools Hg repositories
are now deprecated and no longer maintained.

What are the tools?
===================

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.  As the next level up in advanced functionality, if you are working with
a programmable SIM (supported card models are our own FCSIM1 and Sysmocom
webshop cards sysmoUSIM-SJS1 and sysmoISIM-SJA2), fc-simtool provides the
necessary support for fully programming these SIMs.

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!

Supported card access methods
=============================

fc-simtool and fc-uicc-tool are high-level protocol tools: they form command
APDUs to be sent to the card, but they don't contain any hardware interfacing
code - instead the job of actually accessing the card and exchanging APDUs with
it is deferred to back end programs.  Three card access back ends are included
in the FC SIM tools package: one for pcsc-lite, one for serial SIM readers, and
one for SIM cards inside Calypso GSM devices.