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.11.0.zip matches the hash in krux-v24.11.0.zip.sha256.txt
The signature file krux-v24.11.0.zip.sig can be verified with the selfcustody.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.11.0.zip
./krux verify krux-v24.11.0.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.11.0.zip && cd krux-v24.11.0

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.