diff --git a/Makefile b/Makefile index 31637de..8ba7da3 100644 --- a/Makefile +++ b/Makefile @@ -46,6 +46,9 @@ debug: $(MAKE) $(MAKEFILE) DEBUGFLAG="-g -D DEBUG" @echo "$(TARGET) Make Debug Complete" +docs: + @cd docs; doxygen Doxyfile + install: @$(INSTALLDIR) $(DESTDIR)$(prefix)/bin @$(INSTALL) $(TARGET) $(DESTDIR)$(prefix)/bin @@ -66,3 +69,4 @@ runonboot: @$(LINK) $(DESTDIR)$(prefix)/bin/$(TARGET) $(LINKDIR)/$(LINKNAME) @echo "$(TARGET) Set to Run on Boot" +.PHONY: all debug docs clean install uninstall runonboot \ No newline at end of file diff --git a/README.md b/README.md index 0505a39..a0cd94b 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,78 @@ -Multirotor Flight Controller for the Robotics Cape +# Documentation +[Documentation for rc_pilot](http://www-personal.umich.edu/~ghaggin/rc_pilot/) -Please don't use this and expect it to work the way you want it to!!!!! -I wrote this purely for my own use. NOT FOR PUBLIC USE!!!! -It comes with no warranty, no manual, and I won't answer questions about -how it works. If it breaks something, you get to keep both pieces. +# Setup +## Install dependencies on Beaglebone: -However, enough people have asked me for it so here it is. +```shell +$ sudo apt install libjson-c-dev libjson-c3 +``` +## Install librobotcontrol on Beaglebone: -Note: depends on libjson-c-dev & libjson-c3 -sudo apt install libjson-c-dev libjson-c3 +The repo for the library is located on the [Strawson Design](https://github.com/StrawsonDesign/librobotcontrol) GitHub page. There is a bug in the 1.0.4 release version (```rc_duplicate_filter``` fails for initialized filter) so [install librobotcontrol from source](http://strawsondesign.com/docs/librobotcontrol/installation.html). -also libroboticscape >v0.4.0 + +## Transfer rc_pilot source to Beaglebone: +In the scripts folder there are some convenient scripts for moving files to and from the vehicle. These scripts were build and tested on Ubuntu 19.04 but have not been tested on any other system. They should work on any system with bash and rsync. To transfer the files to the vehicle run: + +```shell +$ ./scripts/transfer_rcpilot [usb|wifi] +``` + +## Build on Beaglebone (from project directory): + +```shell +$ make +``` + +## Run RC_pilot: + +```shell +$ cd bin +$ sudo ./rc_pilot -s ../settings/quad_settings.json +``` + +# Miscellaneous +## Building docs: + +Make sure that doxygen is installed on your system and run + +``` shell +$ make docs +``` + +Open the docs with the web browser of your choice + +```shell +$ firefox docs/html/index.html +$ google-chrome docs/html/index.html +``` + +## (COMING SOON) Testing: +Test cases are written using the [Boost 1.66](https://www.boost.org/users/history/version_1_66_0.html) testing suite. Look at make target test for system install location. This suite is not written with portability in mind so it may take some tweaking to get it to work right now. Typically, installing boost with the option ```--prefix=/usr/local``` should put the libraries and headers in the correct location but don't count on it. + +Run the test suit with the make target: +```shell +$ make test +``` + +### Adding Test Modules + +To add a test modules, create a new file _test.cpp and format it as follows: + +```c++ +#include + +BOOST_AUTO_TEST_SUIT(Test_) + +BOOST_AUTO_TEST_CASE(test1){...} + +BOOST_AUTO_TEST_CASE(test2){...} + +... + +BOOST_AUTO_TEST_CASE_END() +``` + +The make target will compile each test module into a single executable and run all test cases simultaneously. \ No newline at end of file diff --git a/docs/Doxyfile b/docs/Doxyfile index b523495..ceefe7c 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -171,7 +171,7 @@ STRIP_FROM_PATH = # specify the list of include paths that are normally passed to the compiler # using the -I flag. -STRIP_FROM_INC_PATH = ../library/include/ +STRIP_FROM_INC_PATH = ../include # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but # less readable) file names. This can be useful is your file systems doesn't @@ -226,7 +226,7 @@ SEPARATE_MEMBER_PAGES = NO # uses this value to replace tabs by spaces in code fragments. # Minimum value: 1, maximum value: 16, default value: 4. -TAB_SIZE = 8 +TAB_SIZE = 4 # This tag can be used to specify a number of aliases that act as commands in # the documentation. An alias has the form: @@ -531,7 +531,7 @@ CASE_SENSE_NAMES = NO # scope will be hidden. # The default value is: NO. -HIDE_SCOPE_NAMES = YES +HIDE_SCOPE_NAMES = NO # If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will # append additional text to a page's title, such as Class Reference. If set to @@ -570,7 +570,7 @@ INLINE_INFO = YES # name. If set to NO, the members will appear in declaration order. # The default value is: YES. -SORT_MEMBER_DOCS = NO +SORT_MEMBER_DOCS = YES # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief # descriptions of file, namespace and class members alphabetically by member @@ -703,7 +703,7 @@ FILE_VERSION_FILTER = # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE # tag is left empty. -LAYOUT_FILE = src/DoxygenLayout.xml +LAYOUT_FILE = # The CITE_BIB_FILES tag can be used to specify one or more bib files containing # the reference definitions. This must be a list of .bib files. The .bib @@ -790,8 +790,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = ../include \ - ../src/ +INPUT = ../include/ ./src/ # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -907,9 +906,7 @@ EXCLUDE_SYMBOLS = # that contain example code fragments that are included (see the \include # command). -EXAMPLE_PATH = ../examples/src/ \ - ../library/include \ - ../rc_project_template +EXAMPLE_PATH = # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and @@ -923,7 +920,7 @@ EXAMPLE_PATTERNS = * # irrespective of the value of the RECURSIVE tag. # The default value is: NO. -EXAMPLE_RECURSIVE = YES +EXAMPLE_RECURSIVE = NO # The IMAGE_PATH tag can be used to specify one or more files or directories # that contain images that are to be included in the documentation (see the @@ -998,7 +995,7 @@ USE_MDFILE_AS_MAINPAGE = # also VERBATIM_HEADERS is set to NO. # The default value is: NO. -SOURCE_BROWSER = YES +SOURCE_BROWSER = NO # Setting the INLINE_SOURCES tag to YES will include the body of functions, # classes and enums directly into the documentation. @@ -1011,7 +1008,7 @@ INLINE_SOURCES = NO # Fortran comments will always remain visible. # The default value is: YES. -STRIP_CODE_COMMENTS = NO +STRIP_CODE_COMMENTS = YES # If the REFERENCED_BY_RELATION tag is set to YES then for each documented # function all documented functions referencing it will be listed. @@ -1491,14 +1488,14 @@ GENERATE_TREEVIEW = YES # Minimum value: 0, maximum value: 20, default value: 4. # This tag requires that the tag GENERATE_HTML is set to YES. -ENUM_VALUES_PER_LINE = 1 +ENUM_VALUES_PER_LINE = 4 # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used # to set the initial width (in pixels) of the frame in which the tree is shown. # Minimum value: 0, maximum value: 1500, default value: 250. # This tag requires that the tag GENERATE_HTML is set to YES. -TREEVIEW_WIDTH = 300 +TREEVIEW_WIDTH = 250 # If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to # external symbols imported via tag files in a separate window. @@ -2062,7 +2059,7 @@ ENABLE_PREPROCESSING = YES # The default value is: NO. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -MACRO_EXPANSION = YES +MACRO_EXPANSION = NO # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then # the macro expansion is limited to the macros specified with the PREDEFINED and diff --git a/docs/src/mainpage.dox b/docs/src/mainpage.dox index 0241bbc..36dd72b 100644 --- a/docs/src/mainpage.dox +++ b/docs/src/mainpage.dox @@ -1,16 +1,79 @@ /** - \mainpage +# Setup +## Install dependencies on Beaglebone: + +~~~ +$ sudo apt install libjson-c-dev libjson-c3 +~~~ + +## Install librobotcontrol on Beaglebone: + +The repo for the library is located on the Strawson Design GitHub page. There is a bug in the 1.0.4 release version (rc_duplicate_filter fails for initialized filter) so install librobotcontrol from source. + +## Transfer rc_pilot source to Beaglebone: +In the scripts folder there are some convenient scripts for moving files to and from the vehicle. These scripts were build and tested on Ubuntu 19.04 but have not been tested on any other system. They should work on any system with bash and rsync. To transfer the files to the vehicle run: + +~~~ +$ ./scripts/transfer_rcpilot [usb|wifi] +~~~ + +## Build on Beaglebone (from project directory): + +~~~ +$ make +~~~ + +## Run RC_pilot: + +~~~ +$ cd bin +$ sudo ./rc_pilot -s ../settings/quad_settings.json +~~~ + +# Miscellaneous +## Building docs: + +Make sure that doxygen is installed on your system and run + +~~~ +$ make docs +~~~ + +Open the docs with the web browser of your choice + +~~~ +$ firefox html/index.html +$ google-chrome html/index.html +~~~ + +## (COMING SOON) Testing: +Test cases are written using the Boost 1.66. unit test framework. Look at make target test for system install location. This suite is not written with portability in mind so you may need to tweak the build system in order to get it to compile on your machine. The boost libraries should be isntalled in /usr/local/lib and the headers should be installed in /usr/local/boost_1_66_0 (check the Makefile to confirm this). + +Run the test suit with the make target: +~~~ +$ make test +~~~ + +### Adding Test Modules + +To add a test modules, create a new file _test.cpp and format it as follows: + +~~~ +#include +BOOST_AUTO_TEST_SUIT(Test_) -This package contains the C library and example/testing programs for the Robot Control project. This project began as a hardware interface for the Robotics Cape and later the BeagleBone Blue and was originally called Robotics_Cape_Installer. It grew to include an extensive math library for discrete time feedback control, as well as a plethora of POSIX-compliant functions for timing, multithreading, program flow, and lots more. Everything is aimed at developing robotics software on embedded computers. +BOOST_AUTO_TEST_CASE(test1){...} -This package ships with official BeagleBone images and is focused on, but not excludive to, the BeagleBoard platform. The library and example programs are primarily written in C, however there also exists the RCPY python interface to this package available at . +BOOST_AUTO_TEST_CASE(test2){...} -The master branch is always the most current but not necessarily stable. See [releases](https://github.com/StrawsonDesign/Robotics_Cape_Installer/releases) page for older stable versions or install from BeagleBoard.org repositories. +... -To get started, visit the [user manual](manual.html) +BOOST_AUTO_TEST_CASE_END() +~~~ +The make target will compile each test module into a single executable and run all test cases simultaneously. */ diff --git a/include/feedback.h b/include/feedback.h index 4b3bb56..e53e980 100644 --- a/include/feedback.h +++ b/include/feedback.h @@ -10,6 +10,8 @@ * feedback_march(void) will monitor the setpoint which is constantly being * changed by setpoint_manager(void). * + * @addtogroup Feedback + * @{ */ #ifndef FEEDBACK_H @@ -86,3 +88,5 @@ int feedback_arm(void); int feedback_cleanup(void); #endif // FEEDBACK_H + +/**@} end group Feedback */ diff --git a/include/flight_mode.h b/include/flight_mode.h index 1388705..f011a34 100644 --- a/include/flight_mode.h +++ b/include/flight_mode.h @@ -1,5 +1,10 @@ /** * + * + * @brief Flight mode definitions + * + * @addtogroup FlightModes + * @{ */ #ifndef FLIGHT_MODE_H @@ -70,4 +75,6 @@ typedef enum flight_mode_t } flight_mode_t; -#endif \ No newline at end of file +#endif + +/**@}end group Flight Modes */ diff --git a/include/input_manager.h b/include/input_manager.h index 5a7146a..547e04b 100644 --- a/include/input_manager.h +++ b/include/input_manager.h @@ -1,9 +1,12 @@ /** * * - * Functions to start and stop the input manager thread which is the translation + * @brief Functions to start and stop the input manager thread which is the translation * beween control inputs from DSM to the user_input struct which is read by the * setpoint manager. TODO: Allow other inputs such as mavlink + * + * @addtogroup InputManager + * @{ */ #ifndef INPUT_MANAGER_H @@ -75,3 +78,5 @@ int input_manager_init(void); int input_manager_cleanup(void); #endif // INPUT_MANAGER_H + +/**@}end group InputMaganger */ diff --git a/include/mavlink_manager.h b/include/mavlink_manager.h index cd5b9b2..b7319a3 100644 --- a/include/mavlink_manager.h +++ b/include/mavlink_manager.h @@ -1,7 +1,10 @@ /** * * - * Functions to start and stop the mavlink manager + * @brief Functions to start and stop the mavlink manager + * + * @addtogroup MavlinkManager + * @{ */ #ifndef MAVLINK_MANAGER_H @@ -22,3 +25,5 @@ int mavlink_manager_init(void); int mavlink_manager_cleanup(void); #endif // MAVLINK_MANAGER_H + +/* @} end group Mavlink Manager */ diff --git a/include/mix.h b/include/mix.h index eae2fb4..93b4934 100644 --- a/include/mix.h +++ b/include/mix.h @@ -1,14 +1,17 @@ /** * * - * @brief Functions to mix orthogonal inputs to motor controls - * - * MultiRotors are controlled by mixing roll, pitch, yaw, and - * throttle control oututs, a linear combination of which forms the - * control output to each motor. The coefficients to this - * combination is stored in a mixing matrix based on rotor layout. - * Also included here are functions to parse configuration strings - * and do the actual mixing. + * @brief Functions to mix orthogonal inputs to motor controls + * + * MultiRotors are controlled by mixing roll, pitch, yaw, and + * throttle control oututs, a linear combination of which forms the + * control output to each motor. The coefficients to this + * combination is stored in a mixing matrix based on rotor layout. + * Also included here are functions to parse configuration strings + * and do the actual mixing. + * + * @addtogroup Mix + * @{ */ #ifndef MIXING_MATRIX_H @@ -106,4 +109,6 @@ int mix_check_saturation(int ch, double* mot, double* min, double* max); */ int mix_add_input(double u, int ch, double* mot); -#endif // MIXING_MATRIX_H \ No newline at end of file +#endif // MIXING_MATRIX_H + +/* @} end group Mix */ diff --git a/include/printf_manager.h b/include/printf_manager.h index 24c910c..7a73690 100644 --- a/include/printf_manager.h +++ b/include/printf_manager.h @@ -1,8 +1,11 @@ /** * * - * @brief Functions to start and stop the printf mnaager which is a - * separate thread printing data to the console for debugging. + * @brief Functions to start and stop the printf mnaager which is a + * separate thread printing data to the console for debugging. + * + * @addtogroup PrintfManager + * @{ */ #ifndef PRINTF_MANAGER_H @@ -36,3 +39,5 @@ int printf_cleanup(void); int print_flight_mode(flight_mode_t mode); #endif // PRINTF_MANAGER_H + +/* @} end group PrintfManager */ diff --git a/include/rc_pilot_defs.h b/include/rc_pilot_defs.h index 5d43dbe..f38c524 100644 --- a/include/rc_pilot_defs.h +++ b/include/rc_pilot_defs.h @@ -1,7 +1,10 @@ /** * * - * @brief constants and parameters + * @brief Constants and parameters + * + * @addtogroup RcPilotDefs + * @{ */ #ifndef RC_PILOT_DEFS_H @@ -89,4 +92,6 @@ typedef enum arm_state_t //#define DEBUG -#endif // RC_PILOT_DEFS_H \ No newline at end of file +#endif // RC_PILOT_DEFS_H + +/* @} end group RcPilotDefs */ diff --git a/include/setpoint_manager.h b/include/setpoint_manager.h index 2d38961..38834fa 100644 --- a/include/setpoint_manager.h +++ b/include/setpoint_manager.h @@ -1,18 +1,24 @@ /** * * - * @brief Setpoint manager runs at the same rate as the feedback controller - * and is the interface between the user inputs (input manager) and - * the feedback controller setpoint. currently it contains very - * simply logic and runs very quickly which is why it's okay to run - * in the feedback ISR right before the feedback controller. In the - * future this is where go-home and other higher level autonomy will - * live. + * @brief Guidance module for the vehicle + * + * Setpoint manager runs at the same rate as the feedback controller + * and is the interface between the user inputs (input manager) and + * the feedback controller setpoint. currently it contains very + * simply logic and runs very quickly which is why it's okay to run + * in the feedback ISR right before the feedback controller. In the + * future this is where go-home and other higher level autonomy will + * live. + * + * This serves to allow the feedback controller to be as simple and + * clean as possible by putting all high-level manipulation of the + * setpoints here. Then feedback-controller only needs to march the + * filters and zero them out when arming or enabling controllers + * + * @addtogroup SetpointManager + * @{ * - * This serves to allow the feedback controller to be as simple and - * clean as possible by putting all high-level manipulation of the - * setpoints here. Then feedback-controller only needs to march the - * filters and zero them out when arming or enabling controllers */ #ifndef SETPOINT_MANAGER_H @@ -100,3 +106,5 @@ int setpoint_manager_update(void); int setpoint_manager_cleanup(void); #endif // SETPOINT_MANAGER_H + +/* @} end group SetpointManager */ diff --git a/include/settings.h b/include/settings.h index bde065f..c647643 100644 --- a/include/settings.h +++ b/include/settings.h @@ -1,7 +1,10 @@ /** - * + * * - * @brief Functions to read the json settings file + * @brief Functions to read the json settings file + * + * @addtogroup Settings + * @{ */ #ifndef SETTINGS_H @@ -135,3 +138,5 @@ int settings_load_from_file(char* path); int settings_print(void); #endif // SETTINGS_H + +/* @} end group Settings */ diff --git a/include/state_estimator.h b/include/state_estimator.h index 4726289..edcde85 100644 --- a/include/state_estimator.h +++ b/include/state_estimator.h @@ -1,11 +1,14 @@ /** - * @file state_estimator.h + * * - * @brief Functions to start and stop the state estimator + * @brief Navigation module for the vehicle * * This runs at the same rate as the feedback controller. * state_estimator_march() is called immediately before feedback_march() in the * IMU interrupt service routine. + * + * @addtogroup StateEstimator + * @{ */ #ifndef STATE_ESTIMATOR_H @@ -173,3 +176,5 @@ int state_estimator_jobs_after_feedback(void); int state_estimator_cleanup(void); #endif // STATE_ESTIMATOR_H + +/* @} end group StateEstimator */ diff --git a/include/thread_defs.h b/include/thread_defs.h index 3b9e245..dbc82ea 100644 --- a/include/thread_defs.h +++ b/include/thread_defs.h @@ -1,4 +1,11 @@ - +/** + * + * + * @brief Thread speeds, prioritites, and close timeouts + * + * @addtogroup ThreadDefs + * @{ + */ #ifndef THREAD_DEFS_H #define THREAD_DEFS_H @@ -16,4 +23,5 @@ #define BUTTON_EXIT_CHECK_HZ 10 #define BUTTON_EXIT_TIME_S 2 -#endif \ No newline at end of file +#endif +/* @} end group ThreadDefs */ diff --git a/include/thrust_map.h b/include/thrust_map.h index 602aa3d..02b4b42 100644 --- a/include/thrust_map.h +++ b/include/thrust_map.h @@ -1,10 +1,12 @@ /** - * @headerfile thrust_map.h + * * - * @brief Functions to start and stop the printf manager which is a - * separate thread printing data to the console for debugging. + * @brief Functions to start and stop the printf manager which is a + * separate thread printing data to the console for debugging. + * + * @addtogroup ThrustMap + * @{ */ - #ifndef THRUST_MAP_H #define THRUST_MAP_H @@ -40,3 +42,5 @@ int thrust_map_init(thrust_map_t map); double map_motor_signal(double m); #endif // THRUST_MAP_H + +/* @} end group ThrustMap */ diff --git a/src/mix.c b/src/mix.c index f4f9710..57d6ee4 100644 --- a/src/mix.c +++ b/src/mix.c @@ -1,5 +1,5 @@ /** - * @file mixing_matrix.c + * @file mix.c */ #include // for DBL_MAX diff --git a/src/setpoint_manager.c b/src/setpoint_manager.c index 01f9785..dfcbfac 100644 --- a/src/setpoint_manager.c +++ b/src/setpoint_manager.c @@ -1,8 +1,7 @@ /** * @file setpoint_manager.c - * - * **/ + #include #include #include // for memset