FreeCalypso host tools suite includes a large number of different tools, many
of which are quite specialized and rarely needed.  The following tools are the
most essential ones:

fc-loadtool	This is the tool used to read and write the non-volatile flash
		memory of supported GSM devices.  It can be used to reflash
		these devices with new firmware (whether pre-existing or new
		firmwares developed within our project), and to save and restore
		flash backups.  This tool operates on the target device (phone
		or modem) while its regular firmware is shut down.

fc-iram,	Reprogramming the non-volatile flash memory is not the only way
fc-xram,	to run your own code on a Calypso GSM device.  If your code is
fc-compalram	small enough to fit entirely into the available RAM on the
		device, and you would like to just run it without flashing it
		permanently, these tools do the job of loading code images into
		different kinds of RAM through different download protocols.
		Some phones have large enough RAM to allow a complete functional
		firmware image to be run via fc-xram without flashing.

rvinterf	This program is our engine for communicating with up & running
		TI-based firmwares through the RVTMUX binary packet interface.
		It receives and decodes all debug trace and other packets
		emitted by the target fw, and allows the options of printing
		them on the terminal, saving them to a log file, and/or passing
		them to other programs that connect to rvinterf as local socket
		clients.  In the other direction those latter client programs
		can send arbitrary command packets to the target fw.

fc-fsio		Going through rvinterf, this tool connects to GSM devices
		running one of the supported firmware versions while the fw is
		running (unlike fc-loadtool which operates on a device while
		its regular fw is shut down) and allows you to manipulate
		(read and write) the device's flash file system.  It is thus a
		higher-level tool than fc-loadtool.  It is intended primarily
		for working with our own firmwares, but it also works with
		Pirelli's original fw.

fc-shell	FreeCalypso firmwares have a feature of our own invention (not
		present in any pre-existing ones) to accept AT commands over
		the RVTMUX interface.  It is useful when no second UART is
		available for a dedicated standard AT command interface.
		fc-shell is the tool that allows you to send AT commands to the
		firmware in this manner; it also allows a few other kinds of
		asynchronous commands to be sent.  It works through rvinterf.

And here is a listing of all other tools in mostly-alphabetical order:

arfcn2ti	These two utilities convert back and forth between standard
ti2arfcn	ARFCNs and TCS211 L1 radio_freq numbers - see ARFCN-mapping
		article for the explanation.

c139explore	This is a run-from-RAM (no flashing) program for Mot C139/140
		phones that exercises their peripheral hardware: LCD, keypad
		backlight, buzzer and vibrator.

c1xx-calextr	This utility extracts the factory RF calibration values for
		Mot C1xx phones from the records contained in a special sector
		of their flash and converts them to FreeCalypso format, to be
		used when running our own firmware on these phones.  See the
		Compal-calibration article for more details.

compile-fc-batt	This utility compiles a table of battery thresholds for our
		FreeCalypso battery management code (FCHG) from ASCII source
		into the binary form suitable for uploading into /etc/batterytab
		(v1 binary format) on a FreeCalypso device.  It is rarely used
		directly, instead fc-fsio write-battery-table-v1 command invokes
		compile-fc-batt behind the scenes.

compile-fc-batt2
		This utility is like the original compile-fc-batt, but generates
		v2 binary format for uploading into /etc/batterytab2.  This new
		binary format is needed for the new FC Tourmaline version of
		FCHG.  It is rarely used directly, instead fc-fsio
		write-battery-table-v2 command invokes compile-fc-batt2 behind
		the scenes.

compile-fc-chg	This utility compiles a FreeCalypso battery charging
		configuration file from ASCII source into the binary form
		suitable for uploading into /etc/charging on a FreeCalypso
		device.  It is rarely used directly, instead fc-fsio
		write-charging-config command invokes compile-fc-chg behind the
		scenes.

ctracedec	GSM firmwares built in TI's Windows environment (official ones
		as well as our own hacks based on the TCS211 semi-src) have a
		"compressed trace" misfeature whereby many of the ASCII strings
		in debug trace messages get replaced with numeric indices at
		build time, and these numeric indices are all that gets emitted
		on the RVTMUX serial channel.  This numeric trace output can be
		turned back into ASCII strings if you have the str2ind.tab file
		corresponding to the fw version that emitted the output in
		question; this ctracedec utility performs that decoding.

