Volume 39, Numbers 1 and 2, Winter and Spring 2018 (Special Issue)
Chapter One: Introduction
The purpose of this document is to provide detailed descriptions of the Propeller Experiment Controller (PEC). The PEC is free, open-source software for the Parallax Propeller microcontroller (Parallax Inc.; Rocklin, California) that is designed to meet the basic needs of automated behavioral research. First, the PEC detects behavioral and environmental variables, such as the lever-pressing behavior of a rat in an operant chamber, or the ambient temperature. Second, it affects the environment, in turn often indirectly affecting a subject’s behavior. For example, the PEC may control a pellet dispenser, shock grid, stimulus light, or heater. Third, the PEC saves detailed data about any event of interest in an experiment (i.e., dependent and independent variables). In addition to producing its own standard data spreadsheet, the PEC also supports MedPC formatted data, a common standard, and user-customized data output. Finally, the PEC implements the above needs (detect, affect, and save) at very precise intervals of time while also allowing the user to execute events at specific times and record temporal variables. The PEC also goes beyond the basic needs of behavioral research in that it is both uniquely portable, not requiring a connection to a computer, and is very affordable compared to commercial alternatives, costing under $100.00 for the basic experiment controller.
Chapter Two: Technical Specifications of the Parallax Propeller
The Propeller Experiment Controller (PEC) is designed around the capabilities of the Parallax Propeller microcontroller. In this chapter, we will provide an overview the Propeller’s hardware. We will not provide a comprehensive description of the Propeller’s features, instead we will offer an informative framework as a necessary foundation for later discussion of the PEC. The Propeller Datasheet (Parallax Semiconductor, 2012) and Propeller Manual (Martin, 2011) should remain the primary reference on the technical specifications of the Propeller. To make the most of this chapter, the reader should have a basic understanding of electronics. Many introductory resources are available online (see Appendix B), including Parallax’s website.
Chapter Three: Programming the Propeller with Spin
The Propeller can be programmed in several languages, including the Propeller’s native languages, Spin and Propeller Assembly (PASM), as well and as C/C++. The Propeller Experiment Controller (PEC) software is currently available in Spin, so we will only discuss use of this language. Spin is a high-level language created specifically for the Propeller. High-level languages are designed to be easy to use, but do not directly give instructions to a microcontroller or computer. Instead, high-level languages must be transformed into a low-level language that is specific to the hardware being used. For the Propeller, the low-level language is PASM. The transformation from high-to low-level languages can be done by interpreting during operation, or by compiling before a program begins. Generally, interpreted code is slower than compiled code. Spin presents an interesting intermediate between an interpreted and a compiled language. Spin is initially compiled into bytecode, but the bytecode itself is interpreted as a program runs. PASM does not require interpretation and is thus much faster than Spin. However, as a low-level language, PASM is also generally harder to use. Fortunately, Spin programs can launch PASM programs in a new cog, allowing an easy-to-use Spin program to also implement fast, powerful PASM functions. The PEC uses this technique in several cases. The code for communication with an SD card, for example, is written in PASM and is very fast. However, it can be controlled by the user with simple and efficient Spin statements.
Chapter Four: Getting Started with the Propeller Experiment Controller
This chapter describes how to get started with the Propeller Experiment Controller (PEC). It provides information on acquiring the necessary hardware and installing software. There are many hardware options when setting up a system that uses the PEC, much of this will vary based on individual needs. The Propeller Datasheet (Parallax Semiconductor, 2012), Propeller Manual (Martin, 2011), and other information on Parallax’s website (Parallax.com) can be useful for determining the best setup for your application. As the specific needs vary per application, we cannot provide a tutorial on every option. Instead, we provide an overview of the commonly used hardware suitable for someone new to microcontrollers.
Chapter Five: Propeller Experiment Controller Overview
The Propeller Experiment Controller (PEC) software primarily consists of two interdependent Spin objects: Experimental Event and Experimental Functions. Both objects contain a variety of methods that allow the user to execute complex tasks using simple, concise instructions. These objects were designed to work together to fulfill the complex requirements of behavioral research, and often use a specific workflow to implement an experiment. In this chapter, we provide an overview of the PEC system, describing the overall roles of Experimental Event and Experimental Functions, and discuss the basic workflow of a typical experiment. More detailed descriptions of Experimental Event and Experimental Functions are provided in Chapter 6 and Chapter 7, respectively.
Chapter Six: Experimental Event
Experimental Event has a number of public methods that can be used in an experiment program. The public methods can be used in any program that imports the Experimental Event object. A number of private methods are also present, but these cannot be used by parent programs. The following sections describe the pubic methods in Experimental Event that users may employ in their programs. The headers for each section represent the method name, with the method parameters in parenthesis. This is the same general format as would appear in a program.
Chapter Seven: Experimental Functions
The Propeller Experiment Controller’s (PEC) Experimental Functions object provides a variety of public methods to fill the diverse needs of behavioral experiments. To accomplish this, many of the methods in Experimental Functions have multiple variations, such as the several variations of the StartExperiment method. Other methods are related and codependent. For example, the SetFrequency method can generate audio frequencies on I/O pins, but it first requires a StartFrequencyGenerator method to be used. Because of the relationships between the methods in Experimental Functions, the methods are grouped together into method families. In the following sections, we will discuss each method family, as well as individual public methods of Experimental Functions. Private methods cannot be used in other programs and thus will not be discussed. The headers for each method represent the method name, with the method parameters in parenthesis.
Chapter Eight: Applications of the Propeller Experiment Controller
This chapter describes some applications of the Propeller Experiment Controller (PEC). First, it describes how to connect the Propeller to some common types of equipment and how to interface with this equipment using the PEC’s Experimental Event and Experimental Functions objects. Second, it demonstrates several different variations of the PEC’s standard workflow, as well as how the workflow can be adapted to many purposes. Finally, this chapter provides an overview of several of our implementations of the PEC in order to provide a greater understanding of the capabilities of the PEC. Variations and expansions of these applications will provide the user with a number of possibilities. It is up to the user to decide what implementation of the PEC will work best for his or her purpose.
Chapter Nine: Future Directions and Conclusion
The Propeller Experiment Controller (PEC) was developed to meet the needs of research in our laboratory, beginning with a master’s thesis on sexual conditioning in pigeons (Varnon, 2013), and the development of an inexpensive conditioning and learning laboratory (Varnon and Abramson, 2013). As we continued to use the PEC in our laboratory, additional features were added to solve unique problems that we encountered. For example, the methods to record and save raw data events were developed specifically to help a student record light emitted by bioluminescent algae. Development of raw data events allowed us to investigate, not only if the algae illuminated, but also the brightness of the light. Many such features have been added to the PEC over the course of its development, and these additions have proved to be instrumental to using the Propeller as an experiment controller. In the following sections, we describe some potential areas of future development that may also be useful in many applications of the PEC.
Appendix A: Glossary
Appendix B: Useful Links
Appendix C: Character Charts