          Raspberry Pi: Installation and Configuration
          ============================================

1. obtain  the  current  version  of  Raspberry  Pi OS for  your
   hardware platform from

   https://www.raspberrypi.com/software/operating-systems/

   Unless there is compelling  reason no to, download the 32-bit
   image with desktop. The "light" image tends to bit too light,
   the one  bundling  recommended  software  takes  considerably
   longer  to  download,  image and  patch. In most  cases,  the
   32-bit  version does the trick, as there is only one RPI with
   more than 4GB of RAM.

Should  the  install  fail (as in fail to boot), try the  legacy
install  image. If that fails too, use a  different  Pi. If that
fails, but the second Pi has worked up to then, but not with the
new card, then the card might be toast, or the imaging failed. 
   
2. move  the  image.zip   file  into  the   installation   suite
   directory, in my case $HOME/RaspiConfig/

3. for your particular configuration, you might want to edit the
   installer's "setup.sh" script:

   - unless the  installer  is supposed to run on a standard Pi,
     without any external USB drives  attached,  the device name
     for the SDHC card very  likely  needs to be  changed.  In a
     default setting (one without external USB stores), the boot
     and  root  partition  are  hosted  on  /dev/mmcblk0p1   and
     /dev/mmcblk0p2. USB drives show up as /dev/sda*, /dev/sdb*,
     etc. The  setup.sh  script  targets  /dev/sda,  so if there
     already  is a USB drive with data on it, that drive will be
     rendered  useless,  with all its data  gone. So, if your Pi
     has one external disk at /dev/sda*, modify the setup script
     to change all instances of sda to sdb.

   - when  running  the  installer  on a desktop  Linux  system,
     chances  are that its  primary  (boot and root)  partitions
     reside on  /dev/sda*,  so  running an  unmodified  setup.sh
     there will  render  your system  inoperable,  with all data
     gone.

   - to  determine  which  device  your  SDHC card  fixin' to be
     imaged is found, plug the USB reader/writer with the target
     into  your Pi or Linux  host, and,  after a moment,  invoke
     "dmesg".  At the end of the  output  you'll  find your SDHC
     card's device name.
    
   - change the name of the Raspberry Pi OS image to the one you
     downloaded earlier,

   - if you are not using a Linux device to image the SDHC card,
     follow the instructions on https://raspberrypi.org/

4. If   immediate   wireless   connectivity   is  needed,   edit
   wpa_supplicant.conf  to  add  your  WiFi  access  point's  or
   router's name (as the value of ssid) and  credentials (as the
   value of psk). If your access point or router  broadcasts its
   SSID  (means you can see its name on your  laptop and phone),
   remove the line containing "scan_ssid=1", or change the value
   to 0 (zero).

5. setup.sh  drops an archive  (install.tgz),  together  with an
   initial  configuration  (.profile) into pi's directory on the
   target device. This archive contains configuration scripts as
   well as source code and  installation  scripts for  must-have
   packages.  This archive can't be too large because the imaged
   file system is rather small. Feel free edit roll your own.

6. Invoke setup.sh. This will take time.

   Output looks close to this:

root@k102d:/home/pi/RaspiConfig# ./setup.sh
umount: /dev/sda: not mounted
umount: /dev/sda1: not mounted
umount: /dev/sda2: not mounted
4232577024 bytes (4.2 GB, 3.9 GiB) copied, 627.02 s, 6.8 MB/s
0+48646 records in
0+48646 records out
4236247040 bytes (4.2 GB, 3.9 GiB) copied, 649.947 s, 6.5 MB/s
waiting for OS to figure out disks
umount: /dev/sda: not mounted
umount: /dev/sda1: not mounted
umount: /dev/sda2: not mounted
[Sun Mar 13 18:31:22 2022] usb 1-1.4: new high-speed USB device number 7 using dwc2
[Sun Mar 13 18:31:22 2022] usb 1-1.4: New USB device found, idVendor=14cd, idProduct=8123, bcdDevice= 2.01
[Sun Mar 13 18:31:22 2022] usb 1-1.4: New USB device strings: Mfr=1, Product=3, SerialNumber=2
[Sun Mar 13 18:31:22 2022] usb 1-1.4: Product: USB 2.0  SD MMC READER
[Sun Mar 13 18:31:22 2022] usb 1-1.4: Manufacturer: SDMMC MA8123
[Sun Mar 13 18:31:22 2022] usb 1-1.4: SerialNumber: 812822222789
[Sun Mar 13 18:31:22 2022] usb-storage 1-1.4:1.0: USB Mass Storage device detected
[Sun Mar 13 18:31:22 2022] scsi host0: usb-storage 1-1.4:1.0
[Sun Mar 13 18:31:22 2022] usbcore: registered new interface driver uas
[Sun Mar 13 18:31:23 2022] scsi 0:0:0:0: Direct-Access     USB 2.0  SD MMC Reader         PQ: 0 ANSI: 0 CCS
[Sun Mar 13 18:31:23 2022] sd 0:0:0:0: [sda] 61067264 512-byte logical blocks: (31.3 GB/29.1 GiB)
[Sun Mar 13 18:31:23 2022] sd 0:0:0:0: [sda] Write Protect is off
[Sun Mar 13 18:31:23 2022] sd 0:0:0:0: [sda] Mode Sense: 03 00 00 00
[Sun Mar 13 18:31:23 2022] sd 0:0:0:0: [sda] No Caching mode page found
[Sun Mar 13 18:31:23 2022] sd 0:0:0:0: [sda] Assuming drive cache: write through
[Sun Mar 13 18:31:23 2022]  sda: sda1 sda2
[Sun Mar 13 18:31:23 2022] sd 0:0:0:0: [sda] Attached SCSI removable disk
[Sun Mar 13 18:31:23 2022] sd 0:0:0:0: Attached scsi generic sg0 type 0
[Sun Mar 13 18:46:56 2022]  sda: sda1 sda2
[Sun Mar 13 18:47:56 2022] EXT4-fs (sda2): mounted filesystem with ordered data mode. Opts: (null)
total 10768
    4 -rwxr-xr-x 1 pi pi      255 Mar 13 18:47 cmdline.txt
    4 -rwxr-xr-x 1 pi pi     1605 Mar 13 18:47 config.txt
    4 -rw-r--r-- 1 pi pi     2002 Mar 13 18:47 dhcpcd-123-28.conf
