--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/duart28/design-spec	Tue Jul 14 07:40:42 2020 +0000
@@ -0,0 +1,182 @@
+FreeCalypso DUART28 Adapter
+Board design specification
+
+1. What it is and why it is desired
+
+Under our FreeCalypso umbrella we have a family of hardware products based on
+the Calypso chipset from Texas Instruments.  The Calypso chip has two UARTs,
+one with TxD & RxD data leads plus RTS & CTS flow control, and the other with
+TxD & RxD data leads only.  There is also a convention whereby some Calypso
+GPIOs are defined to be additional modem control signals and associated with
+the Modem UART (the one that has RTS & CTS flow control in addition to
+TxD & RxD), thus the result is one UART with a near-complete set of modem
+control signals and one UART with data leads only.
+
+The convention established in FreeCalypso is that all of our Calypso development
+boards bring out both Calypso UARTs in their native form, which is 2.8V native
+logic levels, tolerant of 3.3V but not any higher voltages.  In order to connect
+these UARTs to a PC or laptop serving as the development host, a separate USB
+to low-voltage UART adapter board is used, preferably one that puts both UARTs
+(two ttyUSBx devices) behind a single USB device.  Our USB to dual UART
+converter chip of choice is FT2232D; this chip has been chosen over various
+competitors because it provides two UART channels (ttyUSBx devices) in one USB
+device, because it supports non-standard serial baud rates on both channels,
+allowing us to use GSM-specific high baud rates of 203125, 406250 and 812500
+bps, and because it supports the full set of modem control signals like one
+would find on an old-fashioned RS-232 port.
+
+Since we got our first FCDEV3B boards built in 2017 and up until the present,
+we've been using FT2232D breakout boards made by PLDkit as our USB to dual UART
+adapter:
+
+http://pldkit.com/other/ft2232d-module
+
+These generic FT2232D adapters work quite well for our current purposes, but
+now we have several reasons for desiring our own custom-built adapter to
+replace them, detailed below.
+
+1.1. Desire for custom interface pinout
+
+In FreeCalypso we have the following convention: all FC hardware products that
+bring out both Calypso UARTs do so by way of a single 10-pin (2x5) 2.54 mm
+header in a fixed pinout given below.  This convention was started with
+FCDEV3B, our first FC hw product, and is now being continued with MMTB1 and
+Caramel2 boards.  Our standardized DUART header pinout is as follows:
+
+Header pin	Calypso signal
+1		GND
+2		GND
+3		TX_IRDA
+4		TX_MODEM
+5		RX_IRDA
+6		RX_MODEM
+7		GPIO2_DCD
+8		RTS_MODEM
+9		GPIO3_DTR
+10		CTS_MODEM
+
+Pins 7 and 9 were originally left unused (they are unconnected on FCDEV3B), but
+they have been assigned as DCD and DTR (from the host's perspective) starting
+with MMTB1.  Note that while DCD and DTR in the table above are named from the
+host's perspective, all Calypso signals ending with _MODEM or _IRDA are from
+the chip's perspective, i.e., the opposite.
+
+When we use FT2232D breakout boards from PLDkit as our USB to DUART adapter, we
+use a custom hand-made ribbon cable with crimp terminations: a 10-wire ribbon
+is used, the full ribbon runs intact in the main body of the cable, but toward
+the FT2232D adapter board the ribbon is split in two, with 7 wires going to the
+A side of PLDkit's breakout board and with 3 wires going to the B side.  Each
+of the two subribbons (both the 7-wire one and the 3-wire one) gets terminated
+onto a 15-position female connector, with the two resulting 15-pin connectors
+mating with the two 15-pin single-row headers located on the two sides of
+PLDkit's breakout board.
+
+This current solution is much better than manually connecting each wire
+individually: with connectors being solid pieces rather than individual wires,
+a setup can be very easily taken down and then put back together, which is
+absolutely essential for our mode of usage.  But the downside of this approach
+is that once our two 15-position female connectors mate with PLDkit's headers,
+there is no way to make a separate connection to other signals which are not
+covered by our basic 10-wire set.  This limitation is becoming problematic for
+two reasons:
+
+1) Our upcoming Caramel2 board will have the same 10-pin DUART header as FCDEV3B
+and MMTB1 (with DCD & DTR present like on MMTB1), but it will also have an
+additional RI modem control output on another Calypso GPIO accessible on the
+general expansion interface header.  There is no room to squeeze this extra RI
+signal into our standardized 10-pin DUART interface, but this extra signal is
+rarely needed.  The compromise solution currently being pursued is that the
+main 10-wire ribbon will connect all UART signals (both UARTs) with the
+exception of RI, and those who need RI should be able to connect it with a
+separate individual wire, connecting to the GPIO1 pin on the general expansion
+interface header on the Caramel2 side.  But if we use PLDkit breakout boards
+with our current ribbon cables with crimp terminations, there will be no way to
+connect this extra RI wire to the FT2232D adapter board when the big 15-pin
+connector blocks the entire header.
+
+2) PLDkit's FT2232D breakout boards bring out USB 5V on one of their pins, and
+this auxiliary 5V output is useful in some applications.  We have one upcoming
+application where this auxiliary 5V will be used to exercise the Calypso+Iota
+chipset's VCHG boot mode, also on the upcoming Caramel2 board - but we get into
+the same problem of the PLDkit board header pin becoming inaccessible when our
+crimp-terminated ribbon cables are used.
+
+If we replace the generic PLDkit breakout with our own custom FreeCalypso USB
+to dual UART adapter board, we can easily solve these problems by implementing
+our own custom header pinouts.  The new DUART28 adapter board covered by the
+present design spec will bring out 3 headers as follows:
+
+* One 10-pin header carrying TxD, RxD, RTS, CTS, DTR and DCD for UART 0 and
+just TxD & RxD for UART 1, in a pinout exactly matching our standardized
+FreeCalypso DUART interface;
+
+* One 3-pin header carrying UART 0 auxiliary modem control inputs DSR and RI,
+plus a ground pin;
+
+* One 2-pin header bringing out USB 5V and GND, for auxiliary uses.
+
+1.2. 3.3V vs. 2.8V logic levels
+
+Calypso I/O pins have native 2.8V logic levels, but they are specified as being
+tolerant of 3.3V.  They do have internal clamping diodes to the Calypso chip's
+2.8V V-IO rail, but their forward drop voltage is right around 0.5 V, thus if
+external inputs are at 0.5 V above V-IO (practically meaning 3.3V inputs), no
+significant current flows through these clamping diodes.
+
+When we use a raw FT2232D breakout board as our USB to FreeCalypso DUART
+adapter, we are connecting the FT2232D chip's 3.3V outputs directly to Calypso
+inputs; this arrangement has been working well for us since 2017, but a more
+proper 2.8V DUART adapter is desirable for a few reasons:
+
+* When the Calypso+Iota chipset enters superdeep sleep (our shorthand term for
+Calypso deep sleep combined with Iota ABB sleep mode), the chipset's VRIO
+regulator (the one that produces the 2.8V V-IO raill) switches into sleep mode,
+which has much looser regulation than in the regular Active mode.  In this
+condition external 3.3V can feed into the V-IO rail through pull-up resistors
+and pull the rail itself a little higher than where the chipset's own regulators
+would have it, which is certainly not desirable.  If UART inputs to the Calypso
+board are driven with 2.8V logic levels rather than 3.3V, this problem is not
+expected to occur.
+
+* If we are going to build a custom FreeCalypso DUART adapter for other reasons,
+it is only proper to make it 2.8V native rather than 3.3V - after all, our
+adapter is highly specific to Calypso applications, not generic, and Calypso
+has native 2.8V I/O.
+
+* We have a competitor: Sysmocom folks use CP2105 adapters (mv-uart adapter
+board and other integrated designs) instead of our FT2232D, and their
+CP2105-based designs operate at native 2.8V logic levels, no 3.3V.  For
+political reasons it is important to be no worse than the competition, giving
+us one more reason to go for native 2.8V.
+
+Because FT2232D I/O (unlike CP2105, FT232R and many other chips that aren't
+suitable for other reasons) cannot go below 3.3V, making an FT2232D-based
+adapter put out 2.8V logic levels requires inserting an extra level shifter
+after FT2232D outputs - we shall use an LVC buffer for this purpose.
+
+1.3. Partial power-down considerations
+
+The following two corner cases need to be considered, as each can be a trouble
+spot:
+
+1) When the USB to DUART adapter is connected to a host computer and thus has
+USB power present, but the connected Calypso device is in the switched-off
+state in the Iota VRPC sense (a condition that occurs all the time in normal
+operation, e.g., whenever you are running fc-loadtool and waiting to press the
+PWON button on the board), current can flow from USB DUART adapter outputs into
+powered-down Calypso chip inputs.  This current flow cannot be eliminated
+without putting LVC or similar buffers on the Calypso board side, but we need
+to be mindful of this current and we need to limit it.
+
+2) When a Calypso device is connected to the USB DUART adapter, the Calypso
+device is up and running (VRPC Active state), but there is no USB host
+connected, current can flow from Calypso outputs into a powered-down FT2232D or
+other chips in the USB DUART adapter.  With our current raw FT2232D-to-Calypso
+arrangement we have about 5 mA of current flowing per pin under the described
+condition, which is a little too much.
+
+If we replace the generic FT2232D breakout with our own custom adapter board
+design, we can solve the second partial power-down problem (the case of Calypso
+on, but no USB host) by inserting LVC buffers in front of FT2232D inputs -
+these LVC buffers are fully specified for partial power-down applications and
+have very small Ioff leakage current.