Lab46 Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
<WRAP centeralign round box>
<WRAP><color red><fs 200%>Corning Community College</fs></color></WRAP>
<WRAP><fs 150%>CSCS1730 UNIX/Linux Fundamentals</fs></WRAP>
</WRAP>

======Project: SCRIPTING PRODUCTIVITY FUN (spf1)======

=====Errata=====

  * any bugfixes or project updates will be posted here


=====Objective=====
To create a set of scripts that operate the sequence of LEDs located on the raspberry pi + breadboard setups located at each pod table.

In a group, you will be creating:

  * an initialization script
  * an incrementing 8-bit binary counter (0-255)
  * a decrementing 8-bit binary counter (255-0)
  * a strobing light sequence (back and forth)

=====Accessing the Raspberry Pi=====
At each pod table is a dedicated raspberry pi 1 model B, interfaced with a breadboard and an array of eight LEDs, each wired up individually to a Raspberry Pi general purpose I/O pin.

Using the 'WiringPi' interface (a software library that also provides some command-line commands, such as the **gpio** tool), we can interact with these I/O pins for purposes of input and output.

====Getting started: logging in====
Locating the appropriate pi (the one situated at your table), you will want to ssh into it from a pod or lab46 terminal.

There are four of these systems, numbered as follows:

  * **pi1b_00** - pod0# table, right corner by white board
  * **pi1b_01** - pod1# table, left corner by white board (and my office)
  * **pi1b_02** - pod2# table, by the main door to the room
  * **pi1b_03** - pod3# table, by the back corner / small whiteboard

Each pi is equipped with a standard raspbian release of Linux (one of the default distributions for the raspberry pi), default user credentials unchanged, so to access we have:

  * username: **pi**
  * password: **raspberry**

You will need to ssh into the geographically appropriate pi (shared by your group)

<cli>
lab46:~$ ssh pi@pi1b_0X
</cli>

NOTE that, just like the first time you accessed lab46, you will likely be prompted to approve the connection ("authenticity of host cannot be established" message) by answering the full "yes" and hitting enter, before being prompted for the password.

====Getting a readout of the GPIO pins====
Using the **gpio** tool on the pi in question, we can obtain the current status of the GPIO pins on the pi with the **readall** parameter; output will appear as follows:

<cli>
pi@pi1b_0#:~ $ gpio readall
 +-----+-----+---------+------+---+-Model B1-+---+------+---------+-----+-----+
 | BCM | wPi |   Name  | Mode | V | Physical | V | Mode | Name    | wPi | BCM |
 +-----+-----+---------+------+---+----++----+---+------+---------+-----+-----+
 |     |     |    3.3v |      |   |  1 || 2  |   |      | 5v      |     |     |
 |   2 |   8 |   SDA.1 |   IN | 1 |  3 || 4  |   |      | 5v      |     |     |
 |   3 |   9 |   SCL.1 |   IN | 1 |  5 || 6  |   |      | 0v      |     |     |
 |   4 |   7 | GPIO. 7 |   IN | 1 |  7 || 8  | 1 | ALT0 | TxD     | 15  | 14  |
 |     |     |      0v |      |   |  9 || 10 | 1 | ALT0 | RxD     | 16  | 15  |
 |  17 |   0 | GPIO. 0 |   IN | 0 | 11 || 12 | 0 | IN   | GPIO. 1 | 1   | 18  |
 |  27 |   2 | GPIO. 2 |   IN | 0 | 13 || 14 |   |      | 0v      |     |     |
 |  22 |   3 | GPIO. 3 |   IN | 0 | 15 || 16 | 0 | IN   | GPIO. 4 | 4   | 23  |
 |     |     |    3.3v |      |   | 17 || 18 | 0 | IN   | GPIO. 5 | 5   | 24  |
 |  10 |  12 |    MOSI |   IN | 0 | 19 || 20 |   |      | 0v      |     |     |
 |   9 |  13 |    MISO |   IN | 0 | 21 || 22 | 0 | IN   | GPIO. 6 | 6   | 25  |
 |  11 |  14 |    SCLK |   IN | 0 | 23 || 24 | 1 | IN   | CE0     | 10  | 8   |
 |     |     |      0v |      |   | 25 || 26 | 1 | IN   | CE1     | 11  | 7   |
 +-----+-----+---------+------+---+----++----+---+------+---------+-----+-----+
 | BCM | wPi |   Name  | Mode | V | Physical | V | Mode | Name    | wPi | BCM |
 +-----+-----+---------+------+---+-Model B1-+---+------+---------+-----+-----+
</cli>

When using the **gpio** tool, we are specifically interested in the "wPi" columns.

====Assembly of LED circuits====
The eight LED circuits established on each pi are hooked into a unique GPIO (wiring pi numbers 0-7).

When the pin is active (3.3V applied, the 'true' or 1 state), the LED will be lit up (turned ON).

When the pin is inactive (0V applied, the 'false' or 0 state), the LED will be OFF.

====Configuring GPIO pins for use with our LEDs====
If you look in the table for wiringPi pins 0-7, you'll see under the "Mode" column that all the needed pins are set to IN or "input" mode (expecting to read data in).

