What this project is about
==========================

Welcome to FreeCalypso.  The goal is this project is to produce a Free Dumb
Phone - not yet another smartphone (free or otherwise), but a "dumbphone",
i.e., a traditional cellular telephone handset just like we all had and enjoyed
back in the 1990s - a device with just enough hardware resources to make and
receive traditional phone calls on a standard GSM network, and not one iota
more.  No power-hungry application processors, just have one baseband processor
that does everything from running the GSM protocol stack to responding to the
user pressing buttons on the traditional numeric dialpad.  No big screens with
power-hungry backlights, just a little LCD to display who is calling and the
current date and time - I use my cellphone as a pocketwatch too, so my wrists
stay free.

But we seek to build a "dumbphone" with one VERY SPECIAL twist: namely,
operational firmware for the phone (which includes everything from the UI down
to GSM Layer 1, as there is no separate baseband processor) available to every
end user in the form of full source code.  Hence it will be a Free Dumb Phone.
We seek to achieve this "special twist" by doing the following:

* We'll use the ancient TI Calypso chipset for our Free Dumb Phone instead of
  whatever is the current offering from MTK or other cellular chipset company
  du jour.  TI stopped making these chips ages ago, and got out of the cellular
  baseband chipset business altogether, but we can still source these chips in
  5-digit quantities on the Chinese surplus market.

* Because we'll be using a baseband chipset from the surplus market made by a
  company that long bit the dust, we will not be getting any official firmware
  releases from any vendor.  Therefore, there is no one to sign any NDAs with,
  and there is no one to tell us what we can or cannot do with the firmware as
  we won't be getting any official firmware in the first place.

* Our Free Dumb Phone will run free firmware which we put together ourselves.
  When TI completely exited the cellular baseband chipset business, closed all
  their offices involved with that work and laid off all of the responsible
  employees, they broke their firmware into pieces and threw the pieces in the
  trash.  We have picked these shattered pieces out of the trash dumpster, and
  like anything else found in a dumpster, these abandonware pieces are
  effectively in the public domain, and any person in the world is free to do
  with them as she pleases.

The "shattered pieces" aspect of the firmware needs to be re-emphasized.  TI's
complete firmware suite for their Calypso chipset, also known as TCS2.1.1 or
TCS211, has *not* survived the disbanding of its maker company in an intact
form.  Shattered bits and pieces are all we've been able to gather through our
dumpster diving efforts.

Reconstructing fully-functional firmware for the Calypso from the available
broken pieces is where the bulk of the hard work in our project is.  There is
another project (bb.osmocom.org) seeking to produce similarly-functional fw by
rewriting it completely from scratch with a totally different architecture, but
the lead developer of the present FreeCalypso project has chosen the
reconstruction approach as more reliable and more likely to produce the desired
result.

Hardware vs. software
=====================

Our goal is to produce a complete and usable cellphone product.  Such a product
requires both hardware and software (firmware).  We need to produce both.  We
could do the hw and fw subprojects in either order, but we have chosen to work
on the firmware first.  By doing the fw first, we will get to exercise it on
some existing phones that use the same Calypso chipset; doing the hw ahead of
the fw would give us a fancy paperweight.

Current status
==============

We are currently using the Calypso GSM modem in the Openmoko GTA02 smartphone
as our bring-up vehicle.  We have our own firmware suite, compiled 100% from
source with gcc (no blobs or proprietary compiler toolchains!), but we have not
yet reintegrated the full GSM protocol stack in this project.  (The leo2moko
side project doesn't count.)  But we are getting close: we've got the
FreeNucleus RTOS by XVilka as a working replacement for the binary-only version
of Nucleus used by TI, and we've got the following parts of TI's original
firmware suite integrated and working:

* RiViera framework and everything that runs under it, including TI's original
  FFS (flash file system), RVTMUX serial channel and ETM (Enhanced Test Mode).
  This part has been found in a TCS211 semi-src package.

* GPF (Condat's protocol stack framework) - TI used it mostly as binary libs,
  even internally, and we had to reconstruct it from pieces.  Some parts of GPF
  had to be reconstructed from disassembly.  But it works beatifully now.

* GSM Layer 1 code - we took the version from the LoCosto source (no official
  Calypso L1 source could be found) and backported it from LoCosto to Calypso.

We are now working on reintegrating the rest of the GSM protocol stack code,
also taking it from the LoCosto source (the only available full source) and
reintegrating it to build in our FreeCalypso environment, targeting Calypso
instead of LoCosto.

We have also produced some host tools for loading firmware into Calypso GSM
devices, for communicating with running firmwares over the RVTMUX interface,
and for manipulating TI's flash file system.  See README.hosttools for the
details.

Source tree
===========

The subtrees of this source tree are as follows:

gsm-fw		The main FreeCalypso GSM firmware work, see above.

target-utils	This tree contains code that runs on Calypso targets, but is
		not regular firmware (gsm-fw) or a part thereof.  The two key
		components built in this tree are loadagent (needed for all
		targets) and compalstage (for Compal phones only), which need
		to be installed on the user's host system in order for
		loadtools (see README.hosttools) to do their job.

ffstools	Tools that run on a Unix or GNU/Linux host; see README.hosttools
loadtools	for the details.
miscutil
rvinterf

toolchain	Scripts and patches for building the gcc+binutils toolchain
		targeting ARM7, the CPU core of the Calypso GSM/GPRS baseband
		processor.  You'll need to build and install this toolchain
		first before you can build gsm-fw or target-utils.

If you like this project and would like to see it continue to fruition, please
consider making a Bitcoin donation to the human family behind it:

https://blockchain.info/address/159Yx6JRJ4oMLPTYrh1jW7fQ5D5tPHdnoM