--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README	Fri Feb 12 05:25:43 2021 +0000
@@ -0,0 +1,35 @@
+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!