first proposed structure

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

docs/developers/hardware/architecture.md

@@ -0,0 +1,31 @@
+The FunKey S is a small foldable retro-gaming console.
+
+Its electronic parts consist in:
+
+ - 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
+
+![FunKey S Block Diagram](/assets/images/FunKey%20S%20Block%20Diagram.png)
+
+The FunKey S PCBA Rev. E contains the following main components:
+
+ - 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)
+
+![FunKey Top](/assets/images/FunKey%20S%20Top.png)
+
+![FunKey Bottom](/assets/images/FunKey%20S%20Bottom.png)

docs/developers/hardware/parts.md

@@ -0,0 +1,70 @@
+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/index.md

@@ -1,17 +1,42 @@
-# Welcome to MkDocs
+# Welcome to FunKey!
 
-For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+![Atomic Purple FunKey S](assets/images/Atomic_Purple_FunKey_S.jpg)
 
-## Commands
+Thank you for choosing the **FunKey S**!
 
-* `mkdocs new [dir-name]` - Create a new project.
+The **FunKey S** is the world's smallest foldable retro-gaming console.
-* `mkdocs serve` - Start the live-reloading docs server.
-* `mkdocs build` - Build the documentation site.
-* `mkdocs -h` - Print help message and exit.
 
-## Project layout
+Because of its foldable design, the **FunKey S** provides a
+surprisingly large screen and comfortable key pads while open, but it
+stays compatible with a keychain usage when closed.
 
-    mkdocs.yml    # The configuration file.
+## Basic operation
-    docs/
+
-        index.md  # The documentation homepage.
+The **FunKey S** operation is so straightforward that a 6-year old
-        ...       # Other markdown pages, images and other files.
+child should be able to operate it without any user's manual for the
+most common tasks. But just to make sure you are not missing
+something, you can find the basic device operation description in the
+[Quickstart section][1].
+
+## More advanced features
+
+Despite its size, the **FunKey S** is packed with features, and this
+documentation will also provide more advanced tips in the [Tutorials
+section][2].
+
+## Developers
+
+For developers, a full [Developer's Guide][3] is included, with both
+[Hardware][3] and [Software][4] subsections.
+
+## Miscellaenous stuff
+
+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
+[3]: developers/hardware
+[4]: developers/software
+[5]: glossary/glossary.md
+[6]: faq/faq.md

mkdocs.yml

@@ -1,7 +1,148 @@
+# Copyright (c) 2020 Michel Stempin <michel.stempin@funkey-project.com>
+
+# This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License
+
+# Project information
 site_name: FunKey Project Documentation
+site_author: Michel Stempin
+site_description: >-
+  FunKey S - the world's smallest foldable handeld console
+  Ultra-compact, foldable, powerful and comfortable, the FunKey S is
+  the perfect handheld for playing retrogames anywhere, anytime.
+
+# Copyright
+copyright: >
+  &copy; 2020 FunKey Project<br/>
+  Last updated on 2020-12-18<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
+  <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International License</a>.
+repo_url: 'https://github.com/FunKey-Project/FunKey-Project.github.io'
+
+# Configuration
 theme:
   name: material
   logo: assets/images/logo.png
   favicon: assets/favicon.png
   palette:
     primary: deep purple
+
+# 404 page
+static_templates:
+  - 404.html
+
+# Plugins:
+  - search
+  - minify:
+    minify_html: true
+
+# Customization
+extra:
+  social:
+    - icon: fontawesome/brands/facebook
+      link: https://www.facebook.com/FunKeyProjectOfficial
+    - icon: fontawesome/brands/twitter
+      link: https://twitter.com/FunKeyProject
+    - icon: fontawesome/brands/instagram
+      link: https://www.instagram.com/funkey_project/
+    - icon: fontawesome/brands/youtube
+      link: https://www.youtube.com/channel/UCm6RThJXazA1VMhimqOtjww
+    - icon: fontawesome/brands/pinterest
+      link: https://www.pinterest.fr/davidlarbi/funkey-project/
+    - icon: fontawesome/brands/github
+      link: https://github.com/FunKey-Project
+    - icon: fontawesome/brands/docker
+      link: https://hub.docker.com/r/funkeyproject/funkey-os/
+
+# Extensions
+markdown_extensions:
+  - admonition
+  - abbr
+  - attr_list
+  - def_list
+  - footnotes
+  - meta
+  - toc:
+      permalink: true
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.critic
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+  - pymdownx.highlight
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.magiclink:
+      repo_url_shorthand: true
+      user: squidfunk
+      repo: mkdocs-material
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.snippets:
+      check_paths: true
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+# Page tree
+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'
+    - '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'
+      - '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'
+      - 'Screen': 'developers/hardware/screen.md'
+      - 'Audio': 'developers/hardware/audio.md'
+      - 'Buttons': 'developers/hardware/buttons.md'
+      - 'USB': 'developers/hardware/usb.md'
+      - 'UART': 'developers/hardware/uart.md'
+      - 'SD Card': 'developers/hardware/sd-card.md'
+      - 'Magnetic Sensor': 'developers/hardware/sensor.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'
+  - Miscellaneous:
+    - 'Glossary': 'glossary.md'
+    - 'FAQ': 'faq.md'
+