10716 -rw-r--r-- 1 pi pi 10970585 Mar 13 18:47 install1.tgz
    8 -rw-r--r-- 1 pi pi     7052 Mar 13 18:47 install.txt
    4 -rw-r--r-- 1 pi pi       37 Mar 13 18:47 notes.txt
    4 -rw-r--r-- 1 pi pi      144 Mar 13 18:47 _profile
    4 -rwxr-xr-x 1 pi pi      988 Mar 13 18:47 rc.local
    4 -rwxr-xr-x 1 pi pi      682 Mar 13 18:47 serialSetup.sh
    4 -rwxr-xr-x 1 pi pi     1494 Mar 13 18:47 setup.sh
    4 -rwxr-xr-x 1 pi pi      146 Mar 13 18:47 showTemp
    4 -rwxr-xr-x 1 pi pi      503 Mar 13 18:47 update.sh
    4 -rw-r--r-- 1 pi pi      164 Mar 13 18:47 wpa_supplicant.conf
root@k102d:/home/pi/RaspiConfig#

7. Move the newly imaged card from to your target  device. Power
   it up. By default,  (one of) the LED(s)  flashes  during disk
   access. If it does not, there's something wrong.
   
8. By default, a Pi aquires  its IP  address(es)  using DHCP. If
   you run your Pi headless  (i.e.  without  screen and keyboard
   attached),  you need to find its IP  address.  Log into  your
   router,  find  its DHCP  lease /  reservation  list.  Your Pi
   should show up as the most  recently  added device. You might
   want to add a DHCP address reservation to your router so that
   this particular Pi always receives this particular IP address
   of choice.

9. setup.sh  enables  ssh by default. so, unless you have screen
   and keyboard  attached, ssh to that IP address. Your login is
   "pi", password "raspberry".

10. Once in, invoke Raspberry Pi OS's configuration  utility, by
    issuing:

    sudo raspi-config
    
11. Start with "1. System  Options". If using wireless  settings
    created by setup.sh,  skip "S1 Wireless LAN". Start with "S3
    Password"  to  change  the  default  password  to  something
    secure, then "S4  Hostname" to  configure  some  descriptive
    hostname, followed by "S5 Boot / Auto Login". For a headless
    system, use "B1  Console",  for one with screen "B1 Console"
    or "B3 Desktop". Always(!) ask for a password. Even a simple
    password  for home  media  use is better  than  none. In "S6
    Network at boot" set up the system to boot  immediately, and
    not wait for the network.

12. When running with screen and keyboard, consider enabling VNC
    access in "3 Interface Options", then "I3 VNC".

13. Skip "4 Performace Options". If you feel living on the edge,
    and decide to overclock,  make sure that there's  sufficient
    cooling.

14. In "5 Localization  Options",  select "L1 Locale". Pick your
    locale,  in my case  en_US.UTF-8  UTF-8,  resulting  in that
    locale  getting set up. This takes some time. Follow up with
    "L2 Timezone",  optionally "L3 Keyboard".  Setup.sh sets the
    WiFi  country  to the US. Might  want to  review in "L4 WLAN
    Country".

15. Nothing  to  do on "6  Advanced  Options"  and  "8  Update".
    Chances are then when hitting "<Finished>", the configurator
    asks to reboot. Confirm that.

16. Once the Pi is back, log in using your new  password,  chdir
    into RaspiConfig, untar your most-have tarball.

17. chdir into RaspiConfig/Install, invoke  install-base-pkgs.sh
    and optionally  install-opt-pkgs.sh  to update, upgrade your
    installation, and to add software packages. Reboot again.

18. Like  pretty much all other  modern  computers,  taking them
    down by pulling power is a really bad idea,  resulting, best
    case, in a file system  repair upon  restart.  Depending  on
    file system, there might be data loss. ZFS is supposed to be
    resilient  against that, UFS (the BSDs classic default) too,
    EXT4  under  Linux not so much.  Furthermore,  sudden  power
    withdrawal may confuse the SDHC card's  controller enough to
    brick the card. The  proper way to take down a Pi is a "sudo
    poweroff" in a terminal window, or the appropriate button in
    the GUI.
    
19. Ever  so  often,  invoke  "dmesg  -T" to  take a look at the
    system logs. If you see  messages  such as these not just at
    startup,  but rather  repeatedly  over time, then  reseat or
    replace the USB power cable, or pick another power supply:

  Fri Mar 11 15:03:10 2022] Under-voltage detected! (0x00050005)

  Fri Mar 11 15:03:22 2022] Voltage normalised (0x00000000)

20. Congrats on completing a baseline install.



