MAE 476/576: Mechatronics

Spring 2003

---

[ University at Buffalo] - [ College of Engineering ] - [ MAE Department ] - [Automation Robotics & Mechatronics Lab]

---

Report Documentation Guidelines

Abstract

The purpose of this note is to emphasize the creation of good documentation and provide detailed guidelines for the reports submitted for the lab exercises and final project.

Introduction

The course requirements include submission of several reports for the lab exercises and final project. As a prelude to writing, assume that the reader is someone with the same technical background as yourself but has never read or heard anything about your particular assignment before. It is also pays to remember that these reports must cater to two sets of audiences: (1) readers who want to find out if what you have done will solve their problems; (2) readers who want to reproduce what you have done.

There is no specific length specification for these reports, but try to keep them concise. Be sure to include background material, provide details of what you have accomplished including schematics, code listings etc. Be sure to discuss the assumptions, methods you have employed and obstacles encountered during the process of implementation. Negative results (i.e., failure to achieve your goals) are as important (or more so) than positive (happy!) results. Use the report to also document what you know about what is going wrong and the direction you took to remedy the problems.

Summary of Requirements

The reports should be in standard engineering report format including:

· Title - should be descriptive and short

· Abstract - capsule description of what’s in the report (Remember that in many cases the title and abstract will be published without the rest of the report, so they need to stand on their own.)

· Introduction - what you are trying to do and why, choice of solution method

· Body - One or more sections describing the setup and its components, the programming and a discussion of the results. More details are given below.

· Discussion - relate the results to the objectives

· Conclusion - succinct statement of what was accomplished and what to do next

· Contributions of each member of the team -- A short paragraph (4-5 sentences) to describe how the task was split up between team members and how each member contributed to the implementation and the report. "We both did it!" is an inadequate description.

· Appendices - for relevant material not needed by the average reader

Prepare the report using a word processor (Microsoft Word preferred) for text, a computer-drawing program (e.g. 2D CAD, Corel Draw, Microsoft Photo Editor) for drawings, and software (like CircuitMaker) to draw the circuit diagrams. Use spreadsheet programs (e.g. Microsoft Excel) to prepare tables and graphs if applicable.

You may wish to integrate all report components using a Desktop Publishing program. If you want to use a report as part of your portfolio (for job interviews), you should produce a final copy on a high quality printer (laser, ink jet) after it has been graded and corrected.

The following highlights some specific report requirements:

Title

This should include the name of the report, the course name, your name and date when the report was completed. The report name should be fully descriptive. For example, "Exercise One, Interfacing Basic Stamp with LCD and Keyboard" is fine. "Exercise One" by itself is not.

Body Section: Setup, Components, Programming, Analysis and Explanations

This section describes what you learned and what you want the reader to understand. Also, it describes and any problems you encountered. It describes how you solved the problem or speculation as to how to solve the problem if you did not actually solve it.

Explain any theoretical background. Give a detailed description of hardware, software and mathematical techniques as required. For analysis show calculations. Include tables such ASCII chart (or provide reference) where applicable.

State specifically how you tested the circuit. Show the data used for testing. Show observations from instruments. Describe how troubleshooting was done. Drawings or tables of instrument readings should include the instrument settings used.

You must specify how the system worked. For example, stating that "I tested the keyboard and it worked" is no good. Instead use something like, "Keyboard operation was tested by pressing keys and seeing the corresponding key character displayed on the terminal screen."

In addition to circuit theory, a sub-section should describe any user operation instructions if applicable. For example, if the system is a keyboard interface, provide instructions as to how to start up the system and how to use it.

Figures and graphs can convey a lot more information than text alone. " A picture is worth a thousand words!!" Use figures, schematics and graphs appropriately, with suitable labels and a descriptive caption and refer to them in the text of the document.

Parts List

List all the parts. Cross-reference all parts to applicable part numbers and detailed manufacturers identification number. Include specifications of passive components, wiring and boards where applicable. For a sample, see Table 1 in this document.

Table 1. Components used for simple resistive circuit

Schematic Drawings

A sample schematic of a simple resistive circuit is shown Figure 1 in this report. See other sample circuits enclosed with this document. For circuit diagrams with electronic components, the circuit diagrams must include all pin numbers and signal names. Show cable socket and bus connector numbers when applicable. Show all test points if applicable.

Figure 1 Circuit diagram of a simple resistive circuit

The schematics should identify parts by name (and the part number where approapriate) used in the parts list and should show every individual connection. If you need to use more than one page, cross-reference any connection that continues on another page. For complicated schematics, include a block diagram to summarize the system.

Program Listings

Your program listings should include both source code (on the left) and detailed comments (on the right). You may put comments on a separate line to maintain a neat appearance.

Comments must clarify the program application and not merely translate the BASIC/C language or mnemonics. In other words, they must be appropriate to the intended application. Translating BASIC/C/mnemonics is appropriate only when the intended goal of the program is to illustrate features of an assembly language. This probably does not apply in your case.

Example 1.

The following fragment of code is fine.

CLRB ;initialize data buffer counter

while the following fragment is not fine. In fact it is useless unless its purpose is to teach the basics of assembly language.

CLRB ;clear contents of ACCB to zero, an inherent mode instruction

Example 2,

The following code fragment is fine.

for (intCounter=1;intCounter<10;intCounter++)

\\ Create an incremental counter as part of a for loop

