As of this writing (2020-09), the Mother's company Falconia Partners LLC is
actively in the process of bringing to market a new FreeCalypso hardware
solution based on our FC Tango module, and we also have an FTDI-based
(specifically FT2232D) adapter for connecting to Calypso UARTs (both of them)
and for controlling the Calypso module's PWON and RESET, allowing remote
control of Calypso power and boot in physically unattended environments.
However, this Tango-based solution is expected to become available some time
in 2020-12 (up to 3 months from now), and we realize that some people may not
be able to wait this long - some people may have an immediate need for some
working solution right now.

We are also aware that our European colleagues over at Sysmocom are working on
a competing solution based on the Huawei GTM900 Calypso modem module, but are
going totally the wrong way about it, and seem to be running into roadblocks
resulting from their earlier bad design choices.  In light of this observed
situation, the present document has been put together to provide some guidance
to those who are currently misguided.  If someone needs a working solution
right now, cannot wait another 3 months for our company to deliver our Tango-
based Caramel2+DUART28 solution, is looking at using GTM900 for the Calypso
module, and would be willing to use an FT2232x (either D or H) chip instead of
Sysmocom's poor choice of Silabs CP2105, this document will tell you exactly how
you should hook everything up in order to produce a guaranteed-working solution
without wasting time and energy on multiple design iterations.

FT2232x chip and EEPROM
=======================

Either FT2232D or FT2232H should work equally well, hence the choice between
the two is up to the board designer's preference.  Our DUART28 adapter uses
FT2232D, and this choice was made primarily in the hope of easing the onerous
requirement of PCB controlled impedance (90 ohm differential) for USB traces:
FT2232H supports USB high speed, and this USB HS capability is thought to make
the controlled impedance requirement more stringent.  Our competitor CP2105 has
no USB HS capability just like FT2232D, hence the latter was chosen to match.
But if the 90 ohm controlled impedance requirement is not a problem for you,
then by all means go ahead and use the newer and apparently more popular
FT2232H.

Whichever FT2232x chip you choose, you should include an EEPROM in your board
design.  This EEPROM is officially optional per FTDI, but if you omit it, you
lose the ability to set a custom USB VID:PID.  If you are only interested in
the two Calypso UARTs and don't need programmatic control of PWON and RESET,
then using the FT2232x chip's default USB VID:PID of 0x0403:0x6010 (with or
without an EEPROM) is perfectly fine.  However, if you are going to do what I
recommend below in terms of using (otherwise unused) FT2232x Channel B RTS and
DTR outputs to control PWON and RESET, then you will need to apply a custom
patch to the Linux kernel's ftdi_sio driver (see freecalypso-hwlab Hg
repository) in order to make this mechanism practically usable.  If you are
going to be applying any kind of custom patches to that ftdi_sio driver, having
a custom USB VID:PID will be very helpful in order to apply the needed quirks
conditionally, hence the EEPROM becomes necessary.

LEGAL NOTE: Falconia Partners LLC has received an official allocation of 8 PIDs
from FTDI out of FTDI's USB VID, but these USB IDs are _ONLY_ for hardware
products that are physically produced by Falconia Partners LLC - other parties
may not use these USB IDs without our explicit permission.  Therefore, if you
are going to use a custom USB VID:PID, you will need to provide your own.

Dual UART signal connections
============================

Unlike CP2105, the two channels of FT2232x are perfectly symmetric, hence the
choice of which FT2232x channel should be connected to which Calypso UART is
arbitrary.  As the Mother of FreeCalypso, I very strongly encourage everyone to
use this convention: Calypso MODEM UART (the one for which Huawei brought out 8
wires with full modem control) should be connected to FT2232x Channel A, and
Calypso IrDA UART (the one for which there are only two wires) should be
connected to FT2232x Channel B.

If you are going for the lowest cost in terms of component count and PCB real
estate, it is perfectly acceptable to connect FT2232x I/O pins directly to
Calypso UART pins.  Yes, FT2232x outputs operate at 3.3V and cannot be brought
down to Calypso native 2.8V, but if you read TI Calypso datasheets (document
CAL000/A in particular), is says quite clearly that input voltages of up to
VDDS+0.5V are acceptable, i.e., the inputs are tolerant of 3.3V.  This situation
becomes a little less than ideal during Calypso sleep modes (the higher voltage
feeds into the chipset's V-IO rail and brings that rail a little higher than
normal), but engineering is all about trade-offs and compromises, and sometimes
it is necessary to trade off between perfection and cost.

