Rick Calder rick@llamatrails.com Ver: June 22, 2013

Last Editor: Forrest Frantz

THE HOW-TO FOR CUSTOM CODE

This document describes how to modify the ArduCopter source files. The example used is for motor mapping when a frame deviates from standard. It is based on the AC3.0-rc5 release. The following instructions are for a Windows system.

The topics discussed are:

1. Creating your personal workspace for the code.2. Downloading the source files to create custom firmware.3. Modify the code (an example is given on how to change the motor definitions for a custom frame).4. Downloading the firmware compiler.5. Configuring the compiler to your workspace.6. Verifying code.7. Compiling and uploading code to your multi-copter’s APM.8. Validating the code.9. Maintaining the code.

1 Create a Personal Workspace

Create a new, empty folder for your work. This workspace can be anywhere, but it is best if it is under your documents, not the program directory. For example, under My Documents, create a directory called Copter and under that a directory called ArduCopter Code. The result would be

My Documents > Copter > ArduCopter Code

This is where you will upload and maintain your custom code.

2 Download the Source Code

Download the source files from the git repository.

Go to the git repository at

https://github.com/diydrones/ardupilot/tree/ArduCopter-3.0 Click on the ZIP button. This starts the download of a single zip file containing all of the source

directories and files. The downloaded file will be called ardupilot-ArduCopter-3.0.zip.

Unzip and Save the file to your new folder after the download is complete. o After the download, the file may

end up in your Download directory.

o Double click ardupilot-arduCopter-3.0.zip to Extract All.o You will then have the following directories and files:

Move the ardupilot-ArduCopter-3.0 directory to your work space. The following shows moving the directory using Windows Explorer from the Download directory to the previously created work space (in this case to My Documents > Copter > ArduCopter Code).

3 Modify the Source Code

An example if used to demonstrate how to modify the source code. This example is the case where the copter frame is custom and the pilot needs to modify the motor definitions.

Locate the two files of interest: AP_MotorsOcta.h and AP_MotorsOcta.cpp, the file that defines the each motor parameter in the Octa configuration and the file needing to be changed.

Open the Ardupilot-ArduCopter-3.0 > libraries > AP_Motors directory.

Ensure that Windows Explorer is showing the file extensions because each configuration has 2 associated files, one with a .cpp extension and the other with a .h extension. To tell Windows to show all extensions, change the file viewing options in Windows Explorer to see the file extensions. On Windows Explorer 7: Organize -> File and search options -> View tab uncheck “Hide extensions for known file types”. Click Ok and then you will see the file extensions.

You should see the two files with their extensions. Open AP_MotorsOcta.cpp—Right –click on the file, select “Open with”

and choose WordPad. You may have to “Choose default program…” in order to then select WordPad. If you select Notepad, you will probably see just one or two long lines along the top – Notepad cannot handle the text format of these files.

You will see the following C++ code (don’t panic):

// -*- tab-width: 4; Mode: C++; c-basic-offset: 4; indent-tabs-mode: nil -*-/* * AP_MotorsOcta.cpp - ArduCopter motors library * Code by RandyMackay. DIYDrones.com * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. */

#include "AP_MotorsOcta.h"

// setup_motors - configures the motors for a octavoid AP_MotorsOcta::setup_motors(){ // call parent AP_MotorsMatrix::setup_motors();

