Code Documentation Firmware V00J

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.

Hello World Firmware V0A

I have finally created a “Hello World” project that works with the Espressif IOT API.

First, in the upper right hand side of this page is a link to the GitHub repository for this project firmware. The general rule for version systems is that you only commit if the code is runnable.  I hope to break the code up into small enough chunks that I won’t get a majorly broken version in the repository, however things happen. If I get stuck, I’ll commit broken code to the repository to keep it current with these blog postings.  GitHub maintains Versions, I’ll try to name each commit in a way that ties back to the current blog entry.  The current commit is the same as the post title, “Hello World Firmware V0A”

Things happened again,  I did a security update on my OS and the esptool.py firmware uploader stopped working altogether.  I did a quick search online and found that the pyserial library started failing with this update.  So I figured out how to roll back to the previous version of the OS kernel and I could get the firmware upload to work.

I copied the AT firmware project into the app directory and ran the gen_misc.sh script file to configure the libraries.  I had some problems with this and I feel I need to know more about how the makefile works.  The gen_misc.sh (gen_misc.bat for windows users) creates a file with the needed libraries for the project.  For GitHub I ended up moving the project to the folder named UProgrammer-Firmware in the same folder that the app folder was in.

I deleted the AT firmware files from the project directory, keeping the user_config.h file in the include folder. I then created a new user_main.c file that just set up the serial port to 115200 baud and sent the text “Hello World” out the serial port from the user_init() function.  This worked and I wanted to do something a little more in depth of the API functionality.  So I started a timer that calls my code called user_state() once every second.  I set up this function to send “Hello World” over the serial connection on the second call of it.  I also removed the sending “Hello World” from the user_init() function.  The function user_init() is called once during boot up of the processor.

I also added the commands to connect to my wifi network.  I verified this by using a utility to see what devices were connected to my network.  When I saw the name espressif for one of the devices, I knew it was connected.  I took one more step and added a new file called wifi.c and a new file wifi.h to the project.  To the file wifi.c, I copied a function from the API documentation that reports connection status changes to the serial connection.  I changed which UART is used so it would report back over the serial connection.  I put the prototype for the function in wifi.h.

Finally, I created a file called simple_serial.c and another file called simple_serial.h.  I plan on moving the initialization code into simple_serial.c to clean up the user_init() function.  I also plan on creating a simple text interface for configuring the connection details.

On the hardware side, I couldn’t re-solder the connector to the board because of too much damage so I cut a USB cable and used the A connector end with wires soldered to the board. I then used super glue to form a strain relief for the wires.

Boot Hello World

USB cable connection

TAPR Open Hardware License (OHL)

The TAPR Open Hardware License (OHL) is the only license I am considering that is written specifically for hardware and patent law.  It requires that any derivative works be licensed the same.  It requires distribution of all modified works to include the originals unmodified.


 

This license restricts what a developer can do with the design.  I am hoping that this product has enough value to developers that they would contribute to the design.  With that premise, I would not like other developers to be limited significantly on how they can use the intellectual property.

I am going to use the MIT license for both hardware and software.  I don’t need patent/copyright protection on this product.  Liability protection is a good thing, I intend this product to be “hackable”. Anything submitted to this blog for product design will be considered under the MIT license unless noted otherwise.

MIT License applied to hardware

The MIT license gives a lot of freedom to developers to use the intellectual property in any way they want.  This includes manufacturing, selling, and modifying the design. It does not require or restrict attribution. It does give the designer some protection for liability.  This is not compatible with more restrictive licenses.


The reasons I want to design this product include:

  • Teaching about electronics design
  • Create a low cost universal In Circuit Chip programmer

If some company picks up this design and produces it at a fair price then both objectives are met. This would create a well documented hackable device for a very reasonable price.

The MIT license for software and hardware is compatible with my goals.

If I want to integrate some other design with more a restrictive license, I would have to switch to the more restrictive license or separate the other design into a module or in the case of software a library.

I will continue to look at other software and hardware licenses.