EPICS Hydroponics Display

This repository includes all confuguration and data files required to configure and run the virtual display systems on the EPICS designed Hydroponics Display for Imagination Station in Lafayette, Indiana. Documentation and setup was created in Spring 2024 by the Water Resources Management (WRM) team.

Getting Started

The display software is built on the Pi Presents toolkit. Pi Presents was designed for producing interactive multimedia applications for museums and visitor centers. The software runs on Raspberry PIs, which are high-performance, low-cost, general-purpose computing platforms.

Required Hardware

The hydroponics display was created using Raspberry PI 4 Model B's with 4 GB os on-board memory and 32 GB Micro SD cards for storage of images, videos and programs. The Raspberry PI kits included power cables and a protective housing with cooling fan. Each Raspberry PI 4 also has two micro-HDMI ports, four USB ports and one ethernet port.

• To setup the Raspberry PIs for use, you need the power cable, an HDMI cable and monitor, a USB keyboard and a USB mouse.

• For the running display, only the power cable and HDMI cable are required.

Instructions for setting up a new Raspberry PI are available from the Raspberry PI main page.

If trying to rebuild an original system (so not trying to upgrade all components), here are specfic instructions for setting up the Raspberry PI for Pi Presents (Version 1.5 [pipresents-kms]), which was used for the display control when delieved in Spring 2024:

• Download the Raspberry Pi OS imaging software from https://www.raspberrypi.com/software/. Pick the correct version for your current computer (Windows or Mac OS X, 64-bit).
• Connect the microSD card on which you want to install the Raspberry PI OS.
• Run the imaging program to install the correct version of the Raspberry Pi OS for your planned device (initially these were version 4).
• Use the following settings in the imager program for this version of the display:
  • Raspberry Pi Device: RASPBERRY PI 4
  • Choose OS: Scroll down and select "Raspberry PI OS (other) -> Scroll down to find "Raspberry PI OS (Legacy, 64-bit) Full", which is a port of "Debian Bullseye".
  • Storage: Choose the location of the microSD card you connected to the computer in the earlier step.
  • NEXT
  • This will open a window called "Use OS customization?", select "NO" to use the defalt installation.
  • This will open a window called "Warning" that lets you know the microSD card will be overwritten. Select "YES" to continue with the installation.
• This will install and then verify the installation of the base operating system.
• Once completed, close the program and remove the microSD card from the local computer.
• The micro SD card can now be installed in the Raspberry PI and used for the rest of the setup procedures.

If this is going to be an upgrade installation, check for the version Raspberry of Pi OS required for the most recent release of Pi Presents.

Initial Setup of Raspberry PI

These instructions should apply no matter what version of the Raspberry PI OS is installed in the previous section.

• Plug the microSD card into the Raspberry Pi.
• Plug the Pi into a monitor and attach a keyboard and mouse.
  • The HDMI 0 port works best, that is the port closest to the USB-C port used to supply power tot he Raspberry PI.
• Plug the Pi into power and turn it on.
• Set the location and time zone.
• Create a administrator account, I used the following information:
  • Username: “hydroadmin”
  • Password: “IS-Hydroponics!”
• Connect the Raspberry Pi to the local network.
• Select your preferred browser (I used Chromium and left Firefox installed)
• Start the software updates.
• If asked, restart the Raspberry Pi.

Installing Pi Presents

Please refer to the Pi Presents home page for updated information on the software.

When this display package was delivered in Spring 2024, the presentation was built on Pi Presents (Version 1.5 [pipresents-kms]). If rebuilding that original system, you should use this version of Pi Presents.

If upgrading the system, please make sure that you use the latest stable version of Pi Presents and the version of Raspberry Pi OS that supports it.

To install the software, follow the instructions in the README.md file included in the GitHub repository. This will be visible in a user-friendly formatted display at the bottom of the main repository window.

I do suggest that you create a folder called GitHub in the hydroadmin account home, and clone all repositories to that folder. While not required, it keeps things better organized.

I also suggest installing the following supporting packages:

• The evince document viewer, using the command sudo apt install evince.
• The emacs text editor, using the command sudo apt install emacs.
• The imagemagick suite of image editing tools, using the command sudo apt-get install imagemagick

Note that if it has been a while since software was installed, it is a good idea to update all installaed packages before adding new one, using the commands sudo apt update and sudo apt full-upgrade.

Installing Hydroponics Virtual System Profiles

Here are instructions for installing the hydroponics virtual system on a new Raspberry Pi setup.

1. Install the Pi Presents profile

These steps will create a clone of the Pi Presents profile that defines the hydroponics virtual system show. Then a link will be placed in the home folder so taht the files appear to be in the default location for Pi Presents.

