MatrixPilot’s Interrupt Service Routines

Note: All the examples in this document are for MatrixPilot 3.2.1 for a classic UDB2 or UDB3

Author: Peter Hollands, 9th December 2011

With thanks to Ben Levitt for review and additions

Version: 1.0

Introduction

A good way to understand how MatrixPilot works, is to learn about the interrupt routines, their purpose, frequency, and priority.

First off, note that the code for MatrixPilot is organized into 3 main sections.:-

• libUDB is a library of code that handles all of the low-level, hardware-specific details.  All of the interrupts are handled in this code.  
• libDCM is a library that holds all the code to compute and update the Direction Cosine Matrix, including code that makes use of libUDB to read and use GPS data, magnetometer data, accelerometer and gyroscope data.  
• MatrixPilot itself, which uses libUDB and libDCM, and adds state logic, control logic, flightplan management, etc to create a complete autopilot.

The code is structured so that it is easy to re-use the main libraries for cars, boat, quads or any other uses that may come to mind.

The Main() routine

Developers often try to understand MatrixPilot by looking at the code in main.c (located in the MatrixPilot directory) to see how the software branches into its subroutines. However, there is very little to see in the main routine other than some logic to measure how much time in spent in the interrupts (CPU is busy), and how much time is spent in the main routine (cpu is idle, no interrupts need servicing). The main routine has two purposes:-

1. Initialise all the code and switch on the interrupt routines
2. Measure the percentage of CPU usage when the plane is flying.

The main program looks like this:-

int main (void)

{

            udb_init() ;

            dcm_init() ;

            init_servoPrepare() ;

            init_states() ;

            init_behavior() ;

            init_serial() ;

            udb_run() ;

            // This never returns.

            return 0 ;

}

udb_run() has one statement and looks like this:-

void udb_run(void)

{

            //  nothing else to do... entirely interrupt driven

            while (1)

            {

                    // pause cpu counting timer while not in an ISR

                    indicate_loading_main ;

            }

            // Never returns

}

“indicate_loading_main” is a macro in libUDB_internal.h . The macro is:-

#define indicate_loading_main   {                                  \

                                      T5CONbits.TON = 0 ;          \

                                }

Whenever the main routine is running it continually goes around an infinite while loop turning off the T5 timer  (by setting its control bit  to 0).

At the start of every interrupt routine is the “indicate_loading_inter” macro. This opposite macro

will turn on the T5 timer when the computer enters an interrupt routine.

#define indicate_loading_inter  {                                  \

                                      T5CONbits.TON = 1 ;                 \

                                }

So once the main() routine has initialised MatrixPilot’s variables, and turned on the interrupts, the sole purpose of the main routine is to help to measure cpu usage, by turning off the T5 timer when there are no interrupt routines being serviced.

You may wonder why the macro above is called “indicate_loading_main” rather than “stop_interrupt_timer”. The answer is historical. When Bill Premerlani originally wanted to look at CPU usage, he simply created two macros which turned on one of the LEDs when interrupt routines started and turned off the same LED when in main(). The brightness or dimness of the LED showed how busy the CPU was. The LED was the “indicator”. And the name “indicate_loading_main” has been left as it was. That code for turning the LEDs on and off is still in the source, but commented out, a few lines above ….

//#define indicate_loading_main             //LATEbits.LATE4 = 0

//#define indicate_loading_inter            //LATEbits.LATE4 = 1

So that is it. You’ve seen all there is to see in MatrixPilot’s main() routine (except the initialisation  routines. That is best done later:-) ).

All the real work, in computing the direction cosine matrix, and flying the plane is done using an Interrupt architecture.  We shall now look at the interrupt routines, their priority, frequency and their function.

An Overview of MatrixPilot Interrupt Routines

Interrupts are sorted here by priority, with the highest priority interrupts first.  Interrupts can interrupt each other, but only a higher priority interrupt can interrupt a lower priority interrupt.  If a lower priority interrupt is triggered while a higher priority one is running, the lower priority one will run after the higher priority one finishes.

Please click on underlined table entries to see the relevant code in the main trunk repository.

The above table was constructed using the “Find All” facility in Microchip’s Interactive Development Environment called MPLAB (version 8.63). I used the menu called “Edit / Find in Files” and then filled in the prompt for “Find What” with “__interrupt__” (note there are two underscores at the beginning and end of “intterupt”). I then clicked on “Find”. The following output was then returned.

Note: For conciseness I have deleted the following first part of the file path from each line below:-

C:\Users\phollands\Desktop\MatrixPilot_3_2\libUDB\

All of the interrupt definitions are stored in the libUDB directory for the UDB2 and UDB3.

background.c:128: void __attribute__((__interrupt__,__no_auto_psv__)) _T1Interrupt(void)

background.c:177: void __attribute__((__interrupt__,__no_auto_psv__)) _T7Interrupt(void)

background.c:179: void __attribute__((__interrupt__,__no_auto_psv__)) _T3Interrupt(void)

background.c:200: void __attribute__((__interrupt__,__no_auto_psv__)) _T5Interrupt(void)

background.c:216: void __attribute__((__interrupt__,__no_auto_psv__)) _T6Interrupt(void)

background.c:218: void __attribute__((__interrupt__,__no_auto_psv__)) _PWMInterrupt(void)

analog2digital_udb.c:120: void __attribute__((__interrupt__,__no_auto_psv__)) _ADCInterrupt(void)

magneto_udb.c:190: void __attribute__((__interrupt__,__no_auto_psv__)) _MI2CInterrupt(void)

radioIn_udb.c:114: void __attribute__((__interrupt__,__no_auto_psv__)) _IC7Interrupt(void)

radioIn_udb.c:157: void __attribute__((__interrupt__,__no_auto_psv__)) _IC8Interrupt(void)

radioIn_udb.c:200: void __attribute__((__interrupt__,__no_auto_psv__)) _IC2Interrupt(void)

radioIn_udb.c:243: void __attribute__((__interrupt__,__no_auto_psv__)) _IC1Interrupt(void)

radioIn_udb.c:286: void __attribute__((__interrupt__,__no_auto_psv__)) _INT0Interrupt(void)

radioIn_udb.c:337: void __attribute__((__interrupt__,__no_auto_psv__)) _IC1Interrupt(void)

serialIO_udb.c:71: void __attribute__((__interrupt__,__no_auto_psv__)) _U2RXInterrupt(void)

serialIO_udb.c:90: void __attribute__((__interrupt__,__no_auto_psv__)) _U2TXInterrupt(void)

serialIO_udb.c:155: void __attribute__((__interrupt__,__no_auto_psv__)) _U1RXInterrupt(void)

serialIO_udb.c:174: void __attribute__((__interrupt__,__no_auto_psv__)) _U1TXInterrupt(void)

servoOut.c:194: void __attribute__((__interrupt__,__no_auto_psv__)) _T4Interrupt(void)

Search complete. 19 matches found.

When you are in  MPLAB IDE, each of the above lines can be “double clicked” so that MPLAB will then take you to the exact line where the interrupt function has been defined. For example line 128 of background.c to see the function that executes against the _T1Interrupt (Timer 1).

Using “Find All” is a useful way of exploring how each variable in MatrxiPilot is used, as it will find all occurrences of that variable across the entire project build (not just in one file).

*** DOCUMENT ENDS ***