add hardware description

Signed-off-by: Michel-FK <michel.stempin@funkey-project.com>

docs/developers/hardware/architecture.md

@@ -1,31 +1,78 @@
-The FunKey S is a small foldable retro-gaming console.
 
-Its electronic parts consist in:
+## Block Diagram
 
- - 1x main PCB (0.8 mm thickness) with components on both sides, the maximum component height above PCB on both sides is 1.5 mm. Current revision for this board is Revision E
- - 1x 1.54” IPS LCD TFT screen with SPI interface and using a custom flex cable
- - 1x 420 mAh 402540 LiPo battery
+Eventually, the design constraints listed in the previous section led
+to the following electronic diagram, featuring 3 main blocks:
 
-![FunKey S Block Diagram](/assets/images/FunKey%20S%20Block%20Diagram.png)
+ - 1x main PCB (0.8 mm thickness) with components on both sides, the
+   maximum component height above PCB on both sides is 1.5 mm. Current
+   revision for this board is Revision E
 
-The FunKey S PCBA Rev. E contains the following main components:
+ - 1x 1.54” IPS TFT LCD screen with SPI interface and using a
+   custom flex cable, containing a built-in screen controller chip
 
- - 1x Allwinner V3s SoC with integrated 64MB DDR2 DRAM (LQFP128 package)
- - 1x X-Powers AXP209 companion PMIC chip to provide almost all required power supply rails (QFN48 package)
- - 1x Sylergy SY8088 Buck DC/DC SMPS chip to provide the DRAM power supply rail (SOT23-5 package)
- - 1x NXP PCAL6416 I2C GPIO expander to control all buttons and keypads (except Power Key) (QFN24 package)
- - 1x Diodes Inc. PAM8301 mono audio amplifier (TSOT26 package)
- - 1x 24 MHz main crystal
- - 1x 32.768 kHz RTC crystal
- - 1x Standex-Meder MK24 Reed switch for magnet proximity detection
- - 1x LED for charge indication
- - 1x 8 Ω 0.3 W built-in speaker
- - 1x Micro USB edge-mounted connector
- - 1x Micro SD (TF Card) Push/Push low-profile connector
- - 1x Hirose DF37 0.4 mm pitch miniature LCD connector
- - 1x JST 1 mm pitch battery connector
- - 1x 1.27 mm pitch debug UART header (not mounted)
+ - 1x 420 mAh 402540 LiPo battery, containing an active protection
+   circuitry
 
-![FunKey Top](/assets/images/FunKey%20S%20Top.png)
+![FunKey S Block Diagram](/assets/images/FunKey_S_Block_Diagram.png)
 
-![FunKey Bottom](/assets/images/FunKey%20S%20Bottom.png)
+## 3D View
+
+A 3D rendering of the PCBA done in KiCAD produces the images below:
+
+![FunKey Top](/assets/images/FunKey_S_Top.png)
+
+![FunKey Bottom](/assets/images/FunKey_S_Bottom.png)
+
+## BOM
+
+An interactive BOM is available in the [next section][4].
+
+## Schematics and Layout
+
+All the hardware design and production files required to build the
+[**FunKey S** retro-gaming console][1] electronic PCBA using the
+[KiCAD ECAD tools][2] are available as Open Hardware in the [FunKey S
+Hardware repository][3].
+
+???+ note "Topological vs. logical schematic symbols"
+
+    The **FunKey S** schematics use symbols and placement that are as
+    close as possible to their corresponding physical package and
+    layout, instead of defining symbols that are conveniently arranged
+    by logical properties. Even if this makes schematics more complex
+    at first sight, the benefit of this approach is that the step to
+    go from the schematics to the physical layout becomes much easier,
+    and so is the debugging of the physical board, which is then very
+    close to the schematics too.
+
+???+ note "Explicit schematic wires"
+
+    Another habit that is used everywhere in the **FunKey S**
+    schematics is that all signals (except power supplies and GND) are
+    routed using explicit wires, rather than counting on invisible
+    connection by net names and relying of the reader to search these
+    names all over the place. This forces related components to be
+    clustered in compact groups to shorten the wires, and put more
+    focus on inter-cluster signals, with a natural inclination to
+    unravel wire nests in the schematics before laying out the actual
+    board.
+
+???+ note "Power supply nets"
+
+    There are some "PWR_FLAG" symbols added here and there, which is
+    the proper way in KiCAD to declare that a given net has a known
+    supply and thus prevent the ERC (Electrical Rule Check) to throw
+    an error.
+
+The schematics will be discussed function by function in the following
+sections.
+
+[1]: https://www.funkey-project.com/
+[2]: https://kicad.org/
+[3]: https://github.com/FunKey-Project/FunKey-S-Hardware
+[4]: https://htmlpreview.github.io/?https://github.com/FunKey-Project/FunKey-S-Hardware/blob/master/BOM/ibom.html
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/hardware/audio.md

@@ -0,0 +1,84 @@
+Playing audio is absolutely part of the gaming experience!
+
+So for a retro gaming console like the **FunKey S**, having a decent
+audio playback is a requirement, despite its lilliputian size.
+
+We discarded the solution of using a piezo-electric buzzer: these can
+get a loud sound in a small volume, but only at their resonance
+frequency, so the sound quality is extremely poor.
+
+Turning back to the solutions used in modern smartphones as an
+example, there are 2 paths to consider:
+
+ - playing audio internally by the mean of speaker(s)
+
+ - playing audio externally by using headphones, with or without a cord
+
+The speakers used in today's smartphones are rather sophisticated and
+achieve very good performance. However, these are using
+made-to-measure speakers and cavities, such that they cannot be found
+and reused as standard parts in a design like ours.
+
+As for the external audio solution, the **FunKey S** is so small that
+it is not possible to integrate an audio jack on the PCB to connect
+headphones! And despite our search, there is no simple and small
+enough way to integrate Bluetooth to output audio to cordless
+headphones either.
+
+![Speaker](/assets/images/Speaker.png){: align=left }
+
+The best solution we have found consists in using a single tiny [CUI
+CDM-10008][1] speaker, that is able to output 72 dB spl @ 1m from a
+0.3W input power, with relatively modest dimensions: 10 mm diameter
+and only a 2.9 mm thickness, out of which 1.4 mm can be inserted into
+a PCB hole, thus only having a height above PCB of only 1.5 mm.
+
+Connections are not easy though, since this speaker is meant to have
+wires soldered to its pads, but we used 2x [castellated][2]
+(half-round plated holes) pads with a placement just over the speaker
+pads that enables manual soldering between the speaker and the PCB
+with a solder blob.
+
+## Schematic
+
+The audio schematic is simple, as the Allwinner V3s already
+contains an analog stereo audio codec (coder/decoder): we only have to
+take one of its headphone output channel (left or right) and feed it
+to a mono audio amplifier.
+
+We chose the [Diodes Inc. PAM8301][3] chip because of its cheap price,
+good availability, its more than sufficient output power of 1.5W and
+its filterless operation, meaning that no bulky series capacitor is
+required to drive the speaker.
+
+Here is the corresponding schematic:
+
+![Audio Schematics](/assets/images/Audio_Schematics.png)
+
+We chose the right headphone channel HPOUTR that is fed to the audio
+amplifier **U2** through a coupling capacitor **C3**.
+
+The audio amplifier /SD shutdown input is driven by one V3s GPIO (PF7
+on pin 100), with a pull-down resistor **R2** to disable the amplifier
+by default.
+
+The audio amplifier power supply is filtered using a ferrite bead
+**L1** in order to eliminate high-frequency digital noise, and
+decoupled by 2 capacitors **C4** and **C5**, as recommended in the
+device datasheet.
+
+The speaker **SP1** is driven in differential mode in order to get the
+maximum voltage swing and thus the maximum power available for a given
+output current.
+
+Two ESD protection TVS diodes **D13** and **D14** are added, since the
+speaker may be accessible to the user through the enclosure grid in
+front of the speaker.
+
+[1]: https://www.cui.com/product/resource/cdm-10008.pdf
+[2]: https://www.pcbdirectory.com/community/what-are-castellated-holes-on-a-pcb
+[3]: https://www.diodes.com/assets/Datasheets/PAM8301.pdf
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/hardware/buttons.md

@@ -0,0 +1,137 @@
+As a generic game console emulating many classic ones, the FunKey
+requires numerous buttons:
+
+ - A soft "ON/OFF" button
+ - A "**+**" control pad with "Up", "Down", "Left" and "Right" buttons
+ - A "**X**" control pad with "A", "B", "X" and "Y" buttons
+ - "Start" and a "Fn" buttons
+ - At least L1 and R1 shoulder buttons
+
+As can be seen in the page on the [PMIC][1], the soft "ON/OFF" button
+is directly connected to the power management chip, so we are left
+with 4 + 4 + 2 = 12 buttons for game control.
+
+After testing tactile domes in our [FunKey Zero][2] prototype, we
+decided to go back to integrated tactile switches, as their placement
+is much easier using a regular SMT pick & place machine like any other
+components on the PCB, whereas the separate tactile domes required an
+adhesive tape to be place manually with less accuracy.
+
+![EVBPBB1AAB000](/assets/images/EVPBB1AAB000.png){: align=left }
+
+The [Mitsumi BYS-055A1x12][3] is the same footprint (2.5mm x 1.6mm x
+0.55mm) as the more expensive Panasonic EVBBBxAAB00 tactile switches,
+with a 1.2N actuating force for the "**+**" and "**X**" pads, and a
+1.6N actuating force for the "Start", "Fn" and "ON/OFF" buttons. We
+found these actuating force the best match to provide a good feedback
+to the user.
+
+![EVP-AEBB2A-1](/assets/images/EVP-AEBB2A-1.jpg){: align=left }
+
+For the rear left and right shoulder buttons, we exeperimented several
+models between PCBA rev. C, D and E, until we eventually decided for a
+[replacement for the expensive Panasonic EVP-AEBB2A-1][4]:
+
+This one as an actuating force of 1.6N.
+
+## GPIO Requirements
+
+The Allwinner v3s CPU comes in a large 128-pin TQFP package, with a
+lot of exposed (51!) GPIO pins:
+
+ - PB0 to PB9 (10)
+ - PC0 to PC3 (4)
+ - PE0 to PE24 (25)
+ - PF0 to PF5 (6)
+ - PG0 to PG5 (6)
+
+The FunKey specializes some of them for specific interfaces like
+SDCard, PWM, SPI and I2C buses, console UART, but most of them are
+left available for I/Os.
+
+## GPIO Expander
+
+But for the **FunKey S** device and given the small PCB size, wiring
+all the buttons directly to the V3s puts a lot of constraints on the
+PCB routing, at such a point that we decided to use a dedicated I2C
+GPIO expander chip to relieve the burden from the main V3s CPU.
+
+We use a common chip for this purpose, that is well supported in the
+Linux kernel: the [NXP PCAL6416AHF.128][5]. It is marketed as a
+"low-voltage translating 16-bit I2C-bus/SMBus I/O expander with
+interrupt output, reset, and configuration registers" that just
+matches exactly our needs.
+
+As a bonus, this chip features software-controlable internal
+pull-up/pull-down resistors, so we don't need to add external ones to
+fix the defaut button states.
+
+The connection with the V3s CPU is achieved using standard I2C clock
+(SCL) and data (SDA) signals, plus an additional IRQ signal driven by
+the I/O expander when pre-programmed conditions are met, such as a key
+press / release event. A RESET signal is used to initialize the chip
+when required.
+
+## Schematics
+
+Here is the corresponding main schematic for the buttons:
+
+![Main Button Schematics](/assets/images/Main_Button_Schematics.png)
+
+The main component is of course the I/O expander **U1**, with the
+control signals to the CPU/PMIC on the north side.
+
+The chip's /INT signal is pulled up to the +3V3 power supply by the
+resistor **R1**, such that the active-low interrupt signal is disabled
+by default.
+
+The I/O expander chip features 2 separate power supplies VDD and VDDP
+for the core and peripheral respectively, each decoupled by a bulk
+capacitor **C1** and **C2**.
+
+Except for the GPIO I/Os, the only remaining pin is the ADDR pin 18
+which provides the I2C address LSB bit, so that you can address 2
+PCAL6416AHF.128 chips on the same I2C bus by wiring this pin
+differently.
+
+!!! tip
+
+    One oddity is that the pin 6 (P0_5) is connected to the /RESET
+    signal: it is a routing trick to get this signal to go through
+    this pin pad, as it was very difficult to access it otherwise...
+
+The "Start" and "Select" buttons **S1** and **S2** are 2 low-profile
+SMT tactile switches, each featuring an ESD protection TVS diode
+**D8** and **D5**, as these buttons are of course accessible by the
+user!
+
+The other buttons are wired in the same fashion:
+
+![Secondary Button Schematics](/assets/images/Secondary_Button_Schematics.png)
+
+The "U", "L", "D", "R", "A", "B", "X" and "Y" buttons **S3**, **S4**,
+**S5**, **S6**, **S8**, **S9**, **S10** and **S11** are of the same
+kind and also have a respective TVS diodes **D2**, **D3**, **D4**,
+**D5**, **D6**, **D7**, **D8**, **D9**, **D10** and **D11**.
+
+The left (**S12**) and right (**S7**) shoulder buttons are right angle
+SMT tactile buttons, with their TVS diode **D1** and **D12**.
+
+## Benefit
+
+The main advantage of this solutions is that the 12 signals to wire
+the buttons to the CPU are replaced by only 4 signals, from which 3
+are shared with the other I2C peripherals (the PMIC) on the bus.
+
+It is then much easier to route this dense PCB by delegating the
+button GPIO handling to a satellite chip.
+
+[1]: /developers/hardware/power/pmic
+[2]: https://hackaday.io/project/134065
+[3]: https://github.com/FunKey-Project/FunKey-S-Hardware/blob/master/Datasheets/Replacement%20EVP-BB1AAB000-(Operating%20force%20120GF%EF%BC%89.pdf
+[4]: https://github.com/FunKey-Project/FunKey-S-Hardware/blob/master/Datasheets/replacement%20EVP-AEBB2A-1.pdf
+[5]: https://www.nxp.com/docs/en/data-sheet/PCAL6416A.pdf
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/hardware/cpu.md

