Arduino software

Development tools

In Arduino terminology, a program that runs on an Arduino is called a sketch. These are written in a limited version of C++, described here: https://www.arduino.cc/reference/en/ . In addition, one can include libraries, which are written in C++. If there is code that would be useful to share between sketches, it can be put in a library. Many open-source libraries are available for Arduino -- this lists some popular ones: https://www.arduino.cc/en/reference/libraries

There are several IDEs that support Arduino development:

• The most commonly used is the Arduino IDE provided by arduino.cc. This is free and open-source. It is somewhat limited, but adequate. https://www.arduino.cc/en/Main/Software

• Some students prefer using Visual Studio with the Arduino extension. This actually uses the Arduino IDE under the covers, so things like library structure are the same. Visual Studio has a free community edition: https://visualstudio.microsoft.com/vs/community/ . The extension is here: https://marketplace.visualstudio.com/items?itemName=vsciot-vscode.vscode-arduino . (Note this is not the same as Visual Micro, which is a commercial, i.e. non-free, product.)

• Atmel Studio is a professional IDE. It does not have the library or language limitations of the Arduino IDE. https://www.microchip.com/mplab/avr-support/atmel-studio-7

It's recommended to start with the Arduino IDE as it's simpler and most Arduino information online assumes you are using it.

Arduino software structure

Arduino software has some quirks. Each sketch must be in a directory with the same name as the sketch filename. (That is, if the sketch is called XYZ.ino, then it must be in a directory called XYZ.) Libraries likewise need to be in directories, but names of files in the library don't need to match the directory name. One should avoid nesting directories -- if there are variants of some project (also something to avoid), it is better to put each in a directory at the same level. Also avoid putting extraneous .ino files in sketch directories. The Arduino IDE seems to compile whatever .ino files it finds, even if it's not the actual sketch, so other .ino files may be confusing if they have compile errors.

We have some local software conventions, mainly due to the fact that some settings and code need to be shared between different projects that run on different Arduinos, or are used on different vehicles with different structures.

General Structure

First, the program initializes. After this, the following procedures occur:

• Vehicle initialization:
  • Sets the following values to 0:
    • currentSpeed
    • currentAngle
    • currentBrake
    • brakeHold
    • desired_speed_mmPs
    • desired_brake
    • desired_angle
  • Initializes the CAN bus with 500 kbps baud rate
  • Initializes components of the Adafruit Data Logger Shield:
    • Initializes the PCF8523 real-time clock (RTC)
    • If the RTC time is behind the compile time, it updates to the compile time
    • Initializes the SD card
    • Creates a file in the SD card and names it based on the date
    • Prints the RTC values to the file and the serial

• Looped procedures following initialization:
  • Maps values for the throttle and steering using PWM
  • Sets variables throttlePulse_ms and steerPulse_ms to their mapped values
  • Based on the value of throttlePulse_ms:
    • If throttlePulse_ms = -1 and brakeHold = 0, emergency stop is activated
    • If throttlePulse_ms = -1 and brakeHold = 1, the brakes are activated
    • If neither of those are true, brakes are released
  • The following values are updated:
    • currentAngle is updated to the computed angle based on the mapped steerPulse_ms value
    • currentRightAngle is updated to the reading from the right sense pin
    • steeringVal is updated to the steeringMode value, which changes when currentAngle is updated
  • Both the Serial and the SD file print out data, such as the RTC values

Settings.h

This file contains information that is different per vehicle. This includes mechanical information (e.g. max/min speed, wheel diameter, turning radius, etc.) and electrical information (e.g. pin assignments). It is required by most projects. All the rest of the code should be written to be portable across a wide variety of vehicles.

A template version of this file, called SettingsTemplate.h, is packaged as a library, and is available in the General repository. SettingsTemplate.h should be copied to Settings.h, and local changes made in Settings.h as needed. Anything of general use can be put back into SettingsTemplate.h. Note this division between a template version of settings and a personalized version is the same division as is found with most application preferences or configuration files.

Libraries

In the past, locally-written Arduino libraries were put in a libraries directory alongside one's sketch directories. But a change to the Arduino IDE caused this not to work any longer. They now want libraries put in the installation directory of the Arduino IDE, or just put in the same directory as the sketch.

Neither option is appropriate for software that has to be installed by non-administrators, or that is shared among projects. We are currently reconfiguring our libraries to deal with this. What we hope to do is go back to a local libraries directory, and have a separate repository for each locally-written library. We can use Git "submodules" to bring in the necessary libraries. Git supports soft links, so we can add links from each sketch to the libraries directory. This will allow using the original library structure.

This change is in progress. In the meantime, locally-written library directories, or libraries that are not available in the Arduino installation, can be moved by hand into the user's own libraries directory, and a link called "libraries" created in each sketch directory, that points to the libraries directory. The include statements should then have the form:

   #include "libraries/SomeLibrary/SomeLibrary.h"