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.
2.
3.
4.
5.
6.
7.
8.
9.
Creating your personal workspace for the code.
Downloading the source files to create custom firmware.
Modify the code (an example is given on how to change the motor definitions for a custom frame).
Downloading the firmware compiler.
Configuring the compiler to your workspace.
Verifying code.
Compiling and uploading code to your multi-copter’s APM.
Validating the code.
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 ardupilotarduCopter-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 octa
void 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,
add_motor(AP_MOTORS_MOT_2, 180, AP_MOTORS_MATRIX_YAW_FACTOR_CW,
add_motor(AP_MOTORS_MOT_3,
45, AP_MOTORS_MATRIX_YAW_FACTOR_CCW,
add_motor(AP_MOTORS_MOT_4, 135, AP_MOTORS_MATRIX_YAW_FACTOR_CCW,
add_motor(AP_MOTORS_MOT_5, -45, AP_MOTORS_MATRIX_YAW_FACTOR_CCW,
add_motor(AP_MOTORS_MOT_6, -135, AP_MOTORS_MATRIX_YAW_FACTOR_CCW,
add_motor(AP_MOTORS_MOT_7, -90, AP_MOTORS_MATRIX_YAW_FACTOR_CW,
add_motor(AP_MOTORS_MOT_8,
90, AP_MOTORS_MATRIX_YAW_FACTOR_CW,
1);
5);
2);
4);
8);
6);
7);
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,
add_motor_raw(AP_MOTORS_MOT_2, -1.0, -0.32, AP_MOTORS_MATRIX_YAW_FACTOR_CW,
add_motor_raw(AP_MOTORS_MOT_3, 1.0, -0.32, AP_MOTORS_MATRIX_YAW_FACTOR_CCW,
add_motor_raw(AP_MOTORS_MOT_4, -0.5, -1.0, AP_MOTORS_MATRIX_YAW_FACTOR_CCW,
add_motor_raw(AP_MOTORS_MOT_5, 1.0,
1.0, AP_MOTORS_MATRIX_YAW_FACTOR_CCW,
add_motor_raw(AP_MOTORS_MOT_6, -1.0, 0.34, AP_MOTORS_MATRIX_YAW_FACTOR_CCW,
add_motor_raw(AP_MOTORS_MOT_7, -1.0,
1.0, AP_MOTORS_MATRIX_YAW_FACTOR_CW,
add_motor_raw(AP_MOTORS_MOT_8, 0.5, -1.0, AP_MOTORS_MATRIX_YAW_FACTOR_CW,
}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);
}
}
7);
3);
6);
4);
8);
2);
1);
5);

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
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).
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):



o
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.
For the V frame section of code, the lines of code are ADD_MOTOR_RAW commands which
have the following format:




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);
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,
// add_motor(AP_MOTORS_MOT_2, 180, AP_MOTORS_MATRIX_YAW_FACTOR_CW,
// add_motor(AP_MOTORS_MOT_3,
45, AP_MOTORS_MATRIX_YAW_FACTOR_CCW,
// add_motor(AP_MOTORS_MOT_4, 135, AP_MOTORS_MATRIX_YAW_FACTOR_CCW,
// add_motor(AP_MOTORS_MOT_5, -45, AP_MOTORS_MATRIX_YAW_FACTOR_CCW,
// add_motor(AP_MOTORS_MOT_6, -135, AP_MOTORS_MATRIX_YAW_FACTOR_CCW,
// add_motor(AP_MOTORS_MOT_7, -90, AP_MOTORS_MATRIX_YAW_FACTOR_CW,
// add_motor(AP_MOTORS_MOT_8,
90, AP_MOTORS_MATRIX_YAW_FACTOR_CW,
// plus frame set-up ****new settings****
add_motor(AP_MOTORS_MOT_1,
0, AP_MOTORS_MATRIX_YAW_FACTOR_CW,
add_motor(AP_MOTORS_MOT_2, 180, AP_MOTORS_MATRIX_YAW_FACTOR_CW,
add_motor(AP_MOTORS_MOT_3,
45, AP_MOTORS_MATRIX_YAW_FACTOR_CCW,
add_motor(AP_MOTORS_MOT_4, 135, AP_MOTORS_MATRIX_YAW_FACTOR_CCW,
add_motor(AP_MOTORS_MOT_5, -45, AP_MOTORS_MATRIX_YAW_FACTOR_CCW,
add_motor(AP_MOTORS_MOT_6, -135, AP_MOTORS_MATRIX_YAW_FACTOR_CCW,
add_motor(AP_MOTORS_MOT_7, -90, AP_MOTORS_MATRIX_YAW_FACTOR_CW,
add_motor(AP_MOTORS_MOT_8,
90, AP_MOTORS_MATRIX_YAW_FACTOR_CW,
1);
5);
2);
4);
8);
6);
7);
3);
1);
5);
2);
4);
8);
6);
7);
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 following
o #define FRAME_CONFIG OCTA_FRAME
4 Download the Firmware Compiler





Go to the ardupilot mega site. https://code.google.com/p/ardupilotmega/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 ArduPilot
o Select the board type (e.g., ArduPilot Mega 2.x)

Set the default directory for the code.
o Click File – Preferences
o 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.
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.