1. Change into your home directory, using cd at the Terminal prompt.
2. Create the folder GitHub if it is not present, using mkdir GitHub.
3. Change into the GitHub folder, using cd GitHub.
4. Clone the virtual system repository using the command git clone https://github.itap.purdue.edu/PHIGOrganization/EPICS-Hydroponics-Display.git.
5. Use the ls command of the File Manager tool to confirm that there is now a folder called EPICS-Hydroponics-Display in the GitHub directory.
6. Return to the account home directory, using cd.
7. Create a symbolic link to the pp_home directory, using the command ln -s GitHub/EPICS-Hydroponics-Display/pp_home.
8. Use the ls command or File Manager to confirm that there is a linked file in the home folder called pp_home.

• For the ls command, the fielname should be teal to indicate a link.
• For the File Manager the folder icon should have a little black arrow in the upper left corner indicating the folder is a link.

2. Install the media files

Because of the size of the media files, they are stored in a separate repository. These instructions will walk you through the download and installation process.

1. Change into the pp_home directory, using cd ~/pp_home at the Terminal prompt.
2. Download the media files using the command wget -O media.zip "https://purdue0-my.sharepoint.com/:u:/g/personal/cherkaue_purdue_edu/EdyKhKj2tVpGkbvZk4SS1loB-aPW0mvwK85BAdBmGTsmig?download=1", which will download the file media.zip from the shared oneDrive folder for the Hydroponics Display project.
3. Next, unzip the downloaded file using the command unzip media.zip.
4. This should create a new folder in pp_home called media.
5. Once the media folder is uncompressed there is no need to keep the compressed file, so delete it using the command rm media.zip.

3. Test the show

1. From the command line, use the command python /home/hydroadmin/pipresents/pipresents.py -p pp_NFT_hydroponics_display to start the NFT focused display in a smaller browser window. Replace "NFT" with "AERO" in the profile name to get the aeroponics focused presentation.
2. Use the ^ in the upper right corner of the new window to maximze the screen.
3. Show should loop through several short slideshows, when the Enter key is pressed, it should start one of the videos (selected randomly).
4. Click on the X in the upper right corner to end the show.
5. To see the show using the fulls screen, add a -f -b to the end of the command used to start the show. WARNING: You will need to use <Ctrl>-<Break> to stop the show when it is in full screen. Make sure that your keyboard has a <Break> key before starting.

4. Preventing the Raspberry Pi from sleeping

By default the Raspberry Pi display will go to sleep when untouched for an extended period of time. This feature is not great for the display as the slideshow will no longer be visible until the button is pushed. Sleep can be deactivated on the Pi by compelting the following steps:

• Click on the Raspberry icon in the upper left of the display window to open the control panel.
• Hover the mouse over "Prefereces" to open the submenu.
• Select "Raspberry Pi Configuration" from that submenu to open the Raspberry Pi Configuration window.
• Click on the "Display" tabe at the top of the new window.
• Turn off "Screen Blanking".
• Click on "OK" to save the setting.
• This will prompt you to restart the Raspberry Pi for the new controls to take affect.
• Once the Raspberry Pi has been restarted, the screen will no long turn off while the Pi Presents show is running.

Configuring Raspberry Pi to Autostart Display

This material is taken from the Pi Presents manual, Section 6.6 Start Pi Presents when Power is applied to the Pi. Instructions are specific to the Hydroponics display as configured at delivery, if changes need to be made please refer to the version of the Pi Presents manual that matches the version installed earlier in this document.

This will function only if you have set 'boot to desktop' using raspi-config. The directory .config is already present in the image but you will need to select 'Show Hidden Files' in the File Manager to see it.

For a new Bullseye installation, the autostart file /home/hydroadmin/.config/lxsession/LXDE-pi/autostart does not exist so it, or its contents, needs to be copied from the file: /etc/xdg/lxsession/LXDE-pi/autostart.

1. First use the command mkdir -p /home/hydroadmin/.config/lxsession/LXDE-pi to make the required directory structure.
2. Then use the command cp /etc/xdg/lxsession/LXDE-pi/autostart /home/hydroadmin/.config/lxsession/LXDE-pi/autostart to make c opy of the file in the correct location.
3. The file then needs to be edited using the command: emacs /home/hydroadmin/.config/lxsession/LXDE-pi/autostart &
4. Within the emacs editor, add the following line below the last line to start Pi Presents with the required options:
   • If the current system should be playing the Aeroponics System: /usr/bin/python /home/hydroadmin/pipresents/pipresents.py -o /home/hydroadmin -p pp_AERO_hydroponics_display -f -b
   • If the current system should be playing the NFT System: /usr/bin/python /home/hydroadmin/pipresents/pipresents.py -o /home/hydroadmin -p pp_NFT_hydroponics_display -f -b
5. Click on the Save icon or enter <CTRL>-<x> <CTRL>-<s> to save the file before exiting the emacs editor.

On restarting the computer, the selected show should start automatically.

Note: This file is not a standard .sh file, so the leading @ (seen in the earlier entries) is not required. The @ tells the system to restart the process should it fail, which is necessary for critical startup systems, but not for the Pi Presents show.