To utilize the LEDs, we need to instead OUTPUT from the pins.

A mode change is needed, which can be accomplished with the **gpio** command, **mode** parameter. It requires the wiringPi pin number (0-7), and the desire mode to set it to (in, out).

To set wiringPi GPIO pin 0 for output mode, for instance, we'll want to do this:

<cli>
pi@pi1b_0#:~ $ gpio mode 0 out
</cli>

You may want to repeat (or loop) this for the remaining pins.

====Writing to the GPIO pin====
To modify the state of the pin (it can be in a '0' or '1' state), we once again use the **gpio** command, with the **write** parameter. It requires the wiringPi pin number (0-7) and the state we wish it to become (0 is OFF, or 1 being ON).

To write a 1 to wiringPi GPIO pin 0, we'll want to do this:

<cli>
pi@pi1b_0#:~ $ gpio write 0 1
</cli>

Similarly, to turn it back off again, we'll want to write a zero there:

<cli>
pi@pi1b_0#:~ $ gpio write 0 0
</cli>

You will want to perform similar actions on the other LED-wired pins to create the desired situations as required by this project.
=====Process=====
It is your task to write 4 scripts, specifications laid out as follows:

====script1: initialization script====
A useful bit of logic, appropriately setting the pin modes to OUTPUT and turning the pins to an OFF state is likely something your other scripts will want to call upon before they perform their intended tasks.

Therefore, you will start by writing a script you can run that establishes a sane operating environment for your LED manipulations.

This script should make use of a loop to perform its task (setting OUTPUT mode and WRITING a 0 state to the pin).

====script2: incrementing 8-bit binary counter====
It is not by accident the LEDs were build next to each other, wired up in sequential fashion as they are. The intention was to create an 8-bit  quantity that you could manipulate.

So, it is your task for this script to write a visual "binary counter", that, lacking any arguments, starts at 0 (00000000), and with a short delay between each state change (say, no less than 0.5 seconds), increments one at a time until it reaches 255 (11111111), where 0 indicates an LED in OFF position, and 1 indicates an LED in ON position.

You will want to create your visual output in standard observed form for binary numbers (ie the left side denotes the MOST SIGNIFICANT BIT, and the right-most side denotes the LEAST SIGNIFICANT BIT).

For example, if displaying the number 13 with this script, our binary value being output should be:

<code>0 0 0 0 1 1 0 1</code>

Where 2^7=0, 2^6=0, 2^5=0, 2^4=0, 2^3=1, 2^2=1, 2^1=0, and 2^0=1.

Also, the script should accept the following optional arguments:

  * $1 - step value (the rate of incrementation; default is 1)
  * $2 - starting point (any value between 0 and 255, inclusive)
  * $3 - ending point (any value between 0 and 255, inclusive)

Unless you merge in the decrementing script logic into this script, you should do error checking to ensure that the starting point is LOWER than the ending point, otherwise display an error message and exit, leaving the LEDs in an OFF state.

If you DO choose to incorporate decrement logic into this same script, a starting point being HIGHER than the ending point indicates the script should decrement instead of increment.

If ONLY a step and starting value is given, proceed from that point to the final bound (being an incrementer if step is positive, or decrementer if step is negative).

====script3: decrementing 8-bit binary counter====
Like the script above, only its default behavior is to decrement instead of increment.

NOTE that you CAN combine script2 and script3 into ONE script, with the appropriate supporting logic to handle both modes.

====script4: strobe/flash display====
The purpose of this script is to create a fancy flashing pattern, lighting up and turning off the LEDs to create wavy or "back and forth" style visual effects.