// hard coded config for supported frames if( _frame_orientation == AP_MOTORS_PLUS_FRAME ) { // plus frame set-up add_motor(AP_MOTORS_MOT_1, 0, AP_MOTORS_MATRIX_YAW_FACTOR_CW, 1); add_motor(AP_MOTORS_MOT_2, 180, AP_MOTORS_MATRIX_YAW_FACTOR_CW, 5); add_motor(AP_MOTORS_MOT_3, 45, AP_MOTORS_MATRIX_YAW_FACTOR_CCW, 2); add_motor(AP_MOTORS_MOT_4, 135, AP_MOTORS_MATRIX_YAW_FACTOR_CCW, 4); add_motor(AP_MOTORS_MOT_5, -45, AP_MOTORS_MATRIX_YAW_FACTOR_CCW, 8); add_motor(AP_MOTORS_MOT_6, -135, AP_MOTORS_MATRIX_YAW_FACTOR_CCW, 6); add_motor(AP_MOTORS_MOT_7, -90, AP_MOTORS_MATRIX_YAW_FACTOR_CW, 7); add_motor(AP_MOTORS_MOT_8, 90, AP_MOTORS_MATRIX_YAW_FACTOR_CW, 3);

}else if( _frame_orientation == AP_MOTORS_V_FRAME ) { // V frame set-up add_motor_raw(AP_MOTORS_MOT_1, 1.0, 0.34, AP_MOTORS_MATRIX_YAW_FACTOR_CW, 7); add_motor_raw(AP_MOTORS_MOT_2, -1.0, -0.32, AP_MOTORS_MATRIX_YAW_FACTOR_CW, 3); add_motor_raw(AP_MOTORS_MOT_3, 1.0, -0.32, AP_MOTORS_MATRIX_YAW_FACTOR_CCW, 6); add_motor_raw(AP_MOTORS_MOT_4, -0.5, -1.0, AP_MOTORS_MATRIX_YAW_FACTOR_CCW, 4); add_motor_raw(AP_MOTORS_MOT_5, 1.0, 1.0, AP_MOTORS_MATRIX_YAW_FACTOR_CCW, 8); add_motor_raw(AP_MOTORS_MOT_6, -1.0, 0.34, AP_MOTORS_MATRIX_YAW_FACTOR_CCW, 2); add_motor_raw(AP_MOTORS_MOT_7, -1.0, 1.0, AP_MOTORS_MATRIX_YAW_FACTOR_CW, 1); add_motor_raw(AP_MOTORS_MOT_8, 0.5, -1.0, AP_MOTORS_MATRIX_YAW_FACTOR_CW, 5);

}else { // X frame set-up add_motor(AP_MOTORS_MOT_1, 22.5, AP_MOTORS_MATRIX_YAW_FACTOR_CW, 1); add_motor(AP_MOTORS_MOT_2, -157.5, AP_MOTORS_MATRIX_YAW_FACTOR_CW, 5); add_motor(AP_MOTORS_MOT_3, 67.5, AP_MOTORS_MATRIX_YAW_FACTOR_CCW, 2); add_motor(AP_MOTORS_MOT_4, 157.5, AP_MOTORS_MATRIX_YAW_FACTOR_CCW, 4); add_motor(AP_MOTORS_MOT_5, -22.5, AP_MOTORS_MATRIX_YAW_FACTOR_CCW, 8); add_motor(AP_MOTORS_MOT_6, -112.5, AP_MOTORS_MATRIX_YAW_FACTOR_CCW, 6); add_motor(AP_MOTORS_MOT_7, -67.5, AP_MOTORS_MATRIX_YAW_FACTOR_CW, 7); add_motor(AP_MOTORS_MOT_8, 112.5, AP_MOTORS_MATRIX_YAW_FACTOR_CW, 3); }}

Familiarize yourself with the layout of the code. o There are comment lines that help explain what the code does.

Lines starting with // starts a comment that ends on that line. Lines starting with /* starts a comment that continues for several lines until a */, which ends

the comment.o There are variables with friendly pet names (normally lower case), like _frame_orientation (yes,

that is the setting that you choose to describe your frame orientation (+ or X or V).o There are constant definitions with friendly pet names (normally upper case), like

AP_Motors_Plus_Frame. So now we can compare _fruit to APPLES to see if the fruit really is an apple.

o Then there is code to respond properly to each frame type (like what to do for a + or a X or a V frame). In this program, the author uses ‘if’ statements.

if ( this is true ) { do what is between the first set of brackets }

else if ( this other thing is true ) { do what is between the second set of brackets }

else ( in all other cases ) { do what is between the third set of brackets }

o Note that after each ‘if’ section that there are 8 lines of code—one for each motor. That is what needs to be changed for a custom copter with motors that either: Have angles that are not the same between them (modify the X or + code). Have distances from center that are not the same (modify the V code).

o For the X and + frame sections of code, the lines of code are ADD_MOTOR commands which have the following format (you will only need to change what is in red): add_motor(the APM output pin, the angle from forward in degrees, the prop spin direction _CW (clockwise) or _CCW (counter

clockwise), the order used by the CLI when spinning the motors during test which is usually its physical position on the copter

starting with forward or forward right as 1 and the going clockwise around the copter for 2 through 8); for example, add_motor(AP_MOTORS_MOT_1, 22.5, AP_MOTORS_MATRIX_YAW_FACTOR_CW,1), defines a CW motor being

driven by output pin that is 22.5 degrees right of forward, and to be spun first during test. See Excel Worksheet Motor Definition Calculations for Custom Copters, the Custom Octa X sheet, if you want to convert copter

motor x/y coordinates to angles from forward.

o For the V frame section of code, the lines of code are ADD_MOTOR_RAW commands which have the following format: add_motor_raw(the APM output pin, the roll factor, the pitch factor, the prop spin direction _CW or _CCW, the test order); add_motor_raw(AP_MOTORS_MOT_1, 1.0, 0.45, AP_MOTORS_MATRIX_YAW_FACTOR_CW,1), defines a CW motor being

driven by output pin 1 using a roll factor of 1, a pitch factor of .45, and to be spun first during test. See Excel Worksheet Motor Definition Calculations for Custom Copters the Custom Octa V sheet, to convert x/y coordinates to

the yaw and pitch factors.

Change the motor definitions in the file. There are 8 lines of code in each section, corresponding to each of the 8 motors of an Octa configuration. o Change the original lines to comments by adding // in from of each line of original code. If not

using the Excel file to create the new lines of code (making the changes manually), then first copy the lines, then add the double hashes before them. For example your code might look like the following with a custom Octa +

// hard coded config for supported frames if( _frame_orientation == AP_MOTORS_PLUS_FRAME ) { // plus frame set-up ****original settings**** // add_motor(AP_MOTORS_MOT_1, 0, AP_MOTORS_MATRIX_YAW_FACTOR_CW, 1); // add_motor(AP_MOTORS_MOT_2, 180, AP_MOTORS_MATRIX_YAW_FACTOR_CW, 5); // add_motor(AP_MOTORS_MOT_3, 45, AP_MOTORS_MATRIX_YAW_FACTOR_CCW, 2); // add_motor(AP_MOTORS_MOT_4, 135, AP_MOTORS_MATRIX_YAW_FACTOR_CCW, 4); // add_motor(AP_MOTORS_MOT_5, -45, AP_MOTORS_MATRIX_YAW_FACTOR_CCW, 8); // add_motor(AP_MOTORS_MOT_6, -135, AP_MOTORS_MATRIX_YAW_FACTOR_CCW, 6); // add_motor(AP_MOTORS_MOT_7, -90, AP_MOTORS_MATRIX_YAW_FACTOR_CW, 7); // add_motor(AP_MOTORS_MOT_8, 90, AP_MOTORS_MATRIX_YAW_FACTOR_CW, 3);

// plus frame set-up ****new settings**** add_motor(AP_MOTORS_MOT_1, 0, AP_MOTORS_MATRIX_YAW_FACTOR_CW, 1); add_motor(AP_MOTORS_MOT_2, 180, AP_MOTORS_MATRIX_YAW_FACTOR_CW, 5); add_motor(AP_MOTORS_MOT_3, 45, AP_MOTORS_MATRIX_YAW_FACTOR_CCW, 2); add_motor(AP_MOTORS_MOT_4, 135, AP_MOTORS_MATRIX_YAW_FACTOR_CCW, 4); add_motor(AP_MOTORS_MOT_5, -45, AP_MOTORS_MATRIX_YAW_FACTOR_CCW, 8); add_motor(AP_MOTORS_MOT_6, -135, AP_MOTORS_MATRIX_YAW_FACTOR_CCW, 6); add_motor(AP_MOTORS_MOT_7, -90, AP_MOTORS_MATRIX_YAW_FACTOR_CW, 7); add_motor(AP_MOTORS_MOT_8, 90, AP_MOTORS_MATRIX_YAW_FACTOR_CW, 3);

}else if( _frame_orientation == AP_MOTORS_V_FRAME ) {

o Next change the lines of code for each motor or copy in the code generated in the Excel worksheet: arm angles as needed if working with a custom + or X. pitch and yaw factors as needed if working with a custom V.

o Save the file. Define the ship as an Octa

o Edit APM_Config.h in the Ardu_Copter directory.o Find the comment line that says //#define FRAME_CONFIG …o Delete the // and change the define to the followingo #define FRAME_CONFIG OCTA_FRAME

4 Download the Firmware Compiler

Go to the ardupilot mega site. https://code.google.com/p/ardupilot-mega/downloads/detail?name=ArduPilot-Arduino-1.0.3-windows.zip#makechanges (not the Arduino site as it does not have the special modification to talk to the APM 2.x board).

Click on the ArduPilot-Arduino-1.0.3-windows.zip to download. Wait until the download ends. Click on the download to unzip. Use Windows Explorer to move or copy the ArduPilot_Arduino_1.0.3_windows directory to C:\

Program Files (x86). Create a shortcut for Arduino.

o Find arduino.exe in Program Files (x86) > ArduPilot_Arduino_1.0.3_windows directory.

o Right click and Send to Desktop (create shortcut).o In your desktop you can then right-click the shortcut

to create another shortcut in the Start Menu.

5 Configure the Compiler to Your Workspace

Launch Arduino (in the Start Menu or Desktop) Set the board type

o Click on ArduPiloto Select the board type (e.g., ArduPilot Mega 2.x)

Set the default directory for the code. o Click File – Preferenceso Browse to change the location of your code

Set the Serial Port to the port used by Mission Planner by clicking Tools – Serial Port

File-Quit Arduino for the setting to take effect. o

6 Verify the Custom Firmware Code

Launch Arduino (the setup changes made prior will not take effect) Load your code: File > Sketchbook > ArduCopter A pop-up screen will appear showing the code in various tabs. On the far right is a down arrow that

lists all the tabs. Go to the second tab, APM_Config.h, and you should see the modification that you made to the #define FRAME_CONFIG OCTA_FRAME

Press the green check button under File to verify the code. It will then compile the code and shouldn’t give any error messages. Fix any errors if it does.

7 Compile and Upload the Custom Firmware

Make sure that your copter is plugged into your computer using the USB port and that Mission Planner isn’t using the port (isn’t connected).

Click the green -> button to compile and upload. It will say ‘Compiling sketch’, then ‘Uploading’, then ‘Done Uploading’.

8 Validate the Custom Firmware

Sometimes it is necessary to validate that the changes made were in fact made. For example, in the case of the motor modifications, the pilot might want to make certain that the new definitions are in fact being used by the code. This can be done by special programming to visually or audibly alert the pilot that the changes are gold.

TBD It is now ready to fly. Enjoy.

9 Maintain the Custom Firmware

It is not necessary to stay current with every release of code from the github library. If you are happy with your copter, how it flies, and what it can do, then there is no reason to upgrade and recompile your code. This is true for your code as it is with staying current with every new release of your computer operating system or Word upgrade. If it ain’t broke, why fix it.

But, as the source code from the Github library is updated with new features or fixes that you want, it may become necessary to update the code in your workspace without having to completely start from scratch. The following describes one best practice on how to stay current.

TBD … maybe something like the following is one approach Copy (don’t move) the two files you changed to the directory above the code for safe keeping. For

example, ardupilot_ArduCopter_3.0 might be a subdirectory to ArduCopter Code. So copy APM_Config.h and AP_MotorsOcta.cpp to the ArduCopter Code directory.

When a new release occurs that you wish to use, upload it to the directory ArduCopter Code (maybe the new release will be in a directory ardupilot_ArduCopter_4.0).

Then copy APM_Config.h and AP_MotorsOcta.cpp to the new code to their respective directories. Reset Arduino to look to the new directory (remember to file-quit to make the change stick). Compile and upload using Arduino.