If you do wish to feed proper 2.8V signals to the Calypso instead of 3.3V, the
easiest way to do so would be to insert LVC buffers into signal paths from
FT2232x outputs to Calypso UART inputs.  Power the LVC buffer IC from the
Calypso+Iota chipset's V-IO rail, which Huawei brought out on an interface pin
they named "VDD".  There will be no problem with partial power-down conditions
(USB on, Calypso off) because LVC buffers are specifically designed for such
operation and have very low Ioff specs in the uA range.

Our DUART28 adapter also includes another LVC buffer going the other way, in
the path from Calypso UART outputs to FT2232x inputs, but it is included for
only one reason: in order to gracefully support the other partial power-down
scenario of Calypso up and running, but no USB host connected and thus no USB
power.  If this latter scenario is not a concern for your application, then
there is absolutely no problem with connecting Calypso UART outputs directly to
FT2232x inputs without any buffers.

Controlling PWON and RESET
==========================

FT2232x RTS and DTR outputs are normally CMOS high (RS-232 inactive) when no
one is poking at them, but the standard Linux kernel ftdi_sio driver (following
POSIX stipulations, apparently) unconditionally makes them both CMOS low
(RS-232 active) when the ttyUSBx device is opened.  If you look in our
freecalypso-hwlab Hg repository, you will find a patch to this driver (a quirk
conditionalized on a custom USB VID:PID) that suppresses this automatic
assertion of RTS & DTR on ttyUSBx device open, allowing userspace applications
to control them explicitly with TIOCMBIS and TIOCMBIC ioctls.

Our upcoming Caramel2+DUART28 solution will include an optional (one may connect
the needed jumper wires or leave them unconnected) provision for controlling
the Calypso+Iota chipset's PWON and RESET with otherwise unused FT2232 Channel B
RTS & DTR outputs.  The arrangement we have implemented is that when ChanB RTS
is asserted (CMOS low, TIOCMBIS), Calypso PWON is triggered, and when ChanB DTR
is asserted, Calypso RESET is triggered.  We recommend that others follow the
same convention.

PWON wiring
-----------

The Calypso+Iota chipset's (Iota really) PWON input is internally pulled up to
raw VBAT, thus it must not be connected directly to any ordinary 3.3V or 2.8V
logic - instead it needs to be driven with an OC or OD buffer.  If it is to be
controlled with ChanB RTS (FT2232x BDBUS2 output), the ideal circuit is a simple
non-inverting OD buffer such as Nexperia 74LVC1G07; the OD buffer IC's Vdd
supply should be connected to the FT2232x chip's 3.3V I/O supply rail.

RESET wiring
------------

The RESET input is different between Huawei GTM900 and FC Tango modules.  On FC
Tango it is raw Iota nTESTRESET and thus needs to be driven in the same way as
PWON described above, but GTM900 internally incorporates the JTAG reset circuit
depicted on TI's Leonardo schematics, and the RESET signal they bring out is
what we (FreeCalypso) call XDS_RESET - see the Calypso-test-reset article.  It
is acceptable to drive XDS_RESET with an OC/OD driver just like PWON or raw
nTESTRESET, but this OC/OD driver becomes optional with XDS_RESET - thanks to
the transistor circuit inside the GTM900 module, it is perfectly acceptable to
wire FT2232x BDBUS4 output (ChanB DTR) directly to GTM900 RST input, and it will
work per our convention, triggering a reset when ChanB DTR is asserted.

The XDS_RESET transistor circuit inside GTM900 does have one unpleasant side
effect though: on modules like FC Tango that bring out raw nTESTRESET, that
reset includes a built-in Switch-ON function, and PWON effectively becomes
optional - one can fully control the module using only RESET and soft poweroff
- but the same does NOT hold on GTM900.  XDS_RESET may or may not work (no
guarantees) when the Calypso+Iota chipset is in VRPC switched-off state, thus
one must do a switch-on with PWON first, and then drive a reset if necessary.
And no, driving XDS_RESET with an OC/OD buffer won't do anything to eliminate
this unpleasant side effect - you just have to live with it for as long as you
use GTM900 modules and not FC Tango.