Periodically check this file as the setup workflow will change/improve.
The following hardware is required:
The following software is required:
fastboot
To install on Ubuntu: sudo apt-get install android-tools-fastboot
At a high level, these are the steps for getting a HiKey development environment fully working:
Once the system is correctly configured, your development workflow should resemble a workflow on other hardware (repeated builds done with fx build, a persistent instance of fx pave to automatically update the hardware, and a persistent instance of fx log to capture console output).
To build zircon, invoke the following command from the top level Zircon directory (ensure that you have checked out the ARM64 toolchains). For more information, see docs/getting_started.md:
gn gen build-zircon ninja -C build-zircon
First, get the device to show up on your dev host machine as a serial device. Following that, install and configure a console app.
If using a mezzanine board, follow the instructions included with it. Additional tips:
Take care not to install the mezzanine board backwards on the connector. The micro-USB port should face outward; the corner pushbutton should be in the center of the HiKey board.
Some standard micro-USB cables have a button to enable/disable the data lines. When using one of these cables, ensure that these lines are enabled - the LED should be amber (not green).
The mezzanine board receives power through the micro-USB cable, so power need not be applied to the main HiKey board yet.
If using a FTDI-style serial adapter cable:
The signals are available on the 40 pin LS connector (reference)
This means that for a common FTDI style adapter:
(Optional) an active low reset is available on pin 6 of the 40 pin LS connector. A jumper wire intermittently shorted from this pin to GND (shields of the connectors are all grounded) can provide an easy way to reset the board and place it in fastboot mode.
Once you have correctly configured the hardware (via either method), the device should appear to your host machine as a USB-connected UART, listed in your /dev directory as /dev/ttyUSB0 (or USB1, etc). If this is not the case, you may have forgotten to enable the data lines (LED should be amber), or you may have a bad micro-USB cable or mezzanine board. Regardless, do not proceed until your HiKey board is detected and enumerated in the /dev directory as a tty device.
Use a host application such as screen or putty to connect to the serial port and provide console functionality. Use a baud rate of 115200.
Example commands using screen:
screen /dev/ttyUSB0 115200,-ixoffCtrl-a, Esc to enable scrolling (then k-up, j-down, q-done scrolling)Ctrl-a, d to detach from the session (screen -r -d to reattach)Ctrl-a, \ to kill all screen sessions.If you receive an error when connecting to your tty/USBn, you may need to run your serial console application as sudo. Alternately, you can add a udev rule that allows applications to connect to this device:
Create file /etc/udev/rules.d/99-ttyusb.rules containing the following:
SUBSYSTEM=="tty", GROUP="dialout"
Then sudo udevadm control --reload-rules
Connect the power supply if you have not already. If the power plug doesn't seem to fit, you may have forgotten to get a DC adapter. The power plug for the HiKey boards has a 4.75mm diameter and 1.7mm center pin, whereas most DC power supplies in this class have a 5.5mm diameter and 2.1mm center pin.
To flash the board, it must be connected to your workstation via the USB-C OTG connection on the HiKey960 main board. Additionally, the HiKey960 must be in fastboot mode. You can enter fastboot in one of two ways:
DIP Switch method Use the switches on the back of the board. (Older HiKeys may have jumpers instead of DIP switches.) To boot into fastboot mode, the switches should be in the following positions:
Auto Power up(Switch 1) closed/ON Recovery(Switch 2) open/OFF Fastboot(Switch 3) closed/ON
Once the switches are in these positions, unplug/plug power or reset the board. It will then boot into fastboot mode, awaiting commands from the host. If you are using the serial adapter cable, just a reminder that this can be done with the jumper wire on pin 6, as mentioned earlier.
Note: after you have performed the last of your flash operations, you want the device to boot normally going forward, so you should open (turn OFF) DIP switch 3 before your final boot (once firmware and Zircon updates are complete, before booting into Zircon for the first time).
Double-Reset method Using the button on the mezzanine board, reset the board, then reset it again after seeing the following console messages:
C3R,V0x00000016 e:113 C0R,V0x00000017 e:66 C1R,V0x00000017 e:66 C2R,V0x00000017 e:66 C3R,V0x00000017 e:66
The second reset instructs the board to restart into fastboot for the next boot cycle only. The timing on this double-reset is a little tricky, but you will know you got the timing right if you see the following console messages at the end of the boot spew:
usbloader: bootmode is 4 usb: [USBFINFO]USB RESET usb: [USBFINFO]USB CONNDONE, highspeed usb: [USBFINFO]USB RESET usb: [USBFINFO]USB CONNDONE, highspeed usbloader: usb: online (highspeed) usb: [USBFINFO]usb enum done
These messages confirm that the device has restarted into fastboot mode. If you do not see these messages, use the button to reset the board and try again until you are successful.
As a reminder, with this method, the DIP switches on the HiKey should remain in normal mode (closed/ON open/OFF open/OFF), not the ‘fastboot’ mode mentioned in the previous option.
Once the board is in fastboot mode (regardless of which method you use), it is ready to be flashed with firmware updates and/or the Zircon boot image.
We have run into inconsistent behavior between different HiKey 960 boards, depending on the low level firmware came installed on the device. We recommend setting up your board with known good firmware from the Android AOSP project.
To install firmware, put your board in fastboot mode and run the following:
./scripts/flash-hikey -f
If the hikey gets into a bad state you can try the recovery mechanism. The script should automate the process, including reinstalling the firmware. You first need to put the device into recovery mode:
Auto Power up(Switch 1) closed/ON
Recovery(Switch 2) closed/ON
Fastboot(Switch 3) open/OFF
Then run:
./scripts/flash-hikey -r
The recovery process communicates with the device over the USB-C cable, but it can be a bit flaky at times. If the script complains that it can't open the serial device first check what serial devices are connected (ls /dev/serial/by-id/) and make sure the script is using the correct device. You can specify which serial port to use with -p. Sometimes you just need to try a few times or power cycle the device. Occasionally the script will fail when attempting to install firmware, which can usually be fixed by starting again.
Once the HiKey board is in fastboot mode, run the following script from the zircon root directory to flash the necessary files onto the board:
./scripts/flash-hikey
If you would like to boot future kernels via the network, instead of flashing them directly, then run the script with the -m option.
./scripts/flash-hikey -m
This is the last flash update, and all subsequent boots should use normal mode (not fastboot or recovery). If you used the DIP Switch method to place the board in fastboot mode, you should flip the fastboot switch (switch 3) back to open/OFF before running this script, so that it will boot into Zircon after flashing (otherwise, it will boot back into fastboot mode).
If you used the double-tap reset method to place the board into fastboot mode, no further reconfiguration is needed: the board will boot into the kernel after it completes flashing.
For now, the ethernet connectivity needed for zedboot is actually provided by zircon via USB. This is automatically enabled on the HiKey USB-C connector, if it is changed from host mode into device mode. If all flash steps appear to complete successfully, but the device does not restart into Zedboot, you may need to manually place the device into USB ‘device’ mode. Enter the following command in your console:
usbctl mode device
This step must be repeated each time the device is fully powered-down/up. At some point in the near future, the Fuchsia build will include support for USB NICs via USB-A, at which time this usbctl step will be unnecessary.
Once your device restarts and displays ‘Zedboot’ in the console, the setup process is complete. You can now use your usual build, boot and log commands. When powering up (not simply resetting) the device, you may need to press the reset button for the device to show up again as /dev/ttyUSBn. Recall that this is needed before connecting the serial console and interacting with the device.
Note: the following requires fastboot in your execution path.
To install firmware, put your board in fastboot mode and run the following:
git clone https://android.googlesource.com/device/linaro/hikey hikey-firmware git -C hikey-firmware checkout 972114436628f874ac9ca28ef38ba82862937fbf fastboot flash ptable hikey-firmware/installer/hikey960/ptable.img fastboot flash xloader hikey-firmware/installer/hikey960/sec_xloader.img fastboot flash fastboot hikey-firmware/installer/hikey960/fastboot.img fastboot flash nvme hikey-firmware/installer/hikey960/nvme.img fastboot flash fw_lpm3 hikey-firmware/installer/hikey960/lpm3.img fastboot flash trustfirmware hikey-firmware/installer/hikey960/bl31.bin
This installs all the AOSP firmware except Android itself. To use a different bootloader altogether (not the one from AOSP), first complete the above commands and then install your bootloader.
The console is especially important because the HiKey builds of Fuchsia do not yet support the HDMI port. Related to this, only USB is supported for audio input/output. NOTE: all USB audio devices must be High-Speed (not just USB 2.0 compatible, which might be Full-Speed or High-Speed). If the USB audio device is enumerated as 12Mb/s, then it is Full-Speed.