{

printf("Current Value of the intCounter is:%d \n",intCounter);

\\ Print out the value of the counter as the for loop executes

}

while the following code fragment is not

for(I=1;I<10;I++) \\ for I=1 to 10

{

Printf("I=%d\n",I);

}

You should have comments that summarize the entire program at the beginning. These opening comments should allow someone else to use the program without having to study all of its code. The rest of the comments illustrate details for those who are interested in the details or for those who may wish to modify your program. For a sample of a program listing, see Appendix A and B enclosed below.

Grading

The following is a generic grading sheet which may be used.

Report Grading

Name:

Report: Date:

Item	Maximum Mark	Given Mark	Comments
Introduction & Conclusions	10
Body Section: Analysis and explanations	15
Schematic drawings	10
Program listings	10
Parts list	5
Miscellaneous			add or deduct
TOTAL	50

Suitable marks will be deducted for any of the following (unless specified otherwise)

o Plagiarism between teams

o late submissions

o handwritten reports

o program listings without comments or a title

o drawings and tables without a descriptive title

Appendix A

Sample Program Listing of BASIC code

'************************************************************************
'* Basic Stamp Activity Board Sample Program LTC-1298 *
'* 9 September, 1997 (BS-2) *
'* *
'* This program shows how to use the LTC-1298 from Linear Technology. *
'* Insert the LTC-1298 into Socket A and remove the jumpers in 'X4'. *
'* Apply the analog inputs according to the drawing depicted in the *
'* Basic Stamp Activity Board Notes. Power it up and hit 'Alt-R' to *
'* download. The analog input voltages must be 0-5Vdc. *
'************************************************************************

CS con 12 ' Chip select (low true)
CLK con 15 ' ADC Clock
Din con 13 ' ADC Data input
Dout con 14 ' ADC Data output
config var nib ' Configuration bits for ADC
ADres var word ' Variable to hold 12-bit AD result
startB var config.bit0 ' Start bit for comm with ADC
sglDif var config.bit1 ' Single-ended or differential mode
oddSign var config.bit2 ' Channel selection
msbf var config.bit3 ' Output 0s after data xfer complete

INIT ' Initialization code
high CS ' Deactivate ADC to begin
high Din ' Set up data lines
high Dout
START ' Main loop
for oddSign = 0 to 1 ' Toggle between input channels
gosub convert ' Get data from ADC and display it
debug "Ch:",dec oddSign, " ", dec ADres,cr
pause 500 ' Wait a half second
next ' Change channels
goto START ' Repeat forever
convert ' Convert subroutine start here
config = config | %1011 ' Set all bits except oddSign
low CS ' Activate the ADC
shiftout Din,CLK,lsbfirst,[config\4] ' Send config bits to ADC
shiftin Dout,CLK,msbpost,[ADres\12] ' Get data bits from ADC
high CS ' Deactivate the ADC.
return ' Return to main program

Sample Program Listing of C code

/**********************************************************************
* test_sppspi.c *
* *
* Written by: Geoff Hawker *
* Date: February 12, 1999 *
* *
* This code tests the sppspi.c module routines. It allows the user *
* pick which SPPSPI to test (selected via the parallel port address) *
* and to read all 8 channels from it and to change one of the output *
* channels during each loop. The output is continuously driven *
* until the user applies a key press. *
* *
* INCLUDE FILES: *
* sppspi.h - contains the function headers, and the include *
* statements needed to run the sppspi code *
* *
* TO COMPILE: *
* cc -T1 -o [executable file] test_sppspi.c *
* /home/scoutii/SPPSPI/sppspi.c *
* *
**********************************************************************/

#include <stdio.h>
#include "sppspi.h"

#define SPPSPI1 0x378 /* parallel port addresses of the */
#define SPPSPI2 0x278 /* sppspis being used */

void main()
{
int din[8], dout[8]; /* input and output channels on SPPSPI */
int out_channel, out_value; /* channel and value of SPPSPI output */
int num_SPPSPI; /* which SPPSPI to check (1 or 2) */
int i;
short address; /* parallel port address */

address = SPPSPI1;

/* initializing din and dout arrays */
for (i=0;i<8;i++)
{
din[i] = 0;
dout[i] = 0;
}
/* initializing SPPSPI */
SPPSPI_init();


/* While loop which prompts user to enter which SPPSPI to check,
which output channel to change, and whether to quit the program .
It continues until the user enters -99 for the SPPSPI number. */
while (num_SPPSPI != -99)
{
printf("\nWhich SPPSPI do you want to check (1,2,-99 to quit)?\n");
scanf("%d",&num_SPPSPI);
if (num_SPPSPI == 1) address=SPPSPI1;
else if (num_SPPSPI == 2) address=SPPSPI2;
else
{
printf("\nProgram ends!\n");
SPPSPI_close();
return;
}
printf("Enter which output channel to change (0-7, -99 none)\n");
scanf("%d",&out_channel);
if (out_channel!=-99)
{
printf("Enter value to change output channel %d of SPPSPI %d\n",
out_channel, num_SPPSPI);
scanf("%d",&out_value);
dout[out_channel] = out_value;
}
printf("Press any key to stop writing to SPPSPI.....\n");
while (!kbhit())
{
SPPSPI_read_write(address, din, dout);
}

printf("\n----------------------\n");
for (i=0;i<8;i++)
printf("din[%d] = %d\n",i,din[i]);

}

}