Wiring the Button to Work the Show

This material is taken from the Pi Presents manual, Section 6.4 Using GPIO to Control Pi Presents. Instructions are specific to the Hydroponics display as configured at delivery, if changes need to be made please refer to the version of the Pi Presents manual that matches the version installed earlier in this document.

A button (GPIO) control is enabled when a gpio.cfg file is present in the /pp_io_config directory within a profile. There are gpio.cgf files in both the pp_NFT_hydroponics_display and pp_AERO_hydroponics_display profiles developed for the hydrponics display.

Within those gpio.cfg files the button trigger is wired to the terminal labeled GP22 on the Raspberry Pi, which is the same as the screw terminal labeled IO22, and is referred to as P1-22 in the gpio.cfg file. There is a screw terminal installed on top of the Raspberry Pi to facilitate a stable connection between the botton and the Raspberry Pi.

Using this file the GPIO pins are configured as edge triggered inputs with internal pull-up resistors and require the following device characteristics:

• Push buttons should be mechanical,
• Push to make connection (normally open), and
• Be connected between the GPIO pin and 0 volts.

The contact will close when the button is pressed so it is set to falling edge trigger.

A 330 ohm resistor wired in series with the button is recommended to protect the Raspberry Pi should the inputs inadvertently be used as outputs.

Wiring should look like this:

GPIO Pin (GP-22) ----- R = 330 Ohm ----- contact (button) ---- 0 volts (GND)

The 330 ohm resistor should should be screwed into the GP11 pin. The far side of the resistor should be connected to the wire lead to the button. The return wire from the botton should be screwed into any of the ground terminals marked GND. Be very careful not to connect a GPIO pin to the +5 volt terminal; it is likely to fry your Raspberry Pi.

There is software contact de-bouncing which is set with a small hysteresis. If you have problems with contact bounce increase the THRESHOLD of the appropriate pin by modifying gpio.cfg (See the Pi Presents manual).

If you want the button on the display to light up, you can run a second set of wires to outer (LED) terminals on the botton. One side should be connected to the +5 volt terminal, the return should go to ground. Source document says that the LED in the arcade bottons require 12 volts of power, so the 5 volt power turns on the button but leaves it dim.

WARNING: Files other than gpio.cfg in the /pp_io_config folder seem to cause conflicts and prevent the button from working with the Pi Presents show, so keep that directory clear.

Structure of Repository

Pi Presents Profile

The Pi Presents manual is included in the code repository. If, you have installed pipresents in the home folder, and you installed the optional evince tool, you can view the manual using the command evince pipresents/manual.pdf &. The manual should also be available by opening the PDF file from the Pi Presents GitHub repository used for installation.

To edit the hydroponics display profile, start the Pi Presents Web Editor using the command python pipresents/pp_web_editor.py &. This will open a new tab in the web browser called PPWebEditor. This is the preferred method for editing the Pi Presents profile files that control how the show functions.

To open the hydroponics display profile:

• Use the mouse to select Profile -> Open.
• Select the profile called "pp_hydroponics_display".

This opens the show profile, and allows you to make specific edits to the document.

The current show is setructured as follows:

• Start – this show is required, and will start the radiobutton show that serves as central control

  • Radiobuttonshow – this controls the shows that play in the background when movies are not being played, and controls the trigger and random showing of the hydroponics movie files.

    • Background Mediashow – this will control the display of the slideshow slides. Each slide appears in the medialist for the background media show.

      • Slideshow slides are generated using the script scripts/build_slideshow_slide.py which selects random background and hydroponics images to merge with a image of Alpha and an image with text asking the viewer to press the button.

      • The script scripts/merge_images.sh actually creates each image as diorected by the build_slideshow_slide.py program.

    • Movie Mediashow – this will be triggered by pressing the button (or Enter when the keyboard is connected). The trigger will select a movie to play (can be random, or in order). Movies need to appear in the associate medialist.

      • NOTE: It appears that if the videos are ordered that only the first video is ever played when the button is pressed.

Saving Changes

To update the GitHub repository to reflect local changes, you will need to do the following:

• Change into the GitHub respository on the local disk, using cd GitHub/EPICS-Hydroponics-Display.

• Type git status at the terminal prompt. This should provide a list (in red) of code in the repository that has been changed. If there are no changes, then there is no need to do the next steps.

• Type git add . at the terminal prompt to add all changed files in the current directory (".") and its subdirectories to the staged list.

• Repeat git status and you should see a list of staged programs (in green).

• Type git commit -m "REASON", where you replace "REASON" with a short description of the changes made.

• Repeat git status and you should see the list has been cleared, and replaced with a message that something like "Your branch is ahead of 'origin/main' by 1 commit. (use "git push" to publish your local commits)."

• Next end git push at the terminal prompt to push your changes to the GitHub repository. NOTE: This will only work if you have been granted access to modify the repository by Dr. Keith Cherkauer (cherkaue@purdue.edu).