Skip to content

docs: update Krux Installer usage for v0.0.24 - #970

Open
BLVCK-MAMBA-6 wants to merge 3 commits into
selfcustody:developfrom
BLVCK-MAMBA-6:docs/update-installer-usage
Open

BLVCK-MAMBA-6 wants to merge 3 commits into
selfcustody:developfrom
BLVCK-MAMBA-6:docs/update-installer-usage

Conversation

@BLVCK-MAMBA-6

Copy link
Copy Markdown

What is this PR for?

The Usage guide still showed the old firmware download screens. This PR updates the steps and screenshots for Krux Installer v0.0.24, which bundles the firmware and can flash it offline. The guide also links to the microSD update instructions.

Refs #941

Changes made

  • Docs

What did you test?

I checked the installer screens on Linux. Pre-commit and the strict MkDocs build passed. Pytest reported 1,194 passed and one expected failure. Flashing and wiping on a physical device are still untested.

What is the purpose of this pull request?

  • Docs update

@jdlcdl jdlcdl added the prioritized Prioritized focus for near-term merge label Nov 15, 2026
@codecov

codecov Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.60%. Comparing base (9092846) to head (2c77e13).

Additional details and impacted files
@@           Coverage Diff            @@
##           develop     #970   +/-   ##
========================================
  Coverage    97.60%   97.60%           
========================================
  Files           84       84           
  Lines        11001    11001           
========================================
  Hits         10738    10738           
  Misses         263      263           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@jdlcdl

jdlcdl commented Nov 15, 2026 •

Copy link
Copy Markdown
Member

I believe the ci action test runs will resolve once this pr is rebased against "develop". Lots of changes went into it yesterday, including ci action changes that fix black failures.

alerting for review: @qlrd @joaozinhom since these docs concern usage of krux-installer.

@BLVCK-MAMBA-6
BLVCK-MAMBA-6 force-pushed the docs/update-installer-usage branch from 6b1e1bd to d251b29 Compare November 15, 2026 12:22
@BLVCK-MAMBA-6

Copy link
Copy Markdown
Author

Thanks, @jdlcdl. I rebased the PR onto develop and pushed d251b297. Black passed locally on Python 3.11.5 and 3.12.13. Could you approve the pending GitHub Actions run so CI can check the rebased commit?

@qlrd qlrd left a comment •

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.

LGTM at first read. IMO would be neat to have an updated image of flash procedure like did on wipe device image, if possible. Some nits:

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.

Comment on lines +3 to +6
Krux Installer bundles one version of the Krux firmware. Once installed, it can
flash your device offline. To use a different firmware version, 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).

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.

Suggested change
Krux Installer bundles one version of the Krux firmware. Once installed, it can
flash your device offline. To use a different firmware version, 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).
Krux Installer bundles one version of the Krux firmware. Once installed, it can
flash your device offline. To use a different firmware version, 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). It should be used to first install or to install after a [*Wipe device* procedure](#air-gapped-update). To update firmware, we recommend to see (*Air-gapped update* section)[#air-gapped-update].

@BLVCK-MAMBA-6

Copy link
Copy Markdown
Author

Hi @qlrd, thanks for the review!

I clarified the USB flashing and air-gapped update instructions and updated the Settings screenshot. I couldn’t capture the flash-progress screenshot because I don’t have a compatible device to test with. The strict MkDocs build passes locally.

@qlrd qlrd left a comment

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.

some nit:

@BLVCK-MAMBA-6

Copy link
Copy Markdown
Author

I widened the Settings screenshot from 640px to 960px so the text is easier to read. For the asset destination path, I’m still waiting on confirmation of the right Linux example.

@BLVCK-MAMBA-6
BLVCK-MAMBA-6 requested review from odudex and qlrd November 16, 2026 14:46

@qlrd qlrd left a comment

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.

LGTM i think only confirming the correct path for image. Maybe a follow-up could be done with example for windows and macos, since the paths could diff

@BLVCK-MAMBA-6

Copy link
Copy Markdown
Author

Thanks, @qlrd! I’ll wait for @joaozinhom confirmation. Platform-specific examples for Windows and macOS would be a good follow-up for sure.

@joaozinhom

Copy link
Copy Markdown
Member

LGTM from my side. I verified the guide against the v0.0.24 code: offline flashing, the dimmed devices (bit is correctly dimmed, it has no bundled kfpkg), the SHA256 check before flashing, the wipe text, and the rewritten sections all match the installer behavior. The internal links also resolve fine.

This review surfaced a few loose ends in the installer itself that came from the offline refactor: the destdir.assets setting has no consumer anymore, DEFAULT_DESTDIR in base_krux_installer.py is unused, and the airgap update screens look unreachable from the UI (that is why pointing to the microSD guide in this PR is the right call). I can open a follow-up issue/PR to remove or clean up that dead code. Does that sound good to you, @qlrd?

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

prioritized Prioritized focus for near-term merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants