Repackaging FreeCalypso modem into different physical form factors
==================================================================

As of this writing, our FreeCalypso Triband Modem Solution has reached the
status of a finished product: it is no longer experimental or developmental,
it is now fully fit for operational use on live public GSM networks in end user
applications that need a standards-compliant GSM+GPRS modem.  However, at the
present moment it is only available in the physical form factor of a development
board (FCDEV3B) that was originally designed to serve as a software/firmware
development platform, and as such it is not ideally suited for use as an end
product.  For end use applications it would be highly desirable to take our
proven FC Triband Modem Solution (FC-TMS) as realized on the FCDEV3B and
repackage it into other physical form factors.  This repackaging can be done
in two ways:

Approach 1 (strongly preferred): the party who desires to have our FC-TMS in a
particular form factor gets in touch with FreeCalypso Central, engages in a
discussion with us to arrive at the new form factor to be implemented (it needs
to satisfy your requirements and be feasible for us to implement), then funds
the cost of PCB layout labor to turn the new form factor modem into reality.
More specifically, we would do the design at the schematics+BOM level while the
the PCB layout step would have to be outsourced at cost.

Approach 2 (NOT preferred, but can sometimes be agreed to in limited cases):
someone else does the repackaging work under their own control.

In the case of Approach 1 the new modem product will always be guaranteed to
work flawlessly and be fully compatible with our FreeCalypso sw and fw
architecture because in this case the hardware design is personally supervised
by the Mother of FreeCalypso and must receive her approval prior to being
released to layout and then to fabrication.  In the case of Approach 2 this
assurance is lacking.  This document provides some technical guidelines that
MUST be followed in order for a new modem hw product to stand a chance at being
compatible with FreeCalypso; anyone who follows Approach 2 against our
recommendation but still wishes to have a chance at receiving support from us
MUST follow these design guidelines.

LEGAL NOTICE: Following these technical guidelines does NOT by itself grant you
a license to use our FreeCalypso trademark on your hardware products; this
trademark is personally owned by Mychaela N. Falconia and only she has the
authority to license its use at her sole discretion.  Similarly our agreement
with GSMA does NOT allow us to sublet any part of our IMEI number range to any
other parties; any IMEI number ranges that may be allocated by GSMA to
FreeCalypso products may ONLY be used for those products that are physically
produced by Falconia Partners LLC from start to finish and not any others.

Basic technical guidelines
==========================

The purpose of these guidelines is to make it possible for the same firmware
build configuration to support both our existing FCDEV3B and various
repackagings of the underlying core modem solution (FC-TMS), i.e., to have the
same official FC Magnetite firmware builds for target fcdev3b run not only on
the original development board, but on all physical repackagings of the same
core modem solution.  To make such firmware reuse possible, the following
hardware design constraints MUST be followed:

* The flash+RAM chip must be the same Spansion S71PL129NC0HFW4B as used on our
  FCDEV3B, and it must be wired the same way: first flash chip select on Calypso
  nCS0, RAM on nCS1, second flash chip select on nCS2.  The flash reset line
  needs to be wired the same way as on FCDEV3B V2, otherwise Calypso sleep modes
  will be broken.  We realize that this flash and RAM capacity (16 MiB and
  8 MiB, respectively) is extreme overkill for typical modem applications
  outside of development, but supporting multiple flash chip types would
  introduce a configuration management burden which we are not willing to
  take on.

* Calypso's unused DSR_MODEM/LPG pin was left unconnected in Openmoko's version
  but on our FCDEV3B it is tied to GND on the board.  Other boards seeking to
  be FreeCalypso-compatible need to have this pin tied to GND as well because
  our firmware leaves this pin in its default power-up config of DSR_MODEM input
  and does not change it to LPG output - leaving it unconnected would cause it
  to float.

* Our firmware configures Calypso GPIO 3 as an input; GPIOs 0-2 and those
  multifunction pins which are unused and configured as GPIOs (TSPDI/IO4,
  BCLKX/IO6, MCUEN1/IO8 and MCUEN2/IO13) are configured as outputs.  Board
  wiring must be compatible with these directions: those pins which our fw
  drives as outputs can be simply left unconnected, while GPIO 3 needs to be
  sensibly driven or tied off as explained below.

* If someone needs a modem that produces an Openmoko-style application processor
  wakeup signal (asserted by the fw when the modem needs to send something to
  the host but is blocked by CTS being held high), this signal should be
  connected to GPIO 0.  Openmoko used GPIO 1 for this purpose, but in
  FreeCalypso GPIO 1 is taken because we use it for the loudspeaker control
  signal like on TI's D-Sample and Leonardo boards, hence we are moving the AP
  wakeup signal to GPIO 0, to be implemented if and when anyone builds a modem
  based on FC-TMS that needs to be provide such a signal.

