To get the exact errors causing boot issues, we recommend getting an UART cable: Libre Computer Board Debug Serial UART Connection and Setup Guide
Top 5 Gotchas
- Get a good power supply capable of 1.5A or higher. Our CC boards typical use around 1.0A, each USB device use somewhere between 0.1A to 1A. The cable and connector quality and seating is as important as the power supply. If your board spontaneously reboots without any error message, it’s a power problem.
a) If planning to use a spinning hard drive or SSD, put a powered hub between the board and the device as they exceed normal USB power budget.
b) For power supplies where the cable is not integrated and requires a USB Type A cable, there may be a sufficiently high voltage drop over the wire depending on the wire gauge to affect deliverable power.
c) Transient voltage drops will cause stability issues when running system loads. If your application or system is unstable, check the 5V pin with an oscilloscope. Voltage swings indicate poor power delivery. - Get a good MicroSD card with at least 20MB/s sequential write speed. Slow MicroSD cards will result in a poor experience. Sometimes a slow MicroSD card means the flash cells are dying and the card needs to be replaced. Our software will check for MicroSD card data corruption and switch to read-only mode to prevent further damage to your data. It is recommended to backup your data and replace the card when this happens.
- Make sure you use proper tools to flash correctly. Incorrect images or incomplete flash will not boot. We recommend running a verify pass to make sure the data is correctly written. Also make sure that the image file matches your board model. On Windows, make sure to show file extensions so you can tell if the file has been decompressed. Flashing a compressed image will not boot.
- Each image lists the username and password in the release notes on the download page. We spent time to write them, read them.
- Most of our images will update in the background (unattended-upgrade service from the distributions) on first boot so performance will be slow until the updates complete. You can speed this up by manually running
sudo eatmydata apt dist-upgrade
in a terminal before the update service runs. - Failure to do these will result in a lot of wasted time as they account for 99% of user problems.
If you’re new to single board computers or coming from Raspberry Pi, there can be a few gotchas or conceptual differences to be aware of. We outline how the process works and how you can quickly figure out what the issue is.
The normal process flow is as follows:
- Download Compressed Image (eg. file+model.img.xz)
- Extract Compressed Image (eg. file.img)
- Flash Extracted Decompressed Image to Bootable Storage Medium (MicroSD card)
- Insert Bootable Storage Medium into Board
- Provide Sufficient Power to Board
- Board Boots u-boot Bootloader from Storage Medium
- u-boot Bootloader Loads EFI Bootloader (GRUB)
- EFI Bootloader Boots Linux
- Linux Boots systemd
- systemd starts services and applications
- Download Compressed Image
a. Make sure to download the correct file for your board to get the correct bootloader. The +model suffix on the file name should match your board or it will not work.
b. Make sure to check the SHA256SUM of the downloaded file to verify correctness. - Extract Compressed Image
a. Use a decompression tool to extract the uncompressed image.
b. Skipping this step will result in an image that will not boot. - Flash Extracted Decompressed Image to Bootable Storage Medium
a. Make sure the bootable medium is glitch free by running verify on written data.
b. Make sure flashing tool does not perform any skips or write optimizations.
c. Flashing is not copying the file! Flashing writes the raw data to the disk while copying writes the data on top of a filesystem. Copying files will result in the board not booting at all.
d. Etcher or Raspberry Pi Imager are known to not produce bit accurate data on occasion. If the MicroSD card is not flashed correctly, you will not get any HDMI output. See the individual board behavior guide at the bottom. - Insert Bootable Storage Medium into Board
a. Make sure the storage medium is not damaged. MicroSD cards can break if the board is installed or removed from cases without removing the card first. Hair-line fractures will cause short-circuit so do not try to use them if you notice any fractures or damage! Short-circuit can cause the card to get really hot and burn your skin.
b. We recommend SanDisk and Samsung MicroSD because those brands have a history of making reliability products. There are knockoffs that appear on Amazon. Kingston, PNY, and other brands have put out unreliable products in the past so we do recommend them. - Provide Sufficient Power to Board
a. Make sure your power supply provides enough voltage and current for the board you are using. Boards cannot be powered from computer USB ports which usually only provide 500mA or 0.5A. Most boards need a minimum of 1.5A.
b. Do not trust the label unless the power supply is from a reputable brand.
c. Certain power supplies can cause problems if they exceed 5.5V and cause certain board features to stop working.
d. Check for bent, damaged, or corroded pins and loose connections. They reduce deliverable power.
- Board Boots u-boot Bootloader from Storage Medium
a. If you followed steps 1 through 5 correctly, the board should boot up. LEDs on the board will change if the bootloader is successfully loaded from the storage medium.
Please reference board specific guides for additional information and steps: