Project 4B
Sensors Input

INTRODUCTION:

One of the things that makes small, low-power-consumption systems interesting is ability they give us to create software that interacts with people in the physical world. The input side of those interactions is via a variety of local sensors (e.g., for sound, light, temperature, position, motion, pressure). The output side can be sensory (e.g., sound, lights, low power displays) or physical (e.g. mechanical actuators), or (through digital and analog outputs) any other controllable device. Building interactive personal appliances requires us to be able to communicate with the types of sensors, indicators and actuators that can be connected to such systems. Such devices have become increasingly popular and common in recent years.

In this project we will create applications that run in an embedded system, read data from external sensors, and log the results. Real world devices of this kind are commonly networked. We'll take that step in Project 4C. For now, the device you build will be stand-alone.

RELATION TO READING AND LECTURES:

This project is an introductory exploration of technologies and services not covered in the reading and lectures.

PROJECT OBJECTIVES:

• Primary: Demonstrate the ability to design, build and debug interactive applications on an embedded system.
• Primary: Develop the ability to work with embedded system sensors and actuators through standard tool kits.
• Primary: Gain experience with the processing of digital and analog inputs on an embedded system.

DELIVERABLES:

• C source files for an embedded application that builds and runs (with no errors or warnings) on an embedded system
• A Makefile to build and test your application. The higher level targets should include:
  • default ... build your program (compiling with the -Wall and -Wextra options).
  • check ... execute an automated smoke-test of your application to see if it runs and can talk to its sensors.
  • clean ... delete all programs and output generated by the Makefile
  • dist ... (runnable on a Linux desktop or server) create the deliverable tarball
Note that this Makefile is intended to be executed on an embedded system
• a README file containing:
  • descriptions of each of the included files
  • any other comments on your submission that you would like to bring to our attention (e.g., research, limitations, features, testing methodology).

PREPARATION:

• If you have not already done so, look at the documentation for the poll(2) system call or the O_NONBLOCK option used with the open(2) system call or fcntl(2) F_SETFL operation.
• Read the documentation on the Grove Temperature Sensor, and the algorithm for converting a reading into a temperature.
• Review the documentation for the MRAA library, an open source, platform independent library for embedded system I/O. (The MRAA page does not explicitly list the Beaglebone Green Wireless, the device you will be using, as supported, but it is supported.) Also read the General Purpose and Analog I/O tutorial that discusses the particular classes you will be using. These classes include the functions you will be using to read from the temperature sensor and button. (Note that to link with this library you will have to add -lmraa to your library search list).
• Read the instructions that came with your Grove Starter Kit. They include information on all of your sensors and instructions on where to plug each in to the Base Shield.
• Attach your Grove Base Shield (a plug-on daughter-board with connectors for all of your sensors) to your embedded system.
• Attach your Grove Temperature Sensor to the Analog A0/A1 connector on your Grove cape, where it will be addressed as I/O pin #1.
• Attach your Grove Button to the GPIO_50 connector on your Grove cape, where it will be addressed as I/O pin #60.
• The calibration constants for converting thermometer readings into temperatures depend on the Grove cape voltage switch being set to 5 volts.
• Power-up your embedded system and confirm that you can still log in and transfer files to it.

PROJECT DESCRIPTION:

Write a program (called lab4b) that:

• builds and runs on your embedded system.
• uses the AIO functions of the MRAA library to get readings from your temperature sensor.
• samples a temperature sensor at a configurable rate (defaulting to 1/second, and controlled by an optional --period=# command line parameter that specifies a sampling interval in seconds).
• converts the sensor value into a temperature. By default, temperatures should be reported in degrees Fahrenheit, but this can be controlled with an optional --scale=C (or --scale=F) command line parameter.
• creates a report for each sample that includes:
  • time of the sample (e.g. 17:25:58) in the local timezone
  • a single blank/space
  • a decimal temperature in degrees and tenths (e.g. 98.6)
  • a newline character (\n)
• writes that report to the stdout (fd 1).
• appends that report to a logfile (which it creates on your embedded system) if that logging has been enabled with an optional --log=filename parameter.
• uses the GPIO functions of the MRAA library to samples the state of the button (from your Grove sensor kit) and when it is pushed ...
  • outputs (and logs) a final sample with the time and the string SHUTDOWN (instead of a temperature).
  • exits
• Your program can assume that the sensors are connected as recommended by the Grove documentation.

Note that we want you to use MRAA AIO/GPIO functions to access your sensors, and not the (more powerful and convenient) Grove library functions. The Grove library hides all of the details of embedded I/O, sampling and signal interpretation, but only works for the Grove Sensors. We want you to get experience with direct control of and access to the digital and analog I/O pins.

Many people have observed that the recommended calibration constants appear to be off by ten degrees or more. Every sensor (including the ones that will be used when we grade your submissions) seems to read differently.

The time returned from localtime(3) will only be in the correct timezone if you have correctly configured the local timezone on your embedded system.

• SCALE=F
  This command should cause all subsequent reports to be generated in degrees Fahrenheit.
• SCALE=C
  This command should cause all subsequent reports to be generated in degrees Centegrade
• PERIOD=seconds
  This command should change the number of seconds between reporting intervals. It is acceptable if this command does not take effect until after the next report.
• STOP
  This command should cause the program to stop generating reports, but continue processing input commands. If the program is not generating reports, merely log receipt of the command.
• START
  This command should cause the program to, if stopped, resume generating reports. If the program is not stopped, merely log receipt of the command.
• LOG line of text
  This command requires no action beyond logging its receipt (the entire command, including the LOG). In project 4C, the server may send such commands to help you debug problems with your reports.
• OFF
  This command should, like pressing the button, output (and log) a time-stamped SHUTDOWN message and exit.

All received commands will be terminated by a new-line character ('\n'). Note that when your program is tested (by the sanity checker or grading program) stdin will not be a console, but a pipe. A single read may return a partial line or multiple lines. Make sure that your program buffers and lexes its input, and does not assume that one call to read(2) will return one command.

Nothing special needs to be done about strange combinations of commands:

• a START when you are already started is a no-op.
• a STOP when you are already stopped is a no-op.
• it is not expected that a STOP, PERIOD, or SCALE command will force out a report whose time as not yet come.

If logging is enabled, all received commands (valid or not) should be appended to the log file (exactly as received, with no timestamp) but not displayed to standard output. A sample log is shown below:

	11:37:41 98.6
	11:37:42 98.6
	11:37:43 98.6
	PERIOD=5
	11:37:44 98.6
	11:37:49 98.6
	11:37:54 98.6
	SCALE=C
	11:37:59 37.0
	11:38:04 37.0
	STOP
	START
	11:38:19 37.0
	11:38:24 37.0
	OFF
	11:38:27 SHUTDOWN

If you are typing commands to your program, you may see the echos interspersed with temperature reports. This is unimportant, because they should be correctly distinct in your log, and when we test your submission, the input will becoming from a program rather than a console.

The sanity check script will send a series of commands to your program, and some implementations process all the commands before generating any reports. To make sure this doesn't happen, you should generate your first report before you start processing input commands. Again, this will not be an issue during testing because there will be delays between the commands when we test your program.

You could implement this program with separate threads for sensor polling and command processing, but the computation associated with each operation is so small that you may find it much simpler to use a single thread (and polling or non-blocking I/O) to avoid hanging on standard input for commands that only rarely arrive. A poll system call cannot tell you that the button has been pushed, but GPIO pin read is a non-blocking operation, so you can simply read the button status periodically. If your interval between reads is too long, the button may be pressed and released before you can read its status. To avoid this problem, you can either use a short polling interval or arrange for an interrupt/signal when the button is pushed.

To facilitate development and testing you might find it helpful to write your program to support a (-DDUMMY) define whose special code includes mock implementations for the mraa_aio_ and mraa_gpio_ functionality. Doing so will enable you to do most of your testing on your regular computer. When you are satisfied that it works there, modify your Makefile, run the command "uname -r", and check for the presence of the string "beaglebone" in the resulting output. If it is not found, build with a rule that passed the -DDUMMY flag to gcc.

SUBMISSION:

Your tarball should have a name of the form lab4b-studentID.tar.gz. You can sanity check your submission with this test script. It should run on an embedded system, but if your program is (as above) runnable on your Linux development system, the sanity check script should also run there. There will be no manual re-grading on this project. Submissions that do not pass the test script are likely to receive very low scores.

Your README file (and all source files) must include lines of the form:

NAME: your name
EMAIL: your email
ID: your student ID

SLIPDAYS: #days

SLIPDAYS: 2

GRADING:

Points for this project will be awarded: