--- a/FC-handset-spec	Fri Sep 17 18:35:37 2021 +0000
+++ b/FC-handset-spec	Sun Sep 19 03:40:13 2021 +0000
@@ -1302,8 +1302,9 @@
 development platform.  The newly planned FreeCalypso development board is
 codenamed Venus, and it is envisioned as serving two goals:
 
-1) Many of the hardware features intended for the ultimate FC handset product
-   as described in Chapter 1 can be prototyped on this Venus board;
+1) Our Venus board will be a close-to-final prototype for the actual FC handset,
+   as close as can be achieved in the physical form factor of a development
+   board meant to be used "bare" on a lab bench;
 
 2) The board will serve as the ideal firmware development platform, covering all
    features and options that are listed in the previous chapter and defined as
@@ -1368,15 +1369,39 @@
 platform is likewise.)  If you need MCSI, then you are doing modem work, not
 handset, so use Caramel2 or FCDEV3B.
 
-3.3. RF bands and PCB layout
+3.3. Handset vs. development board
+
+The Mother's vision is that our Venus development board will be fairly close to
+a final handset motherboard in terms of included hardware and general layout:
+on the top side it will feature our LCD, underneath this LCD it will feature our
+keypad button set, whereas the bottom side will feature the same two core
+component clusters (each possibly covered by a shieldcan) as are envisioned for
+the final handset: one for the mobile domain (Calypso+RF core) and one for the
+USB domain (FT2232x subsystem of section 1.12).  However, in terms of physical
+form factor, FC Venus will still be a development board meant to be used "bare"
+on a lab bench, and will exhibit the following key differences from the final
+handset motherboard:
+
+* The general form factor will be simple rectangular and unconstrained, without
+  highly complex mechanical design effort that will later be needed for a
+  handset motherboard that goes into a plastic case.
 
-The Mother's intent for the Venus board is to stop copying Openmoko's triband
-PCB layout and instead switch to TI's original Leonardo+ quadband layout, which
-has been recovered from iWOW TR-800 via professional PCB reverse engineering.
-We will need quadband RF for the final FC Libre Dumbphone handset, thus it would
-be best to switch to it now, starting with Venus.
+* Two handset peripheral features will be omitted: the vibrator and the keypad
+  backlight.
+
+* There will be one additional peripheral just for the fw development platform
+  role of this board, as opposed to the handset prototype role: the magnetic
+  buzzer described in section 3.8.  JTAG and VSP tap header connectors can also
+  be regarded as special development-board-only extra peripherals.
 
-3.4. Power supply arrangement
+* The physical realization of audio interfaces will be a little different from
+  the final handset and more appropriate for a development board, as detailed
+  in section 3.7.
+
+* The SIM socket and all developer-user controls and indicators will be located
+  on the top side of the board.
+
+3.3.1. Power supply or battery connection
 
 FC Venus will have the same orange Weidmuller power input connector as previous
 TI and FreeCalypso development boards C-Sample, D-Sample, Leonardo, FCDEV3B and
@@ -1385,86 +1410,217 @@
 conversion.  During development, operation with an AC-mains-powered fixed 3.6 V
 DC supply is generally much more convenient than a real battery.
 
-For development and testing of handset battery management in the firmware, and
-for exercising the charging boot path in particular, Iota VCHG needs to be
-brought out like it is on iWOW DSK and FC Caramel2 boards, to be connected with
-a jumper wire to +5V pin on the DUART28 USB adapter whenever a "charger plugged"
-condition needs to be presented to the chipset.  FC Venus will feature a 2x3 pin
-header with Iota BCI signals as follows:
+However, in a departure from our previous development boards, it will also be
+possible to connect a real Li-ion battery (instead of a fixed supply) to the
+same connector - the Mother's intent is to use a common off-the-shelf 18650
+battery holder and wire it up to the necessary Weidmuller plug.  When a real
+battery is used, it will also be possible to charge it via Calypso+Iota BCI and
+FreeCalypso FCHG just like in a real handset - see the following section.
+
+3.3.2. USB subsystem
+
+Our Venus development board will include the same USB subsystem as intended for
+the final FC Libre Dumbphone handset, as described in sections 1.11 and 1.12,
+consisting of a USB mini-B interface connector, a charging on/off switch with
+the charging circuit behind it, and the FT2232x subsystem of section 1.12.
+
+This design is a radical departure from our previous development boards which
+bring out the two Calypso UARTs in their raw LVCMOS form, leaving the USB
+interface to an external adapter, most recently our own DUART28.  In fact, the
+Mother's original idea for the Venus board was to keep essentially the same
+interfaces as on Caramel2, retaining the use of the external DUART28 adapter
+and calling for a potential separate battery+charger board - but then this
+design was changed after further reflection.
 
