For
nearly every lab, you will turn in a report documenting what you did
to solve the assignment. The biggest factor in the grade of the lab
report will be how easy it would be for another engineer to replicate
your project using only your lab report. Imagine that at the start of
the semester, future you, having just completed ECE 381, is allowed
to magically send back all of the completed lab reports to present
you. Present you is allowed to use these reports for all of the same
labs we will do in the class this semester, as well as any quizzes
given. What information would be useful to present you or any other
engineer that future you could include?
I would argue that you would need at least the following:
- The
report should have a complete statement of the problem being solved.
Don’t assume the engineer handed your report has access to the
class web site and can download the lab descriptions. Tell them what
you did in your own words. Make sure to include all the requirements
for the lab.
- The report needs a list of all parts with quantities used in the lab.
You are given parts kits, however the engineer given your report may
have to seek them out. Be kind to them and let them know what they
need.
- All hardware should be properly diagrammed. This includes the connection
of all pins of the PSoC that are being used. In combination with the
parts list, this should be a complete diagram of what connects to
what. The engineer might also want to know why some of the
components are connected to each other, so make sure to give them a
nice written summary of what the hardware does. This is especially
true if the hardware includes any equations that impact its
operation. Also, if sections of the datasheet of a component are
relevant, put them in your report as well.
- The report should describe the complete configuration of the PSoC in
full detail. This should include a legible screenshot (or multiple
screenshots if many PSoC modules are used) of the schematic in
PSoC Creator. This should also include the module parameters for any User Module
included in the PSoC project. The mapping
of any pins used in the lab should also be given. If there are
equations for the module operation, this would be a good place to
put them, and how your configuration affects them. Also, a screenshot of the
Clock configuration tab would be nice as well. The main idea
here is that the engineer can launch PSoC Creator, add the modules
needed, configure them, route the pins accordingly, and make sure
the global clocks and voltages are set correctly without having
access to your project files.
- The report should include a decent, easy to follow description of the
software. This could be a flowchart, pseudo-code, or just a nice
narrative of your program logic. It should NOT just describe each
line of code as its own sentence. You will include the code in the
report, right? The engineer can look at that if they want a
line-by-line telling. You want to just give them the higher level
logic here.
- The report should describe how the lab was verified. If the engineer has
followed your report up to this point, then you should give them
some way to test that they’ve done what you told them to do.
Cell phone pictures and oscilloscope screenshots would probably be
nice here if applicable. Then they could compare what they would get
with what you got. Your verification should reasonably try to cover
as many test cases as possible here. That way, the engineer has
decent chance of knowing if their design meets the stated
requirements.
- Include the code in the appendix. The code should be well commented so that
the engineer isn’t scratching their head trying to figure out
what you did. Also, as a general rule for coding style, you might
want to make the variable names meaningful for the engineer. It’s
almost like commenting the code as you go along.
As a good example of what a comprehensive report looks like, take a look
at some of the many PSoC application notes. These are essentially labs Cypress engineers come up with to show off
what the PSoC can do. As such, they pretty much include all of the
above.
As far as formatting the report, 1” margins all around with
inline, numbered, captioned figures will work. Equations should be
numbered too. Use a reasonable font like Arial, Times New Roman,
Cambria, etc with 10 pts. as a minimum, 12 pts. as a maximum for the
body text. You are graded on report completeness, NOT LENGTH, so
don't feel the need to use a fixed-width font (except source code should always be formatted using a fixed width font). You can use whatever word
processor you like (MS Word, LibreOffice, Google Docs, Office365, etc.) or LaTeX if
you are feeling bold and want to learn it or already know it.
All reports should be e-mailed as PDF documents to me and CCed to the TA no later than midnight a week after the demo (ie. For a demo due Tues. Feb. 10, the report would be due by midnight Feb. 17).