LeMaker Wiki

Illustration for LeMaker Wiki documentation

Summary

The LeMaker Wiki is an archive of technical notes for LeMaker boards and related software. The goal is to provide practical, reproducible steps: what to check first, what a healthy system looks like, and which internal pages to open next.

If you are starting from scratch, begin with a board-appropriate quick start and collect a short baseline report (kernel, storage layout, logs). That baseline is the fastest way to recognise when a later change has introduced a regression.

Who this is for

New board owners, developers validating images, and anyone returning to older documentation who needs a stable starting point and a recovery-minded bring-up flow.

What you'll do

  • Pick a starting page for your board or task (login, GPIO, bootloader/kernel work).
  • Prepare a minimal first-boot setup so you can reproduce results.
  • Capture a baseline boot report and keep it for later comparisons.
  • Run verification checks after any change to storage, kernel, or networking.
  • Use troubleshooting shortcuts to isolate power/storage problems early.

Start here

Common tasks

  • Flash / validate an image: verify checksum, confirm device selection, then capture a baseline boot report.
  • Get access: confirm network, SSH, and (optionally) serial console so you can recover from changes.
  • GPIO work: confirm pinout expectations, then test a minimal known-good example before building a larger project.
  • Bootloader/kernel work: change one variable at a time and keep the last known-good combination available.

Quick checklist

  • Stable PSU and cable (avoid undervoltage-induced resets).
  • Known-good storage (SD/eMMC) and a reliable writer.
  • Ethernet for first boot (recommended).
  • Optional: USB'TTL serial adapter (3.3V) for recovery and early boot logs.
  • Verified image file and checksum.
  • A text file or notes area to store a baseline boot report.

Steps / guidance

1. Choose your entry point

If you are new to LeMaker boards or returning after time away, start from the Main Page. It provides curated links to board-specific hubs (Banana Pi/Pro, HiKey960, LeMaker Guitar) and common tasks (GPIO, bootloader, login).

If you already know your board model and task, jump directly to the relevant hub page from the "Start here" section above.

2. Establish access method

Before making any changes, ensure you have at least one reliable way to log in:

  • SSH over Ethernet (recommended for headless): Simplest method. Requires network connectivity and default credentials. Check Log in to the Banana Pi for common defaults (root/bananapi, pi/bananapi, etc.).
  • Local console (HDMI + keyboard): Useful when network is not yet configured or you are debugging network issues.
  • Serial console (3.3V USB-to-TTL): Essential for bootloader work, early kernel debugging, or recovering from misconfigurations that lock you out of SSH. Connect TX, RX, and GND to the board's debug header (consult your board's pinout).

Test access with a simple command (uname -a) before proceeding to configuration changes.

3. Confirm storage layout and health

Verify that storage is detected correctly and filesystems are mounted without errors:

lsblk           # List block devices and partitions
blkid           # Show UUIDs and filesystem types
df -h           # Check mount points and free space
dmesg | grep -E "mmc|sd"  # Look for SD/eMMC errors

If you see I/O errors, filesystem corruption warnings, or "read-only" remounts, replace the storage media before continuing. Many intermittent problems are caused by failing SD cards or eMMC modules.

4. Capture a baseline boot report

Save the following output to a text file on your workstation. This baseline lets you compare behaviour before and after changes (kernel updates, device tree modifications, network reconfiguration):

uname -a                          # Kernel version and architecture
cat /proc/cpuinfo | head -n 20   # CPU model and features
ip a                              # Network interfaces and IP addresses
ip r                              # Routing table
systemctl --failed               # Failed services
journalctl -b -p err | tail -n 80  # Boot errors
dmesg | tail -n 50               # Recent kernel messages

Name the file baseline-BOARDNAME-YYYY-MM-DD.txt and store it safely. If the board stops working after a change, you can diff the new output against the baseline to identify what broke.

5. Change one variable at a time

When modifying the system (kernel, device tree, bootloader, packages, network configuration), change only one component per iteration:

  • Kernel or device tree: Test boot and basic functionality before upgrading packages.
  • Bootloader (U-Boot): Capture serial console output before and after. Keep the old U-Boot binary available for rollback.
  • Network configuration: Verify access via serial or local console before applying changes that might lock you out.
  • Package updates: Run sudo apt update && sudo apt upgrade in one session, then reboot and verify before additional changes.

After each change, re-run the verification checks and compare output to your baseline.

Verification checks

Use at least two after any significant change:

uname -a
ip a
lsblk
dmesg | tail -n 50
journalctl -b -p err | tail -n 120

Troubleshooting

Boot failure or random resets

  • Symptoms: Power LED on, no activity; random resets during boot or operation; no serial output.
  • Common causes: Undervoltage (weak PSU, thin cable), failing SD card, wrong image for board, bootloader corruption.
  • Steps:
    1. Swap power supply and cable. Use a 5V 2A or higher supply with short, thick cable.
    2. Try a different SD card or eMMC module. Flash from a freshly downloaded and verified image.
    3. Remove all USB peripherals except keyboard (if using local console).
    4. Connect serial console to capture bootloader and kernel messages. Look for "panic", "fail", or error codes.
    5. If using a modified U-Boot or device tree, revert to stock configuration and test.
  • Related: Log in to the Banana Pi, Building U-Boot

