Merge pull request #89 from GameTec-live/users-guide

Adding a (not so) basic users guide

CHANGELOG.md

@@ -3,15 +3,16 @@ All notable changes to this project will be documented in this file.
 This project uses the changelog in accordance with [keepchangelog](http://keepachangelog.com/). Please use this to write notable changes, which is not the same as git commit log...
 
 ## [unreleased][unreleased]
+ - Added initial version of the user guides (@GameTec-live)
  - Added support for pasting several command lines at once with prompt_toolkit (@doegox)
  - Added support for interrupting sleep sequence with a button press during animation (@doegox)
  - Fixed logs corruption and app reset on FDS write, added logs flush on sleep (@doegox)
  - Added support for long-press of buttons (@nemanjan00)
- - Changed `hw slot delete`, now it can always delete from slot. (@augustozanellato)
- - Refactor CI pipeline. (@augustozanellato)
- - Added offline copy EM card uid for btnpress.(@nemanjan00)
- - Added offline copy ic card uid for btnpress.(@xianglin1998)
- - Added `hw settings btnpress` to get and set button press function.(@xianglin1998)
+ - Changed `hw slot delete`, now it can always delete from slot (@augustozanellato)
+ - Refactor CI pipeline (@augustozanellato)
+ - Added offline copy EM card uid for btnpress (@nemanjan00)
+ - Added offline copy ic card uid for btnpress (@xianglin1998)
+ - Added `hw settings btnpress` to get and set button press function (@xianglin1998)
  - Added `hw battery` to get battery informartion (@xianglin1998)
  - Added `hw slot delete` to delete HF or LF out of a HF+LF slot (@augustozanellato)
  - Changed CLI prompt autocompletion, saved history and internal cmd registration (@szymex73)

README.md

@@ -24,7 +24,7 @@ Anywhere else: [Sneaktechnology][go_to_buy_sneaktechnology] / [Aliexpress by RRG
 # How to use ?
 
 - ChameleonUltra: [Technical White Paper][tech_white_paper] (Old content of this readme in here)
-- ChameleonUltra: [Firmware][how_use_firmware]
+- ChameleonUltra: [Firmware][./docs/development.md]
 
 More Coming Soon.
 

docs/cli.md

@@ -0,0 +1,131 @@
+# CLI
+
+The CLI (**C**ommand **L**ine **I**nterface) is the official way to control your Chameleon.
+
+## Installing
+
+There are multiple ways to install the CLI, depending on your OS.
+
+### Windows
+
+Windows users have the choice of 4 options:
+
+#### ProxSpace
+
+Using ProxSpace to build the CLI is the easiest and most comfortable way to get started.
+
+1. Download ProxSpace from the [official GitHub](https://github.com/Gator96100/ProxSpace/releases/latest)
+
+2. [Download 7zip](https://www.7-zip.org/) to extract the archive
+
+3. Install 7zip by double clicking the Installer and clicking `Install`
+
+4. Right-click on the downloaded archive and select `7zip -> Unpack to "ProxSpace"`
+
+5. Open a terminal in the proxspace folder. If you are on a new Windows install, you should be able to just right-click and select `Open in Terminal`. If that option is not visible and the ProxSpace folder is still in your downloads folder, press `win+r` and type `powershell` followed by enter. In Powershell now type `cd ~/Downloads/ProxSpace`
+
+6. Run the command `.\runme64.bat`. After successful completion, you should be dropped to the `pm3 ~ $` shell.
+
+7. Clone the Repository by typing `git clone https://github.com/RfidResearchGroup/ChameleonUltra.git`
+
+8. Now go into the newly created folder with `cd ChameleonUltra/software/src`
+
+9. Prepare for package installation with `pacman-key --init; pacman-key --populate`
+
+10. Proceed by installing Ninja with `pacman -S ninja --noconfirm`
+
+11. Build the required config by running `cmake .`
+
+12. And the binaries with `cmake --build .`
+
+13. Copy the binaries by running `cp -r ~/ChameleonUltra/software/bin/* ~/ChameleonUltra/software/script/`
+
+14. Go into the script folder with `cd ~/ChameleonUltra/software/script/`
+
+15. Install python requirements with `pip install -r requirements.txt`
+
+16. Finally run the CLI with `python chameleon_cli_main.py`
+
+To use after installing, just do the following:
+
+1. Run `runme64.bat`
+
+2. Go into the script folder with `cd ~/ChameleonUltra/software/script/`
+
+3. Run the CLI with `python chameleon_cli_main.py`
+
+#### WSL2
+
+Coming Soon
+
+#### WSL1
+
+Coming Soon
+
+#### Build Natively
+
+Building natively is a bit more advanced and not recommended for beginners
+
+1. Download and install [Visual Studio Community](https://visualstudio.microsoft.com/de/downloads/)
+
+2. On the workload selection screen, choose the `Desktop development with C++` workload. Click `Download and Install`
+
+3. Download and install [git](https://git-scm.com/download). When asked, add to your path
+
+4. Download and install [cmake](https://cmake.org/download/). Again, when asked, add to your path
+
+5. Download and install [python](https://www.python.org/downloads/). When asked, add to your path (small checkbox in the bottom left)
+
+6. Choose a suitable location and open a terminal. Clone the repository with `git clone https://github.com/RfidResearchGroup/ChameleonUltra.git`
+
+7. Change into the binaries folder with `cd ChameleonUltra/software/src`
+
+8. Build the required config by running `cmake .`
+
+9. And the binaries with `cmake --build .`
+
+10. Copy the binaries by running `cp -r ../bin/Debug/* ../script/`
+
+11. Go into the script folder with `cd ../script/`
+
+12. Create a python virtual environment with `python -m venv venv`
+
+13. Activate it by running `.\venv\Scripts\Activate.ps1`
+
+14. Install python requirements with `pip install -r requirements.txt`
+
+15. Finally run the CLI with `python chameleon_cli_main.py`
+
+To run again after installing, just do the following:
+
+1. Activate venv by running `.\venv\Scripts\Activate.ps1`
+
+2. Run the CLI with `python chameleon_cli_main.py`
+
+### Linux
+
+*Coming Soon*
+
+### MacOS
+
+*Coming Soon*
+
+## Usage
+
+When in the CLI, plug in your Chameleon and connect with `hw connect`. If autodetection fails, get the Serial Port used by your Chameleon and run `hw connect -p COM11` (Replace `COM11` with your serial port, on Linux it may be `/dev/ttyACM0`)
+
+### Common activities
+
+- Change slot: hw slot change -s [1-8]
+
+*More examples coming soon*
+
+### Available Commands
+
+In `()` is the argument description, `[]` are possible entries for that argument (eg `[1-8]`)
+
+| Command          | Arguments                                                                 | Description                               |
+|:----------------:|:-------------------------------------------------------------------------:|:-----------------------------------------:|
+| `hw factory_reset` | `--i-know-what-im-doing` (Make sure you really want to wipe your Chameleon) | Returns the Chameleon to factory settings |
+|                  |                                                                           |                                           |
+|                  |                                                                           |                                           |

docs/development.md

@@ -1,6 +1,6 @@
-# How to use the Firmware
+# Development
 
-In this file you can look up how to [install requirements](#Prerequisites-for-compiling), [edit](#Editing-the-code), [compile](#Compiling-the-code) and [debug](#Debugging-the-code) the code!
+In this file you can look up how to [install requirements](#Prerequisites-for-compiling), [edit](#Editing-the-code), [compile](#Compiling-the-code) and [debug](#Debugging-the-code) the firmware!
 
 ## Prerequisites for compiling
 
@@ -25,7 +25,7 @@ Moreover it does not contain the `gdb` debugger.
 * **Windows using Chocolatey:**
   * Open a PowerShell terminal with administrator privileges.
   * If not yet installed, run the following command to install Chocolatey:
-  ``` Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1')) ```
+    ``` Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1')) ```
   * In the same PowerShell terminal, run the following command to install Make using Chocolatey: `choco install make`
 * **macOS:**
   * Open a terminal.
@@ -35,10 +35,10 @@ Moreover it does not contain the `gdb` debugger.
 ### install nRF tools
 
 - Install nRF Util tool [nrfutil](https://www.nordicsemi.com/Products/Development-tools/nrf-util)
-    - Move it to a known path like `C:\nrfutil\` or `/usr/local/bin/`
-    - Add this path to the `PATH` Environment Variable if not yet there.
+  - Move it to a known path like `C:\nrfutil\` or `/usr/local/bin/`
+  - Add this path to the `PATH` Environment Variable if not yet there.
 - Install nRF Util packages:
-    - `nrfutil install completion device nrf5sdk-tools trace`
+  - `nrfutil install completion device nrf5sdk-tools trace`
 - Install [nRF Command Line Tools](https://www.nordicsemi.com/Products/Development-tools/nrf-command-line-tools/download) to get `nrfjprog`, `mergehex` etc.
 
 ### install programmer tools
@@ -46,23 +46,24 @@ Moreover it does not contain the `gdb` debugger.
 Depending on the hardware programmer you want to use, additional tools are needed.
 
 - If you are using a J-Link:
-    - Install [Segger J-Link Software](https://www.segger.com/downloads/jlink)
-    - alternatively, you can use openocd as described below
-    - Note: a JLink OB (or a STLink reflashed as a JLink OB) will not work on a nRF.
+  
+  - Install [Segger J-Link Software](https://www.segger.com/downloads/jlink)
+  - alternatively, you can use openocd as described below
+  - Note: a JLink OB (or a STLink reflashed as a JLink OB) will not work on a nRF.
 
 - If you are using a ST-Link V2:
-    - Install [openocd](https://openocd.org/pages/getting-openocd.html)
-    - If under Windows, install [ST-Link drivers](https://www.st.com/en/development-tools/stsw-link009.html), extract the zip and run `dpinst_amd64.exe`
-
+  
+  - Install [openocd](https://openocd.org/pages/getting-openocd.html)
+  - If under Windows, install [ST-Link drivers](https://www.st.com/en/development-tools/stsw-link009.html), extract the zip and run `dpinst_amd64.exe`
 
 ### configure the project
 
-  - Edit `Makefile.defs`:
-    - Change `GNU_INSTALL_ROOT` (path of previously installed Compiler `bin` folder)
-    - Change `GNU_VERSION` (Version of the installed Compiler) (FIXME: is it really used?)
-    - Change the other paths to match your system if needed
-    - Don't forget to remove the `#` in front of the changed lines
-  - Alternatively, if you are committing often code, it may be easier to leave `Makefile.defs` intact and to invoke `make` with the desired variables from a script, e.g. `make GNU_INSTALL_ROOT=../../../arm-gnu-toolchain-12.2.rel1-x86_64-arm-none-eabi/bin/`
+- Edit `Makefile.defs`:
+  - Change `GNU_INSTALL_ROOT` (path of previously installed Compiler `bin` folder)
+  - Change `GNU_VERSION` (Version of the installed Compiler) (FIXME: is it really used?)
+  - Change the other paths to match your system if needed
+  - Don't forget to remove the `#` in front of the changed lines
+- Alternatively, if you are committing often code, it may be easier to leave `Makefile.defs` intact and to invoke `make` with the desired variables from a script, e.g. `make GNU_INSTALL_ROOT=../../../arm-gnu-toolchain-12.2.rel1-x86_64-arm-none-eabi/bin/`
 
 ## Editing the code
 
@@ -74,11 +75,11 @@ install it!
   the [C++ Extension Pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools-extension-pack) in
   VS-Code.
 - Create a new IntelliSense Configuration:
-    - press F1 in VS-Code and enter `C/C++: Edit Configurations (UI)`
-    - Add a new Configuration and name it
-    - Specify your Compiler path (path of previously installed Compiler `bin` folder)
-    - Change IntelliSense mode to `gcc-arm (legacy)`
-    - Add include path `${workspaceFolder}/**`
+  - press F1 in VS-Code and enter `C/C++: Edit Configurations (UI)`
+  - Add a new Configuration and name it
+  - Specify your Compiler path (path of previously installed Compiler `bin` folder)
+  - Change IntelliSense mode to `gcc-arm (legacy)`
+  - Add include path `${workspaceFolder}/**`
 
 ## Compiling the code
 
@@ -86,6 +87,7 @@ install it!
 - Run `build.sh` or try to execute its steps manually if your platform is not yet properly supported. Feedback is always welcome.
 
 The script produces several images in `objects`.
+
 * `fullimage.hex` to be used with a programmer over the SWD pins
 * `dfu-app.zip` and `dfu-full.zip` to be used with DFU mode
 
@@ -94,6 +96,7 @@ The script produces several images in `objects`.
 If the bootloader and the SoftDevice are already properly installed on the Chameleon, you can reflash it directly over DFU.
 
 To set the device in DFU mode:
+
 * you can use the Python client and issue the command `hw dfu`
 * you can use the script `resource/tools/enter_dfu.py` that does exactly the same but may be easier to call from your scripts
 * you can unplug the device, wait for it to sleep, then press the button B and plug it. If the application is bogus, this is the only way.
@@ -115,6 +118,7 @@ Under Linux you can use the scripts `flash-dfu-app.sh` and `flash-dfu-full.sh`,
 Connect pins GND, SWC (swclk) and SWD (swdio) to your programmer.
 
 With a JLink and `nrfjprog`
+
 ```
 # application only:
 nrfjprog -f nrf52 --program objects/application.hex --sectorerase --verify --reset
@@ -123,6 +127,7 @@ nrfjprog -f nrf52 --program objects/fullimage.hex --sectorerase --verify --reset
 ```
 
 With a JLink and `openocd`
+
 ```
 # application only:
 openocd -f interface/jlink.cfg -f target/nrf52.cfg -c "program objects/application.hex verify reset ; shutdown"
@@ -144,6 +149,7 @@ openocd -f interface/stlink.cfg -f target/nrf52.cfg -c "program objects/fullimag
 If you are adventurous it is possible to flash the device over BLE (DFU mode).
 
 To put the device in DFU mode
+
 * you can use the Python client and issue the command `hw dfu` **TODO:** this will be possible only when the client will be able to work over BLE...
 * you can use the script `resource/tools/enter_dfu_over_ble.py`
 
@@ -208,10 +214,12 @@ Then use the official [nRF Device Firmware Update](https://www.nordicsemi.com/Pr
 ## Debugging the code with gdb and openocd
 
 See first if you can execute `arm-none-eabi-gdb` from the installed tools.
+
 * gcc-arm-none-eabi-10.3-2021.10 gdb requires `libncurses5`
 * arm-gnu-toolchain-12.2.rel1 gdb requires Python 3.8
 
 In case Python 3.8 is not available anymore on your distro, to install a local copy you can do
+
 ```
 wget https://www.python.org/ftp/python/3.8.17/Python-3.8.17.tgz
 tar zxvf Python-3.8.17.tgz
@@ -223,23 +231,29 @@ make install
 ```
 
 Connect openocd to the device with a JLink or a ST-Link V2
+
 ```
 openocd -f interface/jlink.cfg -f target/nrf52.cfg
 ```
+
 ```
 openocd -f interface/stlink.cfg -f target/nrf52.cfg
 ```
+
 Then run gdb as follows
 
 ```
 PYTHONHOME=~/opt/python-3.8.17/ arm-gnu-toolchain-12.2.rel1-x86_64-arm-none-eabi/bin/arm-none-eabi-gdb
 ```
+
 and tell gdb to connect to openocd
+
 ```
 target extended-remote localhost:3333
 ```
 
 ## BlackMagicProbe with RTT support, out of a ST-Link V2
+
 You can reflash a ST-Link V2 to use it as a BlackMagicProbe, to get support for RTT and see NRF_LOG messages.
 Some clones have only 64kb, this is too short.
 Even 128kb is too small when enabling RTT, but we can comment parts of the BMP source code.
@@ -248,11 +262,13 @@ Even 128kb is too small when enabling RTT, but we can comment parts of the BMP s
 git clone --recursive git@github.com:blackmagic-debug/stlink-tool.git
 ( cd stlink-tool && make )
 ```
+
 Then put the `stlink-tool` binary in your path.
 
 Get [BMP full sources](https://github.com/blackmagic-debug/blackmagic/releases)
 
 Comment out all probes except Nordic nrf51 in `src/target/cortexm.c` big switch for probes. It should remain
+
 ```c
     switch (t->designer_code) {
     case JEP106_MANUFACTURER_NORDIC:
@@ -260,13 +276,17 @@ Comment out all probes except Nordic nrf51 in `src/target/cortexm.c` big switch
         break;
     }
 ```
+
 ```
 make -j PROBE_HOST=stlink ST_BOOTLOADER=1 ENABLE_RTT=1
 ```
+
 Then flash the ST_Link V2
+
 ```
 stlink-tool src/blackmagic.bin
 ```
+
 See [src/platforms/stlink/README.md](https://github.com/blackmagic-debug/blackmagic/blob/main/src/platforms/stlink/README.md) for more details.
 Unplug/plug.  
 Every time you plug the ST-Link, you have to run `stlink-tool` to enable BMP.  
@@ -285,7 +305,9 @@ stlink-tool
 sleep 1
 screen /dev/ttyBmpTarg
 ```
+
 In another terminal
+
 ```
 $ arm-none-eabi-gdb
 (gdb) target extended-remote /dev/ttyBmpGdb
@@ -305,7 +327,9 @@ cf https://embeddedexplorer.com/nrf52-nrf-log-tutorial/
 ```
 JLinkExe -if SWD -device nrf52 -speed 4000 -autoconnect 1
 ```
+
 in a second terminal:
+
 ```
 JLinkRTTClient
 ```
@@ -318,5 +342,6 @@ UART works at 115200 bauds. E.g. one can use a FTDI dongle and `screen /dev/ttyU
 Contrary to RTT that needs to be activated by a JTAG probe, UART logs are immediately available.
 
 Limitations:
+
 * SWO pin is shared with... SWO so when e.g. reflashing the device, garbage may appear on the monitoring terminal.
 * SWO pin is also shared with the blue channel of the RGB slot LEDs, so faint blue may appear briefly when logs are sent and LED might not work properly when supposed to be blue.

docs/firmware.md

@@ -0,0 +1,115 @@
+# Firmware
+
+The Chameleon flash contains several parts: the bootloader and its settings, the application, the user data and the SoftDevice.
+
+NOTE: If you are a developer searching for the building instructions, look into [development](./development.md)
+
+## The Bootloader
+
+The bootloader is the lowest-level program running on your Chameleon. It is read-only and provides the DFU (**D**evice **F**irmware **U**pgrade) mode. The bootloader being read-only, it makes it really hard to brick your Chameleon. The flash also contains a special section to store bootloader settings required by the nRF to deal with upgrades. This is only a concern for developers.
+
+
+You enter DFU mode by of the following methods:
+
+1. Physical button
+
+- Disconnect the Chameleon and wait for it to enter sleep mode
+- Hold down the 🅑 button. If you are using Windows you have to wait about ~5s before next step.
+- Plug USB into a PC while still holding the button. If you are using Windows you have to wait about ~10s before next step.
+- Then release the 🅑 button
+
+2. From CLI
+
+- Execute the command `hw dfu`
+
+3. From GUI
+
+- Click on `Enter DFU mode`
+
+4. From Shell
+
+- Execute the script `resource/tools/enter_dfu.py`
+
+The device stays in DFU mode for ~30s.
+While in DFU mode waiting for the update, the LEDs 4 and 5 blink alternatively green 🟢🟢.
+You can then perform firmware upgrades either via a GUI or the command line:
+
+1. Download nRF Util from the [nRF website](https://www.nordicsemi.com/Products/Development-tools/nrf-util)
+
+2. Open a Command Line / Terminal on your PC
+
+3. Install the "device" toolkit by running `nrfutil install device`
+
+4. Download the Chameleon firmware from [GitHub](https://github.com/RfidResearchGroup/ChameleonUltra/releases). At the moment it is better to take the *Development release* but beware bugs can occur. Choose `ultra-dfu-app.zip` for the Ultra or the Devkit, and `lite-dfu-app.zip` for the Lite.
+
+5. Put your Chameleon into DFU mode and install the firmware with the following command: `nrfutil device program --firmware ultra-dfu-app.zip --traits nordicDfu` (keep in mind to change the filename if you are using a Lite).
+
+Step 5: Alternatively you can connect the Chameleon over USB and use the script `firmware/flash-dfu-app.sh` which will take care of flipping it into DFU mode and flashing it with the adequate firmware.
+
+While flashing firmware is in progress, the LEDs 4 and 5 should blink fast blue 🔵🔵 and the firmware update should be finished in a matter of seconds. Using DFU and performing a firmware update also helps recovering from most device-related issues.
+
+If LEDs 4 and 5 are flashing slow red 🔴🔴, it indicates an issue with DFU. Try to unplug and plug again or unplug and wait for it to timeout and try again the whole procedure.
+
+## The Application
+
+The application is the piece of software being loaded by the bootloader. It communicates with the client, emulates, reads and writes cards, drives the LEDs, handles buttons and much more. The application is also writable, it is the piece of software being updated via DFU.
+
+The communication with the application is either done via the CLI or a GUI. Communication can be done over USB or BLE (**B**luetooth **L**ow **E**nergy), although, at time of writing, only GUIs support BLE.
+
+On boot, the application starts in emulation mode, so it can emulate up to 8 HF tags and up to 8 LF tags (one slot can handle both a HF and a LF).
+
+The Chameleon can be awaken:
+
+- by pressing a button
+- when it comes close to a HF or LF field, *only if* a card corresponding to that field (HF/LF) is loaded into the active slot.
+
+The white LED labeled RF lights up when it detects a field, again only if the active slot supports it.
+
+In some situations, it can be cumbersome to wait for the boot-up animation. This is configurable, cf e.g. the CLI command `hw settings animation set -h`.
+
+On a new Chameleon (or after a factory reset), 3 slots are defined, slot 1 holding both a HF and a LF:
+
+- slot 1 LF: a EM4100 with UID `DEADBEEF88`
+- slot 1 HF: a MIFARE Classic 1k with UID `DEADBEEF`
+- slot 2 HF: a MIFARE Classic 1k with UID `DEADBEEF`
+- slot 3 LF: a EM4100 with UID `DEADBEEF88`
+
+When a slot is selected, the LED shows what type of card is loaded with the following color code:
+
+- 🟢 HF card loaded
+- 🔵 LF card loaded
+- 🔴 Both HF and LF loaded
+
+When a dual HF/LF slot is activated by an external field, it will turn green or blue according to the frequency.
+
+The application controls the buttons. The behavior of the buttons is customizable via the CLI or a GUI. The default behavior is the following:
+
+- 🅐 short press: Select previous slot
+
+- 🅑 short press: Select next slot
+
+- 🅐 long press: Copy LF or HF tag UID (only Ultra, not Lite)
+
+- 🅑 long press: Copy LF or HF tag UID (only Ultra, not Lite)
+
+*About UID copy*: the action depends on the current slot support. So to be able to copy an EM4100 LF tag, the slot must be configured firstly to emulate an EM4100 tag. And to be able to copy a HF 14a tag, the slot must be configured for the right type of HF tag. Only the UID will be copied, not the data.
+
+The Chameleon also shows the following LED effects:
+
+- Charging: 4 pulsing green lights
+
+- CLI / GUI connected over USB: Chasing LEDs in the color of the selected slot (left to right for slots 1-4 and right to left for slots 5-8).
+
+The device enters sleep mode after about 5s unless it is plugged in USB or if a client is connected over BLE. You can use the buttons to wake it up again. You can also press quickly a button during the sleep animation to keep the device awake.
+
+
+## The SoftDevice
+
+A [SoftDevice](https://infocenter.nordicsemi.com/index.jsp?topic=%2Fstruct_nrf52%2Fstruct%2Fnrf52_softdevices.html) is a precompiled and linked binary software implementing a wireless protocol developed by Nordic Semiconductor.
+
+We are using the [SoftDevice S140](https://infocenter.nordicsemi.com/index.jsp?topic=%2Fstruct_nrf52%2Fstruct%2Fnrf52_softdevices.html) which implements a BLE Central and Peripheral protocol stack solution.
+
+## The User Data
+
+The Chameleon has a reserved space of memory and flash where it stores application settings, active slot and slots configurations and data. This will not be overwritten by DFU updates and the data will only be reset by either issuing `hw factory_reset --i-know-what-im-doing` in the CLI or clicking `Factory reset` in a GUI.
+*Warning:* Settings and/or data might be reset to defaults if you downgrade the firmware version up to a version not supporting the newer format.

docs/gui.md

@@ -0,0 +1,7 @@
+# GUIs
+
+There are multiple GUIs to control your Chameleon, two are featured in this documentation:
+
+- [Chameleon Ultra GUI](./chameleonultragui.md) ([github](https://github.com/GameTec-live/ChameleonUltraGUI))
+
+- Mtools (No Info Yet)

docs/hardware.md

@@ -0,0 +1,51 @@
+# Hardware
+
+The Chameleon comes in 3 Hardware variants, the Ultra, the Lite and the Devkit.
+
+## The Ultra
+
+The Chameleon Ultra comes in a black box with gold printing. This box has the following dimensions: 9.5 cm x 5.5 cm x 3.5 cm
+
+![box.png](./images/ultra-box.jpg)
+
+The Box contains a foam pad, a USB cable that has a removable end to convert it to USB-C, a Proxgrind 3.5 hex screwdriver, 2 replacement screws and a keychain and the device itself.
+
+![box-contents.jpg](./images/ultra-box-contents.jpg)
+
+The device itself features 4 screws holding it together, 2 buttons labeled `A` and `B`.  The device consists of 2 PCBs (**P**rinted **C**ircuit **B**oards) and a plastic spacer, one contains the Electronic and the HF (**H**igh **F**requency), 13.56 MHz, antenna as well as the 8 LEDs indicating which slot is currently active and the other board features the Chameleon Ultra text, the screws and the LF (**L**ow **F**requency), 125KHz, antenna. The plastic spacer houses the battery as well as the ferrite pad which enables HF and LF emulation at the same time. It also has has the USB-C charging and data port and a hole for inserting the keychain loop. The Chameleon Ultra dimensions are: 2.4cm x 4cm x 8mm 
+
+![ultra.png](./images/ultra.jpg)
+
+## The Lite
+
+The Chameleon Lite comes in a white box with blue printing. This box has the following dimensions: 9.5 cm x 6 cm x 3.5 cm
+
+![lite-box.jpg](./images/lite-box.jpg)
+
+The Box contains a foam pad, a USB cable that has a removable end to convert it to USB-C and the device itself.
+
+![lite-box.-contents.jpg](./images/lite-box-contents.jpg)
+
+The device itself features 2 buttons labeled with arrows. The device consists of one PCB in a blue plastic housing. This one PCB contains the electronics and the HF antenna as well as the 8 LEDs indicating which slot is currently active, and the USB-C port. The LF antenna is glued onto the back of the PCB and is visible through the housing. The battery is soldered in place and the housing is held together by thin fragile pins which are easy to snap. It is not designed to be disassembled. The keychain loop is also relatively fragile, so be careful. The Chameleon Lites dimensions are: 3.6 cm x 6.1 cm x 0.8 cm
+
+![lite.jpg](./images/lite.jpg)
+
+## The Devkit
+
+Just like the Chameleon Ultra, the Devkit comes in a black box with gold printing. This box has the following dimensions: 12 cm x  8 cm x 3.5 cm
+
+![devkit-box.jpg](./images/devkit-box.jpg)
+
+Again, just like the lite, the box contains a foam pad, a USB cable that has a removable end to convert it to USB-C and the device itself.
+
+![devkit-box-contents.jpg](./images/devkit-box-contents.jpg)
+
+The device itself features 2 buttons labeled `A` and `B`. The device is made of only one PCB without a case. At the bottom of this PCB both the HF and LF coils are found. Because it is a Devkit, this Chameleon has its SWD (**S**ingle **W**ire **D**ebug) port and some testpoints exposed. (In the photos below, a pinheader is already soldered into the SWD port, this is not the case from factory) The Chameleon Devkit dimensions are:  5.3 cm x 8.5 cm x 1.1 cm (including rubber feet, battery and buttons. PCB thickness: 0,16 cm)
+
+![devkit.jpg](./images/devkit.jpg)
+
+## What is the difference between the Lite and the Ultra/DevKit?
+
+The Chameleon Ultra as well as the Devkit contain a second chip called [MFRC522 ](https://www.nxp.com/docs/en/data-sheet/MFRC522.pdf). This chip allows the Chameleon to read and write to HF 14a tags. The Chameleon Lite does not contain this chip and therefore cannot read and write HF tags, it can only simulate some. The Chameleon Lite also swaps the big LIPO (**LI**thium **PO**lymer) battery with a smaller buttoncell. The Devkit is a Chameleon Ultra on a bigger PCB and with a bigger battery and some component differences such as a mechanical relay but which should not make any practical difference.
+
+# 

docs/home.md

@@ -0,0 +1,21 @@
+# Chameleon Ultra Guide
+
+This guides goal is to guide you through setting up and using your Chameleon Ultra and Lite.
+
+This Guide is split up into multiple "subguides":
+
+- ["Hardware"](./hardware.md) Learn to know the hardware of your Chameleon
+
+- ["Firmware"](./firmware.md) Your Chameleon runs a firmware, learn what it can do and how to use it
+
+- ["CLI"](./cli.md) The official way to control your Chameleon is via the **C**ommand **L**ine **I**nterface (CLI) . Learn how to install and master the CLI.
+
+- ["GUIs"](./gui.md) Some people also develop **G**raphical **U**ser **I**nterfaces (GUIs), theese may be a good start for people that do not want to deal with a CLI.
+
+- ["Troubleshooting"](./troubleshooting.md) For when things go wrong, here are some common tips to maybe fix whatever issue you might have.
+
+- ["FAQ"](./faq.md) Frequently asked questions, if you have a question, it might already be awnsered here.
+
+- ["Quickstart"](./quickstart.md) for the impatient people to just get you up and running with anything.
+
+- ["Development"](./development.md) for all developers. This covers how to build firmware from source and set up a development enviroment.