added hardware assembly and OS install documentation; switched splash screen

README.md

@@ -9,7 +9,9 @@ scripts over the same native-code substrate, deployed on an inexpensive embedded
 
 ## Hardware requirements
 
-- Raspberry Pi 3 with PiTFT touchscreen (Adafruit product ID 2423)
+- Raspberry Pi 3 with PiTFT touchscreen (Adafruit product ID 2423). See
+  [Building the Hardware to Run UPIWIN](docs/hardware-instructions.md) to assemble the hardware, and
+  [Preparing the Operating System for UPIWIN](docs/os-instructions.md) for the system software.
 
 ## Acknowledgements
 

docs/hardware-instructions.md

@@ -0,0 +1,37 @@
+# Building the Hardware to Run UPIWIN
+
+UPIWIN is designed for a hardware configuration with a miniature capacitive-touch touchscreen mounted on a
+Raspberry Pi computer, making for a compact assembly.  This document describes how to assemble one.
+
+## Parts List
+
+- Raspberry Pi 3 Model B+ computer
+- PiTFT Plus 320x240 2.8" Capacitive Touch Touchscreen (Adafruit part number 2423)
+- Pi Model B+/Pi 2 Case Base - Clear (Adafruit part number 2253)
+- PiTFT Faceplate and Buttons (Adafruit part number 2807)
+- 2x Brass M2.5 Standoffs (Adafruit part number 2337)
+- Additional Raspberry Pi hardware (MicroSD card, power supply, keyboard and display connections)
+
+## Assembly Instructions
+
+1. On the back of the PiTFT, solder closed the jumper pads labeled "#18". This will allow the use of GPIO line 18 as
+   a PWM backlight control.
+2. Attach two standoffs to the underside of the PiTFT (pointing in the same direction as the 40-pin connector), on the
+   right side (the side with the pushbutton switches).  Secure with the included nuts.
+3. Attach the PiTFT to the Raspberry Pi, pressing down hard to seat the 40-pin connector atop the Pi's GPIO pins.
+4. Seat the completed assembly inside the case base, lining up the holes for the USB and Ethernet ports on the left
+   side.  Press down to snap the latches into place.
+5. Holding the faceplate upside down, insert four plastic buttons into the four small rectangular slots. Invert the
+   case assembly and snap it together with the faceplate, lining the buttons up with the pushbutton switches.
+6. Connect the Pi to keyboard, display, power, and network (if necessary). Insert the MicroSD card with the operating
+   system installed, and boot as usual.
+
+## Illustrations
+
+### Completed subassembly
+
+![Completed subassembly](subassembly.jpg)
+
+### Completed Assembly
+
+![Completed assembly](complete.jpg)

docs/os-instructions.md

@@ -0,0 +1,62 @@
+# Preparing the Operating System for UPIWIN
+
+The Raspberry Pi OS needs to be configured with the appropriate device tree support, software, and libraries to compile
+and run UPIWIN successfully.  This document describes the process.
+
+## Preparing the Operating System
+
+1. Download an image of Raspberry Pi OS from
+   [the Raspberry Pi Foundation](https://downloads.raspberrypi.org/raspios_armhf/images/). The most-recent version of
+   Raspberry Pi OS that is known to work with the PiTFT is
+   [the December 4, 2020 image](https://downloads.raspberrypi.org/raspios_armhf/images/raspios_armhf-2020-12-04/).
+2. Unzip the `.zip` file for your image and write th included `.img` file to a fresh MicroSD card using one of the
+   methods described on [this page](https://www.raspberrypi.org/documentation/computers/getting-started.html).
+3. Connect your UPIWIN-compatible Raspberry Pi (RPi 3B+ with PiTFT) to power, HDMI display, keyboard, and network
+   (if necessary).  Insert the freshly-written MicroSD card into the Pi.
+4. Turn on the Pi, boot into Raspberry Pi OS, and set it up.  Make sure to get updates installed.
+
+## Installing the PiTFT Drivers
+
+1. In a terminal window, enter the command `sudo -i` to get a root command prompt.
+2. Enter the following commands:
+
+    pip3 install --upgrade adafruit-python-shell click
+    git clone https://github.com/adafruit/Raspberry-Pi-Installer-Scripts.git
+    cd Raspberry-Pi-Installer-Scripts
+    python3 adafruit-pitft.py --display=28c --rotation=90
+
+3. Answer "N" to the questions about the console appearing on the PiTFT display and mirroring HDMI to the PiTFT
+   display.
+4. Reboot the Pi when prompted.
+
+## Installing Libraries for UPIWIN
+
+1. Use `sudo -i` to get a root command prompt.
+2. Execute the command to install packaged libraries:
+
+    apt install python3-dev libfreetype6-dev libpng-dev ttf-mscorefonts-installer
+
+3. Execute the commands to install the BCM2835 library:
+
+    wget http://www.airspayce.com/mikem/bcm2835/bcm2835-1.68.tar.gz
+    tar xzvf bcm2835-1.68.tar.gz
+    cd bcm2835-1.68
+    ./configure
+    make
+    make check
+    make install
+
+4. Copy the Arial font to where the code expects to see it:
+
+    mkdir /usr/local/share/fonts/truetype
+    cp /usr/share/fonts/truetype/msttcorefonts/arial.ttf /usr/local/share/fonts/truetype
+
+## Building the Source
+
+After cloning the repository for UPIWIN, enter the following commands:
+
+    cd upiwin
+    make
+
+To execute, enter the command `sudo src/upiwin` followed by the name of the script to be run. For example,
+`sudo src/upiwin scripts/demo1.py`.

src/Makefile

@@ -17,7 +17,7 @@
 # ------------------------------------------------------------------------
 BUILDUTILS=../buildutils
 RESOURCES=../resources
-SPLASHSCREEN=splash-vmwcblk.png
+SPLASHSCREEN=splash-erbosoft.png
 
 OBJS=main.o sysinput.o ep_init.o ep_upiwin.o ep_backlight.o ep_msg.o ep_graphics.o ep_devctxt.o ep_bitmap.o \
      ep_upiwin_tmp.o ep_util.o fbinit.o rect.o gfxobj.o devctxt.o dc_screen.o fontengine.o \