--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/FCDEV3B-repackaging	Wed Oct 10 07:28:15 2018 +0000
@@ -0,0 +1,182 @@
+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.