--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/GTM900-design-guide	Sun Sep 13 21:36:17 2020 +0000
@@ -0,0 +1,150 @@
+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.