diff --git a/docs/getting-started/installing/from-gui/usage.en.md b/docs/getting-started/installing/from-gui/usage.en.md index 6f28d6bd8..1bd95f9fa 100644 --- a/docs/getting-started/installing/from-gui/usage.en.md +++ b/docs/getting-started/installing/from-gui/usage.en.md @@ -1,251 +1,90 @@ -This guide will walk through the basic use of the installer. At startup, it can differ in some -operational systems. In the rest, the procedures will be similar. +# Usage -### Main Menu -When executing the **Krux-Installer**, you will be presented with a menu of 4 enabled buttons and -two disabled buttons: +Krux Installer bundles one version of the Krux firmware and can flash your +device offline. Use USB flashing for the first installation or to reinstall +after a [Wipe device](#wipe-device) procedure. For subsequent firmware updates, +we recommend the [air-gapped update](#air-gapped-update) using a microSD card. -Krux-Installer Main Menu +To flash a different firmware version over USB, download an +[installer release](https://github.com/selfcustody/krux-installer/releases) that +bundles it or follow the [manual installation instructions](../from-pre-built-release.md). -* Enabled buttons: - * `Version`: select a firmware version; - - * `Device`: select a supported device for the selected version; - - * `Settings`: change some application settings; - - * `About`: just show some information about the application. +## Main menu -* Disabled buttons: +Open Krux Installer, read the disclaimer, and click **I understand** to continue. +On Linux, the installer may ask for permission to access the USB serial port. +Follow the on-screen instructions if prompted. - * `Flash firmware`: This button will start the flash firmware procedure; - - * It will be enabled when user select **both** version and device; - - * `Wipe device`: This button will start the wipe device procedure. - - * It will be enabled when user select the device. +Krux Installer main menu before a device is selected -#### Kivy Fatal Error - OpenGL -Our latest version uses Kivy and requires at least OpenGL version 2.0, if you encounter this error, try installing the [OpenCL™, OpenGL®, and Vulkan® Compatibility Pack](https://apps.microsoft.com/detail/9nqpsl29bfff) from Microsoft. +**Flash firmware** and **Wipe device** become available after you select a device. +You can open **Settings** and **About** from the main menu at any time. - +### Kivy Fatal Error - OpenGL -### Select version +Krux Installer uses Kivy and requires OpenGL 2.0 or later. On Windows, if the +installer shows an OpenGL error, try installing the +[OpenCL™, OpenGL®, and Vulkan® Compatibility Pack](https://apps.microsoft.com/detail/9nqpsl29bfff) +from Microsoft. -At startup, the application will setup it to the latest one, `{{latest_krux}}`. But you can select -even a beta release or older versions: - -Krux-Installer Select Version Menu +Kivy OpenGL error on Windows -* Click in the button that show the text `Version: {{latest_krux}}`; +## Select device -* To select a beta release, click on button that show the text `odudex/krux_binaries`; +Click **Device: select a new one**, then choose your device model. The installer +returns to the main menu with the selected model next to **Device**. -* To select an older version, click on button that show the text `Old versions`; +Krux Installer list of device models -#### Beta release +Models unavailable for the bundled firmware are dimmed. -After choose `odudex/krux_binaries`, you'll be warned with a message: +## Flash device -Krux-Installer warning beta version +1. Connect your device to the computer with a USB data cable and turn it on. +2. Confirm that the model shown next to **Device** matches your hardware, then + click **Flash firmware**. +3. Leave the USB cable connected and the device powered on until the installer + displays **DONE**. Do not disconnect it while flashing. -#### Older versions +Krux Installer with Amigo selected and Flash firmware enabled -* We put this option in case you have any interest in the history of firmware development; +The installer checks the bundled firmware against its build-time SHA256 hash +before flashing. -Krux-Installer Select Old Version Menu - -* Each version supports one device or the other; - -* For example: the version `v22.03.0` has support only for `m5stickv`. - - -### Settings - -**Krux-Installer** will give to you some freedom of choices for: - -* Krux-Installer settings; - -* General settings; - -#### Krux-Installer specific settings - -Here you can configure some of the specifics of krux firmare, like: - -Krux-Installer App settings Menu - -* Where you'll save downloaded assets; - -* The flash baudrate - -* The natural language that will be used in the application ([system locale](https://en.wikipedia.org/wiki/Locale_(computer_software))). - -##### Flash baudrate -The flash baudrate is how quickly the firmware will be written to the device. - -Krux-Installer baudrate - -Use one of the following (m5StickV doesn't support 2000000): 9600, 19200, 28800, 38400, 57600, 76800, 115200, -230400, 460800, 576000, 921600, 1500000, 2000000. - -##### System locale - -At startup, **Krux-Installer** recognize the locale used in your system. If your language isn't supported, it will defaults to `en_US`. - -Krux-Installer locale menu - - -### Select Device - -Everytime you select a new version, you'll see that the device button will be -reseted to `Device: select a new one` state. Once a version is selected you can choose a device -on which the firmware will be written. - -First, select the device we want to flash. After that the menu will shown three items: - -Select Device Menu - -Note that some devices may be disabled if they are not supported by the chosen version - -### Flash device - -Once you choose the device and version, it enables the "flash device" button. It will start an -**automatic** process of: - -* For official firmware's releases: - - * Warning; - - * Download; - - * Verification: - - * Unzip the correct firmware; - - * Flash: - - * The flash itself via USB; - - * Air-gapped update via SD card; - - -* For beta releases: - - * Download asset; - - * The flash itself; - -#### Warning - -If you already downloaded assets, you'll be warned about this and will be offered the possibility -to download again or continue without downloading: - -Krux-Installer already downloaded - -#### Download - -**Krux-Installer** download can download four assets for official releases or one for beta releases. - -##### Official releases - -* A `zip` file containing all firmwares for each device; - -* Download a `zip.sha256.txt` file containing a `zip`'s digital fingerprint; - -* Download a `zip.sig` file containing a `zip`'s digital signature; - -* Download the `selfcustody.pem` file containing a public key certificate, signed by `odudex`; - -Krux-Installer downloading assets - -##### Beta releases - -* A `kfpkg` file containing the specific firmware for choosen device; - -#### Verification - -* Integrity verification compares the computed hash of `zip` against thei provided `zip.sha256.txt`; - -* Authenticity verification check if the `zip` file was really signed by `odudex`, using -the `zip.sig` and `selfcustody.pem`. - -Krux-Installer verification process - - -#### Unzip - -Now you will be able to select if you do a flash process or need to do an airgap process: - -Krux-Installer unzip - -Click on [Flash with](#flash-with) to install via USB or [Air-gapped update with](#air-gapped-update-with) to perform upgrades via an SD card. - -#### Flash with - -When flash starts, it will warn you to **not disconnect the device until the process is complete**. -You'll be able to see the flash progress: - -Krux-Installer unzip -> ⚠️ TIP: You must connect and turn on your device **before click extract and flashing starts!**. - -As well a done icon: - -Krux-Installer unzip - -> ⚠️ TIP: ----8<---- flash-krux-logo.en.txt ----8<---- +### Error flashing -##### Error flashing - -If **Krux-Installer** shows a **flash failed** error or freezes at **PLEASE DO NOT UNPLUG YOUR DEVICE** with the message **INFO Trying to Enter K210 ROM ISP Mode…**, it means the installer couldn’t establish a proper connection to the device. See the [troubleshooting](/krux/troubleshooting/#error-when-flashing) section for guidance on how to fix this. - - -#### Air-gapped update with - -Once you've installed the initial firmware on your device via USB, you can perform further firmware upgrades via SD card to keep the device airgapped. - -Krux-Installer unzip -> ⚠️ Click on "Air-gapped update with" - -Once the `firmware.bin` and `firmware.bin.sig` are extracted, you'll see a warning message. - -Krux-Installer warn airgap - -Insert the SD card and click 'Proceed' to allow the installer to detect it. - -Krux-Installer warn airgap -> ⚠️ If a single SD card is inserted, the screen will display a large button. If multiple removable drives are detected, both SD cards and other drives will be listed. - -Select the desired removable drive to copy both `firmware.bin` and `firmware.bin.sig.` The first is the Krux firmware, and the second is a signature file that verifies the firmware’s integrity and authenticity. - -Now you can compare the firmware's hash computed by installer with the firmware's hash computed by the device. +If flashing fails or stalls while trying to enter K210 ROM ISP mode, see +[Error when flashing](../../../troubleshooting.md#error-when-flashing). -Krux-Installer warn airgap -> ⚠️ Once files are copied, remove the SD card from computer, connect to device and compare the hashes +### Air-gapped update -### Wipe device +After the initial USB installation, follow the +[microSD card update guide](../../features/sd-card-update.md) to update firmware +without connecting the device to a computer over USB. -This is a two step process, **Warning msg** and **Wipe process**. +## Settings -#### Warning +Open **Settings** to change **Flash baudrate**, which controls how fast firmware +is written over USB, or **Locale**, which changes the installer language. -Before the wipe starts, it will show to you a message: +Krux Installer settings showing asset destination path, flash baudrate, and locale -Wipe Warning -> ⚠️ TIP: It's useful when your device is not working or for security reasons. -To use Krux again, you'll need to re-flash the firmware. +## Wipe device -#### Wipe +Wiping permanently erases saved data and removes the firmware. Back up any +wallet recovery information you need before proceeding. -Once the process starts, the screen will appear frozen and a spinner will keep moving. -When it's done, you can scroll down you will see a `check` icon. +1. Connect the device over USB and select its model. +2. Click **Wipe device** and read the warning. Click **Proceed** to start the wipe. +3. Leave the USB cable connected and the device powered on until the installer + displays **DONE**. Do not disconnect it while wiping. Disconnect + and reconnect it before flashing the firmware again. -Wipe Warning -> ⚠️ TIP: Do not unplug or poweroff your device or computer. Wait until the process finishes. +Warning that a full wipe permanently erases data and firmware ----8<---- tips-after-install.en.txt diff --git a/docs/img/krux-installer/app_settings.png b/docs/img/krux-installer/app_settings.png index b5f897647..6d19e5919 100644 Binary files a/docs/img/krux-installer/app_settings.png and b/docs/img/krux-installer/app_settings.png differ diff --git a/docs/img/krux-installer/device_selected.png b/docs/img/krux-installer/device_selected.png new file mode 100644 index 000000000..a1230add5 Binary files /dev/null and b/docs/img/krux-installer/device_selected.png differ diff --git a/docs/img/krux-installer/main.png b/docs/img/krux-installer/main.png index e22fba1f8..57d4641c1 100644 Binary files a/docs/img/krux-installer/main.png and b/docs/img/krux-installer/main.png differ diff --git a/docs/img/krux-installer/select_device.png b/docs/img/krux-installer/select_device.png index e1bed277a..fb1268bb8 100644 Binary files a/docs/img/krux-installer/select_device.png and b/docs/img/krux-installer/select_device.png differ diff --git a/docs/img/krux-installer/wipe_warn.png b/docs/img/krux-installer/wipe_warn.png index 62f1e5076..05d9eeb4f 100644 Binary files a/docs/img/krux-installer/wipe_warn.png and b/docs/img/krux-installer/wipe_warn.png differ