From pre-built official release
This page explains how to install Krux from an official, pre-built release.
Download the latest release¶
Head over to the releases page and download the latest signed release.
Verify the files¶
Before installing the release, it's a good idea to check that:
- The SHA256 hash of
krux-v24.09.1.zip
matches the hash inkrux-v24.09.1.zip.sha256.txt
- The signature file
krux-v24.09.1.zip.sig
can be verified with theselfcustody.pem
public key found in the root of the krux repository.
You can either do this manually or with the krux
shell script, which contains helper commands for this:
./krux sha256 krux-v24.09.1.zip
./krux verify krux-v24.09.1.zip selfcustody.pem
On Mac you may need to install coreutils
to be able to use sha256sum
brew install coreutils
Fun fact: Each Krux release is signed with Krux!
Flash the firmware onto the device¶
Extract the latest version of Krux you downloaded and enter the folder:
unzip krux-v24.09.1.zip && cd krux-v24.09.1
Connect the device to your computer via USB (for Maix Amigo, make sure you’re using bottom port), power it on, and run the following, replacing DEVICE
with either m5stickv
, amigo
, bit
, cube
, dock
or yahboom
(to yahboom you may need to manually specify the port, for example /dev/ttyUSB0
on Linux or COM6
on Windows):
./ktool -B goE -b 1500000 maixpy_DEVICE/kboot.kfpkg
For dock
use the -B dan
parameter:
./ktool -B dan -b 1500000 maixpy_dock/kboot.kfpkg
When the flashing process completes, you should see the Krux logo:
If it doesn't, try turning your device off and on by holding down the power button for six seconds.
Congrats, you're now running Krux!
A note about the Maix Amigo¶
Some Amigo screens have inverted X coordinates, others display colors differently. For more info see Troubleshooting.
Troubleshooting¶
If ktool
fails to run, you may need to give it executable permissions with chmod +x ./ktool
, or you might need to use "sudo" if your user don't have access to serial port. In Windows or Mac you may need to explicitly allow the tool to run by adding an exception for it.
If the flashing process fails midway through, check the connection, restart the device, and try the command again.
Two serial ports are created when Amigo
and Bit
are connected to a PC. Sometimes Ktool will pick the wrong port and flashing will fail. Manually specify the serial port to overcome this issue using -p
argument:
Linux¶
See the correct port using ls /dev/ttyUSB*
, in the example below we use /dev/ttyUSB0
:
./ktool-linux -B goE -b 1500000 maixpy_amigo/kboot.kfpkg -p /dev/ttyUSB1
Windows¶
See the correct port at Device Manager > Ports (COM & LPT), in the example below we use COM6
:
.\ktool-win.exe -B goE -b 1500000 maixpy_amigo\kboot.kfpkg -p COM6
Mac¶
Remove the Gatekeeper quarantine extended attribute from ktool-mac:
xattr -d com.apple.quarantine ktool-mac
See the correct port using the command line: ls /dev/cu.usbserial*
, in the example below we use /dev/cu.usbserial-10
(If the output isn't what you expect try a different cable, preferably a smartphone usb-c charger cable):
./ktool-mac -B goE -b 1500000 maixpy_amigo/kboot.kfpkg -p /dev/cu.usbserial-10
Different OS versions may have different port names, and the absence of ports may indicate a connection, driver or hardware related issue. See Troubleshooting for more info.
Multilingual support¶
Prefer a different language? Krux has support for multiple languages. Once at the start screen, go to Settings
, followed by Locale
, and select the locale you wish to use.
Upgrade via microSD card¶
Once you've installed the initial firmware on your device via USB, you can either continue updating the device by flashing or you can perform upgrades via microSD card to keep the device airgapped.