Buildroot creates Embedded Linux images, 
customised for specific tasks. 
It is a modular system for generating images, 
quite well suited to Internet of Things (IoT) applications. 
It can build runtime systems, but cannot manage:

* packages
	* OpenWrt (or LEDE) may offer manageable packages
* compliation tools
	* if you need more complex images, consider Yocto

## SnapOS

Here is an example of using buildroot for a specific application. SnapOS is a wireless sound receiver 
with synchronisation to provide clean multi-room audio using Snapcast. For more on the software see https://github.com/artmg/MuGammaPi/wiki/multi-room-audio

### Compile image with buildroot

These instructions were developed for use on
Ubuntu derivatives.

```
# Check the latest long term stable version 
# https://buildroot.org/download.html
BUILDROOT_VERS=buildroot-2018.05.1 
DOWNLOAD_FOLDER=$HOME/Downloads

# Install Prereqs
sudo apt install build-essential git libncurses5-dev

## perhaps simpler to use git instead of download/unzip
#git clone -b 2018.02 https://git.buildroot.net/buildroot
#cd buildroot

cd $DOWNLOAD_FOLDER/
wget -qO- https://buildroot.org/downloads/$BUILDROOT_VERS.tar.gz | tar xvz

# Clone SnapOS
git clone https://github.com/badaix/snapos.git

# define SnapOS as an external to buildroot
cd $BUILDROOT_VERS
make BR2_EXTERNAL=$DOWNLOAD_FOLDER/snapos/buildroot-external/ snapos_rpi3_defconfig

# If you are testing, you can speed up recompiling using ccache: in Build options choose Enable compiler cache.
# NB if you want to add custom config files (network ids, ssh keys, etc) to the target during the build process, look for `Root filesystem overlay directories`

# if you want to check the menus for what is configured
make nconfig

# begin creating the image file
make
```

It could take hours for the build so be patient, maybe let it run overnight

### Flash the image to SD

NB: Although the compilation will work from a 
VirtualBox guest running ubuntu, 
this configuration can give issues when 
flashing images to microSD cards plugged into the host
from within the guest system. 
For more reliability, transfer the file directly onto 
a physical device with the SD card plugged in 
and flash the image from there. 


Note: this automation in the rest of this page 
is similar to that used in the pages below, 
so perhaps they could be merged at some point?

* [ArchLinuxArm install](https://github.com/artmg/MuGammaPi/wiki/arch-linux-install)
* [Raspbian basics](https://github.com/artmg/MuGammaPi/wiki/Raspbian-basics)
* [write Distro to flash](https://github.com/artmg/lubuild/blob/master/help/configure/write-Distro-to-flash.md) 
* [disks - rename](https://github.com/artmg/lubuild/blob/master/help/configure/disks.md#rename)

```
MEDIA_DEVICE=sdb
MEDIA_LABEL=SdLabel
NEWHOSTNAME=NewHostName
WIFI_SSID=MySsid
WIFI_PSK=MyPsk
SYSLOG_SERVER=MyLogSvr

IMAGE_FILE=output/images/sdcard.img

sudo dd bs=4M if=${IMAGE_FILE} of=/dev/$MEDIA_DEVICE conv=fsync status=progress
sync

# refresh partitioning without removal

sudo umount /dev/${MEDIA_DEVICE}1
sudo umount /dev/${MEDIA_DEVICE}2
sudo partprobe

sudo mkdir /media/$USER/osboot
sudo mkdir /media/$USER/osroot
sudo chmod 777 /media/$USER/osboot
sudo chmod 777 /media/$USER/osroot
sudo mount /dev/${MEDIA_DEVICE}1 /media/$USER/osboot
sudo mount /dev/${MEDIA_DEVICE}2 /media/$USER/osroot

sudo fdisk -l /dev/${MEDIA_DEVICE}

# if you want to relabel, then
SHORT_LABEL=${MEDIA_LABEL:0:8}
sudo dosfslabel /dev/${MEDIA_DEVICE}1 ${SHORT_LABEL^^}_OS
sudo e2label    /dev/${MEDIA_DEVICE}2 $MEDIA_LABEL\_disk
# display labels
sudo dosfslabel /dev/${MEDIA_DEVICE}1
sudo e2label    /dev/${MEDIA_DEVICE}2 


#### configure the networks

# set the hostname
sudo sed -i "s/snapcast/$NEWHOSTNAME/g"    /media/$USER/osroot/etc/hostname
sudo sed -i "s/snapcast/$NEWHOSTNAME/g"  /media/$USER/osroot/etc/hosts

# wifi
if [[ $WIFI_SSID ]] ; then
sudo tee /media/$USER/osroot/etc/wpa_supplicant.conf <<EOF!
ctrl_interface=/var/run/wpa_supplicant
ap_scan=1

network={
  ssid="$WIFI_SSID"
  psk="$WIFI_PSK"
}
EOF!
fi

# connect SysLog client to nominated server
if [[ $SYSLOG_SERVER ]] ; then
# Buildroot init.d/S01logging calls out to /etc/default/logging for variable changes
sudo tee /media/$USER/osroot/etc/default/logging <<EOF!
SYSLOGD_ARGS=-n -R $SYSLOG_SERVER
EOF!
fi


# Add any special devices (like HAT)
sudo vi /media/$USER/osboot/config.txt


# cleanup
sync
sudo umount /dev/${MEDIA_DEVICE}1
sudo umount /dev/${MEDIA_DEVICE}2
sudo rmdir /media/$USER/osboot
sudo rmdir /media/$USER/osroot
```

### First boot cleanup

```
NEWHOSTNAME=MyNewHost

# replace any old entry from previous build with same hostname
ssh-keygen -R $NEWHOSTNAME

# ssh-keyscan -T 10 -H $NEWHOSTNAME >> ~/.ssh/known_hosts
# key scan is not reliable enough so 
# you will just have to answer 'yes' (all 3 letters) below

# Connect via ssh
# default password is snapcast
ssh root@$NEWHOSTNAME
```


* If you don't get a wireless connection first time, 
	* try connecting an ethernet cable for diagnostics.
* If you can't connect via ethernet, 
	* connect an HDMI screen and keyboard to check from the console.

Once you've logged on, then...

```
# Stop your box getting hacked by rogue code on other internal devices
# Change the default password
passwd

# check your sound card is accessible
aplay -l

# check your soundcard settings
alsamixer

# see the snapcast client settings
# CTRL-C to break out
snapclient -e


```

## Issues

### Firmware request errors

With Buildroot 18.02.5 and the SnapOS rpi3 modules
the image generated the follow error every few seconds

`raspberrypi-firmware soc firmware request 0x00030046 returned status 0x80000001`

Numerous responses to this error 
suggested a firmware upgrade using rpt-update, 
clearly not possible on a buildroot image. 

For instructions on updating the firmware 
on any linux raspberrypi image, see 

https://github.com/artmg/MuGammaPi/wiki/linux-operating-system-generic#firmware-upgrade

These resolved the above issue

### No Wireless

With Buildroot 18.02.5 and the SnapOS rpi3 modules
the image failed to connect to wireless

This image is based on Busybox 
using inittab to start the services. 
See https://buildroot.org/downloads/manual/manual.html#_init_system

The WPA service does not appear to be registered with dbus

### recipe for target aixlog-v1.2.1 failed

The Buildroot 2018.05 make command fails in section `>>> aixlog v1.2.1 Downloading`

This issue is now documented (with workaround) at https://github.com/badaix/snapos/issues/5