=====Specifications=====
Evaluation will be based on correctness of values as well as on commenting/formatting/indentation/spacing of scripts.

  * groupwork! This project is specifically designed to be performed in groups.
    * I want to see groups ranging from a minimum of 2 people, to a maximum of 4 people. Any less and any more are not allowed.
    * There are 4 pi's, 1 per table. There are 11 total people in the class, and on average 9 people regularly showing up; this could mean three groups of three (for example).
    * EVERY group member needs to be identified in your scripts (in a comment listing everyone).
    * ONE GROUP PER TABLE (no group should share a pi with another).
    * EVERY group member needs to be familiar with the end products
    * EVERY group member needs to submit a copy of the scripts (they should all be identical- I will check)
      * in the event you feel other group members have not lived up to their obligations, you may alter your scripts accordingly (be it not giving them the final product, or enhancing functionality to bring it in compliance, or leaving comments indicating who wasn't pulling their own weight).
    * EVERY group member needs to do an approximately equal portion of the work. Slackers should be called out (I'll be keeping an eye out as well) and they will lose credit.
    * EACH group member is responsible for prolifically commenting and demonstrating functionality of ONE of the scripts. The commenter should be identified at the top of the particular script. No one person should be commenting all the scripts.
    * This project is designed to be done DURING class time. It may offer up some useful insights into other projects (that you're doing on your own).
  * You need to check your arguments to ensure if they are present and valid.
    * all mentioned arguments implementing their indicated functionality
    * any invalid arguments or operating modes should generate an error and the script terminating (ie if the 'starting' number is the letter 'g').
  * your script needs to commence with a proper **shabang** to run using bash; your script needs to end with an "**exit 0**" at the very end
  * comments and indentation are required and necessary
    * comments should explain how or why you are doing something
    * indentation should be consistent throughout the script (no mixing of different indentation units; no mixing of tabs and spaces)
    * indentation is to be no less than 3 on-screen spaces (I recommend tabstops/shiftwidths of 4).
  * continuing with our shell scripting, your scripts will need to employ in a core/central way (note that both scripts may not each need all of these, but across both scripts, you should make sure that each of these concepts is utilized):
    * variables
    * command-line argument parsing and usage
    * conditional/selection structures
    * loops
    * if appropriate: 
      * command-line pipelines
      * command expansions
      * regular expressions
  * your logic needs to:
    * flow (one thing leads into the next, as best as possible)
    * make sense within the given context
    * avoid redundancy
    * be understood by you, and everyone in your group (no grabbing snippets that seem to "work" from the internet)
      * if you gain inspiration from some external resource, please cite it
      * comments are a great way of demonstrating understanding (if you explain the why and how effectively, and it isn't in violation of other aspects, I'll know you are in control of things)

To be sure, I'll be checking to make sure you solution follows the spirit of what this project is about (that you implement functional, flowing logic utilizing the tools and concepts we've learned, in an application that helps demonstrate your comprehension). Don't try to weasel your way out of this or cut corners. This is an opportunity to further solidify your proficiency with everything.

=====Spirit of project=====
The spirit of the project embodies many aspects we've been focusing on throughout the semester:

  * recognizing patterns to employ effective solutions in problem solving
  * utilizing concepts and tools covered
  * demonstrating comprehension of concepts, tools, and problems
  * employing concepts in knowledgeable and thoughtful manner
  * following instructions
  * implementing to specifications
  * utilizing creativity
  * being able to control solution via consistent, clear, and organized presentation
  * approximately equal involvement and impact of all group members on the brainstorming and development of the finished scripts.

Basically: I want your solution to be the result of an honest, genuine brainstorming process where you have figured out a path to solving the problem, you have dabbled and experimented and figured things out, and you can command the concepts and tools with a fluency enabling you to pull off such a feat. Your solution should demonstrate the real learning that took place and experience gained.

Cutting corners, avoiding work, skimping on functionality, cheating through getting others to do work for you or finding pre-packaged "answers" on the internet violates the spirit of the project, for they betray your ability to pull off the task on your own.

=====Identifying shortcomings=====
I would also like it if you provided an inventory of what functionality is lacking or out of spec when you submit the project. The better you can describe your deviations from stated requirements, the more forgiving I may be during evaluation (versus trying to hide the shortcomings and hoping I do not discover them).

The more fluent you are in describing your shortcomings on accomplishing the project (ie "I didn't know how to do this" is far from fluent), the better I will be able to gauge your understanding on a particular aspect.

This can be in the form of comments in your script, or even a separate file submitted at time of submission (if a file, be sure to make mention of it in your script so I can be sure to look for it).

=====Submission=====
By successfully performing this project, you should have a fully functioning set of scripts by the names **script1** through **script4** (possibly lacking **script3** if you've merged functionality with **script2**), which are all you need to submit for project completion (no steps file, as your "steps" file ARE the scripts you wrote).

To submit this project to me using the **submit** tool, run the following command at your lab46 prompt:

<cli>
$ submit unix spf1 script1 script2 script3 script4
Submitting unix project "spf1":
    -> script1(OK)
    -> script2(OK)
    -> script3(OK)
    -> script4(OK)

SUCCESSFULLY SUBMITTED
</cli>

You should get some sort of confirmation indicating successful submission if all went according to plan. If not, check for typos and or locational mismatches.

I'll be looking for the following:

<code>
52:spf1:final tally of results (52/52)
*:spf1:scripts submitted in accordance with specifications [4/4]
*:spf1:initialization script logic present and functions [4/4]
*:spf1:initialization logic uses loop to automate task [4/4]
*:spf1:incrementation script logic present and functions [4/4]
*:spf1:counter script logic is centrally based on loop [4/4]
*:spf1:counter script logic does adequate error checking [4/4]
*:spf1:decrementation script logic present and functions [4/4]
*:spf1:flashy script logic present and functions [4/4]
*:spf1:scripts appropriately call the initialization logic [4/4]
*:spf1:scripts are organized and easy to read [4/4]
*:spf1:scripts effectively utilize selection structures [4/4]
*:spf1:scripts effectively utilize looping structures [4/4]
*:spf1:scripts are proper bash scripts with shabang and exit [4/4]
</code>

Additionally:
  * Solutions not abiding by spirit of project will be subject to a 25% overall deduction
  * Solutions not utilizing descriptive why and how comments will be subject to a 25% overall deduction
  * Solutions not utilizing indentation to promote scope and clarity will be subject to a 25% overall deduction
  * Solutions not done in a valid group will be subject to a 25% overall deduction