You’ve worked all day on implementing a complicated function and it’s time to see whether it works. You compile the C++ code and program the memory on the microcontroller.
Dead. Nothing happens.
What to do? First, obviously look for any compiler warnings, such as infinite loops, etc., but if everything looks good, where do you turn to?
In mechatronics there are often many different systems working together and each possibly has its own computer software, hardware programmer, clock speed, voltage input and much more variations. How do you keep all of this straight? Data sheets are vital to have easily accessible and often having both a digital and hard copy is a good idea. The hard copy is good so you can not only rest your eyes, but also to make it easier to type on the computer, e.g. while looking at register descriptions. Digital copies of data sheets in PDF format are wonderful because you can search a document or an entire folder of documents for a search string.
But who wants to always read through data sheets to find what voltage to plug a motor into?
Doing things by memory can be costly and even dangerous — it’s a huge source of human error. You need a central place with condensed information, such as a motor and voltage chart, or a header pin diagram with descriptions, with easy to understand notation in your own style.
A detailed notebook would be essential to help solve these problems.
I’ve seen a researcher too often using a legal pad to write down e.g. resistor values or baud rate calculations. It may be possible to save legal pad sheets of paper, but it’s not natural to save a pile of ragged-topped sheets of paper that are likely curled or otherwise unkempt. When a change cascades through the system, such as an increased baud rate, having the previous calculations in a notebook (that were written as you did them) would help to quickly transition.
I suggest writing almost everything in a notebook as you work on a project. I like to color-code and use symbols to help me find information and make it easier to read. I’ll share one of the early pages of my notebook for a project I’m working on this summer:
The notebooks I love to use do NOT have easily removable pages (no pre-perforated pages) and have pre-numbered pages. A stock photo of my notebook is to the left. Brainstorming with others or by myself, reading journal articles, data sheets, random ideas, measurements, code changes,… I put all of it in my notebook with the date and often even the time. This leads up to my second point.
Working with others on code? or even by yourself? You should be using version control.
The notebook that I keep lines up nicely with version control, so I can see the reasons I made the changes (in the notebook) and what code I actually changed (version control). I use Subversion (SVN), and after I get something working, even if it’s small, I commit the change to the repository. A repository is a relatively secure server where you upload your source code. The SVN server keeps track of file changes between commits. This means if you change one register’s hex value, looking at the difference between two versions of the file, you can easily find the previous hex value and the new hex value. You can find much more about version control here and about Subversion here.
A recent experience I had:
I spent an entire day trying to write simple communication between embedded devices by deciphering data sheets and example code. I wrote my functions and tested them on a robotic arm. They worked! It was the end of the day, so I committed my changes to the repository and went home. After two more days of work of further programming, everything stopped working. The SVN repository was futile because there were too many changes listed, and would take too long to go through. I saved a copy of my changes and reverted to the previous working copy, but now what do I have to change in the working code to catch up to were I was before? I certainly didn’t want to simply copy and paste between the copies, because there was something seriously wrong (even though possibly insignificant), causing nothing to work. Looking at my notebook, I wrote down what things I meant to implement, such as “Function to lock motor on button press.” and “Function to go to a position.” and within an hour had re-implemented the functions, and the ghost error was gone.
Have any tips or questions on keeping a notebook, avoiding errors, version control, or otherwise? Comment below and I’ll respond to any questions.