This guide shows you how to install Fuchsia on a Khadas VIM3. The installation process will probably take between 1 to 3 hours.
Running Fuchsia on VIM3 is useful if you want to explore how Fuchsia works on relatively low-cost real hardware that supports many kinds of peripheral devices. See Appendix: Feature support for details on which VIM3 features Fuchsia supports.
If you just want to explore Fuchsia with the lowest friction possible, check out Get started with the Fuchsia SDK instead.
See Appendix: Support if you have any trouble completing this guide.
If you've never tinkered with electronics you might find this guide difficult to complete. For example, this guide assumes that you know how to hook up serial cable wires to GPIOs to read logs and send commands over a serial communication program.
This guide also assumes that you're comfortable with CLI workflows such as building Fuchsia from source.
You'll need all of the following hardware and software to complete this guide:
A Khadas VIM3 single-board computer.
Caution: It's unknown whether Fuchsia will run on the Basic model VIM3. This guide was validated with the Pro model VIM3.
A desktop or laptop computer that's running Linux and has 2 USB ports available.
Key Term: This desktop or laptop is called the host throughout the rest of this guide.
Caution: A macOS host may work but these instructions have not been validated with macOS. Building Fuchsia on a remote Linux computer and then attempting to flash Fuchsia onto the VIM3 with a local macOS host is known to not work.
Note: This guide assumes that your Linux distribution has Debian commands like apt.
A power supply of at least 24W to your host. The VIM3 can draw that much power when DVFS is enabled.
A working Fuchsia development environment on your host. In other words you should be able to build Fuchsia from its source code on your host. See Build Fuchsia.
A USB-C to USB-* cable that supports both data and power delivery. The USB-C side is for the VIM3. The other side can be whatever USB type your host supports.
The following is optional:
See the VIM3 collection in the Khadas shop for examples of compatible accessories.
Note: All the links in this section are only for your convenience. You don't need to buy from these exact stores or these exact parts.
If you don't already have an [in-tree][glossary.in-tree] environment set up, you should start the process now because it can take a while to complete:
fx set core.vim3 instead.Note: The rest of this guide assumes that your Fuchsia source code directory is located at ~/fuchsia.
Important: Whenever you see an fx command this guide assumes that your working directory is within your in-tree Fuchsia source code checkout. In other words this guide assumes that you run cd ~/fuchsia before running any fx commands.
You'll use the Fuchsia development environment to build the Fuchsia image for VIM3 and run an in-tree CLI tool for flashing the Fuchsia image onto the VIM3.
Set up the VIM3 to communicate with your host:
Connect the VIM3 and your host to each other with the USB-C to USB-* cable. The white LED on the VIM3 should turn on.
Caution: Don't put a USB hub between the VIM3 and your host. The hub may make it harder for your VIM3 and host to detect and communicate with each other.
This connection is used to power and flash the VIM3 with fastboot.
Connect the serial cable wires to the VIM3's GPIOs:
GND to pin 17.
RX (in to VIM3) to pin 18.
TX (out from VIM3) to pin 19.
Don't connect the power wire of your serial cable to any VIM3 GPIO. The VIM3 is getting power through the USB cable.
Tip: Pins 1, 20, 21, and 40 are labeled on the circuit board.
Caution: In general the colors for TX and RX wires are not standardized. For example your RX wire may be blue or green.
See Serial Debugging Tool for an example image of how your serial wires should be connected to the VIM3.
Make sure that you can view the logs being sent over the serial cable:
Open Fuchsia's serial console:
fx serial
Note: If fx serial detects multiple USB devices and you don't know which one to use, try disconnecting the serial cable from your host, running ls /dev/ttyUSB*, then re-connecting the serial cable and running the command again. If you see no difference when running ls /dev/ttyUSB* try ls /dev/tty* or ls /dev/* instead.
Press the reset button on the VIM3. The reset button is the one with the R printed next to it on the circuit board. See VIM3/3L Hardware for a diagram. In your serial console you should see human-readable logs.
In later sections of this guide you‘ll update the bootloader and OS on the VIM3. These updates don’t work unless you completely erase the eMMC first:
Press the reset button on your VIM3.
Right after you press the reset button, start repeatedly pressing the Space key as your VIM3 boots up. Make sure that your cursor is focused on your serial console. The bootloader process should pause and your serial console should show a kvim3# prompt. Your serial console is now providing you access to the U-Boot shell.
Run the following command in the U-Boot shell:
store init 3
Your serial console logs should verify that the eMMC was correctly erased.
See Erase eMMC for more details.
The Android image that ships by default on the VIM3 does not support Fuchsia installation. If you just received your VIM3 from Khadas you must update your Android image:
Click the following URL to download the updated Android image: https://dl.khadas.com/firmware/vim3/android/VIM3_Pie_V211220.7z
Extract the compressed archive file (VIM3_Pie_V211220.7z). After the extraction you should have a VIM3_Pie_V211220 directory with an update.img file in it.
Follow the instructions in Install OS into eMMC. When running aml-burn-tool the value for the -i flag should be the path to your update.img file. Your command should look similar to this:
aml-burn-tool -b VIM3 -i ~/Downloads/VIM3_Pie_V211220/update.img
Caution: Make sure that you're following the instructions for Ubuntu and VIM3 by clicking the Install on Ubuntu and VIM3/VIM3L tabs. These instructions are not shown by default.
Tip: The TST Mode workflow is probably the easiest and fastest way to get your VIM3 into Upgrade Mode.
If the white and red LEDs on your VIM3 are off and the blue LED is on, it means that your VIM3 is in sleep mode. Try putting your VIM3 back into Upgrade Mode and then pressing the reset button again.
At this point the white LED on your VIM3 should be on and you should see logs in your serial console after you press the reset button on your VIM3.
Flash Fuchsia's custom bootloader onto the VIM3:
Access the U-Boot shell again by pressing the reset button and then repeatedly pressing the Space key in your serial console. When your serial console shows the kvim3# prompt, you're in the U-Boot shell.
In your U-Boot shell run the following command:
fastboot
You should see the following logs in your serial console:
g_dnl_register: g_dnl_driver.name = usb_dnl_fastboot USB RESET SPEED ENUM USB RESET SPEED ENUM
If you see the first line (g_dnl_register: g_dnl_driver.name = usb_dnl_fastboot) but not the lines after that, try using a different USB-C to USB-* cable and make sure that it supports both data and power delivery.
Open a new terminal window in your host and run the following commands:
cd ~/fuchsia/prebuilt/third_party/fastboot ./fastboot flashing unlock ./fastboot flashing unlock_critical ./fastboot flash bootloader ~/fuchsia/prebuilt/third_party/firmware/vim3/u-boot.bin.unsigned ./fastboot reboot
Caution: Installing the Android SDK Platform Tools probably installed another instance of fastboot on your host. When working with Fuchsia, remember to use the [in-tree][glossary.in-tree] version of fastboot at ~/fuchsia/prebuild/third_party/fastboot/fastboot. The fastboot protocol allows arbitrary vendor protocol extensions and Fuchsia may rely on this functionality in the future.
Note: You can also build the custom bootloader (u-boot.bin.unsigned) from source: https://third-party-mirror.googlesource.com/u-boot/+/refs/heads/vim3
Complete these steps to install Fuchsia onto your VIM3 for the first time. You only need to do these steps once. Once you have Fuchsia running on your VIM3, the Update your Fuchsia image workflow is a faster way to update the Fuchsia image on your VIM3.
If you just ran the ./fastboot reboot command from the last section then your VIM3 should already be in fastboot mode. You can check your fx serial logs to confirm. Otherwise press the reset button and then repeatedly press the F in your fx serial console until you see USB RESET and SPEED ENUM again.
Important: You have to press the F key now to enter fastboot mode. Previously you pressed the Space key.
From a separate terminal on your host run the following command:
fx flash
Your VIM3 is now running Fuchsia!
Complete these steps when you already have Fuchsia running on your VIM3 and want to update the Fuchsia image on your VIM3.
Run the following command from a terminal on your host:
fx serve
Leave this command running.
Make some changes in your in-tree Fuchsia checkout and build the changes.
Open a new terminal window and perform an OTA update of the Fuchsia image on your VIM3:
fx ota
Do these steps if you've bricked your VIM3 and need to “factory reset” it:
Fuchsia currently supports these features of the VIM3:
These features are under development and may not be supported:
The following features are not supported, but might be added by future contributions:
These features are not supported and are unlikely to be added:
To update the boot splash screen to be the Fuchsia logo, run the following command from a host terminal while the VIM3 is in fastboot mode:
fastboot flash logo ~/fuchsia/zircon/kernel/target/arm64/board/vim3/firmware/logo.img