--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README	Sun Mar 14 08:20:20 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 freecalypso-hwlab and fc-pcsc-tools Hg repositories
+are now deprecated and no longer maintained.
+
+The present version has been refactored to allow other card communication back
+ends besides libpcsclite: the tools can now operate on SIM cards that sit inside
+Calypso phones or development boards (the necessary simagent back end lives in
+the freecalypso-tools Hg repository), and it would be easy to add support for
+Phoenix-style serial SIM readers if someone were to either send me one or point
+me to a place where I can buy one.  All libpcsclite compile-time dependencies
+have been factored out into the pcsc back end; if you don't have a pcsc-lite
+based reader and don't need that support, you can exclude this back end from
+your build and thus eliminate that compile-time dependency.
+
+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!