-VBATS	VCCS
-PCHG	VCHG
-ICTL	GND
+On our previous modem-centric (as opposed to handset-centric) Calypso
+development boards, the USB interface was kept separate for the sake of
+modularity, allowing the two Calypso UARTs to be connected to other entities
+besides just USB.  That design made good sense and continues to make good sense
+for non-handset Calypso modem boards.  However, on a handset development board
+like FC Venus it becomes much more difficult to think of a realistic use case
+where the two Calypso UARTs (or either one of them) would need to be connected
+to something other than USB, thus this particular modularity becomes much less
+of a value - while the opposite approach of integrating USB provides numerous
+benefits:
+
+* One of the primary benefits of the new Venus board over existing Luna is
+  significant reduction in clutter: instead of 3 separate boards (Caramel2 MB,
+  LCD and keypad) connected with ribbon cables, there will be just one
+  integrated board.  If we also integrate the functionality of our DUART28C
+  adapter, then we reduce clutter even further.
 
-Please note that this planned BCI header pinout differs from iWOW DSK and FC
-Caramel2, which implement the following 2x4 pinout instead:
+* In the integrated USB arrangement, the Modem UART channel's RI output (coming
+  from Calypso GPIO8) will be connected just like in the final handset - see
+  section 1.12.1.  OTOH, this signal would have to be omitted if we were to use
+  our legacy 10-pin DUART interface and a DUART28 adapter - RI does not fit well
+  into that arrangement.
+
+* When development is done using an AC-mains-powered fixed DC supply and the
+  BSIM mode in FCHG, there still needs to be a way to present and remove VCHG.
+  Turning on the charging switch will be more convenient than connecting a
+  jumper wire between a VCHG header pin and the USB +5V pin on DUART28.
 
-ICTL	VCCS
-PCHG	VCHG
-ADIN2	ADIN1
-GND	GND
+* If our Venus board includes complete charging circuits just like the real
+  handset, operation with an actual battery will become a much more practical
+  option.  Such operation can be very useful for the purpose of giving field
+  demos away from FreeCalypso HQ: in such field scenarios, having to connect an
+  AC-mains-powered fixed DC supply may be difficult (limited space, no access
+  to AC power outlets, limited attention span of the audience), and furthermore,
+  if the demo is presented to a less technical audience, it will likely feel
+  more "real" if the phone prototype being demonstrated is powered by a battery
+  rather than an AC mains adapter.  In some cases, the charging process itself
+  (with standard USB as the charging power source) can be made a part of the
+  demo.
+
+3.3.2.1. Linux kernel patch requirement
 
-The Mother's approach to development and testing of higher-level UI functions
-dealing with battery management is to use the BSIM feature of our FCHG driver,
-in which case the board remains powered from a fixed DC supply (no actual
-battery) and only VCHG needs to be connected.  However, if a need arises to
-connect an actual battery and an actual Iota-controlled charging circuit, it
-will be possible: the battery will need to be connected to the orange power
-input connector, and the control signals for the charging circuit will need to
-be connected to the 2x3 header.
+The FT2232x USB subsystem implemented on FC Venus will include the boot control
+feature originating from DUART28C, as described in section 1.12.3.  This
+hardware feature has an implication for developer-users of this board: anyone
+wishing to play with a Venus board beyond already-flashed fw (i.e., anyone
+wishing to connect the board to a host computer) will need to apply our DUART28C
+support patch to the ftdi_sio driver in their Linux kernel; as for other host
+OSes beyond Linux, absolutely no support exists currently, thus you would need
+to do all of the necessary support-creating work yourself.
+
+The problem with the needed ftdi_sio driver patch is that it has been rejected
+by mainline Linux maintainers.  The patch is purely additive and non-impacting:
+it simply adds support for an entirely new USB device (a new USB VID:PID) that
+did not exist before, and has exactly zero impact on anything pre-existing, on
+anything outside of this brand-spankin'-new USB device.  But the power-wielding
+maintainers rejected the patch because it isn't general enough to them, because
+it serves only one specific hardware device which they don't wish to support.
+
+The Mother's answer to those Linux maintainers' game of hardball is to play back
+a game of my own: our Venus boards will NOT be sold for money, not for any
+price, instead they will be given out free of cost to loyal FreeCalypso
+supporters.  Anyone wishing to receive a Venus board will be required to apply
+the non-mainlined ftdi_sio driver patch locally to their own Linux kernel, and
+to show proof that they have applied this maintainer-rejected patch as a
+condition of receiving their board.
+
+3.3.2.2. Board bring-up order
+
+With the FT2232x USB subsystem integrated on the Venus board, this subsystem
+will become the only way to access Calypso UARTs for initial bring-up of a
+freshly populated board.  Furthermore, our DUART28C-based boot control mechanism
+will be the only way to trigger RPWON and nTESTRESET boot controls - there will
+also be a PWON button (see section 3.6), but that one is intended for higher-
+level end user functions after FC handset fw has been loaded and after all other
+bring-up tasks are completed on each board.  As a result of these factors, our
+FT2232x USB subsystem becomes part of the critical path for board bring-up, and
+it will in fact become the very first part to be brought up, before Calypso.
 
