cli: color help and add epilog example

- visually closer to pm3 (differenciate groups and commands)
- "dumphelp" allows to quickly dump all cmds and their options
- now all commands support '-h', so e.g. `hw settings store -h` will print help instead of storing
- no more command description in decorator, it is now taken from argparse description

.editorconfig

@@ -0,0 +1,3 @@
+[*.{c,h,py}]
+indent_style = space
+indent_size = 4

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,50 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+***Things to try before submitting a bug report***
+
+* read the [troubleshooting guide](https://github.com/RfidResearchGroup/ChameleonUltra/blob/main/docs/troubleshooting.md)
+* check existing [issues](https://github.com/RfidResearchGroup/ChameleonUltra/issues)
+* use the latest firmware and CLI
+* for issues specific to another client than the Python CLI, use the corresponding issue tracker. E.g. [here](https://github.com/GameTec-live/ChameleonUltraGUI/issues) for the ChameleonUltraGUI
+
+***Compilation problems***
+Try compiling with verbose. Use `make VERBOSE=1` for the firmware and the software/src tools.
+Include the verbose compilation logs.
+
+***flashing problems***
+Have you followed the instructions properly?
+
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior.  
+Explain it as you would do to someone not familiar with the problematic feature.  
+What is the abnormal behavior you observed?  
+E.g.
+1. Connect '....'
+2. Execute '....'
+3. Press button '....'
+4. See error '....'
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem. For console text and logs, better to dump them as text than image. Attach files if too long.
+
+**Host (please complete the following information):**
+ - OS and version
+ - for compilation issues, the toolchain version
+ - inside CLI run `hw version` and paste the output here
+ 
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Official channels Chameleon Ultra Community
+    url: https://github.com/RfidResearchGroup/ChameleonUltra#official-channels
+    about: Got questions? Ask in *official channels*, not in an issue

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,25 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: "[idea]"
+labels: Request, enhancement
+assignees: ''
+
+---
+
+Please keep in mind we are still at the infancy of the project and a lot has still to be done.
+
+Have first a look at the [Whitepaper](https://github.com/RfidResearchGroup/ChameleonUltra/blob/main/docs/technical_whitepaper.md), the Wiki [Roadmap](https://github.com/RfidResearchGroup/ChameleonUltra/wiki/Public-Roadmap) and [Wishlist](https://github.com/RfidResearchGroup/ChameleonUltra/wiki/Wishlist).  
+No need for creating issues for well known missing supports, we are already aware :)
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/workflows/build_client.yml

@@ -0,0 +1,69 @@
+# This is just a placeholder while the whole PyInstaller thing gets figured out
+name: Client build
+
+on:
+  workflow_call:
+    inputs:
+      checkout-sha:
+        required: false
+        type: string
+
+jobs:
+  build_client:
+    name: Build client
+    strategy:
+      matrix:
+        include: 
+          - name: windows
+            os: windows-latest
+            pre_command: |
+              ? .
+            bundle_command: |
+              Compress-Archive -Path software\dist\* -DestinationPath client-windows.zip
+          - name: linux
+            os: ubuntu-latest
+            pre_command: |
+              true
+            bundle_command: |
+              (cd software/dist && zip -r "$OLDPWD/client-linux.zip" .)
+          - name: macos
+            os: macos-latest
+            pre_command: |
+              true
+            bundle_command: |
+              (cd software/dist && zip -r "$OLDPWD/client-macos.zip" .)
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v3
+        with:
+          ref: ${{ inputs.checkout-sha == null && github.sha || inputs.checkout-sha }}
+      - name: Install PyInstaller and client dependencies
+        run: |
+          pip3 install pyinstaller
+          pip3 install -r software/script/requirements.txt
+      - name: Run OS specific setup
+        run: ${{ matrix.pre_command }}
+      - name: Compile native code
+        run: |
+          cd software/src
+          mkdir out
+          cd out
+          cmake ..
+          cmake --build . --config Release
+      - name: Run PyInstaller
+        run: |
+          cd software
+          pyinstaller pyinstaller.spec
+      - name: Upload built client
+        uses: actions/upload-artifact@v3
+        with:
+          name: client-${{ matrix.name }}
+          path: software/dist/*
+      - name: Zip up client for release
+        run: ${{ matrix.bundle_command }}
+      - name: Upload release artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: release-artifacts
+          path: client-${{ matrix.name }}.zip

.github/workflows/build_firmware.yml

@@ -0,0 +1,92 @@
+name: Firmware build
+
+on:
+  workflow_call:
+    inputs:
+      checkout-sha:
+        required: false
+        type: string
+
+jobs:
+  build_fw_builder:
+    name: Build and push fw-builder Docker image
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+    outputs:
+      image_hash: ${{ steps.push.outputs.digest }}
+    steps:
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v2
+      - name: Check out the repo
+        uses: actions/checkout@v3
+        with:
+          ref: ${{ inputs.checkout-sha == null && github.sha || inputs.checkout-sha }}
+          fetch-depth: 0
+      - name: ghcr.io login
+        uses: docker/login-action@v2
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v4
+        with:
+          images: ghcr.io/${{ github.repository }}-fw-builder
+      - name: Build and push Docker images
+        id: push
+        uses: docker/build-push-action@v4
+        with:
+          context: firmware
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+  build_fw:
+    name: Build firmware
+    runs-on: ubuntu-latest
+    needs: build_fw_builder
+    strategy:
+      matrix:
+        device_type: [ultra, lite]
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v3
+        with:
+          ref: ${{ inputs.checkout-sha == null && github.sha || inputs.checkout-sha }}
+          fetch-depth: 0
+      - name: Build firmware
+        env:
+          repo: ${{ github.repository }}
+        run: |
+          docker run --rm -v ${PWD}:/workdir -e CURRENT_DEVICE_TYPE=${{ matrix.device_type }} ghcr.io/${repo,,}-fw-builder@${{ needs.build_fw_builder.outputs.image_hash }} firmware/build.sh
+      - name: Upload built binaries
+        uses: actions/upload-artifact@v3
+        with:
+          name: ${{ matrix.device_type }}-firmware
+          path: firmware/objects/*.hex
+      - name: Unzip dfu images
+        run: |
+          sudo chown -R $USER:$USER firmware/objects
+          mkdir firmware/objects/${{ matrix.device_type }}-dfu-app
+          mkdir firmware/objects/${{ matrix.device_type }}-dfu-full
+          unzip firmware/objects/${{ matrix.device_type }}-dfu-app.zip -d firmware/objects/${{ matrix.device_type }}-dfu-app
+          unzip firmware/objects/${{ matrix.device_type }}-dfu-full.zip -d firmware/objects/${{ matrix.device_type }}-dfu-full
+      - name: Upload dfu app image
+        uses: actions/upload-artifact@v3
+        with:
+          name: ${{ matrix.device_type }}-dfu-app
+          path: firmware/objects/${{ matrix.device_type }}-dfu-app/*
+      - name: Upload dfu full image
+        uses: actions/upload-artifact@v3
+        with:
+          name: ${{ matrix.device_type }}-dfu-full
+          path: firmware/objects/${{ matrix.device_type }}-dfu-full/*
+      - name: Upload release artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: release-artifacts
+          path: firmware/objects/*.zip

.github/workflows/changelog_reminder.yml

@@ -0,0 +1,15 @@
+on: pull_request_target
+name: Changelog Reminder
+jobs:
+  remind:
+    name: Changelog Reminder
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@master
+    - name: Changelog Reminder
+      uses: peterjgrainger/action-changelog-reminder@v1.2.0
+      with:
+        changelog_regex: 'CHANGELOG.md'
+        customPrMessage: 'You are welcome to add an entry to the CHANGELOG.md as well'
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/on_pr.yml

@@ -0,0 +1,44 @@
+name: PR handler
+on:
+  pull_request_target:
+
+jobs:
+  firmware_pipeline:
+    name: Build Firmware
+    permissions:
+      packages: write
+      contents: read
+    uses: ./.github/workflows/build_firmware.yml
+    with:
+      checkout-sha: "${{ github.event.pull_request.merge_commit_sha }}"
+  client_pipeline:
+    name: Build Firmware
+    uses: ./.github/workflows/build_client.yml
+    with:
+      checkout-sha: "${{ github.event.pull_request.merge_commit_sha }}"
+  comment:
+    runs-on: ubuntu-latest
+    name: Comment on PR
+    needs:
+      - firmware_pipeline
+      - client_pipeline
+    permissions:
+      pull-requests: write
+    steps:
+      - uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          message: |
+            # Built artifacts for commit ${{ github.event.pull_request.head.sha }}
+
+            ## Firmware
+
+            - [Ultra APP DFU Package](https://nightly.link/${{ github.repository }}/actions/runs/${{ github.run_id }}/ultra-dfu-app.zip)
+            - [Ultra binaries](https://nightly.link/${{ github.repository }}/actions/runs/${{ github.run_id }}/ultra-firmware.zip)
+            - [Lite APP DFU Package](https://nightly.link/${{ github.repository }}/actions/runs/${{ github.run_id }}/lite-dfu-app.zip)
+            - [Lite binaries](https://nightly.link/${{ github.repository }}/actions/runs/${{ github.run_id }}/lite-firmware.zip)
+
+            ## Client
+
+            - [Linux](https://nightly.link/${{ github.repository }}/actions/runs/${{ github.run_id }}/client-linux.zip)
+            - [macOS](https://nightly.link/${{ github.repository }}/actions/runs/${{ github.run_id }}/client-macos.zip)
+            - [Windows](https://nightly.link/${{ github.repository }}/actions/runs/${{ github.run_id }}/client-windows.zip)

.github/workflows/on_push.yml

@@ -0,0 +1,80 @@
+name: Push handler
+
+on:
+  push:
+
+jobs:
+  firmware_pipeline:
+    name: Build Firmware
+    permissions:
+      packages: write
+      contents: read
+    uses: ./.github/workflows/build_firmware.yml
+  client_pipeline:
+    name: Build Firmware
+    uses: ./.github/workflows/build_client.yml
+  create_dev_release:
+    permissions:
+      contents: write
+    name: Create dev pre-release with artifacts
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    needs:
+      - firmware_pipeline
+      - client_pipeline
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v3
+      - name: Download release artifacts
+        uses: actions/download-artifact@v3
+        with:
+          name: release-artifacts
+          path: release-artifacts
+      - name: Upload to dev release
+        uses: softprops/action-gh-release@v1
+        with:
+          body: |
+            Auto-Generated DFU packages from latest `main` commit.
+            For development purposes only. 
+            These are not tested, here be dragons.
+            Built from commit ${{ github.sha }}
+          tag_name: dev
+          name: Development release
+          draft: false
+          prerelease: true
+          target_commitish: ${{ github.sha }}
+          generate_release_notes: true
+          files: release-artifacts/*
+      - name: Fix up release tag
+        run: |
+          git tag -f dev
+          git push --tags -f
+  create_release:
+    permissions:
+      contents: write
+    name: Create tagged release with artifacts
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs:
+      - firmware_pipeline
+      - client_pipeline
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v3
+      - name: Download release artifacts
+        uses: actions/download-artifact@v3
+        with:
+          name: release-artifacts
+          path: release-artifacts
+      - name: Upload to tagged release
+        uses: softprops/action-gh-release@v1
+        with:
+          body: |
+            Auto-Generated DFU packages for Release ${{ github.ref_name }}
+            Built from commit ${{ github.sha }}
+          name: Release ${{ github.ref_name }}
+          draft: false
+          target_commitish: ${{ github.sha }}
+          generate_release_notes: true
+          append_body: true
+          files: release-artifacts/*

.gitignore

@@ -1,3 +1,5 @@
 .idea/
 .vscode/
-.vs/
+.vs/
+
+.DS_Store

AUTHORS.md

@@ -0,0 +1,3 @@
+Copyright of each contribution is tracked by the Git history.
+See the output of `git shortlog -nse` for a full list or `git log --pretty=short --follow <path/to/sourcefile> |git shortlog -ne` to track a specific file.
+See also [the Contributors page on Github](https://github.com/RfidResearchGroup/ChameleonUltra/graphs/contributors).

CHANGELOG.md

@@ -0,0 +1,110 @@
+# Change Log
+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 colors to CLI help (@doegox)
+ - Changed massively CLI, cf https://github.com/RfidResearchGroup/ChameleonUltra/issues/164#issue-1930580576 (@doegox)
+ - Changed CLI help: lists display and now all commands support `-h` (@doegox)
+ - Added button action to show battery level (@doegox)
+ - Added GUI Page docs (@GameTec-live)
+ - Changed CLI threads polling into blocking reads, to reduce CPU usage (@doegox)
+ - Added support for timestamped comments in CLI via `rem`, `;`, `%` or `#` (@doegox)
+ - Fixed watchdog trigger during `hw factory_reset` (@doegox)
+ - Added PyInstaller support for CLI client (@augustozanellato)
+
+## [v2.0.0][2023-09-26]
+ - Added `hw slot nick delete` and DELETE_SLOT_TAG_NICK (@doegox)
+ - Changed APP_FW_VER now deduced from git tag vx.y.z (@doegox)
+ - Changed initial button wakeup from 4 to 8 seconds (@aramova)
+ - Added MIFARE Ultralight reading features (@FlUxIuS & @doegox)
+ - Fixed MF1 write mode SHADOW was not preserved properly (@doegox)
+ - Changed field LED now active also in reader mode to indicate that reader is powering the field (@doegox)
+ - Changed slot enabled logic: now we have separate enabled_hf and enabled_lf, changed GET_ENABLED_SLOTS and SET_SLOT_ENABLE (@doegox)
+ - Changed tag type enum to be ready for new types, changed stored slotConfig and GET_SLOT_INFO (@doegox)
+ - Added HF14A_RAW and its support in `hf 14a raw` (@xianglin1998)
+ - Removed MF1_DETECT_DARKSIDE (@doegox)
+ - Added MF1_STATIC_NESTED_ACQUIRE and its support in `hf mf nested` (@xianglin1998)
+ - Changed `hf 14a scan`: Automatically send RATS to 14443-4a tags (@augustozanellato)
+ - Changed Darkside: use LEDs for visual feedback of attack progression (@doegox)
+ - Changed Darkside: longer RF field off for reset and longer CLI timeout (@doegox)
+ - Fixed Darkside: parity byte-to-array bug made it low probability to succeed (@doegox)
+ - Changed `hw detection decrypt` show progression and remove duplicate keys (@doegox)
+ - Changed dynamic cmd_map_init() by static cmd_map initialization (@doegox)
+ - Changed `hf slot list` to add clarity and colors (@doegox)
+ - Changed `hf mf sim` and `hf mf info` to support ATS (still to be used in actual emulation) (@doegox)
+ - Changed `hf mf eload` and `hf mf eread`: uploads/downloads are now 30x faster (@doegox)
+ - Changed CLI HF14AInfo logic merged inside HF14AScan for more consistent display of the results (@doegox)
+ - Added guessed type information for NXP tags, and reorganization of HF information part. (@FlUxIuS)
+ - Changed `hw raw` to detail status message (@doegox)
+ - Changed CLI to query capabilities on connect, not on every single command if device does not support get_device_capabilities (@doegox)
+ - Changed CLI to not instanciate ChameleonCMD on every single command (@doegox)
+ - Changed massively the protocol and its handlers for more consistency and easier maintenance and future dev (@doegox)
+ - Added `hf settings blepair` command to get and set ble pairing enable state, and default disable ble pair (@xianglin1998)
+ - Added `hf mf info` command to get UID/SAK/ATQA from slot (@Foxushka)
+ - Added `hw raw` to send raw command to Chameleon (@Foxushka)
+ - Added command to fetch all available commands from Chameleon and test if Chameleon supports it (@Foxushka)
+ - Fixed ChameleonLite emulation bug (@spp2000)
+ - Fixed MFC emulation issues with OEM readers, also temporarily disabling NFC_MF1_FAST_SIM (@xianglin1998)
+ - Fixed Chameleon crash during BLE pairing (@Foxushka)
+ - Fixed CLI takes into account Lite refusing to enter Reader mode (@doegox)
+ - Added BLE Security support (@xianglin1998)
+ - Added `hw settings blekey` to get and set ble connect key (@xianglin1998)
+ - Added `hw ble bonds clear` to delete all ble bonds (@xianglin1998)
+ - Fixed argument completion bug inserting additional hyphens (@szymex73)
+ - Fixed device address not the same within app (@taichunmin)
+ - 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)
+ - Changed 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 information (@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)
+ - Fixed SDK NFC IRQ handler busy loop (@doegox)
+ - Added `hf mf eread` to download slot dump to file (@domints)
+ - Added `lf em sim get` and old `lf em sim` is now `lf em sim set` (@domints)
+ - Changed MF1 command ids (@domints)
+ - Changed nonce randomness on nested auth for hardnested attack (@Foxushka)
+ - Added commands to configure MF1 emulation magic modes and more (@Foxushka)
+ - Added `hw factory_reset` to wipe user data (@augustozanellato)
+ - Changed slot nickname encoding gbk -> utf8 (@doegox)
+ - Added 5-second watchdog (@doegox)
+ - Added option to enable NRF_LOG UART on SWO pin (@doegox)
+ - Added `hw slot list` (@Foxushka)
+ - Added `hw version` (@nemanjan00 and @augustozanellato)
+ - Fixed data sanity check in MF1 emulation (@sgnusov)
+ - Fixed settings/dumps/nicks data corruption in flash (@doegox)
+ - Fixed slot LED on button wake-up (@doegox)
+ - Added support for init, reset and migrate settings (@augustozanellato)
+ - Added support to save settings in flash (@domints)
+ - Added `hw settings animation` to configure startup animation (@domints)
+ - Fixed compilation warnings from SDK (@doegox)
+ - Changed TagSenseType, TagSpecificType and SlotNumber enums (@F9Alejandro and @doegox)
+ - Added support for 7-byte UID MF1 emulation (@xianglin1998)
+ - Added high perf MF1 emulation (@xianglin1998)
+ - Added udev rules file (@iceman1001)
+ - Added documentation to use BlackMagicProbe out of ST-Link and show RTT NRF_LOG (@doegox)
+ - Added `hw chipid` and `hw address` (@gentilkiwi)
+ - Added helper scripts to enter DFU from USB or BLE and flash over DFU (@doegox)
+ - Fixed recv thread exception after `hw dfu` (@doegox)
+ - Fixed entering sleep after BLE disconnection (@doegox)
+ - Added ChameleonLite and ChameleonUltra hardware resources (@xianglin1998)
+ - Added NTAG21x emulation support (@ca1e)
+ - Fixed LF EM410x emulation (@doegox)
+ - Added automatic file format detection in `hf mf eload` (@GameTec-live)
+ - Fixed CLI exit exception (@doegox)
+ - Added CI pipeline, producing DFU packages (@augustozanellato)
+ - Added docker toolchain (@augustozanellato)
+ - Added automatic port detection (@GameTec-live)
+ - Added GET_MF1_DETECTION_STATUS (@Foxushka)
+ - Fixed compilation errors with GCC 12 (@Foxushka)
+ - Added documentation for JLink (@xianglin1998)
+ - Added support for ST-Link and debugging documentation (@derGraph)
+
+## [v1.0][2023-06-06]

How_to_use_Firmware.md

@@ -1,40 +0,0 @@
-# How to use the Firmware
-In this file you can look up how to [edit](#Editing-the-code), [compile](#Compiling-the-code) and [debug](#Debugging-the-code) the code!
-
-## Editing the code
-We are using [Visual Studio Code](https://code.visualstudio.com/download) to edit this project! Simply download and install it!
- - Install the [ARM-GCC](https://mynewt.apache.org/latest/get_started/native_install/cross_tools.html) version [9.3.1 Compiler](https://developer.arm.com/downloads/-/gnu-rm) and remember the path where you installed it.
- - Install the [C++ Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) 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}/**`
-## Compiling the code
- - Install the compiler (for instructions have a look at [Editing the code](#Editing-the-code))
- - Edit Makefile.defs:
-	- Change `GNU_INSTALL_ROOT`(path of previously installed Compiler `bin` folder)
-	- Change `GNU_VERSION` (Version of the installed Compiler)
-	- Don't forget to remove the `#` in front of the changed lines
-- Install make
-	- **Ubuntu:**  
-		- Open a terminal.
-		- Run the following command to install Make: `sudo apt-get install build-essential`
-	- **Windows using Chocolatey:**  
-	  - Install Chocolatey: 
-		  - Open a PowerShell terminal with administrator privileges. 
-		   - 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')) ``` 
-	  - Install Make:
-	    - In the same PowerShell terminal, run the following command to install Make using Chocolatey: `choco install make`
-	- **macOS:** 
-	  - Open a terminal.
-	  - Install Homebrew package manager by running the following command: `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`
-	  - Once Homebrew is installed, run the following command to install Make: `brew install make`
-- go into folder and run `make`
-
-## Debugging the code
-- Install [openocd](https://mynewt.apache.org/latest/get_started/native_install/cross_tools.html)
-- Install [Cortex-Debug](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug) VS-Code Extension
-- MORE INFO ADDED LATER

README.md

@@ -1,219 +1,57 @@
-[nrf52_nfc_module_doc]: https://infocenter.nordicsemi.com/index.jsp?topic=%2Fcom.nordic.infocenter.nrf52832.ps.v1.1%2Fnfc.html
+![logo](docs/images/ultra-logo.png)
 
-[nxp_rc522_datasheet]: https://www.nxp.com/docs/en/data-sheet/MFRC522.pdf
+![ultra picture](docs/images/ultra-overview.png)
 
-![alt text](https://github.com/RfidResearchGroup/ChameleonUltra/blob/main/resource/picture/Header.png)
+# ChameleonUltra Authorized Distributors
 
-# ChameleonUltra
+Europe: [Lab401](https://lab401.com/)
 
-Why not keep using ATxmega128?
-First of all, it is difficult to buy chips because the lead time for the main chip is too long, and because the price
-has skyrocketed. Secondly, because the interaction speed of the ATxmega simulation is slow, the decryption performance
-of the READER mode cannot meet the needs, and the low-frequency function cannot be added, so we have been trying to
-upgrade it, such as using the latest ARM to replace the AVR framework, and the performance will definitely be greatly
-improved.
+United States: [Hackerwarehouse](https://hackerwarehouse.com/)
 
-# Why NRF52840?
+Anywhere else: [Sneaktechnology](https://sneaktechnology.com) / [Aliexpress by RRG](https://proxgrind.aliexpress.com/store/1101312023)
 
-NRF52840 has a built-in NFC Tag-A module, but no one seems to care about it. After playing with HydraNFC's TRF7970A and
-FlipperZero's ST25R3916, the developers found that they can only simulate MIFARE UID. I accidentally tested the NFC of
-52840, and found that it is not only surprisingly easy to simulate a complete MIFARE card, but also has very good
-simulation performance, friendly data flow interaction, and very fast response, unlike the former which is limited by
-the SPI bus clock rate. We also found that it has ultra-low power consumption, ultra-small size, 256kb/1M large RAM and
-FLASH, also has BLE5.0 and USB2.0 FS, super CotexM4F, most importantly, he is very cheap! This is undoubtedly a treasure
-discovery for us!
+# What is it and how to use ?
 
-Below we will explain in detail how we exploited the performance of the NRF52840, and what seemingly impossible
-functions have been realized with it!
+Read the [available documentation](docs/README.md).
 
-# Supported functions
+# Public Roadmap with reference to [Here](https://github.com/RfidResearchGroup/ChameleonUltra/wiki/Public-Roadmap)
 
-## High Frequency Attack
+Table for future functionality progress
+---------------------------------
 
-| Attack Type  |   Tag Type    | Whether the hardware supports | Does the software support | Whether the application layer supports |                    Note |
-|--------------|:-------------:|------------------------------:|---------------------------|:--------------------------------------:|------------------------:|
-| Sniffing     |      No       |                            No | No                        |                   No                   |                         |
-| MFKEY32 V2   | MifareClassic |                       Support | Support                   |                Support                 | MifareClassic Detection |
-| Darkside     | MifareClassic |                       Support | Support                   |                Support                 |    Encrypted 4 bit NAck |
-| Nested       | MifareClassic |                       Support | Support                   |                Support                 |    PRNG(Distance guess) |
-| StaticNested | MifareClassic |                       Support | Support                   |          Not yet implemented           |  PRNG(2NT Fast Decrypt) |
-| HardNested   | MifareClassic |                       Support | Support                   |          Not yet implemented           |                      No |
-| Relay attack |   ISO14443A   |                       Support | Support                   |          Not yet implemented           |                      No |
+|No.|Functionality to achieve| Date | In Progress / Achieved ? | Contributors | RRG will reward |
+|:--------------:|:--------------:|:--------:|:------------:|:------------:|:------------:|
+|1| Adding DESfire Support|28/09/2023|:--------------:|:--------------:|:------------:|
+|2| Adding Indala Emulation|28/09/2023|:--------------:|:--------------:|:------------:|
+|3| Adding HID Prox 26 bit Emulation|28/09/2023|:--------------:|:--------------:|:------------:|
+|4| Adding custom keys for t5577 read|28/09/2023|:------------:|:------------:|:------------:|
+|5|:--------------:|:--------------:|:------------:|:------------:|:------------:|
+|6|:--------------:|:--------------:|:------------:|:------------:|:------------:|
+|7|:--------------:|:--------------:|:------------:|:------------:|:------------:|
+|8|:--------------:|:--------------:|:------------:|:------------:|:------------:|
+|9|:--------------:|:--------------:|:------------:|:------------:|:------------:|
+|10|:--------------:|:--------------:|:------------:|:------------:|:------------:|
+|11|:--------------:|:--------------:|:------------:|:------------:|:------------:|
+|12|:--------------:|:--------------:|:------------:|:------------:|:------------:|
+|13|:--------------:|:--------------:|:------------:|:------------:|:------------:|
+|14|:--------------:|:--------------:|:------------:|:------------:|:------------:|
 
-## High Frequency Simulation
+# Compatible applications
 
-| Card Type                     |    Encoding Type     | Whether the hardware supports | Does the software support | Whether the application layer supports |                                     Note |
-|-------------------------------|:--------------------:|------------------------------:|---------------------------|:--------------------------------------:|-----------------------------------------:|
-| Non <13.56MHz or ISO14443A>   |          No          |                            No | No                        |                   No                   | [NRF52 NFC Module][nrf52_nfc_module_doc] |
-| NTAG 21x (210-218)            | ISO14443A/106 kbit/s |                       Support | Support                   |          Not yet implemented           |                                          |
-| Mifare Ultralight             | ISO14443A/106 kbit/s |                       Support | Support                   |          Not yet implemented           |                                          |
-| Mifare Ultralight Ev1         | ISO14443A/106 kbit/s |                       Support | Support                   |          Not yet implemented           |                                          |
-| Mifare Ultralight C           | ISO14443A/106 kbit/s |                       Support | Support                   |          Not yet implemented           |                                          |
-| MifareClassic1K/2K/4K (4B/7B) | ISO14443A/106 kbit/s |                       Support | Support                   |                Support                 |                                          |
-| Mifare DESFire                | ISO14443A High Rate  |       Only supported Low rate | Only supported Low rate   |          Not yet implemented           |                                          |
-| Mifare DESFire EV1            | ISO14443A High rate  |       Only supported Low rate | Only supported Low rate   |          Not yet implemented           |                      Backward compatible |
-| Mifare DESFire EV2            | ISO14443A High rate  |       Only supported Low rate | Only supported Low rate   |          Not yet implemented           |                                          |
-| Mifare PLUS                   | ISO14443A High rate  |       Only supported Low rate | Only supported Low rate   |          Not yet implemented           |                                          |
+* [ChameleonUltraGUI](https://github.com/GameTec-live/ChameleonUltraGUI)
 
-## High Frequency Reader
+# Videos
 
-| Card Type                     |    Encoding Type     |                Whether the hardware supports | Does the software support                    | Whether the application layer supports |                                       Note |
-|-------------------------------|:--------------------:|---------------------------------------------:|----------------------------------------------|:--------------------------------------:|-------------------------------------------:|
-| Non <13.56MHz or ISO14443A>   |          No          |                                           No | No                                           |                   No                   | [NXP RC522 Datasheet][nxp_rc522_datasheet] |
-| NTAG 21x (210-218)            | ISO14443A/106 kbit/s |                                      Support | Support                                      |          Not yet implemented           |                                            |
-| Mifare Ultralight             | ISO14443A/106 kbit/s |                                      Support | Support                                      |          Not yet implemented           |                                            |
-| Mifare Ultralight Ev1         | ISO14443A/106 kbit/s |                                      Support | Support                                      |          Not yet implemented           |                                            |
-| Mifare Ultralight C           | ISO14443A/106 kbit/s |                                      Support | Support                                      |          Not yet implemented           |                                            |
-| MifareClassic1K/2K/4K (4B/7B) | ISO14443A/106 kbit/s |                                      Support | Support                                      |                Support                 |                                            |
-| Mifare DESFire                | ISO14443A High Rate  | Supports low rates, or possibly higher rates | Supports low rates, or possibly higher rates |          Not yet implemented           |                                            |
-| Mifare DESFire EV1            | ISO14443A High rate  | Supports low rates, or possibly higher rates | Supports low rates, or possibly higher rates |          Not yet implemented           |                        Backward compatible |
-| Mifare DESFire EV2            | ISO14443A High rate  | Supports low rates, or possibly higher rates | Supports low rates, or possibly higher rates |          Not yet implemented           |                                            |
-| Mifare PLUS                   | ISO14443A High rate  | Supports low rates, or possibly higher rates | Supports low rates, or possibly higher rates |          Not yet implemented           |                                            |
+*Beware some of the instructions might have changed since recording, check the current documentation when in doubt!*
 
-## Low Frequency Attack
+* [Downloading and compiling the official CLI](https://www.youtube.com/watch?v=VGpAeitNXH0)
+* [Downloading ChameleonUltraGUI](https://www.youtube.com/watch?v=rHH7iqbX3nY)
+* [ChameleonGUI features overview](https://www.youtube.com/watch?v=YqE8wyVSse4)
 
-| Vulnerability Type | Tag Type  | Whether the hardware supports | Does the software support | Whether the application layer supports | Note |
-|--------------------|:---------:|------------------------------:|---------------------------|:--------------------------------------:|-----:|
-| Sniffing           |  125KHz   |                       Support | Support                   |          Not yet implemented           |      |
-| Brute Force        | EM410x ID |                       Support | Support                   |          Not yet implemented           |      |
+# Official channels
 
-## Low Frequency Simulation
-
-| Card Type                | Encoding Type | Whether the hardware supports | Does the software support | Whether the application layer supports |                                          Note |
-|--------------------------|:-------------:|------------------------------:|---------------------------|:--------------------------------------:|----------------------------------------------:|
-| Non <125KHz/ASK/PSK/FSK> |      No       |                            No | No                        |                   No                   | Only 125 khz RF, Modulation ASK, FSK and PSK. |
-| EM410x                   |      ASK      |                       Support | Support                   |                Support                 |                   EM4100 is support(AD 64bit) |
-| T5577                    |      ASK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| HID Prox                 |      FSK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| Indala                   |      PSK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| FDX-B                    |      ASK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| Paradox                  |      FSK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| Keri                     |      PSK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| AWD                      |      FSK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| ioProx                   |      FSK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| securakey                |      ASK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| gallagher                |      ASK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| PAC/Stanley              |      ASK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| Presco                   |      ASK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| Visa2000                 |      ASK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| Viking                   |      ASK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| Noralsy                  |      ASK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| NexWatch                 |      PSK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| Jablotron                |      ASK      |                       Support | Support                   |          Not yet implemented           |                                               |
-
-## Low Frequency Reader
-
-| Card Type                | Encoding Type | Whether the hardware supports | Does the software support | Whether the application layer supports |                                          Note |
-|--------------------------|:-------------:|------------------------------:|---------------------------|:--------------------------------------:|----------------------------------------------:|
-| Non <125KHz/ASK/PSK/FSK> |      No       |                            No | No                        |                   No                   | Only 125 khz RF, Modulation ASK, FSK and PSK. |
-| EM410x                   |      ASK      |                       Support | Support                   |                Support                 |                                               |
-| T5577                    |      ASK      |                       Support | Support                   |             Support(Write)             |                                               |
-| HID Prox                 |      FSK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| Indala                   |      PSK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| FDX-B                    |      ASK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| Paradox                  |      FSK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| Keri                     |      PSK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| AWD                      |      FSK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| ioProx                   |      FSK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| securakey                |      ASK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| gallagher                |      ASK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| PAC/Stanley              |      ASK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| Presco                   |      ASK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| Visa2000                 |      ASK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| Viking                   |      ASK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| Noralsy                  |      ASK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| NexWatch                 |      PSK      |                       Support | Support                   |          Not yet implemented           |                                               |
-| Jablotron                |      ASK      |                       Support | Support                   |          Not yet implemented           |                                               |
-
-## Low Frequency Modulation
-
-[modulation_psk]: https://github.com/RfidResearchGroup/ChameleonUltra/blob/main/resource/picture/PSK.png
-
-[modulation_fsk]: https://github.com/RfidResearchGroup/ChameleonUltra/blob/main/resource/picture/FSK.png
-
-[modulation_ask]: https://github.com/RfidResearchGroup/ChameleonUltra/blob/main/resource/picture/ASK.png
-
-| Modulation Type |                         wav |
-|-----------------|----------------------------:|
-| PSK             | ![alt text][modulation_psk] |
-| FSK             | ![alt text][modulation_fsk] |
-| ASK             | ![alt text][modulation_ask] |
-
-# 1. Ultra-low power consumption
-
-It integrates a high-performance and low-power NFC module inside. When the NFC unit is turned on, the total current of
-the chip is only 5mA@3.3V.
-The underlying interaction is done independently by the NFC unit and does not occupy the CPU.
-In addition, the 52840 itself is a high-performance low-power Bluetooth chip, and the encryption and calculation process
-is only 7mA@3.3V. It can greatly reduce the battery volume and prolong the working time. That is to say, the 35mAh 10mm*
-40mm button lithium battery can guarantee to be charged once every half a year under the working condition of swiping
-the card 8 times a day for 3 seconds each time. Full potential for everyday use.
-
-# 2. Not just UID, but a real and complete MIFARE encrypted data simulation
-
-We can easily and completely simulate all data and password verification of all sectors, and can customize SAK, ATQA,
-ATS, etc. Similar to an open CPU card development platform, 14A interaction of various architectures can be easily
-realized.
-
-# 3. Super compatibility with low-power locks using batteries
-
-The structure of the old Chameleon AVR is slow to start during simulation. Faced with a battery-powered low-power lock
-and an integrated lock on the door, it will be frequently interrupted, and the verification interaction cannot be
-completed completely, resulting in no response when swiping the card.
-
-In order to reduce power consumption, the battery lock will send out a field signal as short as possible when searching
-for a card, which is no problem for the original card, but it is fatal for the MCU simulated card. Cards or mobile smart
-bracelets simulated by the MCU cannot wake up and respond in such a short time, so many battery locks cannot open the
-door, which greatly reduces the user experience.
-
-This project specially optimizes the start-up and interaction logic and antenna for low-power reading heads. After
-testing a variety of common low-power reading heads, they can open the door perfectly by swiping the card.
-
-# 4. Ultra-fast response speed and low interaction delay(MifareClassic)
-
-[fdt_standard_s50]: https://github.com/RfidResearchGroup/ChameleonUltra/blob/main/resource/picture/Standard_m1_s50.png
-
-[fdt_redmi_k30]: https://github.com/RfidResearchGroup/ChameleonUltra/blob/main/resource/picture/Xiaomi_k30u_smartkey.png
-
-[fdt_pm3_rdv401]: https://github.com/RfidResearchGroup/ChameleonUltra/blob/main/resource/picture/Proxmark3_Rdv4_RRG_(Firmware%20build%20at%2020201026).png
-
-[fdt_chameleon_ultra]: https://github.com/RfidResearchGroup/ChameleonUltra/blob/main/resource/picture/ChameleonUltra.png
-
-[fdt_chameleon_tiny]: https://github.com/RfidResearchGroup/ChameleonUltra/blob/main/resource/picture/ChameleonTiny.png
-
-[fdt_flipper_zero]: https://github.com/RfidResearchGroup/ChameleonUltra/blob/main/resource/picture/FlipperZero%20Simulation.png
-
-| Simulation            |             FDT             |                                "**_FDT_**" Rating                                |
-|----------------------|:---------------------------:|:--------------------------------------------------------------------------------:|
-| Standard MIFARE Card |  ![alt][fdt_standard_s50]   | &#x2B50;&#x2B50;&#x2B50;&#x2B50;&#x2B50;&#x2B50;&#x2B50;&#x2B50;&#x2B50;&#x2B50; |
-| ChameleonUltra       | ![alt][fdt_chameleon_ultra] |         &#x2B50;&#x2B50;&#x2B50;&#x2B50;&#x2B50;&#x2B50;&#x2B50;&#x2B50;         |
-| Proxmark3 Rdv4.01    |   ![alt][fdt_pm3_rdv401]    |                         &#x2B50;&#x2B50;&#x2B50;&#x2B50;                         |
-| RedMi K30            |    ![alt][fdt_redmi_k30]    |                 &#x2B50;&#x2B50;&#x2B50;&#x2B50;&#x2B50;&#x2B50;                 |
-| ChameleonTiny        | ![alt][fdt_chameleon_tiny]  |                     &#x2B50;&#x2B50;&#x2B50;&#x2B50;&#x2B50;                     |
-| FlipperZero          |  ![alt][fdt_flipper_zero]   |                                 &#x2B50;&#x2B50;                                 |
-
-# 5. 256kB super large RAM cooperates with RC522 to replace Proxmark3 magically to complete the decoding
-
-[attack_mifare_darkside]: https://github.com/RfidResearchGroup/ChameleonUltra/blob/main/resource/picture/Darkside.png
-
-[attack_mifare_nested]: https://github.com/RfidResearchGroup/ChameleonUltra/blob/main/resource/picture/Nested.png
-
-[attack_mifare_mfkey32]: https://github.com/RfidResearchGroup/ChameleonUltra/blob/main/resource/picture/MFKEY32V2.png
-
-| Attack Type  |              CLI               |
-|--------------|:------------------------------:|
-| MFKEY32 V2   | ![alt][attack_mifare_mfkey32]  |
-| Darkside     | ![alt][attack_mifare_darkside] |
-| Nested       |  ![alt][attack_mifare_nested]  |
-| StaticNested |          Coming Soon           |
-| HardNested   |          Coming Soon           |
-| Relay attack |          Coming Soon           |
-
-# Hardware frame diagram:
-
-![alt text](https://github.com/RfidResearchGroup/ChameleonUltra/blob/main/resource/picture/Hardware%20%20Frame%20Diagram.png)
-
-# Hardware Pictures
-
-![alt text](https://github.com/RfidResearchGroup/ChameleonUltra/blob/main/resource/picture/Hardware%20Photos.png)
+Where do you find the community?
 
+* [RFID Hacking community discord server](https://t.ly/d4_C)
+  * Software/chameleon-dev for firmware and clients development discussions
+  * Devices/chameleon-ultra for usage discussions

docs/README.md

@@ -0,0 +1,37 @@
+# Chameleon Ultra Guide
+
+This guide goal is to guide you through setting up and using your Chameleon Ultra and Lite.
+
+This Guide is split up into multiple "subguides":
+
+### About the device
+
+- [Whitepaper](./technical_whitepaper.md): Discover what the Chameleon Ultra is capable of.
+
+- [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.
+
+### Interacting with the device
+
+- [Quickstart](./quickstart.md): For the impatient people to just get you up and running with anything.
+
+- [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), these 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.
+
+### For developers
+
+- [Development](./development.md): For all developers. This covers how to build firmware from source and set up a development environment.
+
+- [SDKs](./sdk.md): SDKs for Chameleon, useful if you want to develop your own application to control Chameleon.
+
+- [Protocol](./protocol.md): The gory details of the communication protocol, useful if you want to develop your own client.
+
+### Miscellaneous 
+
+- [Modding](./modding.md): Third party moddings worth mentioning.
+
+- [FAQ](./faq.md): **F**requently **A**sked **Q**uestions, if you have a question, it might already be answered here.

docs/chameleonultragui.md

@@ -0,0 +1,144 @@
+## Get ChameleonUltraGUI
+
+- [on Google Play](https://play.google.com/store/apps/details?id=io.chameleon.ultra) / [APK](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/build-app/main/apk.zip)
+- [on iOS](https://apps.apple.com/dk/app/chameleon-ultra-gui/id6462919364)
+- [on Windows](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/build-app/main/windows-installer.zip) ([or without installer](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/build-app/main/windows.zip))
+- [on Linux](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/build-app/main/linux.zip)
+- [on macOS](https://apps.apple.com/app/chameleon-ultra-gui/id6462919364)
+
+## Page Breakdown
+
+### Homepage
+![CUGUI Homepage](./images/cugui-homepage.png)
+
+Starting from the top left, you find
+
+- the *Device Name*: `Chameleon Ultra` or `Chameleon Lite` depending on the device connected ;
+- the *Disconnect* button: pressing this icon cleanly disconnects the Chameleon. It is recommended to use this button whenever possible ;
+- the *Connected Port*: it tells you where and how the chameleon is connected, followed by how it is connected (*Connection Method*), which displays a USB or Bluetooth icon. Last in that row is the *Battery Charge* display ;
+- the *Used Slots*: it displays how many out of the 8 slots are used ;
+- the *Slot Changer*: the currently selected slot is highlighted with a red circle, while enabled slots are filled in. Everything else is a hollow circle. The arrows left and right allow you to change the currently selected slot ;
+- the *Firmware version*: the version is pulled from the device displayed, as well as git commit information ;
+- the *Check for updates* button: it compares the firmware with the one available on GitHub and then updates if a newer version is available ;
+- the *Switch mode* button: use it to switch between reader and emulator modes. The icon will update accordingly ;
+- the *Device Setting* button: it allows you to change settings concerning the device, like changing the animation mode.
+
+### Device settings
+![Device Settings](./images/cugui-devicesettings1.png)
+![Device Settings2](./images/cugui-devicesettings2.png)
+
+Top to bottom:
+- *Enter DFU mode*: to enter the device DFU mode. Allows the user to take over ;
+- *Flash latest FW via DFU*: download the newest firmware from GitHub, disregarding if the device is already up to date, and flash it ;
+- *Flash .zip FW via DFU*: it allows the user to select a zip they would like to flash to the device ;
+- *Animations*: choose if the device should play the boot-up animation when woken up by an external RFID field ;
+- *Button config*: it allows you to define both short-press and long-press actions
+- *BLE pairing* toggle: you can decide whether pairing with a BLE PIN is required or not. Enabling PIN increases security at the loss of convenience. You can define a *BLE PIN* once pairing is enabled and you can force forgetting about existing pairings with the *Clear bounded devices* option.
+- *Reset settings*: it resets all device settings but does not wipe user data.
+- *Factory reset*: **IT WIPES ALL USER DATA** and resets the device to factory settings.
+
+### Slot Manager
+![Slot Manager](./images/cugui-slotmanager.png)
+
+The *Slot Manager* consists of 8 cards representing the 8 slots on the device.
+
+The *RFID icon* in the top left corner can either be green or red, meaning the slot is enabled and disabled respectively.
+
+The *Credit Card icon* displays the name and card type of the HF card in the slot.
+The *Wi-Fi icon*, on the other hand, displays the name and card type of the LF card in the slot.
+
+The *Gear icon* opens the slot settings. These settings can be changed per slot.
+
+The entire card is also one big button, pressing anywhere on the card opens the select dialog for loading a card.
+
+### Slot Settings
+![Slotsettings](./images/cugui-slotsettings1.png)
+![Slotsettings2](./images/cugui-slotsettings2.png)
+
+The two rows at the top, labeled HF and LF respectively, display the names of the currently loaded cards. Next to them, the *X* clears them out of the slot. If both are empty, the slot will automatically be disabled.
+
+Under *Slot Status* you can set if the slot is enabled or disabled.
+
+The *Mifare Classic emulator settings* section allows you to toggle various behaviors:
+- *Gen1A Magic Mode*: behaves like a gen1a magic card and allows writing to it using magic commands like the Proxmark3 `cload` ;
+- *Gen2 Magic Mode*: behaves like a gen2 magic card, makes Block 0 writable ;
+- *Use UID/SAK/ATQA from 0 block*: the Chameleon Ultra stores the UID and other anti-collision data independently of the card content. Enabling this setting tells the Chameleon to derive them from card content block 0. Only for MFC with 4-byte UID ;
+- *Collect nonces (Mfkey32)*: it toggles nonce collection for mfkey32. When enabled you will be prompted to present the Chameleon to a reader. After you have collected nonces the *Present Chameleon to reader* message will change into a *Recover Keys from x nonces* button. Pressing this will start the recovery process ;
+- *Write mode*: Please refer to the [firmware docs](./firmware.md).
+
+### Search dialog
+![Search Dialog](./images/cugui-searchdialog.png)
+
+When using the GUI you may encounter a *Search* dialog. The dialog is structured as follows:
+
+Top left you find the *Back* button, this will abort the selection and bring you back.
+
+Near the end of the row, if it is a card search dialog, a filter option will show. This allows you to filter between *HF*, *LF* and *All* cards.
+
+At the end you find a *X*, this X will clear the query.
+
+You enter the query into the *textbox* on the top with the placeholder text "Search"
+
+The search results get listed below. The Card or Wi-Fi symbol indicates if it is LF/HF. The color of the Icon is the user-defined color.
+
+Listed also are the name and type.
+
+Selecting the entry automatically closes the search.
+
+### Saved Cards
+![Saved Cards](./images/cugui-savedcards.png)
+
+The *Saved Cards* page allows you to manage your cards and dictionaries.
+
+You import a card or dictionary by clicking the *+* button in their respective half. This opens a select dialog. You may then either select a CUGUI Json file or a Bin file. A Json file gets imported immediately while a Bin file asks if the supplied data is correct before saving.
+
+Once again, we got a card per card or dictionary. At the left you find the Icon for HF/LF with the user-defined color. To the left of that the card name, type and quick actions for edit, export and delete.
+
+The Card is again one Big button, pressing it brings up the Slot info. It displays info about the selected item and also has the quick actions present at the bottom.
+
+![Card Info](./images/cugui-savedcardinfo.png)
+
+### Card Edit Menu
+![HF Card edit](./images/cugui-editcard-HF.png)
+![LF Card edit](./images/cugui-editcard-LF.png)
+
+Depending on the selected card type the menu only displays options applicable to it.
+At the top of the menu is the name and icon. Pressing on the icon allows you to change the color.
+
+Right below is the drop-down for the type. You may switch between any type at will.
+
+A bit lower again you find the UID, SAK, ATQA, ATS and all other options for the selected type. This form auto-validates, so you should not be able to save a invalid config.
+
+And finally at the bottom are the save and cancel options, to save the changes and exits, or to cancel the operation with no changes.
+
+### Settings
+![Settings](./images/cugui-settings.png)
+
+The App settings have their own page and consist of a few simple settings:
+- *Sidebar Expansion*: Whether or not the sidebar shall be expanded or if the windows size should decide that
+- *Theme*: Light/Dark or get it from the System
+- *Color Scheme*: Allows you to choose a color you like for the app
+- *Language*: Choose any of the languages available. Translating is done via our Crowding project.
+- *About*: Displays simple info about the app, such as build number, contributors and people who have donated on Opencollective
+- *Activate debug mode*: Don't, just Don't
+
+## How to use MFKEY32
+
+- set slot to MIFARE Classic (by uploading an empty dump)
+- enable mfkey32 for that slot (toggle in slot settings)
+- select slot and present ultra repeatedly to the reader in order to collect nonces
+- after collecting some nonces, go back into slot settings and click recover keys
+
+## Troubleshooting
+
+### Font scaling issues on HiDPI screens
+
+If you have font scaling issues (tiny fonts) with the Linux desktop app and a HiDPI screen, you can solve it by running the app as
+```
+GDK_SCALE=2 GDK_DPI_SCALE=0.5 /usr/local/lib/chameleonultragui/chameleonultragui
+```
+
+### Key recovery from this card is not yet supported
+This error may occur when the card you are trying to recovery keys from is requiring a not yet supported recovery technology. You cannot tell the required recovery method from the outside.
+
+You may be able to solve this issue by dumping the card with a Proxmark3 or Mifare Classic Tool (Mobile App) and then importing a bin file.

docs/cli.md

@@ -0,0 +1,160 @@
+# CLI
+
+The CLI (**C**ommand **L**ine **I**nterface) is the official way to control your Chameleon.
+
+It requires at least **Python 3.9** version.
+
+## 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; pacman -S msys2-keyring --noconfirm; pacman-key --refresh`
+
+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
+
+- Connect to the CLI: `hw connect`
+- Change slot: `hw slot change -s [1-8]`
+
+*More examples coming soon*
+
+### MFKEY32v2 walk-through
+Make sure to be in the `software/` directory and run the Python CLI from there.
+
+- Connect to the CLI: `hw connect`
+- Check which slot can be used: `hw slot list`
+- Change the slot type, here using slot 8 for a MFC 1k emulation: `hw slot type -s8 -t3`
+- Init the slot content: `hw slot init -s8 -t3`
+  - or load an existing dump and set UID and anticollision data, cf `hf mf eload -h` and `hf mf sim -h`
+- Enable the slot: `hw slot enable -s8 -e1`
+- Change to the new slot: `hw slot change -s8`
+- Activate the detection: `hf detection enable -e1`
+
+Now disconnect, go to a reader and swipe it a few times
+
+- Come back and connect to the CLI: `hw connect`
+- See if nonces were collected: `hf detection count`
+  - We need 2 nonces per key to recover
+- Recover the key(s) based on the collected nonces: `hf detection decrypt`. Output example:
+```
+ - MF1 detection log count = 6, start download.
+ - Download done (144bytes), start parse and decrypt
+ - Detection log for uid [DEADBEEF]
+  > Block 0 detect log decrypting...
+  > Block 1 detect log decrypting...
+  > Result ---------------------------
+  > Block 0, A key result: ['a0a1a2a3a4a5', 'aabbccddeeff']
+  > Block 1, A key result: ['010203040506']
+
+```
+
+- To clean the logged detection nonces: `hf detection enable -e0` then `hf detection enable -e1`
+
+
+
+*More examples coming soon*

docs/development.md

@@ -0,0 +1,351 @@
+# 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 firmware!
+
+## Prerequisites for compiling
+
+### install a cross-compiler
+
+So far, the following compilers have been reported to work fine.  
+Download one of them and decompress it.  
+Remember the path where you installed it.
+
+- [gcc-arm-none-eabi-10.3-2021.10](https://developer.arm.com/downloads/-/gnu-rm)
+- [arm-gnu-toolchain-12.2.rel1-XXX-arm-none-eabi](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads), e.g. [arm-gnu-toolchain-12.2.rel1-x86_64-arm-none-eabi.tar.xz](https://developer.arm.com/-/media/Files/downloads/gnu/12.2.rel1/binrel/arm-gnu-toolchain-12.2.rel1-x86_64-arm-none-eabi.tar.xz) for a x86_64 Linux host
+
+Always use the official versions from ARM, *DO NOT* install `gcc-arm-none-eabi` from Debian/Ubuntu.  
+For some unknown reasons, same gcc version from Debian creates a bootloader too large to fit in the allocated flash space.  
+Moreover it does not contain the `gdb` debugger.
+
+### install make
+
+* **Debian/Ubuntu alike**
+  * Open a terminal.
+  * Run the following command to install Make: `sudo apt-get install build-essential`
+* **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')) ```
+  * In the same PowerShell terminal, run the following command to install Make using Chocolatey: `choco install make`
+* **macOS:**
+  * Open a terminal.
+  * If not yet installed, install Homebrew package manager by running the following command: `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`
+  * Once Homebrew is installed, run the following command to install Make: `brew install make`
+
+### 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.
+- Install nRF Util packages:
+  - `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
+
+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.
+
+- 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`
+
+### 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/`
+
+## Editing the code
+
+You can use [Visual Studio Code](https://code.visualstudio.com/download) to edit this project! Simply download and
+install it!
+
+- Install the [C++ Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) in VS-Code.
+- Install
+  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}/**`
+
+## Compiling the code
+
+- Install prerequisites (for instructions have a look at [Prerequisites for compiling](#Prerequisites-for-compiling))
+- 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
+
+## Uploading the code in DFU mode
+
+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.
+
+The LEDs 4 & 5 should blink green when in DFU mode.
+
+To flash only the application (safer):
+
+`nrfutil device program --firmware objects/dfu-app.zip --traits nordicDfu`
+
+To flash everything (be sure to also have a JLink or ST-Link V2 programmer if something goes wrong):
+
+`nrfutil device program --firmware objects/dfu-full.zip --traits nordicDfu`
+
+Under Linux you can use the scripts `flash-dfu-app.sh` and `flash-dfu-full.sh`, they will put the device in DFU mode and flash it.
+
+## Uploading the code with a programmer
+
+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
+# full:
+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"
+# full:
+openocd -f interface/jlink.cfg -f target/nrf52.cfg -c "program objects/fullimage.hex verify reset ; shutdown"
+```
+
+With a ST-Link V2 and `openocd`
+
+```
+# application only:
+openocd -f interface/stlink.cfg -f target/nrf52.cfg -c "program objects/application.hex verify reset ; shutdown"
+# full:
+openocd -f interface/stlink.cfg -f target/nrf52.cfg -c "program objects/fullimage.hex verify reset ; shutdown"
+```
+
+## Uploading the code over BLE
+
+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`
+
+Once in DFU mode, the device will announce itself over BLE as `CU-xxxx` where xxxx are the last 2 bytes of the Device Serial Number.
+
+Then use the official [nRF Device Firmware Update](https://www.nordicsemi.com/Products/Development-tools/nRF-Device-Firmware-Update) mobile application to flash one of the DFU images.
+
+## Debugging the code from VSCode
+
+- Install [Cortex-Debug](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug) VS-Code Extension
+- Open `app_main.c`
+- Open the extension with `CTRL-SHIFT-D`
+- Klick on `create a launch.json file`
+- Select `Cortex-Debug`
+- Add this in the configuration bracket:
+
+```
+{
+    "cwd": "${workspaceFolder}",
+    "executable": "${workspaceRoot}/firmware/objects/bootloader.out",
+    "name": "Debug with JLink",
+    "request": "launch",
+    "type": "cortex-debug",
+    "runToEntryPoint": "main",
+    "showDevDebugOutput": "none",
+    "servertype": "jlink",
+    "device": "nrf52",
+    "interface": "swd",
+    "svdFile": "${workspaceRoot}/firmware/nrf52_sdk/modules/nrfx/mdk/nrf52.svd",
+}, 
+{
+    "cwd": "${workspaceFolder}",
+    "executable": "${workspaceRoot}/firmware/objects/bootloader.out",
+    "name": "Debug with STLink",
+    "request": "launch",
+    "type": "cortex-debug",
+    "runToEntryPoint": "main",
+    "showDevDebugOutput": "none",
+    "servertype": "openocd",
+    "device": "nrf52",
+    "svdFile": "${workspaceRoot}/firmware/nrf52_sdk/modules/nrfx/mdk/nrf52.svd",
+    "gdbPath": "C:/Program Files (x86)/GNU Arm Embedded Toolchain/10 2021.10/bin/arm-none-eabi-gdb.exe",
+    "configFiles": [
+        "interface/stlink.cfg",
+        "target/nrf52.cfg"
+    ]
+}
+```
+
+- If you are jlink probe, create `settings.json` in {projectRoot}/.vscode directory.
+
+```
+{
+    "cortex-debug.armToolchainPath": "C:\\UserProgram\\arm_gcc\\none\\bin",
+    "cortex-debug.JLinkGDBServerPath": "C:\\Program Files\\SEGGER\\JLink\\JLinkGDBServerCL.exe",
+}
+```
+
+- To change `executable` target in `launch.json` to `application` or `bootloader`
+- In the debug menu you can select `Debug with JLink` or `Debug with STLink`
+
+## 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
+cd Python-3.8.17
+./configure --prefix=$HOME/opt/python-3.8.17 --enable-shared
+make
+rm -rf ~/opt/python-3.8.17
+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.
+
+```
+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:
+        PROBE(nrf51_probe);
+        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.  
+Under linux, it is convenient to install [udev rules](https://github.com/blackmagic-debug/blackmagic/blob/main/driver/README.md#99-blackmagic-plugdevrules) to get aliases `/dev/ttyBmpGdb` and `/dev/ttyBmpTarg`.
+
+Note that using a native ST-Link V2 with BlackMagicProbe "hosted" will not allow to see NRF_LOG messages.
+
+## Debugging the code with gdb and BMP with RTT to monitor NRF_LOG
+
+Assuming you have a BlackMagicProbe with RTT support made out of a ST-Link V2.
+
+RTT usage: https://black-magic.org/usage/rtt.html
+
+```
+stlink-tool
+sleep 1
+screen /dev/ttyBmpTarg
+```
+
+In another terminal
+
+```
+$ arm-none-eabi-gdb
+(gdb) target extended-remote /dev/ttyBmpGdb
+(gdb) monitor swdp_scan
+ 1      Nordic nRF52 M4
+ 2      Nordic nRF52 Access Port.
+(gdb) attach 1
+(gdb) monitor rtt
+```
+
+We are now able to use gdb and see the NRF_LOG messages on the other terminal.
+
+## Using JLink with RTT to monitor NRF_LOG
+
+cf https://embeddedexplorer.com/nrf52-nrf-log-tutorial/
+
+```
+JLinkExe -if SWD -device nrf52 -speed 4000 -autoconnect 1
+```
+
+in a second terminal:
+
+```
+JLinkRTTClient
+```
+
+## Using SWO pin as UART to monitor NRF_LOG
+
+One can set `NRF_LOG_UART_ON_SWO_ENABLED := 1` in `Makefile.defs` to activate this functionality.
+When activated, NRF_LOG will be available if one connects a UART bridge to the SWO pin which will work as a UART TX pin.
+UART works at 115200 bauds. E.g. one can use a FTDI dongle and `screen /dev/ttyUSB0 115200`.
+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.
+
+# Resources
+
+* [nRF52840 Objective Product Specification v0.5.1](https://infocenter.nordicsemi.com/pdf/nRF52840_OPS_v0.5.1.pdf)

docs/firmware.md

@@ -0,0 +1,120 @@
+# 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.
+
+## Write Modes
+- **Normal**: Behaves like any normal card
+- **Denied**: Read-only card, send NACK to write attempts
+- **Deceive**: Accepts write commands but don't change any data (reader thinks write was successful but when reading back, nothing changed)
+- **Shadow**: Accepts writes but reverts changes when device goes to sleep (reader can read and write like a normal card but changes are kept in RAM and are lost when the chameleon goes to sleep) 
+
+## 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.