* If your product includes a loudspeaker amplifier like on our FCDEV3B, connect
  its on/off control input to GPIO 1, otherwise leave our GPIO 1 output
  unconnected.

* Our fw produces a DCD modem control output on GPIO 2; if you are connecting
  the MODEM UART channel to an RS-232 port or to a USB-serial chip with a full
  set of modem control signals, connect DCD to GPIO 2.

* Our fw treats GPIO 3 as a DTR modem control input following TI's C-Sample and
  D-Sample boards.  If your product has a real DTR signal coming from an RS-232
  interface or from a USB-serial chip, connect it to GPIO 3, otherwise GPIO 3
  needs to be pulled down to GND like on Leonardo and FCDEV3B.

* If you are connecting the MODEM UART channel to a full RS-232 port or to a
  USB-serial chip with a full set of modem control signals, you should connect
  DSR and RI to TSPDI/IO4 and MCUEN1/IO8, respectively.  Right now our fw
  drives IO4 low and IO8 high, corresponding to DSR asserted and RI negated
  (normal quiescent state), and connecting the signals in this way allows the
  possibility of extending the fw to drive them in some more intelligent manner.

* Both Calypso UARTs need to be wired in an accessible way so that our standard
  FC Magnetite firmware can be used with the AT command interface on the MODEM
  UART and RVTMUX on the IrDA UART.

* Our fw configures the MODEM UART with hardware flow control enabled; if your
  applications lacks RTS/CTS signals, then Calypso's CTS_MODEM signal needs to
  be pulled down to GND so it is seen as asserted.

* Our fw configures the 4 MCSI/GPIO pins as MCSI rather than GPIO.  If your
  board does not use MCSI because you are tapping VSP instead or not using any
  digital voice interface at all, then you should put pull-down resistors on
  MCSI_RXD, MCSI_CLK and MCSI_FSYNCH, otherwise these signals will float.

Tapping VSP for the digital voice interface
===========================================

The Calypso+Iota chipset includes an interface called VSP for Voice Serial Port;
per TI's design intent it is a strictly private interface between Calypso and
Iota chips, but it is possible to tap into this interface to get an external
digital voice channel.  TI's official method for getting a digital voice channel
out of a Calypso modem is to use MCSI in their so-called "Bluetooth headset"
mode, however, our experiments on the FCDEV3B have revealed that this interface
does not work the way one would naively expect.  Unless we can convince TI to
dig up and release the sources for the Calypso DSP ROM, which we obviously
cannot count on, we won't be able to use MCSI reliably until and unless we
undertake to fully reverse their DSP ROM code from disassembly, which would be
an extremely major and very costly undertaking.  Because of this unfortunate
situation, the alternative way of tapping into VSP needs to be given
consideration.

Tapping into VSP is absolutely not possible on our current FCDEV3B, as the
signals in question are currently routed directly from one BGA to another and
do not come up to the surface at any accessible point.  The same situation holds
on every other existing Calypso phone and modem known to us - after all, VSP was
meant to be a private chip-to-chip interface.  Instead we are presenting the
idea of tapping VSP as a possibility for anyone who undertakes to repackage our
FC-TMS into some new form factor and desires a digital voice channel while at
it.

In TI's standard solution VSP clock and frame sync signals are generated by the
Iota ABB and are inputs to the Calypso DBB.  Because they are inputs to the
Calypso, it may be tempting to disconnect them from the ABB and have them
originate from an external source instead - however, TI's DSP code in the ROM
was most certainly written with the assumption that these signals will only
ever be driven by their ABB and never by anyone else, hence having them come
from a source whose timing does not come from the Calypso can cause all kinds
of strangeness which we will never be able to debug properly because the DSP is
a mysterious black box.  Therefore, my (Mother Mychaela's) stance is that if
you break the VSP connection between Calypso and Iota, then you are entirely on
your own - don't expect any help from me.  Instead my idea is to tap into VSP
without breaking it, specifically:

* Keep the clock and frame sync connection between Calypso and Iota, with Iota
  remaining the driver on these nets - but also bring these signals out
  externally, so external logic can sync itself to this interface as well.

* Do likewise for the line that carries downlink voice from the DBB to the ABB:
  let the ABB receive it and use it to drive the analogue earpiece output (which
  would be unconnected in a digital voice application), but let external logic
  receive it too.

* Break only the line that carries uplink voice from the ABB to the DBB: bring
  the Iota output side on one external interface pin and the Calypso input side
  on another external interface pin.  Putting a jumper on these adjacent header
  pins would restore TI's original configuration and allow uplink voice to come
  from an analogue microphone connected to the ABB, and if a digital uplink
  voice source is desired, remove the jumper and have an external source provide
  the bits which would otherwise come from Iota's voice ADC.

The above approach would provide a usable digital voice interface that would be
completely transparent (invisible) to the Calypso DSP and even to the ARM-side
firmware, hence it should work without any nasty surprises.