From 053eb1232919b8cdd76109109dddc97bd897fe57 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Beat=20K=C3=BCng?= Date: Tue, 2 May 2017 16:06:58 +0200 Subject: [PATCH] Module documentation: switch to Markdown --- src/drivers/px4fmu/fmu.cpp | 20 +++++++++++++++----- src/modules/events/send_event.cpp | 1 + src/modules/logger/logger.cpp | 9 +++++++-- src/modules/mavlink/mavlink_main.cpp | 10 +++++++--- src/platforms/common/module.cpp | 5 ++++- src/platforms/px4_module.h | 19 ++++++++++++++----- 6 files changed, 48 insertions(+), 16 deletions(-) diff --git a/src/drivers/px4fmu/fmu.cpp b/src/drivers/px4fmu/fmu.cpp index 1f6a2120cd..bc27257d44 100644 --- a/src/drivers/px4fmu/fmu.cpp +++ b/src/drivers/px4fmu/fmu.cpp @@ -3493,11 +3493,13 @@ int PX4FMU::print_usage(const char *reason) PRINT_MODULE_DESCRIPTION( R"DESCR_STR( -This module is responsible for driving the output and reading the input pins for boards without a separate IO chip -(eg. Pixracer). On boards with an IO chip, the px4io driver is used. +### Description +This module is responsible for driving the output and reading the input pins. For boards without a separate IO chip +(eg. Pixracer), it uses the main channels. On boards with an IO chip (eg. Pixhawk), it uses the AUX channels, and the +px4io driver is used for main ones. It listens on the actuator_controls topics, does the mixing and writes the PWM outputs. -In addition it does the RC input parsing and auto-select the method. Supported methods are: +In addition it does the RC input parsing and auto-selecting the method. Supported methods are: - PPM - SBUS - DSM @@ -3508,17 +3510,25 @@ The module is configured via mode_* commands. This defines which of the first N By using mode_pwm4 for example, pins 5 and 6 can be used by the camera trigger driver or by a PWM rangefinder driver. +### Implementation By default the module runs on the work queue, to reduce RAM usage. It can also be run in its own thread, specified via start flag -t, to reduce latency. When running on the work queue, it schedules at a fixed frequency, and the pwm rate limits the update rate of the actuator_controls topics. In case of running in its own thread, the module polls on the actuator_controls topic. Additionally the pwm rate defines the lower-level IO timer rates. +### Examples It is typically started with: $ fmu mode_pwm To drive all available pins. -Use the 'pwm' command for further configurations (PWM rate, levels, ...). +Capture input (rising and falling edges) and print on the console: start the fmu in one of the capture modes: +$ fmu mode_pwm3cap1 +This will enable capturing on the 4th pin. Then do: +$ fmu test + +Use the `pwm` command for further configurations (PWM rate, levels, ...), and the `mixer` command to load +mixer files. )DESCR_STR"); PRINT_MODULE_USAGE_NAME("fmu", "driver"); @@ -3528,7 +3538,7 @@ Use the 'pwm' command for further configurations (PWM rate, levels, ...). PRINT_MODULE_USAGE_PARAM_COMMENT("All of the mode_* commands will start the fmu if not running already"); PRINT_MODULE_USAGE_COMMAND("mode_gpio"); - PRINT_MODULE_USAGE_COMMAND("mode_rcin"); + PRINT_MODULE_USAGE_COMMAND_DESCR("mode_rcin", "Only do RC input, no PWM outputs"); PRINT_MODULE_USAGE_COMMAND_DESCR("mode_pwm", "Select all available pins as PWM"); #if defined(BOARD_HAS_PWM) PRINT_MODULE_USAGE_COMMAND("mode_pwm1"); diff --git a/src/modules/events/send_event.cpp b/src/modules/events/send_event.cpp index 109c3438d4..ab80e5afff 100644 --- a/src/modules/events/send_event.cpp +++ b/src/modules/events/send_event.cpp @@ -199,6 +199,7 @@ int SendEvent::print_usage(const char *reason) PRINT_MODULE_DESCRIPTION( R"DESCR_STR( +### Description Background process running periodically on the LP work queue to perform housekeeping tasks. It is currently only responsible for temperature calibration. diff --git a/src/modules/logger/logger.cpp b/src/modules/logger/logger.cpp index dffcea5121..d40ebb11c6 100644 --- a/src/modules/logger/logger.cpp +++ b/src/modules/logger/logger.cpp @@ -143,21 +143,26 @@ int Logger::print_usage(const char *reason) PRINT_MODULE_DESCRIPTION( R"DESCR_STR( -System logger which logs a (configurable) set of uORB topics and system printf messages +### Description +System logger which logs a configurable set of uORB topics and system printf messages (warnings and errors) to ULog files. These can be used for system and flight performance evaluation, tuning, replay and crash analysis. It supports 2 backends: - Files: write ULog files to the file system (SD card) - MAVLink: stream ULog data via MAVLink to a client (the client must support this) + Both backends can be enabled and used at the same time. +### Implementation The implementation uses two threads: - The main thread, running at a fixed rate (or polling on a topic if started with -p) and checking for -data updates + data updates - The writer thread, writing data to the file + In between there is a write buffer with configurable size. It should be large to avoid dropouts. +### Examples Typical usage to start logging immediately: $ logger start -e -t diff --git a/src/modules/mavlink/mavlink_main.cpp b/src/modules/mavlink/mavlink_main.cpp index 3cd160610a..004f8f480c 100644 --- a/src/modules/mavlink/mavlink_main.cpp +++ b/src/modules/mavlink/mavlink_main.cpp @@ -2703,19 +2703,23 @@ static void usage() PRINT_MODULE_DESCRIPTION( R"DESCR_STR( +### Description This module implements the MAVLink protocol, which can be used on a Serial link or UDP network connection. It communicates with the system via uORB: some messages are directly handled in the module (eg. mission protocol), others are published via uORB (eg. vehicle_command). Streams are used to send periodic messages with a specific rate, such as the vehicle attitude. When starting the mavlink instance, a mode can be specified, which defines the set of enabled streams with their rates. -For a running instance, streams can be configured via 'mavlink stream' command. +For a running instance, streams can be configured via `mavlink stream` command. There can be multiple independent instances of the module, each connected to one serial device or network port. -The implementation uses 2 threads, a sending and a receiving thread. +### Implementation +The implementation uses 2 threads, a sending and a receiving thread. The sender runs at a fixed rate and dynamically +reduces the rates of the streams if the combined bandwidth is higher than the configured rate (`-r`) or the +physical link becomes saturated. This can be checked with `mavlink status`, see if `rate mult` is less than 1. -Example usage: +### Examples Start mavlink on ttyS1 serial with baudrate 921600 and maximum sending rate of 80kB/s: $ mavlink start -d /dev/ttyS1 -b 921600 -m onboard -r 80000 diff --git a/src/platforms/common/module.cpp b/src/platforms/common/module.cpp index 6df2611b07..c6ed41a7b5 100644 --- a/src/platforms/common/module.cpp +++ b/src/platforms/common/module.cpp @@ -44,7 +44,10 @@ pthread_mutex_t px4_modules_mutex = PTHREAD_MUTEX_INITIALIZER; void PRINT_MODULE_DESCRIPTION(const char *description) { - printf("%s\n", description); + // TODO: the output could be improved by: + // - mark titles in bold (lines starting with ##) + // - highlight commands (lines starting with $, or `cmd`) + printf("%s\n\n", description); } #endif /* __PX4_NUTTX */ diff --git a/src/platforms/px4_module.h b/src/platforms/px4_module.h index a42891a79c..faee961924 100644 --- a/src/platforms/px4_module.h +++ b/src/platforms/px4_module.h @@ -352,7 +352,9 @@ int ModuleBase::_task_id = -1; __BEGIN_DECLS -/* module documentation and command usage help methods */ +/* Module documentation and command usage help methods. + * These are extracted with the Tools/px_process_module_doc.py script and must be kept in sync + */ #ifdef __PX4_NUTTX // disable module description on NuttX to reduce Flash usage. @@ -361,10 +363,17 @@ __BEGIN_DECLS static inline void PRINT_MODULE_DESCRIPTION(const char *description) {} #else /** - * Print module documentation (Will also be used for online documentation). This should include: - * - provided functionality of the module - * - high-level implementation overview - * - examples how to use the CLI interface (if it's non-trivial) + * Print module documentation (will also be used for online documentation). It uses Markdown syntax + * and should include these sections: + * - ### Description + * Provided functionality of the module and potentially the most important parameters. + * - ### Implementation + * High-level implementation overview + * - ### Examples + * Examples how to use the CLI interface (if it's non-trivial) + * + * In addition to the Markdown syntax, a line beginning with '$ ' can be used to mark a command: + * $ module start -p param */ __EXPORT void PRINT_MODULE_DESCRIPTION(const char *description); #endif