Monthly Archives: August 2016

More code cleanup

by

I spent the time on this project this week cleaning up the code to match code style and better documentation.  Boring things just have to be done.  I would say in most projects, that approximately 50% of my time is spent on stuff that needs to get done but I don’t enjoy doing.  If you get a good team, this percentage can be reduced.  For instance, some software developers enjoy and even find fascinating the stuff I find boring and tedious.  So if you have a team that is well filled out, then each person gets to work on the stuff he finds interesting.

There will always be some areas that need to be done that no one on your team finds interesting to do and it will just have to get done.  It can be assigned, or just fall to the most relevant team member.  Sometimes the task is shared.

Of course for the Uprogrammer project, I am the “team”.  This means all the tasks (boring or otherwise) fall to me.

This week I worked on the following files.

gpio16.c — reformatted style, no other changes

sigma_delta.c — reformatted style, removed excess comments and dead code

simple_serial.c — reformatted style, skipped editing(big project)

spi_overlap.c — reformatted style, removed excess comments and dead code

SPI.c — reformatted style, removed excess comments and dead code

SPIram.c — reformatted style, removed excess comments and dead code

After all these changes, the code still compiled with no errors or warnings. This is all I had time for this week. I have uploaded these changes to GitHub. Use the link at the top of the right column to download it.  No version change, no functional changes.

I would love to have help on this project. Do you find this project interesting? I could use help in all aspects of this project especially firmware development.  Would you like to be a developer on this project? What parts of this project do you find interesting?

Code Style

by

Along with self and or well documented code, there is a way to format the code.

A style guide (or manual of style) is a set of standards for the writing and design of documents, either for general use or for a specific publication, organization, or field. (It is often called a style sheet, though that term has other meanings.) from Wikipedia.

In software(and firmware) coding it is good to follow a style guide.  Some software developers are very passionate about which style they follow.  My opinion is to pick one that you like you and stick with it. When working on code that was not written by yourself, you should match the style of the original author.  I am not passionate about which particular style to use, but I believe that a project should follow the same style in every file.  When the compiler or interpreter doesn’t require specific details, things like indent size, block placement, and capitalization, are left to the programmers choice.

I have not chosen a particular style. This week I am looking at the common coding styles that are used.  I intend to pick one for this project.  I want to choose wisely because I will probably use whatever I choose on all subsequent “C” projects.  I want to choose a style that is popular because, I want a high probability of seeing it in other code I will be working with.  I also want a style that is easy to read. I don’t care whether tabs or spaces are used for indenting, or how far indenting goes.  I found a good article describing why to use and adhere to a style guide.

One thing I found useful in that article, is that Eclipse has a code formatter that will verify your code follows a particular style.  There are four built in “C” code styles: K&R, BSD/Allman, GNU, and Whitesmiths. If I type Shift+Ctrl+F while a source file is selected, Eclipse will apply the style to the whole file.  A online poll I found indicates Allman and K&R are the most commonly used.  I personally like the Allman style better.

I have decided on the BSD/Allman style moving forward with this project.

Do you have a particular coding style you use.  What are it’s advantages and or disadvantages?

Good Enough

by

Designing anything new rarely goes as expected.  Of course you try to design as much as possible using technology and designs you are already familiar with.
I was working with a monopole wire antenna this week.  I needed to tune and impedance match the antenna to be as efficient as possible between 905 and 930 MHz.

The tool I had available to do this tuning with is a Spectrum analyzer with a built in Tracking Generator and an external return loss bridge.

Note: For optimal transfer of energy from a transmitter to an antenna, they have to have the same impedance.  Most rf transmitters are designed with an output impedance of 50 Ohms. This means that the most efficient antenna will have a characteristic impedance of 50 Ohms. The characteristic impedance of an antenna depends on it’s length and it’s surroundings.

When the impedance doesn’t match, a matching network is needed to fill in the gap.  If an antenna looks more like a capacitor than an inductor, then a series inductor can be used to make up the difference.  If the antenna looks more like an inductor, then a series capacitor can bring it back to close to 50 Ohms.  Of course the series inductor or capacitor will burn a little energy but most will get transfered to the antenna.

The antenna I worked on this week tuned fairly easily around 860 MHz.  When I cut the antenna shorter for 915 MHz, it became very hard to tune.  My job would have been a lot easier if I had a network analyzer that operated in the 900 MHz Range.  An analyzer would have told me the characteristic impedance of the antenna as well as whether it was more inductive or capacitive.

I didn’t have the a network analyzer and was under a time and budget constraint. My solution was to put different inductors in series and see if that would work. It worked great at 860 MHz. It didn’t work at 915 MHz.  My next idea was to put a capacitor in series, the only capacitor I had that would fit on the PCB was a 0.1uF.  This would be too high of a value of reactance to be useful.

My next idea was to put an inductor to ground to reduce the inductive reactance of the antenna.  This produced mediocre results.  I could only get about 85% efficiency from the antenna in the 900 MHz Band.  I tried successively larger values looking for the best return loss.(most emitted energy).

I had to settle for “Good Enough”. If I get the chance, I would like to go back and buy a capacitor kit that will let me try the series capacitors.  The antenna will work well, but the overall range of the radio will a little bit smaller.

Have you had to settle for good enough?  What are your thoughts about how “Perfect is the enemy of good”?

Code Documentation Firmware V00J

by

I Know that my code is very poorly documented.  So I want to focus on organizing and documenting the code.  To start with, I started looking for online classes that teach documenting code.

I found very little about commenting code.  I did find an interesting article I need to think about a bit more. The general theme of this article is to write code in such a way that comments should be rare.  For instance, code should probably be re-written if it needs comments to explain it. Variables should be named in a way that describes what they contain.

I was just about to give up searching. I was thinking I would start by putting header comments before each function or method.  This article gives pretty good reasoning not to do that. So this week, I decided to look at just one file — user_main.c.  Git does line by line version control.  I decided on one small header block at the beginning of the file.  This header block will indicate the license, original author, and/or the template source.

I looked to the header comments to know what to pass to and get back from a given function.  I have decided to make a new document that describes in better detail how to use each function.  This new file will be called UprogrammerFunctions.txt.  Since I removed the Comment block from in front of user_rf_cal_sector_set, That is the first function I am documenting in the API.

There is a big block of code in user_init() that all it does is set up the IOs to their initial states.  I copied that code into a new function called setup_io_pins() at the end of the user_main.c file. Next, I deleted all the test code I had commented out.  Finally, I made a couple of macros in user_config.h called VOLTAGE_BOOST_ENABLE()  and another one called VOLTAGE_BOOST_DISABLE()

Note: My definition of a macro is the use of a symbolic reference to represent other code.  In this place, I am using VOLTAGE_BOOST_ENABLE()  to represent  gpio16_output_set(0) to make it a little more clear what is going on. I also created a function in wifi.c to set up the wifi modem called wifi_init() and also put a prototype of wifi.init() in wifi.h.  I then moved the two wifi calls out of user_init() into the function wifi_init().

I tried to build and the call to the new function setup_io_pins() caused a linker error.  I needed to create a prototype of this function. I put it in user_config.h and it compiled, I uploaded it and it ran just like before I started cleaning up the code. I believe my user_main.c file is much more readable now.  I have uploaded the new version to GitHub. Click the firmware link in the right column of this page to go look at it or download it.

I would like to hear about your experiences cleaning up and commenting code.  What are your preferences for commenting code.