-The Mother's vision is that if and when we do need to exercise an actual Li-ion
-battery with an actual Iota-controlled charging circuit, we will need to build
-a separate battery+charger board that will connect to the power input and BCI
-control interfaces on the Venus board.  That battery+charger board will feature
-an 18650 battery holder and a +5V charging power source connection, the charging
-current path (aside from BCI controls) will be contained entirely in that add-on
-board, whereas the battery power interface between Venus and the add-on board
-will carry only the load or discharge current.
+The charging switch will need to be off during board bring-up, and it is
+expected to remain off during most development activities on FC Venus, to be
+turned on only rarely when exercising the charging function.
+
+3.3.3. Stepping stone toward the final handset
 
-The reasons for changing the BCI header pinout from iWOW DSK and FC Caramel2 to
-a different one for FC Venus are as follows:
+When the time comes to embark on the design of the actual FC Libre Dumbphone
+handset, after all necessary fw development work gets done on the Venus
+development board, one of the biggest challenges will be the need for close
+coordination between electronico-mechanical design of the motherboard PCBA and
+ergonomico-mechanical design of the handset case.  It is the Mother's hope that
+by being as close as possible to the final handset motherboard while subject to
+the constraints of a development board, our Venus board will serve as a useful
+stepping stone toward the actual handset.  When the time comes to hire a
+cellphone mechanical design expert to create the mechanical design for our FC
+handset, we will present a working Venus board (battery-powered and running
+well-polished fw, for proper psychological impact) to our hired mechanical
+designer, and hopefully this Venus board reference will work for the purpose of
+communicating to that mechanical designer our requirements from the electronics
+side, as in how much space is required for all of our functional components,
+which will be quite different from the more recent mainstream proprietary
+phones.
 
-* FC Tango (iWOW TR-800) module that forms the core of FC Caramel2 does not
-  bring out Iota VBATS as a separate signal - instead it is connected to the
-  VBAT supply inside the module.  However, if the charging current measurement
-  resistor will reside on a separate battery+charger board, then it would be
-  most proper to connect both VBATS and VCCS to the two sides of this resistor,
-  providing more accurate charging current measurement and CI control loop
-  operation.  Thus VBATS needs to be added to the BCI header.
+In terms of electronic circuit details, our final FC Libre Dumbphone handset is
+expected to be somewhat different from FC Venus, different enough to call for a
+different fw build target, as a matter of fact.  However, we expect that in
+terms of PCB layout, these electronic circuit differences won't be heavily
+disruptive, and we hope that once our hired mechanical designer gives us a
+design for the handset, we will then able to transform the PCB layout of FC
+Venus into the real handset motherboard.
 
-* ADIN1 and ADIN2 won't be needed when using a common off-the-shelf 18650
-  battery for prototyping - see section 1.10.1 for background information.
+3.4. RF bands and PCB layout
+
+The Mother's intent for the Venus board is to stop copying Openmoko's triband
+PCB layout and instead switch to TI's original Leonardo+ quadband layout, which
+has been recovered from iWOW TR-800 via professional PCB reverse engineering.
+We will need quadband RF for the final FC Libre Dumbphone handset, thus it would
+be best to switch to it now, starting with Venus.
 
 3.5. LCD module and backlight
 
-The Mother's original intent was to finalize the selection of LCD module for the
-actual handset before embarking on the detailed design (as in schematics, BOM
-and layout) of FC Venus, and to implement the final LCD and the final backlight
-circuit on the Venus board.  However, because of the delay in KWH020ST23-F01 LCD
-testing caused by Digi-Key part backorder issues (see section 1.4.2), this plan
-is being modified slightly: the design of FC Venus board is being ungated on the
-bet that KWH020ST23-F01 LCD module will pass all necessary qualification tests,
-but this Venus board design won't be sent out to PCB fab until those LCD tests
-actually pass.
+The LCD module on FC Venus will be Formike KWH020ST23-F01, the same LCD module
+which we have settled on for the actual FC handset.  As of 2021-09, we are in
+the process of ordering 100 pcs of this LCD module (the payment has already been
+made, and we are waiting for the shipment to clear customs), thus we are now
+past the point of considering different candidate LCD modules.  Our chosen
+Formike LCD module is almost perfect for development boards such as FC Venus;
+the only blemish is that in the absence of additional mechanical restraints, an
+elastic force that originates somewhere in the area of the folded-under FPC tail
+pushes the bottom of the module upward, away from the PCB, acting against both
+gravity and adhesive forces.  However, we have a planned workaround: we are
+working with a local-to-us mechanical engineering company to produce a custom
+retaining bracket; with the addition of this bracket, the mounting of our LCD
+module is expected to become secure enough for development board purposes.
 
 The backlight circuit design of section 1.4.4.1, which is hoped to be final, is
