README.md

   1 # Lichee Pi Nano Bootable Linux Image (Buildroot)
   2
   3 ![Lichee Pi Nano with LCD screen](licheepi-nano-lcd.jpg)
   4
   5 [Lichee Pi Nano](http://nano.lichee.pro/index.html) ([English article](https://www.cnx-software.com/2018/08/17/licheepi-nano-cheap-sd-card-sized-linux-board/)) is a very small single-board computer that is about the size of an SD card. It can run Linux. There is a good amount of official documentation on the [original manufacturer site](http://nano.lichee.pro/get_started/first_eye.html) (in Chinese, but easily readable thanks to Google Translate). However, the tooling used to build the full card/SPI-Flash images is mostly made up of custom shell scripts, and is not always easy to extend or maintain.
   6
   7 This repository contains a Buildroot config extension that allows all of those build steps to be handled via a single Buildroot `make` command. That means fully building the U-Boot image, Linux kernel, the rootfs image and the final partitioned binary image for flashing onto the bootable SD card (SPI-Flash support is possible but not handled here yet).
   8
   9 All the configuration is packaged as a `BR2_EXTERNAL` Buildroot extension to avoid the need to fork the entire Buildroot repo. You can fork this project or integrate it as a Git subtree to customize your own OS build on top of it as needed.
  10
  11 This effort heavily borrowed from the work done by the FunKey Zero project: https://github.com/Squonk42/buildroot-licheepi-zero/. The latter targets Lichee Pi Zero, a sibling board to the Nano, but I was able to adapt it for use with Nano, and also converted the content to be a `BR2_EXTERNAL` extension rather than a full Buildroot fork.
  12
  13 The config files should be reasonably readable, e.g. here is the main Buildroot defconfig file: [configs/licheepi_nano_defconfig](configs/licheepi_nano_defconfig).
  14
  15 ## Dependencies
  16
  17 - Vagrant (if building inside the VM)
  18   - vagrant-vbguest plugin
  19   - vagrant-disksize plugin
  20 - Ubuntu Bionic or similar (see Vagrant VM)
  21 - Buildroot 2020.02 (auto-downloaded by VM, otherwise see [project downloads page](https://buildroot.org/download.html))
  22
  23 Buildroot takes care of downloading any further dependencies automatically.
  24
  25 ## Building the Image
  26
  27 First, clone this repo:
  28
  29 ```sh
  30 git clone [email protected]:unframework/licheepi-nano-buildroot.git
  31 ```
  32
  33 If not using Vagrant, ensure build scripts are executable:
  34
  35 ```sh
  36 chmod a+x licheepi-nano-buildroot/board/licheepi_nano/*.sh
  37 ```
  38
  39 If using Vagrant VM to perform the build:
  40
  41 ```sh
  42 cd licheepi-nano-buildroot # location of this repo's files
  43
  44 # install required plugins
  45 vagrant plugin install vagrant-vbguest
  46 vagrant plugin install vagrant-disksize
  47
  48 vagrant up
  49 vagrant ssh
  50 ```
  51
  52 Otherwise, download Buildroot and extract it into a folder that is separate from this repo's files.
  53
  54 Before building, install these Ubuntu packages:
  55
  56 ```sh
  57 sudo apt-get install swig python-dev fakeroot devscripts
  58 ```
  59
  60 If there are still error messages during later build, try installing these (sorry, did not clean up the list yet, some might be unnecessary):
  61
  62 ```sh
  63 sudo apt-get install -y chrpath gawk texinfo libsdl1.2-dev whiptail diffstat cpio libssl-dev
  64 ```
  65
  66 Now, if you are using Vagrant your main Buildroot checkout will be in `/home/vagrant/buildroot-2020.02`. Note that it is not the same folder as the location of this board-specific config repo (which would be `/vagrant` if using the Vagrant VM). The Buildroot folder will be the main spot where actual compilation happens, so chdir inside it:
  67
  68 ```sh
  69 # if not using Vagrant VM, cd <your_buildroot_folder>
  70 cd /home/vagrant/buildroot-2020.02
  71 ```
  72
  73 Then, generate initial build configuration:
  74
  75 ```sh
  76 # if not using Vagrant VM, change "/vagrant" to be location of this repo's files
  77 BR2_EXTERNAL=/vagrant make licheepi_nano_defconfig
  78 ```
  79
  80 The above generates a `.config` file in the Buildroot checkout folder - this is the build configuration for `make` later on. Customize it if needed:
  81
  82 ```sh
  83 make menuconfig
  84 ```
  85
  86 Proceed with the build:
  87
  88 ```sh
  89 make
  90 ```
  91
  92 The build may take 1.5 hours on a decent machine, or longer. For a faster build, try changing configuration to use external toolchain. I have tried building with Linaro GCC 7.5, but ran into crashes at time of `/sbin/init` invocation (issue with bundled glibc?).
  93
  94 A successful build will produce a `output/images` folder. That folder contains a `sdcard.img` file that can now be written to the bootable SD card. Note that if Vagrant VM is used, the `output/images/sdcard.img` file first needs to be copied back out to the host machine, since it is unlikely that your VM has direct access to the SD card writer.
  95
  96 Example command to write image to SD card on Linux host:
  97
  98 ```sh
  99 sudo dd if=YOUR_HOST_FOLDER/sdcard.img of=DEVICE # e.g. /dev/sd?, etc
 100 ```
 101
 102 On Windows, Rufus or Balena Etcher can be used, or another utility like that.
 103
 104 ## LCD Screen Support
 105
 106 This build includes a customized DTS file that supports a 480x272 TFT screen (plugged into the 40-pin flex-PCB connector on the board). The source kernel branch comes with a pre-existing DTS file with support for 800x480 TFT resolution: in `menuconfig` change to use "in-tree" `suniv-f1c100s-licheepi-nano` DTS file, and update `boot.cmd` and `genimage.cfg` to reference that device tree as well.