@@ -0,0 +1,221 @@
+The main part in the **FunKey S** device is of course its CPU.
+
+As discussed in the [Design Constraints section][1], a CPU with
+external DRAM chips would take too much real-estate on the PCB, so we
+had to find a CPU with integrated DRAM.
+
+There are [several options][2] for integrating RAM in a SoC:
+
+ - use SRAM: not possible because of the small amount of memory
+   available (64Mbit max.)
+
+ - embedded DRAM on the same chip: This is the solution used in the
+   [Apple M1 chip][3], but this chip is not available for retail and
+   no other solutions seems readily available
+
+ - Stacked Chip-on-Chip (PoP): This is the solution used on some
+   Raspberry Pi boards, but this solution is only available for custom
+   designs, with minimum order quantities not compatible with the
+   **FunKey S** low volumes
+
+ - DRAM die in SiP: with capacities ranging from 64Mbit to 1Gbit
+
+We found only 2 manufacturers providing the last option:
+[Microchip][4] and [Allwinner Technology][5]. Microchip solutions are
+too limited in term of CPU power for our needs (ARM926EJ-S or Cortex
+A5), so we did not consider them.
+
+And with the exception of the mostly similar Allwinner S3 CPU which
+features the same characteristics but with 128MB DDR3 DRAM in an
+FBGA234 package, the [Allwinner V3s][6] is the CPU with integrated DRAM
+having the highest memory capacity (512Mbit / 64MB DDR2 DRAM):
+
+![Allwinner V3s SoC](/assets/images/Allwinner_V3s.jpeg)
+
+Despite its larger package size (16mm x 16mm vs. 11mm x 11mm), we
+selected the V3s over the S3 because of its better availability and
+ease of soldering of the LQFP128 over the FBGA234 package for the
+prototypes.
+
+The V3s features a rather powerful single-core ARM Cortex A7-A clocked
+@ 1.2GHz with an additional Vector Floating Point Version 4 (vfpv4)
+FPU extension and an SIMD NEON architecture with a 32 × 64-bit
+register file and 64-bit ALU, but unfortunately no GPU or 2D graphic
+engine containing a hardware scaler that could be extremely useful for
+the retro-gaming emulators.
+
+As a bonus, as the V3s is based on an ARM Cortex A7-A low-power
+architecture, it also features a low power consumption which is
+required by our battery operation.
+
+These characteristics do not look very impressive compared to a
+Raspberry Pi for example, but using many optimizations and after
+running many tests, we found them nevertheless satisfactory for our
+purpose.
+
+## CPU Schematics
+
+Here is the part of the schematics corresponding to the CPU core:
+
+![CPU Schematics](/assets/images/CPU_Schematics.png)
+
+## SoC Blocks
+
+As can be seen, there is not much besides the CPU chip **U3**
+itself... The CPU is in fact a SoC (System on Chip) containing a
+collection of built-in peripheral and memory blocks along with the CPU
+itself:
+
+ - the LCD / DSi display peripheral
+
+ - the GPIO port G / SDC1 (SD Card #1) interface
+
+ - the AUDIO codec
+
+ - the LRADC0 (Low-Resolution Analog to Digital Converter)
+
+ - the USB OTG controller
+
+ - the GPIO port F / SDC0 (SD Card #0) / UART0 interface
+
+ - the RTC (Real Time Clock) timer
+
+ - the EPHY (Ethernet PHYsical) interface
+
+ - the MIPI CSi camera interface
+
+ - the built-in 64 MB DDR2 DRAM
+
+ - the GPIO port C / SPI interface
+
+ - the GPIO port B / UART2 / PWM0 / PWM1 / TWI0 (I2C #0) / TWI1 (I2C
+   #1)
+
+Among these, the FunKey device only uses a few blocks:
+
+ - AUDIO
+
+ - USB (as device only)
+
+ - SDC0 (for SD Card)
+
+ - RTC
+
+ - DRAM
+
+ - SPI (for the LCD screen)
+
+ - PWM0 (for backlight)
+
+ - TWI0 (for I2C bus to control the GPIO expander and power management
+   chips)
+
+ - A couple of GPIOs to power the audio power amplifier and get
+   feedback interrupt signals from the the GPIO expander and power
+   management chips
+
+## CPU Power Supplies
+
+What is remarkable though is that the V3s requires a lot of different
+voltages for its power supply:
+
+ - +3V3 for the I/O power supply
+ - +3V3_AO for the Always-On power supply (RTC timer)
+ - +3V0 for analog power supply
+ - +1V8 for the DDR2 DRAM power supply
+ - +1V25 for the core power supply
+
+This profusion of different power supplies as well as the high power
+drawn by some of them (1.2A for +3V3, 1.6A for +1.25V) requires a
+sophisticated power management that will be detailed further.
+
+## LRADC0
+
+The LRADC0 (Low-Resolution Analog to Digital Converter #0) is designed
+to measure the voltage of a resistor ladder switched by keyboard keys:
+this single input is thus in theory able to manage a keyboard of up to
+10 keys @ 250 Hz.
+
+Unfortunately, the FunKey has 12 keys (U/D/L/R, A/B/X/Y, RR/RL, Start
+and Fn), and the resulting key detection accuracy is not compatible
+with a gaming usage because of long term stability problems. This is
+the reason why it is not used in the FunKey and just terminated by a
+proper low-pass filter **R6**/**C9** to avoid picking up noise
+glitches.
+
+## SD Card
+
+The SD Card interface is almost a direct connection between the chip
+and the dedicated SD Card connector. Only a single series resistor
+**R8** is required on the high-speed clock line in order to [prevent
+ringing][7].
+
+## Crystals
+
+The V3s chips requires 2 crystals:
+
+ - one low-frequency [32.768 kHz crystal][8] **Y1** for the RTC clock
+
+ - one high-frequency [24 MHz crystal][9] **Y2** for deriving the 1.2 GHz clock
+
+The 24 MHz crystal is used by an internal oscillator to lock the phase
+of the 1.2 GHz oscillator using a PLL (Phase-Locked Loop).
+
+The 32.768 kHz crystal is used by another internal oscillator to tick
+the RTC (Real-Time Clock) at a standard watch frequency.
+
+These crystals require 2 load capacitors each (**C12**/**C13** and
+**C14**/**C15** respectively) in order to guarantee that the
+oscillators still start and work with a comfortable operation margin
+taking into account voltage, temperature and aging.
+
+The 32.768 kHz crystal features an additional high-value resistor
+**R12** in order to limit the internal oscillator's output current and
+thus reduce further the RTC timer power consumption.
+
+For more details on crystal oscillator design, please check [this
+application note from STM][10].
+
+## DRAM
+
+The DRAM within the V3s chip is a [DDR2 one][11], meaning that its data
+lines are clocked using both edges of an up to 400 MHz clock signal.
+
+At these high frequencies, even short wires have a length that is of
+the same order of magnitude as the signal's [wavelength][12] and thus
+each signal should be considered as a [transmission line][13], for
+which impedance must be matched to avoid signal reflections, requiring
+termination resistors on the data lines DQx.
+
+DDR2 or DDR3 DRAMs feature merged drivers and dynamic on-chip
+termination like this ("VDDQ/2" is labeled "SVREF" in our schematic):
+
+![DRAM Merged Drivers](/assets/images/DRAM_Merged_Drivers.png)
+
+The V3s DDR2 DRAM has an active termination calibration circuitry and
+procedure called "_ZQ Calibration_" requiring an accurate 1% 240 Ω
+resistor **R11** connected internally like this:
+
+![Pull-Up Calibration](/assets/images/Pull-Up_Calibration.png)
+
+More information on the DDR2 DRAM ZQ Calibration subject can be found
+in this [Micron Application Note][14].
+
+[1]: /developers/hardware/design/#design-constraints
+[2]: https://www.electronicsweekly.com/news/products/memory/how-to-guide-for-on-chip-memory-2012-06/
+[3]: https://www.apple.com/mac/m1/
+[4]: https://www.microchip.com/design-centers/32-bit-mpus/sip-som/system-in-package
+[5]: https://www.allwinnertech.com/
+[6]: https://linux-sunxi.org/images/f/f5/Allwinner_V3_Datasheet_V1.1.pdf
+[7]: https://electronics.stackexchange.com/questions/7709/why-put-a-resistor-in-series-with-signal-line
+[8]: https://github.com/FunKey-Project/FunKey-S-Hardware/blob/master/Datasheets/C55208_FC-12M32.768K12.5PF20PPM_2017-01-16.PDF
+[9]: https://github.com/FunKey-Project/FunKey-S-Hardware/blob/master/Datasheets/C270485_24MHZ18PF%C2%B110PPM4PIN-20_%2B70%E2%84%83_2018-08-14.PDF
+[10]: https://www.st.com/content/ccc/resource/technical/document/application_note/c6/eb/5e/11/e3/69/43/eb/CD00221665.pdf/files/CD00221665.pdf/jcr:content/translations/en.CD00221665.pdf
+[11]: https://en.wikipedia.org/wiki/DDR2_SDRAM
+[12]: https://en.wikipedia.org/wiki/Wavelength
+[13]: https://en.wikipedia.org/wiki/Transmission_line
+[14]: https://www.micron.com/-/media/client/global/Documents/Products/Technical%20Note/DRAM/TN4102.pdf
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/hardware/design.md

@@ -0,0 +1,82 @@
+The **FunKey S** is the world's smallest foldable retro-gaming console.
+
+Holding a world's record is great, but we wanted a device that was
+_actually_ playable and that still could be attached to a keychain.
+
+Reaching this goal required more than just the usual job to shrink
+everything you can: it required a radical change in the design itself.
+
+## Foldable Design
+
+The idea to use a foldable clamshell design came up rapidly as the
+only way to get _both_ a small form factor when closed, and offer the
+largest screen and keypads while playing.
+
+But this solution also brings a lot of challenges, as the required
+hinge make connections between the 2 halfs of the shell more
+difficult.
+
+However, this has been done before in the classic GameBoy Advanced SP,
+ or in many clamshell cellphones from some years ago, so why can't we?
+
+## Design Goals
+
+Passed this first design decision, we fixed ourselves some additional
+goals in order to provide the user a good gaming experience:
+
+ - have a CPU that is powerful enough to be able to emulate most
+   retro-gaming consoles, up to the PS1
+
+ - have a good quality screen with a resolution large enough to
+   display even the games featuring small texts
+
+ - have a set of keys and pads large enough and complete enough to be
+   able to play comfortably
+
+ - have a built-in audio capability (who can play without sound?)
+
+ - be able for a 6-year old child to add games and emulators
+
+ - as an extremely nomad device, be able to stop playing just by
+   closing the console, and restart when opening it just where you
+   left (we call this feature "**_Instant Play_**")
+
+## Design Constraints
+
+Besides the constraint brought by the hinge listed above, the main
+difficulty is due to the maximum device dimensions that should not
+exceed those of a (large) car key.
+
+And because of the foldable design, the most constrained dimension is
+thickness: having a folding screen also means doubling the plastic
+enclosure around the screen and the other internal parts.
+
+In order to meet these constraints, we had to take more
+(heart-breaking) decisions:
+
+ - a CPU with external DRAM chips would take too much real-estate on
+   the PCB, so we had to find a CPU with integrated DRAM
+
+ - an audio Jack would be very difficult to integrate, so we decided
+   to use an internal speaker instead
+
+ - an USB C connector is too thick and large, so we used a Micro USB
+   connector instead
+
+ - a Micro SD connector with external access would be too large, as
+   the required "push/push" mechanism, plus the mechanical design to
+   make sure the card does not get loose make the solution much larger
+
+ - because of real-estate constraints on the PCB as well as power
+   consumption constraints, we decided to not integrate Wi-Fi and/or
+   Bluetooth
+
+ - the only keypad technology able to meet our thickness goal is using
+   integrated tactile switches
+
+ - battery capacity had to be adjusted to the maximum available
+   internal volume, using standard battery dimensions
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/hardware/magnetic_switch.md

@@ -0,0 +1,41 @@
+The **FunKey S** features no ON/OFF switch. Instead, a small magnet
+placed near the LCD screen in the lid is detected using a magnetic
+sensor that is placed in front of it when the lid is closed.
+
+The magnetic sensor controls the PMIC N_OE (Negative logic Output
+Enable) input, which turns off all voltage rails except the +3.3V
+Always On when the signal is at the high level.
+
+We thus need a sensor that will close when a magnetic field is
+detected, and in order to reduce power consumption when the **FunKey
+S** is turned off and preserve its battery when stored on a shelf, it
+should be a fully passive device. This rules out magnetic Hall effect
+sensors, wich require some power for their operation.
+
+The only practical solution is to use a "Reed switch", which is a
+relatively thin flexible piece of metal inside the switch envelope
+that is sensitive to a magnetic field, which opens or closes a contact
+accordingly.
+
+Most of the Reed switch available are made of a tiny glass tube, which
+is rather fragile and may break if the device falls on the floor,
+something quite usual for a keychain...
+
+We found only a unique plastic-molded model which almost meets our
+low-profile requirements of 1.5 mm (1.6 mm height!): the [Standex
+Meder MK24][1].
+
+Here is the corresponding schematics, already covered in the PMIC discussion:
+
+![Magnetic Sensor Schematics](/assets/images/Magnetic_Sensor_Schematics.png)
+
+The global PMIC chip enable signal N_OE is activated by default
+through a 47kΩ resistor **R17** to GND, but the magnetic Reed switch
+**S14** can disable it by forcing its level to +VOUT, with a filter
+capacitor **C83**.
+
+[1]: https://github.com/FunKey-Project/FunKey-S-Hardware/blob/master/Datasheets/MK24_V02.pdf
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/hardware/parts.md

@@ -1,70 +0,0 @@
-Electronic Parts
-====
-
-CPU
----
-
-The main part in the FunKey device is of course the CPU: an AllWinner V3s SoC with integrated 64MB DDR2 DRAM. Not much compared to a Raspberry Pi for example, but it turns out it has just the right capacity for our purpose, and a minimum size because of its integrated DDR2 RAM, without the length and impedance-controlled constraints on PCB trace requirements.
-
-The V3s also features a low power consumption and all the required peripheral that we need.
-
-Power
------
-
-The V3s CPU is generally used with a companion AXP209 PMIC chip in charge of supplying all the required voltages for the CPU: +3V3, +3V3 (RTC), +3V0, +1V25, most of these using integrated DC/DC buck converters or simpler LDOs for the ones requiring the less power. The AXP209 also features an integrated Coulomb counter for monitoring the available battery power, as well as a soft-power switch controller that acts just like the one in your smartphone!
-
-A separate AP3418KTR-G1 DC/DC converter is used for providing the DDR2 DRAM +1V8 power.
-
-Screen
-------
-
-The second most important part in our design is probably our small 1.5" LCD screen. It has an amazing 240 x 240 pixel resolution, while using a simple SPI-based interface and not a complex DSi interface based on the differential high-speed MIPI specification, which requires a dedicated controller that is only available in higher-end SoC:
-
-![FunKey Top](/assets/images/9913621524305225162.jpeg)
-
-It is connected to the PCB using a small DF37NB-24DS-0.4V(51) connector, matching the LCD screen connector.
-
-Audio
------
-
-For audio playback, we wanted to have an internal speaker. But given the reduced dimensions, we tried to find the smallest available one, which has a very small 10 mm diameter, with a total height of 2.9 mm, out of which 1.4 mm can be inserted into a PCB hole, thus only having a height above PCB of 1.5 mm:
-
-![FunKey Top](/assets/images/MFG_CDM-10008_sml.webp)
-
-We use a simple mono audio playback through a PAM8301AAF amplifier. This amp has all the required characteristics, with a filterless (no capacitor) design.
-
-Buttons
--------
-
-After testing tactile domes in our FunKey Zero prototype, we decided to go back to standard tactile switches, as their placement can be done by a regular SMT pick&place machine with a very good accuracy, just like all the other components on the PCB, unlike the tactile domes which require an adhesive tape to place them, making them less accurate in their absolute positioning.
-
-We also need some right-angled tactile switches for the rear left and right buttons:
-
-We took the smallest we could get, but we may experiment with softer (no-click) ones for the rear buttons to bring a better play experience.
-
-USB
----
-
-For the microUSB connector we choose a common mid-mount model with through-hole pins in order to avoid tearing it off the board if you don't pull the chord straight. 
-
-UART
-----
-
-For debug, we features a 3-pin  1.27 mm pitch header, with console UART RX, TX and GND pins.
-
-SD Card
--------
-
-Magnetic Sensor
----------------
-
-Miscellaneous
--------------
-
-The only remaining active part is a P-MOSFET used to drive the screen backlight from a V3s GPIO pin.
-
-We use TVS diodes on all user-accessible parts to prevent ESD (these are small 0402 TVS), and a dedicated USB ESD protection a close as possible to the USB connector.
-
-All other parts are passive resistors, capacitors or ferrite beads in 0402 form factor whenever possible, as we don't have a lot of available real estate on this board.
-
-As you can see, none of the components was chosen randomly, and finding the right part took us a significant amount of time!

docs/developers/hardware/power/dc-dc.md

@@ -0,0 +1,170 @@
+Simple DC electronic circuits can be powered by directly connecting a
+battery. However, more complex circuits usually require a constant
+input voltage for proper operation.
+
+This page is a small sidetrack to explain the different regulated DC
+power supply topologies, before looking at the **FunKey S** power
+supply schematics in details.
+
+If you are already comfortable with this subject, you can skip this
+section entirely!
+
+## Linear Regulators
+
+The easiest method to achieve a constant voltage viewed from the load
+despite a varying source voltage is to linearly control the resistance
+of the regulator in accordance with the load, resulting in a constant
+output voltage.
+
+### Shunt Regulator
+
+The simplest voltage regulator is the [shunt regulator][1], built
+around a Zener diode which most interesting characteristic is to
+maintain a constant voltage across itself when the current through it
+is sufficient to take it into the Zener breakdown region. A simple
+shunt regulator looks like this:
+
+![Zener Regulator](/assets/images/Zener_Regulator.gif)
+
+### Series Regulator
+
+By adding a emitter-follower transistor to the simple shunt regulator,
+the small base current of the transistor forms a very light load on
+the Zener, thereby minimizing variation in Zener voltage due to
+variation in the load, resulting in a better regulation. Here is a
+schematic for this [series regulator][2]:
+
+![Series Regualtor](/assets/images/Series_Regulator.gif)
+
+### Integrated Linear Regulator
+
+In integrated voltage regulators, the discrete Zener diode is replaced
+by a more sophisticated (but easier to integrate) circuit built around
+a resistor divider feeding an operational amplifier, a voltage
+reference, and a transistor driving the emitter-follower pass
+transistor:
+
+![Integrated Regulator](/assets/images/Integrated_Regulator.png)
+
+Usually, the pass transistor and its driving transistor are combined
+into a single Darlington transistor plus a controllable current source
+like this:
+
+![Darlington Transistor](/assets/images/Darlington_Transistor.jpg)
+
+### LDO (Low Drop-Out) Regulator
+
+The above circuit works well, but its drop-out voltage (the difference
+between the input and output voltage) is rather high because of this
+transistor cascade, around 1.5V to 2.5V.
+
+By replacing the emitter-follower Darlington transistor by a PNP
+transistor in an open collector or open drain topology, the drop-out
+voltage is reduced to 0.7V or lower:
+
+![PNP Transistor](/assets/images/PNP_Transistor.jpg)
+
+## SMPS (Switched-Mode Power Supply) or DC/DC Converters
+
+A linear regulator provides the desired output voltage by dissipating
+excess power as heat in the Zener diode or in the pass
+transistor. Hence its maximum power efficiency is VOUT/ VIN since the
+voltage difference is wasted to heat the birds.
+
+In contrast, a Switched-Mode Power Supply changes output voltage and
+current by switching non-linear storage elements, such as inductors,
+transformers and capacitors between different electrical
+configurations.
+
+These elements are said to be non-linear because the inductor and
+transformer respond to changes in current by inducing its own voltage
+to counter the change in current, whereas a capacitor responds to
+changes in voltage by inducing its own current to counter the change
+in voltage.
+
+Thus, depending on the way the components are arranged, it is possible
+to obtain SMPS circuits that either have an output voltage higher than
+the input voltage ("Boost Converters"), or lower than the input
+voltage ("Buck Converters", as is it subtracts or “Bucks” the supply
+voltage).
+
+Because of technology, power inductors are easier to manufacture, take
+less space and are more stable over time than their counterpart
+capacitors. This is why most power DC/DC converters are built using
+inductors. Capacitor-based SMPS are generally used for lower power
+applications, such as for generating the +12V and -12V voltages
+required by true RS232 from a +3.3V or +5V power supply in the
+ubiquitous MAX232 drivers.
+
+### Boost Converter
+
+The most basic circuit for the Boost converter is the following:
+
+![Boost Converter](/assets/images/Boost_Converter.png)
+
+If the switch is driven by a square wave, the peak-to-peak voltage of
+the waveform measured across the switch can exceed the input voltage
+from the DC source. This is because the non-linear characteristic of
+the inductor, and this voltage adds to the source voltage while the
+switch is open.
+
+!!! warning
+    In this converter, the output voltage is not isolated from the
+    input voltage.
+
+### Buck Converter
+
+The corresponding basic circuit for the Buck converter is the
+following:
+
+![Buck Converter](/assets/images/Buck_Converter.gif)
+
+The way this converter works is described in details
+[here][3]. Basically, when the switch is closed, the inductor will
+produce an opposing voltage across its terminals in response to the
+changing current, reducing the output voltage, and meanwhile the
+inductor stores this energy in the form of a magnetic field. When the
+switch is opened, the current will decrease and will produce a voltage
+drop across the inductor, and now the inductor becomes a current
+source, where the stored energy in the inductor's magnetic field is
+restored and fed to the load.
+
+!!! warning
+    In this converter too, the output voltage is not isolated from the
+    input voltage.
+
+### Isolated SMPS
+
+Isolated Switched-Mode Power Supplies use a transformer to isolate the
+input voltage from the output voltage, and thus can produce an output
+of higher or lower voltage than the input by adjusting the turns
+ratio.
+
+## Pros and Cons
+
+Linear regulators are simpler than SMPS, and their linear behavior
+produce a very clean output voltage, but their efficiency is directly
+proportional to the difference between the input and output voltage,
+which is dissipated as heat.
+
+However, for light loads and/or when the voltage drop-out is low, LDOs
+are very useful.
+
+OTOH, SMPS are more complex and require more components, but their
+efficiency is much better (typically 80-90%), resulting in less heat,
+with the drawback of a switching electrical noise pollution of both
+the input voltage (that may couple electrical switching noise back
+onto the mains power line) and the output voltage (with
+electromagnetic interference (EMI) and a ripple voltage at the
+switching frequency and all its harmonic frequencies).
+
+SMPS are thus almost exclusively used when heavy loads are used and/or
+when the voltage drop-out is important.
+
+[1]: https://en.wikipedia.org/wiki/Linear_regulator#Simple_shunt_regulator
+[2]: https://en.wikipedia.org/wiki/Linear_regulator#Simple_series_regulator
+[3]: https://en.wikipedia.org/wiki/Buck_converter#Concept
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/hardware/power/decoupling.md

@@ -0,0 +1,122 @@
+## Capacitor Usage
+
+So far, we already encountered capacitors for many different usages:
+
+### Load Capacitors
+
+We have seen load capacitors used with the 2 crystals in the
+discussion about [CPU][1].
+
+A quartz crystal always provides both series and parallel resonance,
+the series resonance being a few kilohertz lower than the parallel
+one.
+
+Crystals below 30 MHz like ours are generally operated between series
+and parallel resonance, which means that the crystal appears as an
+inductive reactance in operation, this inductance forming a
+**parallel resonant circuit** with externally connected parallel
+"load" capacitance. Any small additional capacitance added in parallel
+with the crystal pulls the frequency lower in the range between the
+series and parallel resonance frequencies, insuring crystal startup
+and stable operation.
+
+For modern circuits, these load capacitors have a typical small value
+< 20 pF.
+
+### Bulk Capacitors
+
+Bulk capacitors are used to prevent a power supply from dropping too
+far during the periods when current is not available. At the same
+time, they help to reduce the power supply voltage ripples by
+smoothing their output voltage.
+
+Many such capacitors are used at both the input and output of the
+numerous linear and switched mode power supplies in the [PMIC
+discussion][2].
+
+The main bulk capacitor value is generally high (some µF), but there
+may be smaller parallel capacitors added for stability.
+
+### Coupling Capacitors
+
+As you probably know, capacitors are made of 2 parallel conductive
+electrodes separated by a (thin) isolating dielectric material (even
+if these electrodes are rolled or layered to reduce the component
+size). Thus by construction, no DC (Direct Current) can flow from one
+electrode to the other, but by influence using the electric field, AC
+(Alternative Current) still can go through. This is how coupling
+capacitors are used to link 2 circuits while removing any DC bias
+voltage on one side or the other of the capacitor.
+
+We use such a coupling capacitor in the [Audio schematic
+description][3] for feeding the audio power amplifier from the CPU
+audio output.
+
+### Filter Capacitors
+
+We have seen many examples where capacitors are used within passive
+filter circuits along with resistors or inductors, mainly to remove
+unwanted frequencies from a power supply or a signal.
+
+### Decoupling (Bypass) Capacitors
+
+We use some decoupling capacitors in the [buttons circuit][4].
+
+Active components such as transistors and chips are connected to their
+power supplies through conductors featuring a (small) common impedance
+made up of complex (resistive, capacitive and inductive)
+value. Because of these parasitic components, a device that suddenly
+draws some current in spikes will generate a drop in its voltage power
+supply. If many devices are sharing the same power supply and
+impedance, the state of one device will be coupled to the other ones
+through the common impedance of the power supply conductors and may
+affect their operation.
+
+In order to decouple the devices, capacitors placed as close as
+possible to the device power supply input pins are used, which act as
+local energy storage. These capacitors are also named "bypass
+capacitors" as they shunt transient energy from the power supplies
+past the device to be decoupled, right to the GND return path.
+
+There may be different capacitors values placed on the same power
+supply pins in order to filter transients at different frequencies:
+the bigger the capacitor value, the lower the frequency. A typical
+value is 100 nF, and values from 1 µF to 10 µF are used for lower
+frequencies and / or higher current draws, while lower values of a few
+nF are used for filtering higher frequencies.
+
+In essence, decoupling capacitors are not very different in their
+function from bulk capacitors: the only difference is one of scale,
+both of current and of transient duration. Bulk capacitors deal with
+large currents and periods of 10s of ms, whereas decoupling capacitors
+are used for much lower currents and much briefer periods (typically
+10s of ns for TTL or CMOS devices) .
+
+## Schematics
+
+The last part of the FunKey schematics merely contains only decoupling
+capacitors:
+
+![Decoupling Schematics](/assets/images/Decoupling_Schematics.png)
+
+One exception is the Allwinner V3s CPU HPR/HPL circuit which features
+an RC-to-ground circuit between the amplifier and the preamplifier
+input with the resistor **R27** and capacitors **C79** and **C81**, as
+recommended in the [V3s hardware design guide][5].
+
+The only other remarkable point left in this schematic is the resistor
+divider **R25**/**R28** which provides a reference voltage at half the
+DRAM power supply voltage level, which is used for the integrated DDR2
+DRAM merged drivers and dynamic on-chip termination already discussed
+at the end of the previous [CPU schematic description][6].
+
+[1]: /developers/hardware/cpu
+[2]: /developers/hardware/power/pmic
+[3]: /developers/hardware/audio
+[4]: /developers/hardware/buttons
+[5]: https://github.com/Squonk42/V3s_Documentation/blob/master/V3s%20hardware%20design%20guide%20V1.0_20150519%20EN%20Non%20Official.pdf
+[6]: /developers/hardware/cpu
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/hardware/power/dram.md

@@ -0,0 +1,49 @@
+A separate [Sylergy SY8088][1] Buck DC/DC SMPS chip is used to provide
+the DDR2 +1V8 DDR2 DRAM power.
+
+This is because the AXP20x is originally the PMU (Power Management
+Unit) used by most Allwinner SoCs (A10, A13 and A20), which do not
+integrate SDRAM, so the board designer has a wide choice of memory
+option: DDR2, DDR3, DDR3L, LPDDR3, LPDDR4 with various voltage
+requirements.
+
+But no specific PMIC was created for the Allwinner V3s used in the
+FunKey device which however integrates a fixed SiP (System In Package)
+512Mbit (64MB) DDR2 SDRAM.
+
+We thus have to design a separate SMPS (DC-DC) power supply for
+providing the +1.8V 1A required for the DDR2 DRAM power supply.
+
+For this purpose, we followed closely the [Allwinner Reference
+Design][2].
+
+Here is the corresponding DRAM Power schematics:
+
+![DRAM Power Schematics](/assets/images/DRAM_Power_Schematics.png)
+
+Nothing very fancy here: the SMPS chip **U4** has its required input
+filter capacitor **C37** and output capacitors **C65** and **C73**.
+
+The low-profile ferrite-core power inductor **L6** (rated with a
+saturation current of 1.76A and low < 0.1 Ω resistance) provides the
+DC-DC energy storage element.
+
+The **R20**/**R23** precision voltage divider provides the required
++0.6V feedback voltage from the +1.8V output voltage by having a 1/3
+resistor ratio.
+
+The last component is a pull-up resistor **R19** which ties the SMPS
+chip enable input to its active level permanently. The pull-up voltage
+is +3.0V (just as in the original reference design), probably as it is
+the next higher voltage available, in order to limit the current in it
+to its lowest possible value.
+
+[1]: https://github.com/FunKey-Project/FunKey-S-Hardware/blob/master/Datasheets/C79313_SY8088AAC_2017-03-29.PDF
+[2]: https://github.com/Squonk42/V3s_Documentation/blob/master/V3S_CDR_STD_V1_0_20150514.pdf
+[3]: https://datasheet.lcsc.com/szlcsc/Silergy-Corp-SY8088AAC_C79313.pdf
+[4]: https://datasheet.lcsc.com/szlcsc/1901241230_LOWPOWER-LP3220S-AB5F_C324565.pdf
+[5]: https://www.diodes.com/assets/Datasheets/AP3418.pdf
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/hardware/power/pmic.md

@@ -0,0 +1,298 @@
+From the previous section, we can summarize the V3s power supply
+requirements to:
+
+ - SMPS for +3.3V / 1.2A for the I/O power supply
+ - LDO for +3.3V_AO / 30 mA for the Always-On power supply (RTC timer)
+ - LDO for +3.0V / 200 mA for the analog power supply
+ - SMPS for +1.8V / 1A for the DDR2 DRAM power supply
+ - SMPS for +1.25V / 1.6 A for the core power supply
+
+On the [LicheePi Zero board][1] used in our **[FunKey Zero][2]**
+prototype, a triple SMPS [EA3036][3] is used for generating these
++3.3V, +1.8V and +1.2V voltages, with an additional [XC6206][4] LDO
+for the +3.0V (the +3.3V Always On is connected directly to
++3.3V). Although compact (the EA3036 is a tiny 3 mm x 3 mm QFN20
+package), this solution is not ideal as it does not provide a battery
+charger and monitoring capability, which is a requirement for the
+**FunKey S** device.
+
+## PMICs
+
+As it is generally the case with such a complex SoC requiring multiple
+voltages, high current and proper voltage sequencing, all major
+manufacturers provide dedicated companion chips called PMICs (Power
+Management Integrated Circuits), in charge of these tasks. Allwinner
+is not an exception through its sister company [X-Powers][5].
+
+Their AXP20x products are highly-integrated PMICs that are optimized
+for applications requiring single-cell Li-battery (Li-Ion/Polymer),
+multiple output DC-DC converters and LDOs. Here is a block diagram:
+
+![PMIC Block Diagram](/assets/images/AXP20x_Block_Diagram.png)
+
+The AXP20x features:
+
+ - A wide choice of input power source, the best source is output as
+   IPSOUT inside the IPS (Intelligent Power Select) block:
+
+    - USB VBUS
+
+    - Battery BAT
+
+    - ACIN wall plug (not used in the **FunKey S**)
+
+    - BACKUP battery (not used in the **FunKey S**)
+
+ - A 1.8A fast PWM battery charger (also called DC/DC1) with battery
+  voltage / current sense and programmable charge indication LED
+
+ - A soft key power-on/off logic with timer (just as in smartphones!)
+
+ - An I2C interface with interrupt signal to communicate with the CPU
+
+ - An optional battery temperature monitoring if the battery is
+   equipped with an NTC resistor (not used in the **FunKey S**)
+
+ - A reference voltage
+
+ - A built-in 12-channel 12 bit ADC that measures various voltages and
+   currents data, as well as feeding an internal Coulomb counter and
+   fuel gauge system (more on this later)
+
+ - A "power OK" output used to generate the global RESET signal for the
+   **FunKey S**
+
+ - 5x GPIOs (not used in the **FunKey S**), GPIO0 can be programmed as
+   LDO5 output
+
+ - 2x DC/DC SMPS DC-DC2 and DC-DC3
+
+ - 5x LDOs (only 2 are used in the **FunKey S**, LDO5 is optionnaly
+   output to GPIO0)
+
+Looking at their datasheets, it is difficult to tell the difference
+between the [AXP202][6], [AXP203][7] and [AXP209][8] (any hint
+welcome!). In the **FunKey S** design, we use an AXP209 because it is
+the one that comes along with the V3s when you buy it on AliExpress.
+
+## AXP20x Application Diagram
+
+For complex dedicated chips like this, the best option is to follow as
+much as possible the application diagram and reference design given by
+the manufacturer, as the internals of the chips are seldom fully
+disclosed, so you need to take their word on some of the external
+component values to use.
+
+The [Allwinner V3s Reference Design][9] contains on page 6 the
+schematics for using an AXP203 to supply the power to a V3s-based
+dashboard camera design. It follows closely the application diagram
+provided in the AXP20x datasheets:
+
+![AXP20x Application Diagram](/assets/images/AXP20x_Application_Diagram.png)
+
+More hints are provided in our self-translated [V3s Hardware Design
+Guide][10] (page 7) too.
+
+## PMIC Schematics
+
+The **FunKey S** device uses all of the **U5** AXP209 integrated SMPS:
+
+ - the PWM charger DC-DC1 for the battery
+ - the DC-DC2 for providing the +1.25 V / 1.6A to the core
+ - the DC-DC3 for providing the +3.3V / 1.2A to the I/Os
+
+But compared to the sophisticated reference design above, the **FunKey
+S** device only uses 2 out of the 5 integrated LDOs:
+
+ - LDO1 supplies the +3.3V / 30 mA Always On for the RTC
+ - LDO2 provides the +3.0V / 200 mA for the analog power supply
+ - LDO3 / LDO4 / LDO5 are not used in the **FunKey S**
+ 
+Here are the PMIC schematics:
+
+![PMIC Schematics](/assets/images/PMIC_Schematics.png)
+
+These schematics may look intimidating and complex, but they are in
+fact just a collection of simple basic elements, and it is actually
+very close to the manufacturer-recommended design.
+
+Here are the details for each PMIC functions, one by one:
+
+### Power Inputs (East side)
+
+A wall-plug AC adapter input is not used in the **FunKey S** device,
+so +VIN is just filtered using C75 on pins 32 and 33.
+
+The USB power input +VUSB on pin 31 is filtered using **C70**, and the
+best (between +VUSB and +VBAT) available voltage is output to +VOUT on
+pins 34 and 35 and filtered using **C78**.
+
+The BACKUP supply on pin 30 is not used and is left unconnected.
+
+### Internal Connections (All sides)
+
+Some AXP20x signals are externally available and should be connected
+to external components:
+
+ - The BIAS connection on pin 23 is connected to a precision 200k 1%
+   resistor **R22**, as recommended
+
+ - The reference voltage VREF on pin 24 is decoupled with **C64**
+
+ - The +2.5V internal logic voltage VINT on pin 26 is filtered using
+   the recommended value for **C67**
+
+Additionally, the AXP20x is actually made up of separate flexible
+blocks that require external interconnections to set their desired
+operation:
+
+ - All DC/DC inputs (VIN1 on pin 44, VIN2 on pin 7 and VIN3 on pin
+   14), as well as LDO3IN input on pin 40 are connected to the best
+   available voltage +VOUT with filter capacitors **C59**, **C23**,
+   **C30**, and **C69**, respectively
+
+ - LDO1SET on pin 27 is used to set the initial voltage of LDO1, and
+   according to the datasheets, setting it to VINT sets its voltage to
+   the desired +3.3V for the +3.3V Always On power supply
+
+ - OTOH, combined LDO 2 and 4 input LDOIN24 on pin 13 is instead
+   connected to +3.3V in order to minimize the voltage drop for LDO2
+   to generate the +3.0V. Here too, there is a filter capacitor
+   **C34**
+
+ - It is not clear what is the exact function of APS on pin 21 (it is
+   described as "Internal Power Input"), but it must be connected to
+   +VOUT, too
+
+### DC-DC1 PWM Battery Charger (North East side)
+
+The battery is connected to J5 (a [2-pin JST 1.0 mm pitch
+receptacle][11]) and uses **R21** as a precision current sense
+resistor, with **C53**/**C56**/**C60** filter capacitors and **L5** (a
+low-profile ferrite-core power inductor rated with a saturation
+current of 1.2A and low < 0.1 Ω resistance).
+
+!!! Warning
+    The battery is not protected on the board against reversing
+    polarity, as the model used already contains a built-in
+    protection.
+
+**R24** is mounted to simulate a battery NTC resistor for measuring
+temperature, as the chosen LiPo battery does not feature this
+temperature sensor.
+
+A user-programmable (through the I2C interface) charge [LED][12]
+**D30** is provided, with its current-limiting resistor **R26**, as
+well as a TVS diode **d31** to prevent ESD, as the LED body will be
+indirectly accessible to user.
+
+### DC-DC2 +1.25V / 1.6A (West side)
+
+This SMPS is built around the ferrite core power inductor **L3** and
+filter capacitors **C26** and **C29**.
+
+### DC-DC3 +3.3V / 1.2A (South side)
+
+This SMPS is built around the ferrite core power inductor **L4** and
+filter capacitors **C39** and **C43**.
+
+### LDO1 +3.3V Always On 30mA (South East side)
+
+The LDO output on pin 28 is filtered with capacitor **C72**.
+
+### LDO2 +3.0V / 200mA (South West side)
+
+The LDO output on pin 12 is filtered with capacitor **C33**.
+
+### LDO3 (North side)
+
+This LDO is not used and its output on pin 41 is nevertheless filtered
+with a capacitor **C63**.
+
+### LDO4 (South West side)
+
+This LDO is not used and its output on pin 11 is nevertheless filtered
+with a capacitor **C38**.
+
+### Power Key (North West side)
+
+The AXP20x features a soft power key with internal short and
+long-press detection with user-programmable time settings, which
+enables turning power ON or OFF much like the way it is done in
+cellular phones.
+
+Only a few external components are required: the tactile switch
+**S13**, its ESD protection TVS **D29**, and a low-pass filter **R18**
+and **C42** for debouncing the switch.
+
+### I2C Bus (North West side)
+
+The AXP20x can be externally controlled by the main CPU using the I2C
+bus on pins 1 and 2. This bus has pull-up resistors to +3.3V **R14**
+and **R16**, and the IRQ/WAKEUP signal on pin 48 enables warning or
+waking up the CPU on a selection of AXP20x-generated events, with a
+pull-up resistor **R13** to +3.3V.
+
+### GPIOs (South and West sides)
+
+GPIO0-3 on pins 19, 18, 5 and 3 are not used in the **FunKey S** and
+are left unconnected.
+
+### PWROK (South West side)
+
+The PWROK signal on pin 25 is used to generate the global RESET signal
+for the whole board, with a pull-up resistor **R15** to the +3.3V
+Always On power supply and a filter capacitor **C18**.
+
+### Enable Signals (West side)
+
+The global chip enable signal N_OE on pin 4 is activated by default
+through a 47kΩ resistor **R17** to GND, but a magnetic Reed switch
+**S14** can disable it by forcing its level to +VOUT, with a filter
+capacitor **C83**. This circuit will be disscused later in the
+[Magnetic Switch section][13].
+
+The USB enable signal N_VBUSEN on pin 6 is directly tied to GND to
+always enable power from the USB bus.
+
+### Monitoring
+
+Through the I2C bus and the numerous internal available registers, the
+AXP20x provides a very fine control of its operation, including many
+threshold and timing settings, but also many voltage and curent
+monitoring values.
+
+### Coulomb Counters / Fuel Gauge
+
+It is well known that battery discharge voltage curve over time is
+very flat, making it very difficult to estimate the real
+charge/discharge state of the battery. Moreover, this state will vary
+with temperature, load, and aging.
+
+The only accurate way to monitor the battery status is to actually
+count the energy that is stored when charging, and the one that is
+consumed. This particularly important feature is achieved in the
+AXP20x using a dual Coulomb counter which continuously sums the
+current intensity over time for monitoring the battery accurate charge
+and discharge status, with user-defined alert thresholds.
+
+This fuel gauge is providing the ability to precisely report the
+remaining battery capacity, just like people are used to with cellular
+phones.
+
+[1]: https://licheepizero.us/
+[2]: https://hackaday.io/project/134065-funkey-zero
+[3]: http://club.szlcsc.com/article/downFile_D72C44885C60F9F1.html
+[4]: https://www.torexsemi.com/file/xc6206/XC6206.pdf
+[5]: http://www.x-powers.com/en.php
+[6]: http://www.x-powers.com/en.php/Info/down/id/55
+[7]: https://github.com/Squonk42/V3s_Documentation/raw/master/AXP203_Datasheet_V1.0.pdf
+[8]: https://github.com/Squonk42/V3s_Documentation/raw/master/AXP209_Datasheet_v1.0en.pdf
+[9]: https://github.com/Squonk42/V3s_Documentation/blob/master/V3S_CDR_STD_V1_0_20150514.pdf
+[10]: https://github.com/Squonk42/V3s_Documentation/raw/master/V3s%20hardware%20design%20guide%20V1.0_20150519%20EN%20Non%20Official.pdf
+[11]: https://github.com/FunKey-Project/FunKey-S-Hardware/blob/master/Datasheets/1811151533_JST-Sales-America-SM02B-SRSS-TB-LF-SN_C160402.pdf
+[12]: https://github.com/FunKey-Project/FunKey-S-Hardware/blob/master/Datasheets/C165977_%E8%B4%B4%E7%89%87LED%E8%93%9D%E8%89%B2_2018-01-26.PDF
+[13]: /developers/hardware/magnetic_switch
+--8<--
+includes/glossary.md
+--8<--

docs/developers/hardware/power/voltages.md

@@ -0,0 +1,113 @@
+Looking back at the section on the [CPU schematics][1], the **FunKey
+S** device clearly needs a sophisticated power supply in order to
+fulfill the CPU power requirements. They are recalled below, along
+with the maximum current requirements found in the [Allwinner V3s
+reference design][2] (page 3):
+
+ - +3.3V / 1.2A for the I/O power supply
+ - +3.3V_AO / 30 mA for the Always-On power supply (RTC timer)
+ - +3.0V / 200 mA for the analog power supply
+ - +1.8V / 1A for the DDR2 DRAM power supply
+ - +1.25V / 1.6 A for the core power supply
+
+But why in the first place are there so many different power supply
+voltages required?
+
+## Power Efficiency
+
+A first answer is: for better power efficiency.
+
+As P = U x I (Electrical power is the product of voltage level by
+current intensity), you can reduce power by decreasing the required
+current or by reducing the operating voltage. Assuming you already do
+your best to reduce the required current, you can still reduce power
+by reducing the voltage.
+
+## Reducing Power Supply Voltage
+
+### Voltage Drop
+
+But how far can you go? Over long distance, you have the voltage drop
+from the conductor linear resistance, but this effect can be neglected
+for small boards.
+
+### Noise Margin
+
+You have inductive and capacitive coupling between conductive wires
+and planes too, but within a PCB, these coupling only have a limited
+direct effect on voltage. However, these coupling play a role in that
+they will pick up external electromagnetic noise from the surroundings
+and inject it into the circuit.
+
+And with digital circuits, a critical limit when lowering the
+operating voltage is the "noise margin" or difference in absolute
+voltage levels between a logical '0' and logical '1', which determines
+the maximum amplitude of spurious voltage spikes that a conductor can
+pick up that will trigger an erroneous logic level change.
+
+This phenomenon mostly depends on the circuit scale: a long-distance
+circuit between boards will require higher voltages (typically +12V or
++24V) to limit this effect, whereas a circuit between boards a few
+meters apart or using through-hole chips on the same board wile
+require a lower voltage (typically +5V like the old Arduinos). Using
+SMT chips will allow even smaller boards and lower voltages (+3.3V is
+typical today), and with wires running on the same silicon die, it is
+possible to go down to +1.2V, given the current technological limits.
+
+### Voltage Swing
+
+There are other reasons why you should try to minimize voltages: the
+core CPU for example needs to run as fast as possible, and lowering
+its operating voltage will shorten the signal rise and fall duration
+as the voltage swing is reduced.
+
+## Other Power Supply Considerations
+
+Besides reducing the operating voltage, there are other considerations
+that may push to multiply the number of power supplies in a design:
+
+### Quiescent Current
+
+As for power supply used for standby operation providing small
+currents, a very-low leakage current ("quiescent current") is required
+as it can no longer be neglected compared to the current required by
+the light load and even more importantly because this current
+consumption is permanent.
+
+### Ripple Voltage
+
+For sensitive circuits such as ADCs (Analog to Digital Converters) or
+PLLs (Phase-Locked Loops) which rely on comparing very small voltage
+differences, a "clean" power supply featuring very low ripple voltage
+amplitude is required to achieve a good resolution and/or
+accuracy. This characteristic is only possible to obtain using LDOs
+and not SMPS, and the figure to pay attention to is then the PSRR
+(Power Supply Rejection Ratio) or how much a variation in the input
+voltage will affect the output voltage: the higher, the better! A
+value > 50 dB is a good starting point.
+
+## Application to the FunKey Design
+
+Based on these considerations, it is now clear that each V3s power
+supply voltage has a good reason to exist:
+
+ - +3.3V / 1.2A is used for powering the I/Os to connect between chips
+   on the board. Given the required current, a SMPS is required for
+   reaching a good efficiency
+ - +3.3V_AO / 30 mA for the Always-On power supply (RTC timer)
+   requires a low quiescent-current, so an LDO is used
+ - +3.0V / 200 mA for the analog power supply also requires an LDO,
+   this time to minimize the ripple voltage
+ - +1.8V / 1A for the DDR2 DRAM power supply: this strange voltage
+   level is typical for DDR2 DRAM memory chips, and is the result of
+   driving the large memory array inside the chip
+- +1.25V / 1.6 A for powering the CPU core to minimize the voltage
+  swing and increase the possible CPU frequency. Given the required
+  current, a SMPS is required for reaching a good efficiency, too
+
+[1]: /developers/hardware/cpu#cpu-schematics
+[2]: https://github.com/Squonk42/V3s_Documentation/blob/master/V3S_CDR_STD_V1_0_20150514.pdf
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/hardware/screen.md

@@ -0,0 +1,143 @@
+The second most important part in the **FunKey S** is certainly its
+screen: in an overall form factor of roughly 45mm x 45mm x 15mm (1.75"
+x 1.75" x 0.6"), it has to be comfortable enough to provide a good
+gaming experience.
+
+In theory, 1.75" would allows to shoehorn a 2.4" (diagonal) square
+screen, but in practice, 2.4" screens are seldom square and more
+rectangular in shape.
+
+Unless you are a large manufacturer and selling millions of devices,
+you are limited to using the existing screen sizes that are available
+on the market, which most of the time were designed for a
+long-forgotten specific devices (think of PDAs, MP3 players,
+clam-shell phones, pods, etc.)  and standard aspect ratio are either
+1:1, 5:3 or 16:9. Thus, for a given pixel technology, this results in
+rather standard screen sizes.
+
+So the next available size down are 2" and 1.8", but these screens
+tend to be quite thick and based on an older technology, so their
+typical resolution is rather limited @ 128x160 pixels: too small for
+gamers.
+
+Still going down in size, you can find 1.5" to 1.55" screens with an
+interesting resolution of 240x240 or even 320 x 320 ("Retina") pixels,
+but most of them use a fast MIPI DSi interface. These particular
+screens were popular as they were used in the 6th-generation "square"
+iPods, but unfortunately, they require a dedicated controller on the
+host side, which is only available in higher-end SoC.
+
+Another important characteristic of the required screen is that it
+needs to have a narrow flex cable in order to be rolled into the hinge
+(like a _fly-paper_) in order to spread the mechanical flex constraint
+over several loop rather than at always the same section, resulting in
+less wear and an expected longer lifespan.
+
+Fortunately, we found this 1.54" LCD screen on AliBaba:
+
+![LCD TFT Screen](/assets/images/LCD_TFT_Screen.png)
+
+What makes this screen special is its standard SPI interface, which
+only requires a few wires and thus a narrow flex cable like the MIPI
+DSi interface, so it is easy to roll into a hinge. But unlike the MIPI
+DSi one, the SPI interface is readily available on most of the SoC,
+including the Allwinner V3s.
+
+This 1.54" display features a 240x240 16/18-bit full color pixel
+resolution and is an **IPS** display, so the color looks great up to
+80 degrees off-axis in any direction.
+
+However, in order to achieve a 50 fps @ 240 x 240 pixel resolution in
+RGB565 (2 bytes / pixel), this requires a ~44 MHz SPI clock rate,
+which is rather high.
+
+Once again, we were fortunate as both the V3s CPU and the screen
+built-in controller (a Sitronix [ST7789V][1]) both support this high
+clock speed (after checking with the manufacturer and despite the
+controller datasheet that specifies only a serial clock cycle (Write)
+of 66 ns or 15 MHz!).
+
+We were even luckier as its backlight consists in 3 white LEDs in
+parallel and not in series, such that no additional step-up DC-DC
+converter is required, as a standard 3.3V / 60 mA (typical) power
+supply is sufficient. Of course, we won't be able to drive this
+current directly from a CPU GPIO and the backlight will require an
+additional transistor to interface to the LCD backlight.
+
+Its flex cable requires a mating Hirose 0.4 mm pitch
+[DF37NB-24DS-0.4V][2] dual row SMT connector, out of which only one
+single row is actually used.
+
+## Customization
+
+Unfortunately, the flex cable for the stock LCD screen we found does
+not match our particular **FunKey S** mechanical design.
+
+For the prototypes, we designed custom flex extension cables for a
+~ $100 cost, but we had to design [our own custom flex][3] and have
+this standard screen assembly attached to it for mass production, with
+a one-time tooling fee of ~ $800.
+
+## Schematic
+
+The schematic is quite simple:
+
+![SPI LCD Schematics](/assets/images/SPI_LCD_Schematics.png)
+
+The main component is of course the Hirose screen connector **J3**,
+with the following signals:
+
+ - LEDA: the backlight LED common Anode connection (+)
+ - GND
+ - +3V3 power supply
+ - /SPI_CS: SPI Chip Select
+ - SPI_MOSI: SPI Master Out / Slave In
+ - SPI_CLK: SPI Clock
+ - TE: Tearing Effect sync signal from the screen
+ - RS: LCD-specific Register/Memory Select (or Data/Control Select)
+ - LCD_RESET: LCD Reset
+
+All data signals feature an ESD TVS protection diode **D19-D24** and
+**D37**, and except for the power supplies and LEDA + LCD_RESET and TE
+signals, all signals are directly connected to the V3s CPU's SPI
+interface, so there is not much to say about these.
+
+The LCD_RESET signal is controlled by a V3s GPIO (PB2 on pin 41).
+
+The TE signal from the screen controller is fed to an
+interrupt-enabled input pin PB1 (pin 40) in order to synchronize the
+sending of data to the screen with its inactive period in order to
+avoid the hardware tearing effect.
+
+## Backlight PWM
+
+The backlight control requires a few more components: a MOSFET-P
+transistor **Q1** and 2 resistors **R5** and **R7** to provide its
+polarization, more on this below.
+
+As the backlight LEDs cathode (-) pin are directly tied to GND within
+the screen, we need to drive these LEDs "from the high-side",
+i.e. between the +3V3 power supply and the LEDA pin, so a MOSFET-P
+transistor is necessary:
+
+![Backlight Schematics](/assets/images/Backlight_Schematics.png)
+
+As we want the backlight to be on by default, we need to drive it to
+GND by default: this is the role of **R7**. The role of **R5** is then
+to make sure that -Vgs is driven below its threshold voltage and turns
+off the transistor when the CPU drives a GPIO high.
+
+As an ultimate sophistication, we can drive the backlight from the CPU
+using one of its built-in PWM controllers PWM0 with a varying
+duty-cycle, thus controlling the LCD backlight brightness
+accurately. For this purpose, the other end of the **R5** resistor is
+connected to the PB4 output (pin 43) on the V3s, wich provides this
+function.
+
+[1]: https://www.numworks.com/shared/binary/datasheets/st7789v-lcd-controller-73f8bc3e.pdf
+[2]: https://github.com/FunKey-Project/FunKey-S-Hardware/blob/master/Datasheets/1811071030_HRS-Hirose-DF37NC-24DS-0-4V-51_C324720.pdf
+[3]: https://github.com/FunKey-Project/FunKey-S-Hardware/blob/master/Datasheets/DISPLAY%20-%20SF-TC154B-8737A-N%20-%20CUSTOM%20FLEX%20-%200.3.PDF
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/hardware/sd-card.md

@@ -0,0 +1,125 @@
+The **FunKey S** game console uses the SD Card both as its boot device
+and its only storage device, so a good operation of this interface is
+absolutely mandatory.
+
+The Allwinner V3s provides 2x 4-bit MMC / SD Card / SDIO
+interfaces. In the FunKey, only interface #0 is used.
+
+If you look on the Web, you will find many contradictory SD Card
+interface designs, with a combination of pull-up / pull-down
+resistors, ESD devices and power supply filtering, with all pins wired
+or not, such that it is very difficult to know what is really
+required. To better understand the situation, we need to go back to
+the specifications.
+
+## Specifications
+
+The SD Card physical interface is provided in the "<i>SD specifications,
+part 1, Physical Layer Specification version 2.00, May 9, 2006</i>", for
+which a simplified version is available [here][1].
+
+The MMC phyiscal interface can be found in the "<i>Multi Media Card
+System Specification version 4.3, JESD84-A43, November 2007</i>",
+available [here][2] (registration required).
+
+But a good summary of the requirements is given in the "[<i>AN10911
+SD(HC)-memory card and MMC Interface conditioning</i>][3]" application
+note from NXP, from which this schematic is taken:
+
+![SD/MMC Interface](/assets/images/SD_MMC_Interface.png)
+
+!!! Warning
+    This schematic does not include details concerning card-supply and
+    typical power-supply decoupling capacitors.
+
+## Write Protect (WP)
+
+A mechanical write protect switch is provided in the full-size SD
+Card, but not in the mini or micro SD Card form factor. As we plan to
+use a micro SD Card only, it is not used for the FunKey, along with
+its pull-up resistor and ESD protection.
+
+## Card Detection (CD)
+
+As the SD Card is mandatory to boot the **FunKey S**, is always
+inserted and opening the device is required for its removal, we don't
+need the optional card detect mechanical switch feature (even if the
+chosen connector provides it) and its related pull-up resistor and ESD
+protection.
+
+The SD Card specification provides another mean to detect the card
+using a card built-in pull-up resistor on its DAT3 signal, that can be
+later disconnected during normal operation using he
+**SET_CLR_CARD_DETECT** (**ACMD42**) command. In order to correctly
+detect if the card is inserted, a high value external pull-down
+resistor (> 270 kΩ) is required to drive the detect signal low when no
+card is inserted, while the card built-in 10-50 kΩ resistor will drive
+this signal high when inserted.
+
+However, this feature is not compatible with MMC cards, so its usage
+should be avoided and the mechanical detection is preferred.
+
+## Pull-Up Resistors
+
+Both the SD Card and MMC specifications require not to leave the
+interface signals floating, except for the CLK signal, where a pull
+resistor would cause significant signal distortion because of the
+required high speed and short rise/fall times. However, it is
+recommended to add a series resistor on this CLK signal as close as
+possible to the clock source (the CPU) to avoid ringing, as we already
+discussed it in the page about the [CPU][4].
+
+Fortunately, the Allwinner V3s CPU provides internal pull-up resistors
+for all these signals, so we don't have to add external pull-up
+resistors. These resistors are given with a typical value of 100 kΩ
+(50 min, 150 max). Unfortunately, the CMD signal for MMC card features
+an open-drain output mode, and its value should be undercut (down to
+4.7 kΩ) to guarantee a sufficiently short rise time in this mode.
+
+## Schematics
+
+The FunKey SD Card interface schematic is the following:
+
+![SD Card Schematics](/assets/images/SD_Card_Schematics.png)
+
+![TF-110](/assets/images/TF-110.png){: align=left }
+
+As can be expected, the main component is the [Micro SD (TF Card)
+Push/Pull connector][5] **J4**, which has been selected for its
+low-profile (1.3 mm height) characteristic and overall minimal
+dimensions.
+
+!!! Tip
+
+    "Push-Pull" means that you have to "Push" to insert the card and
+    to "Pull" to remove it, i.e. the operation is completely manual,
+    whereas "Push/Push" implies that you have a bistable mechanism to
+    remove the card.
+
+Even if in the FunKey device the SD Card and its connector are not
+accessible without opening the enclosure, there may be some situations
+where the user may decide to do so. We thus attach an ESD protection
+TVS diode (**D16**, **D17**, **D18**, **D25**, **D26**, **D27**,
+**D28**) on each signal to avoid any ESD hazard.
+
+As discussed above, a single pull-up resistor **R10** is used on the CMD
+signal for MMC compatibility.
+
+The micro SD Card connector built-in card detection switch is not
+used, since the card must always be inserted for the **FunKey S** to
+boot, and the corresponding pins are thus connected to GND.
+
+The SD Card power supply is applied through an RC low-pass filter
+**R9** / **C11** in order to provide a soft-start operation, as the
+card built-in large bulk capacitor on its power rail may collapse the
+supply voltage when initially powered up.
+
+[1]: https://www.sdcard.org/downloads/pls/click.php?p=Part1_Physical_Layer_Simplified_Specification_Ver6.00.jpg&f=Part1_Physical_Layer_Simplified_Specification_Ver6.00.pdf&e=EN_SS1
+[2]: https://www.jedec.org/document_search/field_keywords/emmc-3147
+[3]: https://www.mouser.com/catalog/specsheets/an10911.pdf
+[4]: /developers/hardware/cpu
+[5]: https://github.com/FunKey-Project/FunKey-S-Hardware/blob/master/Datasheets/C266613_%E6%8A%BD%E6%8B%89%E5%BC%8FTF%E5%8D%A1%E5%BA%A7_2018-08-20.PDF
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/hardware/uart.md

@@ -0,0 +1,50 @@
+The Allwinner V3s provides 3x UARTs (Universal Asynchronous Receivers
+/ Transmitters): UART0 with only RX and TX signals, and UART1 and
+UART2 with additional RTS and CTS hardware flow control signals.
+
+Like most SoCs, the Allwinner V3s provides a serial console as a
+control terminal for debug and/or normal operation. By default, it is
+mapped to UART0, and it is used by the BROM (Boot Rom), the U-Boot
+bootloader and by the Linux kernel to output messages during the boot
+process, and later by the Linux kernel to log messages during normal
+operation. Depending on the configuration, it can be used too for
+loging into the system over an UART.
+
+The Console schematic only requires a minimum of external components:
+
+![Console Schematics](/assets/images/UART_Schematics.png)
+
+Besides the 3-pin 1.27 mm (0.05") pitch header J1 that will not be
+mounted on standard products, there is only a single series resistor
+**R3**.
+
+What is the purpose of this resistor?
+
+ - As explained previously for the SD Card clock signal, this may be
+   to prevent ringing. But given the relatively slow signal speed
+   (115200 bps), it is not the case here
+
+ - If it were placed on the RX input signal, this could prevent frying
+   the input pin if a large voltage (+5V, for example) is applied to
+   it by dissipating the excessive voltage as heat in the resistor. It
+   is not the case here, as the resistor is placed on the TX output
+   signal, but we could have added one, if only we had some space left
+   on the board... But as the V3s SoC can tolerate input voltages up
+   to +3.6V on its pins, we should be safe!
+
+ - In fact, the resistor is on the output TX signal to prevent
+   short-circuits if the serial cable is reversed and the 2 TX outputs
+   are connected together, one driving the signal low, while the other
+   is driving it high: again in this case, the voltage difference
+   between the 2 outputs will be burned as heat in the resistor,
+   saving the internal output buffers!
+
+!!! Warning
+
+    There is no ESD protection TVS diodes on the UART: this interface
+    is not supposed to be mounted in the final user device, and PCB
+    space is really constrained in this area, so they are omitted.
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/hardware/usb.md

@@ -0,0 +1,55 @@
+In the **FunKey S** device, the USB interface has 2 functions:
+
+ - provide an external power supply source for both powering the
+   device and charging the built-in LiPo battery
+- provide a data interface to transfer firmware upgrades,
+  configuration files, game emulators and game ROMs
+
+The first function only requires the +5V USB power and GND pins. The
+second function requires to wire the additional differential data
+lines D+ and D-. As we only need to operate as an USB device and
+although the V3s is able to work as either an USB host or USB device
+using the USB OTG protocol, we don't need the ID pin to determine by
+the cable wiring which role we must take.
+
+![U02-BFD3111B0-009](/assets/images/U02-BFD3111B0-009.png){: align=left }
+
+The main part is of course the [Micro USB edge-mounted connector][1]
+**J2**, which we chose in order to "mask out" its already low-profile
+height into the PCB thickness. And with its "harpoon-like"
+through-hole legs, it should avoid tearing it off the board if the
+user don't pull the chord straight.
+
+The USB schematic is the following:
+
+![USB Schematics](/assets/images/USB_Schematics.png)
+
+Before connecting 2 devices using an USB cable, they may be at
+completely different absolute voltages, and during cable insertion,
+the shield will be in contact before the other pins, including
+GND. The **C6** capacitor between the Protective Earth (Shield) and
+GND is here to provide an AC path for sinking this difference in
+voltage and align the GND levels when plugin the cable.
+
+The resistor **R4** on the USB ID connector pin should probably not be
+mounted: as we act only as an USB device, this pin should be left
+floating.
+
+The capacitors **C7**, **C8**, **C10** and ferrite bead **L2** form a
+constant-k 3 pole CLC low pass filter to remove any spurious in/out on
+the USB power supply wire. The USB 2.0 specification limits the
+maximum bulk capacitance value to 10 µF in order to avoid power supply
+excessive droops when plugin in a device with a discharged large bulk
+capacitor.
+
+**D15** is a [NXP PRTR5V0U2X,215][2] combined TVS protection diode for the VBUS pin and a set
+of clamping diodes that will limit the voltage on D+ and D- pins to
+stay between GND and VBUS levels to in order to protect the V3s USB
+driver from under / over-voltages.
+
+[1]: https://github.com/FunKey-Project/FunKey-S-Hardware/blob/master/Datasheets/C40958_MICRO5P%E6%B2%89%E6%9D%BF%E5%BC%8F0.8%E5%9B%9B%E8%84%9A%E5%85%A8%E6%8F%92%E6%97%A0%E5%AF%BC%E4%BD%8D%E6%9C%89%E5%AD%94%E8%80%90%E9%AB%98%E6%B8%A9_2016-05-20.PDF
+[2]: https://github.com/FunKey-Project/FunKey-S-Hardware/blob/master/Datasheets/C12333_PRTR5V0U2X%2C215_2017-10-31.PDF
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/software/applications/build_system.md

@@ -0,0 +1,4 @@
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/software/applications/input.md

@@ -0,0 +1,4 @@
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/software/applications/toolchain.md

@@ -0,0 +1,4 @@
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/software/applications/video.md

@@ -0,0 +1,4 @@
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/software/system/architecture.md

@@ -0,0 +1,54 @@
+The **FunKey S** retro-gaming console software contains a set of
+console emulators, standalone games, applications and utilities using
+a custom Operating System (OS) that from now on will be referenced as
+**_FunKey-OS_**.
+
+The **FunKey-OS** is a Linux-based operating system, optimized for the
+**FunKey-S** hardware, with a special focus on performance and fast
+boot time.
+
+## Instant Action
+
+The **FunKey S** introduces a unique feature called **_Instant Action_**,
+which enables automatically saving the running state when closing
+the console before turning it off, and restoring this state when
+opening and turning it back on in a matter of seconds.
+
+This feature is only possible because of the optimized fast boot time
+detailed in the [Boot Process](bootprocess.md) section.
+
+## Storage
+
+The only storage system available in the **FunKey S** is its
+integrated MicroSD card. Most of its contents is made available to a
+host computer when connected over USB.
+
+The MicroSD card format is detailed in the [Disk
+Partition](partition.md) section.
+
+## Video Processing
+
+The **FunKey-S** CPU does not feature a GPU. For this reason, the
+**FunKey-S** cannot use a hardware-accelerated OpenGL engine, and
+adding a software-emulated OpenGL-ES engine is not efficient, given
+the limited CPU performance.
+
+However, because of the small screen size and the fact that all
+applications are used in full-screen mode only, there is no need for a
+full-blown windowing system like X11, which greatly simplifies the
+video processing as no window overlapping or frame decoration is thus
+required.
+
+Instead, all graphical computations are performed by the CPU itself,
+directly into the video frame buffer that will be sent to the screen
+for display.
+
+## User Input
+
+The **FunKey S** has no standard keyboard but features common
+console-oriented controls in the form of a D-Pad, A/B/X/Y Pad,
+Menu/On/Off, Fn and Start buttons.
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/software/system/bootprocess.md

@@ -0,0 +1,4 @@
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/software/system/init.md

@@ -0,0 +1,4 @@
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/software/system/kernel.md

@@ -0,0 +1,4 @@
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/software/system/partition.md

@@ -0,0 +1,4 @@
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/software/system/recovery.md

@@ -0,0 +1,4 @@
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/software/system/rootfs.md

@@ -0,0 +1,4 @@
+
+--8<--
+includes/glossary.md
+--8<--

docs/developers/software/system/shared.md

@@ -0,0 +1,4 @@
+
+--8<--
+includes/glossary.md
+--8<--

docs/index.md

@@ -1,6 +1,6 @@
 # Welcome to FunKey!
 
-![Atomic Purple FunKey S](assets/images/Atomic_Purple_FunKey_S.jpg)
+![Atomic Purple FunKey S](assets/images/Atomic_Purple_FunKey_S.jpg){: align=left }
 
 Thank you for choosing the **FunKey S**!
 
@@ -35,8 +35,12 @@ Last but not least, this documentation would not be complete without a
 [Glossary of terms][5] and an [FAQ][6] section for reference.
 
 [1]: quickstart.md
-[2]: tutorials/tutorials.md
+[2]: tutorials/update.md
 [3]: developers/hardware
 [4]: developers/software
-[5]: glossary/glossary.md
-[6]: faq/faq.md
+[5]: miscellaneous/glossary.md
+[6]: miscellaneous/faq.md
+
+--8<--
+includes/glossary.md
+--8<--

docs/miscellaneous/faq.md

@@ -0,0 +1,4 @@
+
+--8<--
+includes/glossary.md
+--8<--

docs/miscellaneous/glossary.md

@@ -0,0 +1,36 @@
+ - ADC: Analog to Digital Converter
+ - CPU: Central Processing Unit
+ - CSi: Camera Serial Interface
+ - DAC: Digital to Analog Converter
+ - DDR: Dual Data Rate
+ - DRAM: Dynamic Random-Access Memory
+ - DSi: Display Serial Interface
+ - ERC: Electrical Rule Check
+ - ESD: Electro-Static Discharge
+ - GPIO: General-Purpose Input/Output
+ - I/O: Input/Output
+ - I2C: Inter-Integrated Circuit Bus
+ - IPS: In-Plane Switching
+ - LED: Ligh-Emitting Diode
+ - LCD: Liquid-Crystal Display
+ - LDO: Low Drop-Out
+ - LiPo: Lithium Polymer
+ - MIPI: Mobile Industry Processor Interface
+ - PCBA: Printed Circuit Board Assembly
+ - PCB: Printed Circuit Board
+ - PLL: Phase-Locked Loop
+ - PMIC: Power Management Integrated Circuit
+ - PWM: Pulse Width Modulation
+ - RTC: Real-Time Clock
+ - SD: Secure Digital
+ - SMPS: Switched-Mode Power Supply
+ - SPI: Serial Peripheral Interface
+ - SoC: System on Chip
+ - TFT LCD:  Thin-Film-Transistor Liquid-Crystal Display
+ - TVS: Transcient Voltage Suppressor
+ - UART: Universal Asynchronous Receiver/Transmitter
+ - USB: Universal Serial Bus
+
+--8<--
+includes/glossary.md
+--8<--

docs/quickstart.md

@@ -0,0 +1,4 @@
+
+--8<--
+includes/glossary.md
+--8<--

docs/tutorials/buttons.md

@@ -0,0 +1,4 @@
+
+--8<--
+includes/glossary.md
+--8<--

docs/tutorials/gba_bios.md

@@ -0,0 +1,4 @@
+
+--8<--
+includes/glossary.md
+--8<--

docs/tutorials/recovery.md

@@ -0,0 +1,4 @@
+
+--8<--
+includes/glossary.md
+--8<--

docs/tutorials/themes.md

@@ -0,0 +1,4 @@
+
+--8<--
+includes/glossary.md
+--8<--

docs/tutorials/update.md

@@ -0,0 +1,4 @@
+
+--8<--
+includes/glossary.md
+--8<--

includes/glossary.md

@@ -0,0 +1,49 @@
+*[ADC]: Analog to Digital Converter
+*[ADCs]: Analog to Digital Converters
+*[CPU]: Central Processing Unit
+*[CPUs]: Central Processing Units
+*[CSi]: Camera Serial Interface
+*[DAC]: Digital to Analog Converter
+*[DACs]: Digital to Analog Converters
+*[DDR]: Dual Data Rate
+*[DRAM]: Dynamic Random-Access Memory
+*[DSi]: Display Serial Interface
+*[ERC]: Electrical Rule Check
+*[ESD]: Electro-Static Discharge
+*[FPU]: Floating Point Unit
+*[GPIO]: General-Purpose Input/Output
+*[GPU]: Graphic Processing Unit
+*[I/O]: Input/Output
+*[I2C]: Inter-Integrated Circuit Bus
+*[IPS]: In-Plane Switching or Intelligent Power Select
+*[IRQ]: Interrupt ReQuest
+*[LED]: Ligh-Emitting Diode
+*[LCD]: Liquid-Crystal Display
+*[LDO]: Low Drop-Out
+*[LiPo]: Lithium Polymer
+*[MIPI]: Mobile Industry Processor Interface
+*[NTC]: Negative Temperature Coefficient
+*[OTG]: On-The-Go
+*[PCBA]: Printed Circuit Board Assembly
+*[PCB]: Printed Circuit Board
+*[PLL]: Phase-Locked Loop
+*[PLLs]: Phase-Locked Loops
+*[PMIC]: Power Management Integrated Circuit
+*[PMU]: Power Managment Unit
+*[PoP]: Package on Package
+*[PSRR]: Power Supply Rejection Ratio
+*[PWM]: Pulse Width Modulation
+*[RTC]: Real-Time Clock
+*[SD]: Secure Digital
+*[SIMD]: Single Instruction Multiple Data
+*[SiP]: System in Package
+*[SMPS]: Switched-Mode Power Supply
+*[SoC]: System on Chip
+*[SoCs]: System on Chips
+*[SPI]: Serial Peripheral Interface
+*[SRAM]: Static Random-Access Memory
+*[TFT LCD]:  Thin-Film-Transistor Liquid-Crystal Display
+*[TVS]: Transcient Voltage Suppressor
+*[UART]: Universal Asynchronous Receiver/Transmitter
+*[UARTs]: Universal Asynchronous Receiver/Transmitters
+*[USB]: Universal Serial Bus

mkdocs.yml

@@ -12,8 +12,8 @@ site_description: >-
 
 # Copyright
 copyright: >
-  &copy; 2020 FunKey Project<br/>
-  Last updated on 2020-12-18<br/>
+  &copy; 2020-2021 FunKey Project<br/>
+  Last updated on 2021-01-16<br/>
   <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">
   <img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-sa/4.0/80x15.png" />
   </a><br />This work is licensed under a
@@ -27,15 +27,19 @@ theme:
   favicon: assets/favicon.png
   palette:
     primary: deep purple
+  font:
+    text: Roboto
+    code: Roboro Mono
 
-# 404 page
-static_templates:
-  - 404.html
+  # 404 page
+  static_templates:
+    - 404.html
 
-# Plugins:
+# Plugins
+plugins:
   - search
   - minify:
-    minify_html: true
+      minify_html: true
 
 # Customization
 extra:
@@ -80,8 +84,8 @@ markdown_extensions:
   - pymdownx.keys
   - pymdownx.magiclink:
       repo_url_shorthand: true
-      user: squidfunk
-      repo: mkdocs-material
+      user: FunKey-Project
+      repo: FunKey-Project.github.io
   - pymdownx.mark
   - pymdownx.smartsymbols
   - pymdownx.snippets:
@@ -101,48 +105,50 @@ nav:
   - Overview: index.md
   - Quickstart: 'quickstart.md'
   - Tutorials:
-    - 'Firmware upgrade': 'quickstart/update.md'
-    - 'Install the GBA BIOS': 'quickstart/gba_bios.md'
-    - 'Change the buttons': 'quickstart/buttons'
+    - 'Firmware upgrade': 'tutorials/update.md'
+    - 'Install the GBA BIOS': 'tutorials/gba_bios.md'
+    - 'Change the buttons': 'tutorials/buttons.md'
     - 'Access the built-in Recovery': 'tutorials/recovery.md'
     - 'Create themes': 'tutorials/themes.md'
   - Developer's Guide:
     - Hardware:
-      - 'Architecture / Block Diagram' : 'developers/hardware/architecture.md'
-      - 'Electronic Parts': 'developers/hardware/parts.md'
+      - 'Design' : 'developers/hardware/design.md'
+      - 'Architecture': 'developers/hardware/architecture.md'
+      - 'BOM': 'https://htmlpreview.github.io/?https://github.com/FunKey-Project/FunKey-S-Hardware/blob/master/BOM/ibom.html'
       - 'CPU': 'developers/hardware/cpu.md'
       - 'Power':
-        - 'Regulated DC Power Supply Topologies': 'developers/hardware/dc-dc.md'
-        - 'Why so many different Power Supply Voltages?': 'developers/hardware/voltages.md'
-        - 'PMIC': 'developers/hardware/pmic.md'
-        - 'DRAM Power': 'developers/hardware/dram.md'
+        - 'Regulated DC Power Supply Topologies': 'developers/hardware/power/dc-dc.md'
+        - 'Why so many different Power Supply Voltages?': 'developers/hardware/power/voltages.md'
+        - 'PMIC': 'developers/hardware/power/pmic.md'
+        - 'DRAM Power': 'developers/hardware/power/dram.md'
+        - 'Decoupling' : 'developers/hardware/power/decoupling.md'
       - 'Screen': 'developers/hardware/screen.md'
       - 'Audio': 'developers/hardware/audio.md'
       - 'Buttons': 'developers/hardware/buttons.md'
+      - 'SD Card': 'developers/hardware/sd-card.md'
       - 'USB': 'developers/hardware/usb.md'
       - 'UART': 'developers/hardware/uart.md'
-      - 'SD Card': 'developers/hardware/sd-card.md'
-      - 'Magnetic Sensor': 'developers/hardware/sensor.md'
+      - 'Magnetic Switch': 'developers/hardware/magnetic_switch.md'
     - Software:
-        - 'Built-in Recovery': 'developers/software/recovery.md'
-        - 'Bare Metal Appliance Store': 'developers/software/appliancestore.md'
-        - 'Kernel and Bootloader':
-          - 'The Boot Process': 'developers/software/bootprocess.md'
-          - 'Firmware Builder': 'developers/software/firmware-builder.md'
-          - 'Kernel': 'kernel.md'
-        - 'Distributions':
-          - 'Distribution Support': 'developers/software/distributions.md'
-          - 'Board Support Package': 'developers/software/distributions/board-support.md'
-          - 'OpenWrt': 'developers/software/openwrt.md'
-        - 'Reflash': 'developers/software/reflash.md'
-        - 'Cryptographic acceleration': 'developers/software/crypto.md'
-        - 'Virtualization and Containers':
-          - 'μVirt': 'developers/software/muvirt.md'
-          - 'Docker': 'developers/software/docker.md'
-          - 'VFIO': 'developers/software/vfio.md'
-        - 'Hardware Watchdog': 'watchdog.md'
-        - 'Roadmap': 'developers/software/roadmap.md'
+        - 'System':
+          - 'Software Architecture': 'developers/software/system/architecture.md'
+          - 'Instant Action':
+            - 'Boot Process': 'developers/software/system/bootprocess.md'
+            - 'Bootloader': 'developers/software/system/bootloader.md'
+            - 'Kernel': 'developers/software/system/kernel.md'
+            - 'Init Scripts': 'developers/software/system/init.md'
+            - 'Shutdown Process': 'developers/software/system/shutdown.md'
+          - 'Storage':
+            - 'Partition Map': 'developers/software/system/partition.md'
+            - 'Built-in Recovery': 'developers/software/system/recovery.md'
+            - 'Root Filesystem': 'developers/software/system/rootfs.md'
+            - 'USB Shared Partition': 'developers/software/system/shared.md'
+          - 'Video Processing': 'developers/software/applications/video.md'
+          - 'User Input': 'developers/software/applications/input.md'
+          - 'Build System': 'developers/software/applications/build_system.md'
+        - 'Applications':
+          - 'Toolchain': 'developers/software/applications/toolchain.md'
   - Miscellaneous:
-    - 'Glossary': 'glossary.md'
-    - 'FAQ': 'faq.md'
+    - 'Glossary': 'miscellaneous/glossary.md'
+    - 'FAQ': 'miscellaneous/faq.md'