-being included in the Venus board design.
+being included in the Venus board design.  Specific LED currents don't need to
+be finalized for Venus PCB layout or PCB fabrication; resistor values that set
+these currents will only need to be finalized when the time comes to populate
+the first fabricated Venus PCBs with components.
 
 3.6. Keypad buttons
 
-The complex mechanical arrangement of keypad buttons that will be needed for the
-real handset will NOT be done on the Venus board.  Instead there will be a
-simple 5x5 matrix of buttons in rows and columns, with silk screen labels
-indicating the function of each button, matching D-Sample - the same arrangement
-as on our current Luna platform.  There will also be 3 out-of-matrix buttons for
-PWON, RPWON and RESET.
+The Mother's original intent for FC Venus was to punt on the more complex keypad
+arrangement that approximates the real handset, instead continuing what we
+currently have on FC Luna: a "raw" 5x5 matrix of buttons in rows and columns,
+with silk screen labels indicating the function of each button, matching TI's
+D-Sample.  However, this plan has been changed upon further reflection - the
+Mother's new thinking is that FC Venus will be a prototype toward the final
+handset, a prototype as close as possible to "the real thing" while staying
+within the constraints of a development board, thus the keypad arrangement needs
+to be made closer to "real" as well.
+
+The main 21-button keypad described in section 1.5 will need to be implemented
+on our Venus board, with the buttons in approximately correct relative
+positions, all below the LCD.  The buttons will be generic off-the-shelf tactile
+switches with finger-accessible actuators, similar to those used on Caramel2 and
+on our current Luna keypad add-on, except that SMT parts will need to be used,
+in order to not put extra constraints on component placement on the opposite
+side of the board.  Because we won't have any overlay with button legends, we
+will need to put silk screen labels on our PCB next to each button, denoting
+logical functions.
+
+Out of the 21 buttons of the main keypad, 20 will fall onto KBC/KBR cross-
+points, i.e., they will be "regular" keypad buttons.  However, the button in the
+END position (the one which is traditionally red, for power on/off and call
+hang-up) will be special: in hardware terms it will be the PWON button, both on
+FC Venus and on the final handset.  This special arrangement exactly follows
+TI's canon (D-Sample and predecessors), and has also been followed by the makers
+of Pirelli DP-L10.
+
+The 3 side buttons of section 1.6 will also need to be implemented on FC Venus.
+The two left side buttons (volume up/down) will be placed on the left side of
+our LCD, and the single right side button will be placed on the right side of
+our LCD.
 
 There will be no keypad backlight on the Venus board.  This secondary backlight
 is not needed for firmware development, as it is not managed separately in our
 fw architecture - instead its control will be absorbed into our R2D BLRR control
 mechanism on the final handset where this backlight will be added.
 
+3.6.1. No boot control buttons
+
+The Mother's original idea for FC Venus was to implement pushbutton switches for
+all 3 boot controls as in PWON, RPWON and nTESTRESET.  However, now that we are
+integrating the FT2232x USB subsystem of section 1.12 and the boot control
+mechanism of section 1.12.3 as a non-removable part of the Venus board itself,
+pushbutton switches for RPWON and RESET are being eliminated, leaving only PWON
+in the "END" position in the main keypad.
+
 3.7. Audio interfaces
 
 Corresponding to the 3 audio channels of section 1.7, there will be 3 analog
@@ -1500,20 +1656,6 @@
 controlled by the respective Calypso outputs) exactly like D-Sample, and either
 of these LEDs can be used to simulate vibrator on/off state.
 
-3.10. Host computer interface
-
-The host interface model on FC Venus will need to follow that of section 1.12.
-More specifically, our Venus board will implement the mobile side of the "wall"
-between USB and mobile power domains, complete with all provisions of section
-1.12.2 for the mobile side, whereas the USB domain is already implemented on our
-DUART28 adapter board.  The two domains will be interconnected with a ribbon
-cable in the FC Venus lab bench setup.  The 10-pin DUART header will have our
-standardized FreeCalypso DUART pinout.
-
-Also following the principal design of section 1.12.3, there will be a 3-pin
-header on the Venus board bringing out RPWON, nTESTRESET and GND, to be
-connected to the boot control header on DUART28C.
-
 4. Motorola C139 port
 
 4.1. Background information