Network access failure

  • Symptoms: Board boots to login prompt but no IP address; cannot SSH; DHCP lease not appearing in router.
  • Common causes: Ethernet cable fault, interface not brought up, DHCP client not running, DNS misconfiguration.
  • Steps:
    1. Check link LEDs on Ethernet port. Try different cable and router/switch port.
    2. Run ip a. If eth0 shows "state DOWN", bring it up: sudo ip link set eth0 up.
    3. Check for DHCP lease: ip r should show a default gateway. If missing, run sudo dhclient eth0.
    4. Verify DNS: cat /etc/resolv.conf should list nameservers. Test with ping -c 3 8.8.8.8.
    5. Review logs: journalctl -u NetworkManager or journalctl -u systemd-networkd.
  • Related: Network setup notes (main site), Login defaults

GPIO not working

  • Symptoms: Pin state does not change; permission errors accessing /sys/class/gpio; conflicts with other functions.
  • Common causes: Wrong pin numbering scheme, pin already used by another function (I2C, SPI, UART), permission issues.
  • Steps:
    1. Confirm pinout using board-specific documentation. Check if you are using physical, BCM, WiringPi, or SoC numbering.
    2. Verify pin is not already exported: ls /sys/class/gpio/.
    3. Check user permissions: sudo usermod -aG gpio $USER (logout/login required).
    4. Test with minimal example (LED blink) before complex circuits.
    5. For multiplexed pins, check device tree configuration. Some pins default to I2C/SPI and require DT changes for GPIO use.
  • Related: WiringPi, GPIO library documentation

Bootloader or kernel changes cause boot failure

  • Symptoms: Board does not boot after updating U-Boot, changing device tree, or installing new kernel.
  • Common causes: Incompatible U-Boot/kernel combination, wrong device tree for board variant, missing kernel modules.
  • Steps:
    1. Keep a known-good SD card with working configuration as backup. Swap to this card to recover.
    2. If you can access U-Boot via serial console, manually boot from old kernel: setenv bootargs ...; bootm ....
    3. Check for typos in boot.scr or uEnv.txt. Re-generate from known-good template.
    4. Verify device tree matches board variant. Run ls /boot/*.dtb and confirm correct DTB is referenced in boot script.
    5. If kernel panics, check for missing initramfs or root filesystem UUID mismatch.
  • Related: Building U-Boot and kernel, FEX Configuration

FAQ

What is this wiki for?

This wiki contains archival technical documentation for LeMaker boards, including GPIO library notes, bootloader/kernel build workflows, and legacy configuration systems (FEX/script.bin). For current quick-start guides, OS downloads, and product specifications, visit the main site at www.lemaker.org.

Which board should I start with?

Check the silkscreen on your board or compare the port layout with product photos. Banana Pi/Pro have SATA connectors; Banana Pro has WiFi antenna; HiKey960 has PCIe slot; LeMaker Guitar is smaller form factor. Once identified, go to the corresponding hub page from the "Start here" section.

Do I need a serial console?

Not for typical usage (flashing images, running applications). Serial consoles are essential for bootloader debugging, early kernel work, recovering from SSH lockouts, or diagnosing boot failures when no video output is available. Use a 3.3V USB-to-TTL adapter (NOT 5V) and connect TX, RX, GND to the board's debug header.

Can I use Raspberry Pi tutorials for LeMaker boards?

Partially. Userspace tools (Python libraries, SSH configuration, package management) are often compatible. However, GPIO pin numbering, bootloader commands, kernel compilation, and device tree configurations differ. Always verify board-specific details before assuming compatibility.

How do I know if my image uses FEX or device tree?

Check the boot partition after booting: ls /boot/. If you see script.bin, the image uses FEX (legacy, for 3.4.x kernels). If you see .dtb files, it uses device tree (modern, for 4.x+ kernels). Use the FEX Configuration page only for legacy systems.

What GPIO numbering scheme should I use?

It depends on your library or script. Physical numbering (pin 1-40 on header), BCM (Broadcom GPIO numbers used by Raspberry Pi), WiringPi (WiringPi library numbering), or SoC naming (Allwinner PA/PB/PC/PD). Always check the pinout diagram on your board's hub page and confirm which scheme your code expects.

Can I boot from USB or SATA without an SD card?

On Banana Pi/Pro, U-Boot typically resides on the SD card and loads the kernel/rootfs from SATA or USB. Full SATA-only boot (no SD card) requires special U-Boot configuration and is not supported by default. Some community images enable this. Check the bootloader documentation for your board.

How do I recover from a bad bootloader or kernel update?

Keep a known-good SD card with a working system as backup. If the board does not boot, swap to the backup card. If you have serial console access and can reach U-Boot, you may be able to manually boot from an alternate kernel or revert boot script changes. Always test risky changes on non-production boards first.

Why does my board reset randomly or show filesystem corruption?

Almost always caused by undervoltage (weak PSU, thin/long cable) or a failing SD card. Swap the power supply and cable first, then try a new high-endurance SD card (SanDisk Extreme, Samsung EVO, Kingston Industrial). Cheap or old SD cards fail unpredictably and cause symptoms that look like software bugs.

Where can I get help if I am stuck?

Check the docs and search for your board model and error message. For kernel or driver issues on Allwinner SoCs, the linux-sunxi community is active. For bootloader questions, consult U-Boot documentation and mailing lists.

Common mistakes

  • Debugging software before swapping PSU/cable and storage when behaviour is inconsistent.
  • Changing multiple variables at once (kernel + DTB + packages + network).
  • Running headless without a recovery path (serial or local console).
  • Not saving a baseline boot report while the system is healthy.

Author: LeMaker Documentation Team
Last updated: 2026-01-11