-
Notifications
You must be signed in to change notification settings - Fork 2
Debug Terminal
The Debug Terminal ground control station (GCS) protocol is a human-readable text-based way to interface with the APM using only a dumb terminal. With the Debug Terminal GCS, users can change many aspects of the APM's behavior, even while in flight, and read many different types of information to gain better insight into what the APM is doing.
The Debug Terminal is intended primarily for exploring and testing the behavior of the APM; it is not currently intended as an end-user interface. A number of the status reports are structured according to how the calculations are performed in the code rather than what might make most intuitive sense for people who have not looked at the code. This makes it a good tool to understand what the APM is thinking, but currently a rather poor polished user interface. When Debug Terminal responds in a way you don't expect, please take a look at the code generating the response to see if you can figure out why it is doing what it is doing.
A common issue is that there is a conflict between displaying numbers as they exist on the APM and as is easy for a human to interpret. For instance, latitude is stored as an integer equal to degrees times ten million. But, it would make a lot more sense to a human to see that number printed in decimal degrees than ten millionths of a degree. Currently, Debug Terminal is mixed in the way it displays numbers. The commands that have been developed mostly recently and used most often tend to display human-friendly numbers. Older or less-used commands tend to display the raw data, which is frequently 100 times the size of the represented value.
Here are the steps to follow to use Debug Terminal with your APM:
- Attach a serial interface to the telemetry port
- Add the following lines to the end of your APM_Config.h: {{{ //Select Debug Terminal as the GCS to use: #define GCS_PROTOCOL GCS_PROTOCOL_DEBUGTERMINAL
//Use the telemetry port for the Debug Terminal interface: //(selecting 0 here would cause the USB serial port to be used instead) #define GCS_PORT 3
//Set the baud rate for the telemetry port to match your XBee setup: #define SERIAL3_BAUD 115200 }}}
In its default mode, Debug Terminal is designed to provide help remembering command syntax. If you don't remember something, just type as much as you remember and then add {{{-?}}} on the end. Typing just {{{-?}}} will provide a list of command groups. For instance, {{{status -?}}} will print a list of recognized {{{status}}} commands:
All Debug Terminal commands are case- and white space-sensitive. Commands are terminated by a carriage return (so be sure to select {{{Carriage return}}} rather than {{{No line ending}}} if using the Arduino serial monitor). In the reference below, {{{}}} denotes a non-negative integer. {{{}}} denotes a numeric value that may, based on context, be a decimal and/or negative. The straight bar | denotes "or" and braces enclose a set of options. So,{{{ {A|B|C} }}}indicates that you must choose either {{{A}}} or {{{B}}} or {{{C}}}. Brackets denote optional parameters. For commands below without a description, the command syntax alone should give a decent idea of what it is intended to do. Further information can be found by reading the code for {{{GCS_DebugTerminal.pde}}} (in the SVN repository here).
{{{show heartbeat}}} Enables automatic display of 'heartbeat' messages that report the APM control mode, especially when it changes. These messages are shown by default.
{{{show attitude}}} Enables automatic display of 'attitude' messages which indicate:
- The RC signals for roll, pitch, yaw and throttle
- The APM's reconstruction of the plane's roll, pitch
- Navigation information including the target bearing, desired roll, and number of degrees loitered
- Orientation actuation including roll and pitch servo outputs
{{{show location}}} Enables automatic display of GPS location along with:
- Airspeed
- Climb rate
- Distance from waypoint
- % throttle
- Difference between desired and current altitude
{{{show severity }}} Enables display of MSGs (sent via send_message) with severity at least as high as N
{{{hide {heartbeat|attitude|location} }}} Hide the automatic display of the respective message type
{{{hide all}}} Hide the display of all automatic message types
{{{echo }}} Send back over the serial line all the text following the space after {{{echo}}} and before the carriage return
{{{groundstart}}} Force a groundstart, which will (re)initialize and (re)calibrate the IMU
{{{inithome}}} Set the current location as home
{{{print altitude}}}
{{{print attitude}}} Prints one attitude message (described in {{{show attitude}}})
{{{print commands}}} Prints a list of all the commands stored in EEPROM (count is determined by wp_total)
{{{print ctrlmode}}} Prints one heartbeat message
{{{print curwaypts}}} Prints the three waypoints used in the current step of autonomous navigation
{{{print flightmodes}}}
{{{print kp {servoroll|servopitch|servorudder|navroll|navpitchasp|navpitchalt|throttlete|throttlealt} }}} Print the current gain constant for the response proportional to error on the selected PID channel. See channels for a description of each channel.
{{{print ki {servoroll|servopitch|servorudder|navroll|navpitchasp|navpitchalt|throttlete|throttlealt} }}} Print the current gain constant for the response to integrated error on the selected PID channel. See channels for a description of each channel.
{{{print kd {servoroll|servopitch|servorudder|navroll|navpitchasp|navpitchalt|throttlete|throttlealt} }}} Print the current gain constant for the response to the change in error on the selected PID channel. See channels for a description of each channel.
{{{print kff {pitchcomp|ruddermix|pitchtothrottle} }}} Print the constant used to mix one channel into another.
- pitchcomp: Additional up-elevator to add when the plane is banked
- ruddermix: How much rudder should be deflected with roll to keep the plane in approximately coordinated flight
- pitchtothrottle: Currently unused
{{{print location}}} Print the last recorded GPS location (current_loc)
{{{print navsettings}}} Prints various navigation constants:
- Cruise airspeed (with AIRSPEED_SENSOR) or cruise throttle (without AIRSPEED_SENSOR)
- Altitude above home to hold
- Loiter radius
- Waypoint radius
{{{print pressure}}} Prints information about the BMP085 sensor
**{{{print rlocation [Prints the relative location of an object from the plane in cartesian format. If {{{home}}} is omitted, the object is assumed to be the next waypoint
{{{print speed}}}
{{{print tuning}}}
{{{reset commands}}} Issues a reload_commands() call
{{{rtl}}} Initiates a return-to-launch procedure (return_to_launch())
{{{set cmd {here| } }}}
{{{commandindex}}} > 0
{{{commandtype}}} = {waypoint|takeoff|land|loiter|loiternturns|loitertime|delay|landoptions|resetindex|airspeedcruise|throttlecruise|resethome|index|{{{}}} }
Sets a command in the EEPROM memory (does not necessarily load the command even if the command index being set is the current one). The purpose of {{{param1}}} is dependent on the http://code.google.com/p/ardupilot-mega/wiki/Commands command type, but it must be a non-negative integer. When specifying a location, {{{alt}}} is in meters (and is usually relative to home altitude), and {{{lat}}} and {{{lng}}} are in degrees; these numbers may be decimals and/or negative. Instead of specifying a location with the alt,lat,lng triplet, you may substitute {{{here}}} and the plane's current location will be used instead. This is useful to quickly set up a mission by having an assistant simply fly to the desired locations.
Examples:
{{{
set cmd 1 takeoff 10 15 0 0
set cmd 2 waypoint 0 here
set cmd 3 waypoint 0 15 34.090956 -118.032020
set cmd 4 land 0 0 34.089355 -118.032932
set cmd 5 landoptions 10 10 15 -5
set cmd 6 rtl 0 0 0 0
}}}
{{{set cmd }}}
{{{commandindex}}} > 0
{{{paramtype}}} = {id|p1|alt|lat|lng|p2|p3|p4}
Changes just one parameter of a command and writes the change to EEPROM. {{{alt}}}, {{{lat}}}, and {{{lng}}} are treated specially, so be sure to use those identifiers if and only if you are describing those characterisitics. For instance, never set the {{{lat}}} parameter on a landoptions command. This command is particularly useful for setting the correct altitudes after defining a rough course using the {{{here}}} identifier
{{{set cmdcount }}} Sets the number of commands expected to be valid; this does not actually make the commands valid
{{{set cmdindex }}} Sets and loads the desired command. Index 0 is home, index 1 is the first user-defined command in the mission, and is the command the APM will start with when the plane is initialized
{{{set cruise }}} Sets a new cruise speed in m/s (with AIRSPEED_SENSOR) or throttle setting in % (without AIRSPEED_SENSOR)
{{{set holdalt }}} Sets and writes to EEPROM a new value to the altitude over home to hold
{{{set kp {servoroll|servopitch|servorudder|navroll|navpitchasp|navpitchalt|throttlete|throttlealt} }}} Sets proportional gain constant. See {{{print kp}}} for more information.
{{{set ki {servoroll|servopitch|servorudder|navroll|navpitchasp|navpitchalt|throttlete|throttlealt} }}} Sets integration gain constant. See {{{print ki}}} for more information.
{{{set kd {servoroll|servopitch|servorudder|navroll|navpitchasp|navpitchalt|throttlete|throttlealt} }}} Sets derivative gain constant. See {{{print kd}}} for more information.
{{{set kff {pitchcomp|ruddermix|pitchtothrottle} }}} Sets feed-forward constant. See {{{print kff}}} for more information.
{{{set loiterradius }}} Sets and stores in EEPROM a new loiter radius
{{{set wpradius }}} Sets and stores in EEPROM a new waypoint hit radius (how close to the waypoint the APM must be to "arrive" at the waypoint
{{{status control}}} Gives the status of basic control information including desired roll and pitch angles
{{{status gps}}}
{{{status landing}}}
{{{status loiter}}}
{{{status navigation}}}
{{{status navpitch}}}
{{{status navroll}}}
{{{status rc}}} Summarizes the status of all RC channels beginning from the hardware pulse length detection through the hardware PWM output
{{{status rcinputch}}} Measures and displays pulse lengths of all RC channels; this is as close to the hardware as it is practical to get from the APM main code
{{{status rcin}}} Displays the buffered and adjusted pulse lengths of all channels after mixing, etc
{{{status rcout}}} Displays the buffered and adjusted output pulse lengths of all channels after mixing, etc
{{{status rcpwm}}} Displays the current setting of the hardware PWM generators for all RC channels; this is as close to the hardware as it is practical to get from the APM main code
{{{status rctrim}}} Displays the trim values for all RC channels
{{{status system}}}
{{{status takeoff}}}
{{{status telemetry}}}
{{{status throttle}}}
*{{{status waypoints}}}