Our upgraded system added an Adafruit piTFT resistive touch screen, a piezo buzzer, updated LED light functions, and four GPIO buttons for functions listed above. The full system also includes an RPi 3, a radio antenna, a USB flash drive, and a real-time clock.

piTFT Screen

The piTFT screen served as a user interface for scientists who might want to use the base station out in the field. The base screen displays the most recent tag detected, a scrolling history of the last 9 tags detected, and three toggle buttons: the left-most button, “Scrolling”, toggles to a histogram of the most-frequently detected tags (it displays “Histogram” when in histogram mode); the middle button, “Screen Off”, turns off the screen, and the right-most button, “Brightness”, toggles between three different levels of brightness. A mockup of the scrolling display and histogram is shown below:

GPIO Buttons

The GPIO buttons that came with the piTFT screen were tied to various interrupt based functions. The button mapped to pin 17 allows the RPi to reboot; the button mapped to pin 22 allows the RPi to shutdown, 23 controls beeper noise (on or off), and pin 27 serves as a bailout button, allowing users to exit the main program and enter development mode. All GPIO pins are in BCM numbering.

Beeper

A beeper was added to the system to serve as an audio signal for tag detection, in case a researcher using the base station was unable to see either the screen or the LED flash -- upon tag detection, the beeper emits a short beep.

The beeper is controlled via PWM at 4kHz for the loudest tone per the manufacturer’s suggestion.

The beeper is controllable via the button attached to pin 23, which toggles the duty cycle of the PWM between 0 and 50% -- silencing the beeper or turning the beeper back on is a matter of pressing it.

LED

The LED has three main functionalities: one, to serve as a warning signal for when the RPi is about to mount the USB flash drive, two, to serve as a visual indicator of tag detection, and three, to serve as a base station ‘heartbeat’ -- that is, indicate that the RPi base station program is alive and running.

For the first function, the LED turns on for a full five seconds before the RPi mounts the USB, and remains on until the RPi unmounts. For the second function, the LED blinks four times in rapid succession upon tag detection, and for the third, the LED blinks every five seconds to indicate that the program is currently running.

The entire project was written in Python, and the main portions of the code are separated into four different files: BaseStation, BaseStationLogger, BaseStationTFT, and BaseStationUSB. Since this project is an upgrade of an existing project and not an original, much of the code was already in place, and we simply expanded upon it to add the above functionalities.

The program is split into two parallel processes: a polling process whose only functions is to detect touchscreen touch events (apparently there is no interrupt-based event-detect in pygame) and the main process that handles everything else i.e. LED flashing, tag logging, beeping, and histogram/scrolling history animation. The main process also spawns a USB mounting thread that runs every fifteen minutes (this was implemented by the previous team working on this project).

BaseStation.py

This is the main python program that is launched by the shell script check_script.sh, which starts BaseStation.py at reboot and checks if it is running every three minutes and if it is not, starts it again. BaseStation.py also instantiates the logger object from BaseStationLogger.py, spawns the USB mounting thread, and starts the parallel process that runs the polling function from BaseStationPiTFT.

BaseStationUSB

Mostly left from previous team that worked on the project. We added the advanced five seconds USB mounting warning and had to pass in a lock to the USB thread so the tag logger and the USB mounting thread do not try to access tag.txt and the LED at the same time. The USB mounting is handled by a thread that runs every fifteen minutes.

BaseStationLogger

Mostly left from previous team that worked on the project. Logger writes to tag.txt file whenever a tag is detected. It acquires the lock when writing to tag.txt. Instead of having the App object from BaseStationPiTFT to access the tag.txt file directly, we had the logger call App’s update function and passing in the new tag information to the App object. The logger also checks if the user is in the histogram or scrolling mode.

BaseStationPiTFT

BaseStationPiTFT (or ‘BSTFT’) is a new module (i.e. not part of the original) that operates the piTFT, which has several functionalities and gimmicks. The home screen for the piTFT displays a scrolling history of bird tag detections and the most recent bird tag detected: tags read from BSLogger are passed into a BSTFT Tag object as arguments, and Tag objects kept in a list for easy tracking and analysis. To display the most recent bird tag, BSTFT simply reads the last item in the list; the display the past nine tags, BSTFT reads the last nine items in the list.

BSTFT also has an option to view a histogram of the most-frequently detected bird tags, viewable via on-screen touch buttons. While we originally planned to use matplotlib to analyze and display the histogram, our disk image was incapable of using ‘sudo apt-get install’ command to download matplotlib. We ended up sorting the BSTFT list using Python’s sorted functionality, and displaying the top 9 results on screen instead.

There are three on-screen buttons available on the piTFT: the first is the option to toggle between histogram and the scrolling display. The second is a ‘Screen Off’ option, and the third a toggle button between three different brightness levels. Since the piTFT backlight is controllable via PWM, and the piTFT PWM output is connected to GPIO pin 18, we simply echo the desired PWM output as a shell command. The PWM output could be anywhere from 0 (backlight off) to 1023 (backlight brightest), and the brightness function cycles through levels 300, 600 and 1023 while the off function sets it to 0.

Our setup is above: our scrolling history (without on-screen buttons yet), beeper, antenna, and LED light are visible. Not visible is the RTC. For the most part, our program runs well: the scrolling display works, the GPIO buttons functions, and beeper beeps, and our LED blinks. Throughout the project, we were able to consistently meet our week’s end goals, which made it easy to stay on track as we worked towards completing the project.

Issues (Bugs Galore)

We ran into several problems while doing the project, the most significant of which was that our RPi disk image obtained from TABER Group was incapable of running ‘sudo apt-get’. We were able to implement most of our functions without needing to sudo apt-get; however, we realized from previous class lab work that the piTFT touchscreen malfunctions with Jessie and we have to use the functions for the piTFT from Wheezy. Since we were unable to download the appropriate Wheezy packages onto the disk image provided to us, we reflashed the disk image from Lab 3 and lifted our completed code onto the the new disk image.

A second problem that we ran into was the piTFT: since certain portions of the base station was event-driven, and others polling-based, we were forced to separate the program into two parallel processes to accommodate each to minimize delays. We tried threading before switching to multiprocess but apparently in Python threading is not truly parallel and instead relies on context-switching and uses the GIL, which slowed our touchscreen response time to an unacceptable degree. However, unlike threading, multiprocessing does not share the same memory space, so we had to consult the multiprocessing API to figure out how to share values/objects between processes. In our program, the polling process and the main process share the mode of the display i.e. histogram or scrolling history mode.

A third problem occurred when we implemented the GPIO buttons: while we managed to get them functioning for shutdown and reboot, we corrupted an SD card during testing. Our bailout button, connected to pin 27, also gave us problems during testing, since we simply called ‘sudo shutdown -h now’ without cleaning up the program properly. Our professor suggested that we exit the program cleanly i.e. terminates the while loop and let the function call reaches its end.

A fourth problem lies with the piTFT: upon RPi shutdown, the piTFT does not fully turn off; rather, it displays the last vestiges of RPi’s shutdown sequence, since although we turn off the RPi, the piTFT remains connected to the RPi, which is still connected to the battery. This is akin to how a desktop monitor stays on after shutdown; the monitor has to be powered off separately.

More Bugs

There are a few bugs with the final program. Our histogram, which we managed to get functioning with both noise tags and actual tags, resets to 0 after a set number of real tag detections and fails to increment afterwards: we did not discover this until after our demo. A second potential bug is that after we switched to using the disk image of Lab 3, we never set up the RTC, which means that upon the BaseStation’s disconnect from either Ethernet or WiFi, the RPi will likely display incorrect tag times.