fc-add-ramps	This program is a developer tool, specifically for engineers
		working on RF Tx tract tuning.  It reads a table of Tx ramp
		templates in FreeCalypso RF table ASCII format, adds up each
		ramp and reports the resulting sums.

fc-bin2rftab	This program is a developer tool: it reads a binary RF table of
		the user-specified type from a binary file (at a user-specified
		offset, allowing extraction of tables from alien firmwares and
		whatnot) and emits it in FreeCalypso ASCII format.

fc-buzplay	This program plays Calypso buzzer melodies (BU or PWT) on an
		actual Calypso device equipped with such a buzzer (Mot C1xx,
		TI's D-Sample board, our next planned development board) by
		loading a buzplayer agent onto the target and feeding melodies
		to be played to it.  See the Buzzer-melodies article for more
		details.

fc-cal2bin	This utility takes an RF table in FreeCalypso ASCII format and
		converts it to the firmware's native binary format.  See the
		RF_tables article for more details.

fc-cal2text	This utility takes a dump of TI's /gsm/rf flash file system
		directory subtree as input (either extracted in vitro with tiffs
		or read out in vivo with fc-fsio) and converts all RF tables
		found therein into a readable ASCII format.  See the RF_tables
		article for more details.

fc-dspapidump	This utility uses ETM in synchronous mode (going through
		rvinterf) to read and dump the contents of the DSP API RAM in a
		target Calypso GSM device while the firmware is running.

fc-dspromdump	This utility feeds a dump agent program (dspdump) to the target
		Calypso device's ARM boot ROM and then commands this dump agent
		program to perform a complete dump of the chip's DSP ROM.  See
		the DSP-ROM-dump article for more details.

fc-e1decode	This utility decodes a melody in TI's Melody E1 format from the
		the native binary format to our own ASCII-based representation;
		see the Melody_E1 article for more information.

fc-e1gen	This utility compiles an E1 melody from our own ASCII source
		format into binary bits to be loaded into a FreeCalypso phone;
		see the Melody_E1 article for more information.

fc-efr2tch	This utility converts a GSM EFR speech sample from Themyscira
		gsmx format (defined in the GSM codec libraries & utilities
		package) into an uplink play file that can be played with the
		tch play command in fc-shell; see our TCH-bit-access article
		for more information.

fc-fr2tch	This utility converts a GSM 06.10 speech sample from the
		de facto standard libgsm format (which can be recorded with
		standard tools like SoX) into an uplink play file that can be
		played with the tch play command in fc-shell; see our
		TCH-bit-access article for more information.

fc-gsm2vm	This utility converts a GSM 06.10 speech sample from the same
		libgsm source format into a voice memo file that can be
		uploaded into the FFS of a FreeCalypso device and played with
		the audio_vm_play_start() API or the AT@VMP command that
		invokes the latter.

fc-imy2pwt	This program converts monophonic ringtone melodies from iMelody
		interchange format into our own native PWT format.  See the
		Buzzer-melodies article for more details.

fc-imyplay	Shell script for quickly playing IMY melodies: the script runs
		fc-imy2pwt | fc-pwt-comp pipeline, compiling the melody into
		PWT binary format (under /tmp), then uploads the binary melody
		(via fc-fsio) to /buz/test.bz on the running FC phone or
		devboard, and then plays it via AT@BUZ command via fc-shell.

fc-lcdemu	Moved to freecalypso-ui-dev repository; look there for more
		info.

fc-lcdpoll	New companion utility to fc-lcdemu; look in freecalypso-ui-dev
		for more info.

fc-meltest-e1	Shell script for quickly playing E1 melodies: the script runs
		fc-e1gen, compiling the melody from ASCII source into binary
		format (under /tmp), then uploads the binary melody (via
		fc-fsio) to /mel/test.e1 on the running FC phone or devboard,
		and then plays it via AT@E1 command via fc-shell.

fc-meltest-pwt	Shell script for quickly playing PWT melodies: the script runs
		fc-pwt-comp, compiling the melody from ASCII source into binary
		format (under /tmp), then uploads the binary melody (via
		fc-fsio) to /buz/test.bz on the running FC phone or devboard,
		and then plays it via AT@BUZ command via fc-shell.

fc-memdump	This tool captures a memory dump from a GSM device whose
		firmware implements one of TI's Test Mode memory read commands,
		either the old TM3 version or the new ETM one.  It works with
		FreeCalypso Citrine, with TCS211-based firmwares including
		FreeCalypso Magnetite, with really old TI firmwares which
		predate ETM, and with Mot C1xx original firmwares.  It works
		through rvinterf.

fc-pulse-dtr	This trivial utility opens a serial port, asserts DTR for 50 ms,
		then negates it and exits.  See the DUART28-boot-control article
		for the explanation.

fc-pulse-rts	This trivial utility opens a serial port, asserts RTS for 50 ms,
		then negates it and exits.  See the DUART28-boot-control article
		for the explanation.

fc-pwt-comp	This program compiles a FreeCalypso PWT melody from our ASCII
		source format into the compact binary format that will be
		uploaded into FC device FFS for use by our BUZM melody player
		engine.  See the Buzzer-melodies article for more details.

fc-readcal	This program attempts to read a bunch of RF calibration tables
		out of a running firmware through Test Mode commands: first
		tms 1, then rfpw 7 for each band, then rftr and ttr commands to
		read various tables.  The primary intended purpose is extracting
		RF calibration or static configuration data from alien
		firmwares.  Please beware that the tms 1 and rfpw 7 commands
		sent by this tool are highly disruptive to normal GSM operation.

fc-rftab2c	This program is a developer tool: it takes an RF parameter
		table of one of the supported types in FreeCalypso ASCII format
		and converts it into a C code snippet suitable for insertion
		into the firmware source in the L1 RF "customization" code
		where compiled-in default RF parameter tables are defined.

fc-rgbconv	A simple aid for phone UI development that converts RGB color
		values between human-intuitive 8:8:8 format and the 5:6:5 format
		used by the color LCDs in the phones targeted by FreeCalypso.

fc-ringlist-comp
		This program compiles a list of ringing tone or message alert
		tone melodies from ASCII source into the binary format (.mls)
		that will be uploaded into FreeCalypso device FFS and read by
		the UI layer of FC phone firmwares.  See the Buzzer-melodies
		article for more details.

fc-serterm	This tool is a trivial serial terminal program.  Its special
		feature is that any output coming from the serial port that
		isn't printable ASCII is displayed as by cat -v.  It is useful
		for talking to serially-interfaced devices that mix ASCII with
		binary in their serial talk.

fc-simint	This program is a specialized front end to fc-simtool, allowing
		the latter tool to operate on SIM cards inside Calypso phones
		and development boards.  fc-simint loads and runs simagent on
		the Calypso device in the manner of loadtools, then passes the
		open file descriptor to fc-simtool.

fc-simtool	Maintained in a separate fc-sim-tools repository, fc-simtool is
		our tool for operating on SIM cards.  Its primary mode of usage
		is operating on SIM cards inserted into special smart card
		reader/programmer devices, without going through any kind of
		phone or other GSM device, but fc-simtool can also be invoked
		indirectly via fc-simint, in which case it operates on SIM cards
		inside Calypso devices.

fc-tch2fr	This hack-utility takes a TCH downlink recording produced with
		the tch record command in fc-shell (specifically, the old format
		that will only be produced if the source of TCH DL bits is a
		very old FC firmware version) and tries to convert it to a
		playable libgsm file (containing garbage frames in reality,
		resulting in very unpleasant noises on subsequent decoding) by
		completely disregarding the DSP status words which were not
		understood back when this hack was written in 2016.  See our
		TCH-bit-access article for more information.

fc-tmsh		TI-based GSM firmwares provide a rich set of Test Mode commands
		that can be issued through the RVTMUX (debug trace) serial
		channel, used for L1/RF test functions, production line RF
		calibration, FFS (flash file system) access, audio configuration
		and other miscellany.  fc-tmsh is our test mode shell for
		sending these Test Mode commands to targets and displaying
		decoded target responses; it works through rvinterf.  fc-tmsh
		supports all Test Mode commands (both TM3 and ETM) implemented
		in our target firmwares except FFS access; use fc-fsio for the
		latter.  fc-tmsh is fully asynchronous in that the issuance of
		commands to the target and the handling of target responses are
		fully decoupled.

fc-tmsync	This program reimplements a small subset of fc-tmsh commands in
		a synchronous manner; it was written together with fc-readcal
		for the same purpose of extracting "in vivo" data from alien
		firmwares.

fc-vm2gsmx	This utility takes a TCS211 classic (non-AMR) voice memo
		recording (a binary file as you would read out with fc-fsio) and
		converts it into extended-libgsm (gsmx) format defined in our
		gsm-codec-lib package.  Please refer to Voice-memo-utils article
		for more information.

fc-vm2hex	This utility takes a TCS211 VM binary file just like fc-vm2gsmx
		and converts it into ASCII hex format that can be analyzed by a
		human, either directly or with the aid of gsmfr-dlcap-parse
		utility from our gsm-codec-lib package.  Please refer to
		Voice-memo-utils article for more information.

fcup-*		FreeCalypso User Phone Tools; see the User-phone-tools article.

imei-luhn	A simple utility for computing or verifying the Luhn check
		digit of an IMEI number.

l1trace-filter	This program connects to rvinterf as a client and displays only
		certain filtered L1 traces; it was written for the purpose of
		isolating specific traces of interest out of the noise.

make-imeisv	This utility is intended for use in shell scripts: it constructs
		a 16-digit IMEISV from a 15-digit IMEI (which must have a valid
		Luhn check digit) and a 2-digit SV field.

mokosrec2bin	This utility converts "moko-style" S-record files (those
		produced by TI's hex470 tool with -memwidth 16 -romwidth 16
		options) to straight binary.

pcm-sms-decode	Some TI-based vendor firmwares (not TI's original and not
		FreeCalypso) implement SMS storage in their FFS in a file named
		/pcm/SMS in the same format in which SMS records are stored in
		SIM cards (EF_SMS elementary file).  Pirelli's firmware is one
		major user of this mechanism.  This /pcm/SMS file can be read
		out in vivo via fc-fsio or extracted in vitro via tiffs; the
		new pcm-sms-decode utility decodes the stored SMS content from
		this binary file similarly to sms-pdu-decode.

pirexplore	This is a run-from-RAM (no flashing) program for Pirelli DP-L10
		phones that exercises their peripheral hardware, primarily their
		LCD.

rvtdump		This tool produces a human-readable dump of all output emitted
		by a TI-based GSM fw on the RVTMUX binary packet interface.  It
		can also log this dump to a file.

sms-pdu-decode	This utility is part of FC User Phone Tools; see the
		User-phone-tools article.

srec-regions	This utility parses a firmware image file in S-record format,
		identifies the set of discontiguous regions into which this
		SREC image deposits bits, and lists these identified regions.

tfc139		This tool breaks into Mot C1xx phones via shellcode injection,
		a method that works despite any bootloader locks, allowing you
		to reflash locked phones with new firmware with fc-loadtool.
		The name of the utility is historical: previously it was
		specific to TFC139 phones (C139s sold with TracFone branding),
		but the current version is expected to work with all Mot C1xx
		firmware versions.

tiaud-compile	This utility compiles an audio mode configuration table for TI's
		Audio Service from our own ASCII source format into the binary
		format for uploading into FreeCalypso GSM device FFS with
		fc-fsio.

tiaud-decomp	This utility decodes TI's audio mode configuration files read
		out of FFS into our own ASCII format.  It is the reverse of the
		operation performed by tiaud-compile.

tiaud-mkvol	This utility is a companion to tiaud-compile that generates the
		*.vol binary files which need to accompany the main *.cfg ones.

tiffs,		These tools perform "in vitro" analysis of flash file system
mokoffs,	(FFS) images read out of GSM devices with TI-based firmwares.
pirffs,		You can list and extract the FFS content captured as a raw
tiffs-8m	flash image, and even perform a few "forensic" operations along
		the lines of reading deleted files and seeing the history of
		FFS modifications.  tiffs is the main program, whereas mokoffs,
		pirffs and tiffs-8m are convenience wrappers for the common FFS
		configurations from Openmoko, Pirelli and Tango.

tiffs-mkfs	This utility constructs a TI flash file system (TIFFS) image
		completely from scratch "in vitro", containing initial directory
		and file content given by a Unix directory and file tree on the
		host system.  The resulting image can then be flashed into a
		Calypso GSM device running FreeCalypso firmware.

tiffs-mkfile	This utility is intended for use in shell scripts: it generates
		certain types of binary files that go into TIFFS, for subsequent
		feeding to tiffs-mkfs.