Smarter Arduino Programming - Tips and Tricks

Smarter Arduino Programming

Introduction

This draft is for an instructable not yet written. Note that this is an article started by Russ Hensel, see "http://www.opencircuits.com/index.php?title=Russ_hensel#About My Articles" About My Articles

The following are some tips for better quicker programming of Arduinos. Much of the advice applies to other platforms so you may want to take a quick look even if you do not use the Arduino. This advice applies to the standard computer arduino ide, but applies to other environments as well. Some of the tips are fairly well known/standard but are often not used in the code I see published.

Sample Program

I have written a simple program that illustrates some of these techniques. You can download it from github https://github.com/russ-hensel/BlinkInstruct If you download it and unzip into a directory called BlinkInstruct then you can open it with arduino.exe. And here is a tip: the download consists of several files, .ino, .h, .cpp; when you open the .ino file arduino.exe will open all of them in separate tabs of the arduino ide. Having several files offers advantages some of which will be discussed below. If you do not want to download the files you can still read them directly on github. If you do not want read along with it you can still get something out of just reading the tips. In the topics that follow I will use as examples the code in these files.

Easier Reading while Coding

Much of coding of all but the smallest programs involves scrolling up and down in the code looking for subroutine, names, signatures, code snippets... This scrolling makes you loose your place where you are actually writing the code. Simple solution: Open the file in another editor for read only access. You can still copy and paste between the two copies. From time to time refresh the read only copy.

Use Header Files

This is a very standard practice by C programmers, but I rarely see it in instructable projects.

Header files or .h files are commonly used for any settings that are used in the code that you might want to change without searching through the code. Very often this is done with pound defines. For example if you have a program foo.ino make a text file foo.h. In my example BlinkInstruct.h I have:

#define  VERSION_ID       F( "BlinkInstruct 2018 02 03.2" )
          
#define  BAUD_RATE        19200      // including 9600 19200 38400 .......   set the terminal to match 

#define  MY_LED_PIN       13         // 13 is the builtin led but you can connect leds to other pins 
#define  DEFAULT_DELAY    100        // delay used in the blink

Then at the top of BlinkInstruct.h put the line

#include "BlinkInstruct.h"  

Finally use the #defines in the code something like:

digitalWrite( MY_LED_PIN, LOW );  

You will see more examples in the files. The example has another .h file, which is similar but I will not cover it here.

Dot H file can be use for many other useful things, but this is not an instructable on them or macro expansion. Google for a lot more useful info.

I am not sure what the official way is to get the arduino.exe to open the .h files ( and .cpp files.... ). My method is just to put the files in the directory with the code ( when the code is not open ). The next time you open the file the .h and other files will be show in the project, each in its own tab.

Easier Search

Most programs consist of a bunch of subroutines. If you have a list near the top of the program ( perhaps as comments ) it is easy to highlight them ( perhaps with a double click ) it ctrl-f ( for find ) and then zip down to the routine ( or calls to it ) in a flash.

In the example I have a help routine rptHelp() with the relevant subroutine names as comments that serves this purpose, and in the loop() is a small command interpreter that dispatches to different subroutines. Each can serve double duty as an assistant to finding the code. Both are near the top of the program so you do not have to scroll a long distance to find them.

A better IDE

I have not looked hard but there may be more powerful IDE's for the Arduino. They may take some effort to find and setup, I have not done this, but if you do not like arduino.exe look around. Let me know what you like in the comments.

Add Some Documentation

I put another .h file in my projects called readme.h. It is not included in any other file but is a good location for scratch work, example code, and longer notes that you might not want to put in the code.

Comments in this file do not need // to mark them as comments because the file is never complied.

Arduino.exe will automatically open the file so it is always at hand when you are working on your code.

Serial Monitor

Always have a serial monitor as part of your code. This lets you more easily see what is going on in the program and optionally control it. I have another instructable that give a quite powereful way to do this that is also simple to implement. If no serial monitor ( terminal program ) is connected there is generally no harm, the bits just go right in the bit bucket for recycling.

F...ing Strings

I use lots of messages which means lots of string literals like:

Serial.println( "ABCDEFGHIJKLMNOPQRSTUVWXYZ" )

this can use a lot of dynamic memory ( which you have less of than program memory ). Change your code to:

Serial.println( F( "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ) )

and the string goes in program memory ( which you normally have lots of )

Version

I do a lot of programs and a lot of revisions. Sometimes I am not working with the version that I want. So my code always includes a version that it sends to the serial port when the program starts and any time I ask the program for it. In the header file:

1. define VERSION_ID F( "SerialCmdMaster with Blink Ver4 2017 11 17.777" )

In the program:

Serial.println( VERSION_ID );

Draft material

Better Arduino Programs with Serial Commands

A lot of programs for the arduino are very simple and limited. Some only repeat what is on the arduino.cc site. Lets take blink. You compile it, Run it. And ( with luck ) the led blinks. Want to change how many times it blinks or how often and you change the code, recompile, upload, and run again. A better way is to alter the program so you can tell it what to do at run time with a serial monitor, or with another terminal program ( I recommend my …... ).

Here is how.

A good way to see how this is done is to look at a program that implements this approach. Download the attached zip file, unzip and put the results in a directory called SerialCmdMaster wherever you keep your arduino programs Then open the location in arduino.exe. You will see 4 files each in its own tab. Or go to github () and you can look at the files in your browser.

You will find 4 different files, one for each of the two parts of the program. SerialCmd.cpp and SerialCmd.h are used over and over in my different programs, they are essentially library programs and you can just use them as is without every looking at them. SerialCmdMaster.ino and SerialCmdMaster.h are where the type of programming I am recommending live. I have used the strategy of using a header file SerialCmdMaster.h for the important constants in the code, neither of the .h files have executable content.

So most of the action is in SerialCmdMaster.ino which is what I will discuss now.

The whole program is divided into a bunch of subroutines including the familiar setup and loop. I put a comment section with some documentation at the top. Then, pretty much as usual in a C program are some includes and variable declarations. All straight forward.

The next subroutine is my tiny little help system. It is just a bunch of serial print statements that print one line for each command in the system.

So let me digress from how the internals of the program work to how it works when you connect it to a serial terminal ( of the serial monitor )

It boots up, starts its serial port and prints the help text.

One of the commands that it then available is h followed by a newline, the newline is automatically appended if you turn …...... What does h show help do? It just prints the same help text shown at startup.

The command v version of software prints the version of the software: something like "SerialCmdMaster with Blink Ver4 2017 11 17.2"

In general all commands are just a single letter. To add a bit more functionality to the commands you can also stick a number on the command: "unn set micro seconds" might look like u22 which would cause a variable in the program to be set to 22 microseconds. "bnn blink_1 n times uses micros only " which might be given as b2000 calls the blink_1 subroutine and causes it to blink 2000 times using the microsecend value set with the u command.

So the help command prints out a reminder of the commands. On each line of the help printouts there may be a comment that help you search for the subroutine that supports the command.

Often the loop subroutine is found at the bottom of the program. I put it right after the help because it implements the help by getting the command letter ( and number if any ) and then using a switch statement calls the proper subroutine. The call statements in it are also useful in searching the rest of the code.

The rest of the code is just a series of pretty simple subroutines that implement the commands the help system names.

This code has little practical purpose except to show how the serial command system works ( and as my test framework for SerialCmd ) and to run a few basic blink routines. The idea is that you make a copy, rename the bits of pieces, and transform it into your own code with a command interface.

This code has a connection to another instructable because it is an example of some of the techniques discussed there: