Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
271 changes: 55 additions & 216 deletions docs/getting-started/installing/from-gui/usage.en.md
Original file line number Diff line number Diff line change
@@ -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.

<img width="640" src="../../../../img/krux-installer/main.png" alt="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.
<img width="640" src="../../../../img/krux-installer/main.png" alt="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.

<img src="../../../../img/krux-installer/opengl-error.jpg" style="width: 37%; min-width: 250px;">
### 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:

<img width="640" src="../../../../img/krux-installer/select_version_menu.png" alt="Krux-Installer Select Version Menu" />
<img src="../../../../img/krux-installer/opengl-error.jpg" style="width: 37%; min-width: 250px;" alt="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`;
<img width="640" src="../../../../img/krux-installer/select_device.png" alt="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

<img width="640" src=" ../../../../img/krux-installer/warn_beta.png" alt="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
<img width="640" src="../../../../img/krux-installer/device_selected.png" alt="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.

<img width="640" src=" ../../../../img/krux-installer/select_old_version_menu.png" alt="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:

<img width="640" src=" ../../../../img/krux-installer/app_settings.png" alt="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.

<img width="640" src=" ../../../../img/krux-installer/baudrate.png" alt="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`.

<img width="640" src=" ../../../../img/krux-installer/locale_menu.png" alt="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:

<img width="640" src=" ../../../../img/krux-installer/select_device.png" alt="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:

<img width="640" src=" ../../../../img/krux-installer/warn_already_downloaded.png" alt="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`;

<img width="640" src=" ../../../../img/krux-installer/download_assets.png" alt="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`.

<img width="640" src=" ../../../../img/krux-installer/verification.png" alt="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:

<img width="640" src=" ../../../../img/krux-installer/unzip.png" alt="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:

<img width="640" src=" ../../../../img/krux-installer/flash.png" alt="Krux-Installer unzip" />
> ⚠️ TIP: You must connect and turn on your device **before click extract and flashing starts!**.

As well a done icon:

<img width="640" src=" ../../../../img/krux-installer/flash_done.png" alt="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.

<img width="640" src=" ../../../../img/krux-installer/unzip.png" alt="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.

<img width="640" src=" ../../../../img/krux-installer/warn_airgap.png" alt="Krux-Installer warn airgap" />

Insert the SD card and click 'Proceed' to allow the installer to detect it.

<img width="640" src=" ../../../../img/krux-installer/list_drivers.png" alt="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).

<img width="640" src=" ../../../../img/krux-installer/airgap_done.png" alt="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:
<img width="960" src="../../../../img/krux-installer/app_settings.png" alt="Krux Installer settings showing asset destination path, flash baudrate, and locale">

<img width="640" src=" ../../../../img/krux-installer/wipe_warn.png" alt="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.

<img width="640" src=" ../../../../img/krux-installer/wipe.png" alt="Wipe Warning" />
> ⚠️ TIP: Do not unplug or poweroff your device or computer. Wait until the process finishes.
<img width="640" src="../../../../img/krux-installer/wipe_warn.png" alt="Warning that a full wipe permanently erases data and firmware">

----8<----
tips-after-install.en.txt
Expand Down
Binary file modified docs/img/krux-installer/app_settings.png

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/root/.local/krux-installer isn´t a good place to give as example. Prefer another image with a proper example name.

@qlrd qlrd Nov 16, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now I'm reading /home/user/krux-installer. But IIRC the path is is similar to $HOME/.local/krux-installer (need peer verification from others too). Also the image appear to be very small to me (i put some zoom to read it), is good to read on your video guys?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the clarification, @qlrd

I'll increase the displayed image width to improve readability.

Regarding the path, would /home/user/.local/krux-installer be an appropriate example based on the default $HOME/.local/krux-installer location? I'm currently testing on Windows, so I can't independently verify the Linux default.

@qlrd qlrd Nov 16, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's wait, i really not remember the correct path on unix-like cc @joaozinhom

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed: the default is $HOME/.local/krux-installer on both Linux and macOS (Windows: %LOCALAPPDATA%\krux-installer\local). So the /home/user/krux-installer in the screenshot is not the default; a retaken screenshot showing /home/user/.local/krux-installer would match a fresh install.

One thing worth noting about this setting: I checked the code and the "Asset's destination path" entry is a leftover from the download era. Since v0.0.22 the installer bundles the firmware and downloads nothing; the bundled .kfpkg files are unpacked by PyInstaller into its own temp directory and by KTool into a temporary directory at flash time, and nothing reads the destdir.assets config anymore. So the "Destination path of downloaded assets" description in Settings doesn't match any current behavior. I'd suggest not documenting it as a download path; maybe just drop that sentence and keep baudrate and locale.

@qlrd qlrd Nov 16, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@BLVCK-MAMBA-6 please update with a compliant image and instructions above

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I just updated the Settings screenshot with the correct Windows default destination path.

I also dropped the old asset destination explanation, since the current installer doesn’t use that setting. Only Flash baudrate and Locale are left.

I only have Windows, so a Linux screenshot will have to be a separate follow-up.

Thank you guys @joaozinhom @qlrd

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/img/krux-installer/device_selected.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/img/krux-installer/main.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/img/krux-installer/select_device.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/img/krux-installer/wipe_warn.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading