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

[This document was originally written in 2018-10; subsequent updates
 are noted inline in the same bracketed form as this note.]

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.

[2019-03 update: we now have working flash chip type autodetection, and
 commercial modem products can use a smaller flash+RAM chip, specifically
 Samsung K5A3240CTM or K5A3281CTM as used by Openmoko.]

* 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 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
  if need be.

* 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
  application 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.
  MCSI_RXD can be directly tied to GND without a resistor as it is always an
  input to the Calypso, but MCSI_CLK and MCSI_FSYNCH need to be pulled down
  with resistors: our fw can enable TI's "Bluetooth headset" and "Bluetooth
  cordless" modes, in which case these signals become outputs.  If the signals
  are switched to being outputs by software command but are tied to GND on the
  board, the result will be a shorted output driver which could damage the chip,
  and it is clearly not acceptable to produce hardware that can be damaged by
  an AT command, even an obscure and non-standard one.

Cost increment
==============

If you don't need huge flash and XRAM capacity, don't have a DTR input and are
not using MCSI, then the incremental cost of being firmware-compatible with
FCDEV3B compared to Openmoko's approach of leaving all unused signals
unconnected and using a smaller flash+RAM chip consists of:

* A logic voltage level translating buffer to provide a reset to the flash chip
  that meets its timing requirements;

[2019-03 update: the above is no longer required, you can now use one of the
 smaller flash chips which are compatible with TI's silly FDP scheme and thus
 don't need the extra translating buffer IC for reset.]

* 3 pull-down resistors on GPIO3, MCSI_CLK and MCSI_FSYNCH;

* Direct connections to GND on DSR_MODEM and MCSI_RXD pins.

For parties other than the Mother, it is up to you to decide if being firmware-
compatible is worth the cost increment or not, but all modem repackagings
produced by us under the FreeCalypso brand will follow these software and
firmware configuration management compatibility guidelines, and the same is
required for anyone else who wishes for their hardware variant to be accepted
into the FreeCalypso family.

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.

[2019-03 update: we got MCSI working now, please read the Calypso-digital-voice
 article for more info about both MCSI and VSP options.]

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.

Triband vs. quadband
====================

One shortcoming of our current FreeCalypso modem solution is that it is triband
and not quadband; more specifically our standard hw build omits the GSM850 band,
or we can build a different configuration that supports GSM850 but omits EGSM
(the 900 MHz band).  To the best of our knowledge the GSM850 band is used very
little these days, but being only triband makes us look bad compared to the
competition: all of the mainstream proprietary GSM modem modules are fully
quadband these days.

It *is* possible to make a Calypso-based quadband modem, as TI had one: their
Leonardo reference board for the Calypso+Iota+Rita chipset existed in several
versions some of which were quadband, and their E-Sample board (Calypso+) which
used the same Rita RF block was also quadband.  However, changing our current
FC modem design from triband to quadband would involve a highly invasive PCB
layout change: basically our entire modem PCB layout and particularly the GHz RF
section would have to be ripped up and reshuffled into a different arrangement.
Furthermore, if we as the FreeCalypso community do decide that we wish to
produce a quadband modem, I (Mother Mychaela) would NOT be comfortable with
entrusting the needed re-layout work to an "ordinary" PCB layout contractor who
is not a cellphone RF design expert, instead we would need to get a consultation
from an RF PCB design expert who has experience very specifically with GSM
cellphone design and not any other applications.  Finding such an expert would
be a major task in itself, and that expert most certainly won't come cheap.
Therefore, a quadband FreeCalypso modem probably won't happen unless we get
someone with a lot of money to throw around.

There is one exception, though: if anyone would like to see our FreeCalypso
modem repackaged into the SMT module form factor copied from BenQ M32 and pays
for that venture, the result would be naturally quadband as the layout of BenQ's
module follows the same floorplan in the RF section as TI's quadband Leonardo
and E-Sample layout.  However, that approach would involve a step to reverse-
engineer BenQ's layout by slicing their board and imaging its inner layers,
hence anyone seeking this approach would need to be prepared to pay for that
step.

If anyone ever does pay for the creation of a quadband version of our
FreeCalypso modem solution, be it in BenQ's physical form factor or some other,
what about the firmware?  For a long time I thought that a quadband modem would
need a different firmware build configuration because of incompatible TSPACT
signals.  Our current triband modem (copied from Openmoko) has them wired like
this:

TSPACT2 = Tx high bands
TSPACT1 = Rx PCS band
TSPACT4 = Tx low bands

But TI's original TSPACT wiring for the quadband RFFE on their Leonardo and
E-Sample boards was different:

TSPACT2 = Tx low bands
TSPACT1 = Tx high bands
TSPACT4 = Rx GSM850 band

These two TSPACT signal assignments are mutually incompatible, hence if we make
a quadband modem following TI's original Leonardo/E-Sample TSPACT wiring, it
won't be able to share the same fw with our triband modems.  But then I got an
idea: what if we wire them up in our own creative way as follows:

TSPACT2 = Tx high bands
TSPACT4 = Tx low bands
TSPACT5 = Rx GSM850 band

Then we can have the same fw build configuration support both triband and
quadband FreeCalypso modems by driving the signals as follows:

TSPACT1 = Rx PCS band
TSPACT2 = Tx high bands
TSPACT4 = Tx low bands
TSPACT5 = Rx GSM850 band

TSPACT1 will be driven but unused on quadband modems, whereas TSPACT5 will be
driven but unused on triband ones like our current FCDEV3B.  To me (Mother
Mychaela) being able to have the same fw among *all* FreeCalypso modem variants,
both triband and quadband, is more valuable than the symbolic act of recreating
TI's original RFFE wiring, hence I am now leaning toward this new approach.