diff --git a/README.md b/README.md index 71156a334d..3d678f51f7 100644 --- a/README.md +++ b/README.md @@ -15,15 +15,17 @@ process that you can fine-tune to your needs. - [This project has a homepage](http://modm.io). - Check out our [install instructions][install] and our [getting started guide][guide]. - Feast your eyes on [lots of working examples][examples]. - - - Our CI checks every contribution for regressions: ![Build Status](https://circleci.com/gh/modm-io/modm/tree/develop.svg?style=shield) - We care [about testing modm][testing]. + + + This project also has a [technical blog][blog] to document larger design concepts. - You found a bug? [Open up an issue, we don't bite][issues]. -- You want to contribute? [Read the contribution guidelines][contributing] and [open a pull request][prs]. +- You want to contribute? [Read the contribution guidelines][contrib] and [open a pull request][prs]. + modm is optimized for the harsh requirements of the [Eurobot competition][eurobot], @@ -66,29 +68,30 @@ git clone --recurse-submodules https://github.com/modm-io/modm.git ## Targets -modm can generate code for 76 AVR and 865 STM32 devices, however, there are different levels of support and testing. +modm can generate code for 76 AVR and 865 +STM32 devices, however, there are different levels of support and testing.
-| Device Family | Support | Device Family | Support | -|:--------------|:------------------------------------|:--------------|:------------------------------------| -| AVR | ★★★ | STM32F3 | ★★★★★ | -| STM32F0 | ★★★★ | STM32F4 | ★★★★★ | -| STM32F1 | ★★★★ | STM32F7 | ★★★★ | -| STM32F2 | ★★★ | STM32L4 | ★★★★ | +| Device Family | Support | Device Family | Support | +|:--------------|:--------|:--------------|:--------| +| AVR | ★★★ | STM32F3 | ★★★★★ | +| STM32F0 | ★★★★ | STM32F4 | ★★★★★ | +| STM32F1 | ★★★★ | STM32F7 | ★★★★ | +| STM32F2 | ★★★ | STM32L4 | ★★★★ |
All of these targets are compiling and booting correctly -(★) +(★) and have GPIO and UART working -(★★). +(★★). Most targets have support for basic peripherals, like I2C, SPI and ADC -(★★★) +(★★★) as well as complicated peripherals, like Timers, CAN and external memory -(★★★★). +(★★★★). We also use a few targets in everyday development, which are very well tested -(★★★★★). +(★★★★★). We are only a small team of developers and are limited in the amount of targets we can support and test in hardware. We have prepared, but currently not finished @@ -144,9 +147,9 @@ documentation. ### Drivers -We also have a number of completely target-independent [drivers for external +We also have a number of completely target-independent [drivers for external devices][drivers] connected via I2C, SPI, UART, BitBang, etc. -Most of these also give you access to the entire device so you +Most of these also give you access to the entire device so you can easily configure them for you specific needs.
@@ -218,22 +221,22 @@ Please see [our examples for a complete list][examples] of tested targets and dr ## How can I contribute? -The easiest way for you and the best way for us to see if something is unclear -or missing, is if you use the library and give us some feedback by +The easiest way for you and the best way for us to see if something is unclear +or missing, is if you use the library and give us some feedback by [filing a bug report][issues] or if you have a fix already, [opening a pull request][prs]. -See [CONTRIBUTING.md][contributing] for our contribution guidelines. +See [CONTRIBUTING.md][contrib] for our contribution guidelines. The modm project is maintained by -Niklas Hauser ([@salkinium](https://github.com/salkinium)) with significant contributions from -Sascha Schade ([@strongly-typed](https://github.com/strongly-typed)), -Fabian Greif ([@dergraaf](https://github.com/dergraaf)), -Kevin Läufer ([@ekiwi](https://github.com/ekiwi)), -Martin Rosekeit ([@thundernail](https://github.com/thundernail)), -Daniel Krebs ([@daniel-k](https://github.com/daniel-k)), -Georgi Grinshpun ([@georgi-g](https://github.com/georgi-g)) and -[20 more contributors](https://github.com/modm-io/modm/blob/develop/AUTHORS). +Niklas Hauser ([\@salkinium](https://github.com/salkinium)) with significant contributions from +Sascha Schade ([\@strongly-typed](https://github.com/strongly-typed)), +Fabian Greif ([\@dergraaf](https://github.com/dergraaf)), +Kevin Läufer ([\@ekiwi](https://github.com/ekiwi)), +Martin Rosekeit ([\@thundernail](https://github.com/thundernail)), +Daniel Krebs ([\@daniel-k](https://github.com/daniel-k)), +Georgi Grinshpun ([\@georgi-g](https://github.com/georgi-g)) and +[20 more contributors](https://github.com/modm-io/modm/blob/develop/AUTHORS). ## Folder structure @@ -275,7 +278,7 @@ Georgi Grinshpun ([@georgi-g](https://github.com/georgi-g)) and [blog]: http://blog.salkinium.com [changelog]: https://github.com/modm-io/modm/tree/develop/docs/CHANGELOG.md [circle_ci]: https://circleci.com/gh/modm-io/workflows/modm/tree/develop -[contributing]: https://github.com/modm-io/modm/tree/develop/CONTRIBUTING.md +[contrib]: https://github.com/modm-io/modm/tree/develop/CONTRIBUTING.md [devboards]: https://github.com/modm-io/modm/tree/develop/src/modm/board [drivers]: https://github.com/modm-io/modm/tree/develop/src/modm/driver [eurobot]: http://www.eurobot.org/ diff --git a/ext/fatfs/module.lb b/ext/fatfs/module.lb index af1bea1cac..bc30beb79c 100644 --- a/ext/fatfs/module.lb +++ b/ext/fatfs/module.lb @@ -13,6 +13,15 @@ def init(module): module.name = "fatfs" + module.description = """\ +# FatFS + +Generic FAT Filesystem Module. +See http://elm-chan.org/fsw/ff/00index_e.html. + +!!! warning + This version of FatFS is outdated and rarely used in modm. +""" def prepare(module, options): return True diff --git a/ext/freertos/module.lb b/ext/freertos/module.lb index 4fea04e9f3..0b4213272f 100644 --- a/ext/freertos/module.lb +++ b/ext/freertos/module.lb @@ -13,6 +13,14 @@ def init(module): module.name = "freertos" + module.description = """\ +# FreeRTOS + +Imported v7.0.1 of FreeRTOS with custom modifications. + +!!! warning + Please be aware this version is quite outdated and modified for modm. +""" def prepare(module, options): device = options[":target"] diff --git a/ext/gcc/module.lb b/ext/gcc/module.lb index 16835f2ae4..27a1864ed1 100644 --- a/ext/gcc/module.lb +++ b/ext/gcc/module.lb @@ -15,6 +15,12 @@ def init(module): module.name = "stdc++" + module.description = """\ +# C++ Standard Library + +A partial port of GCC 8 libstdc++ for AVR. +See https://github.com/modm-io/avr-libstdcpp. +""" def prepare(module, options): diff --git a/ext/ros/module.lb b/ext/ros/module.lb index 1a85af361d..de7f4ec3a2 100644 --- a/ext/ros/module.lb +++ b/ext/ros/module.lb @@ -12,6 +12,12 @@ def init(module): module.name = "ros" + module.description = """\ +# ROS Library + +Repository of generated messages headers for rosserial. +See https://github.com/modm-io/ros-lib. +""" def prepare(module, options): return True diff --git a/ext/tlsf/README.md b/ext/tlsf/README.md index 18643844c7..3fe7967c4a 100644 --- a/ext/tlsf/README.md +++ b/ext/tlsf/README.md @@ -1,7 +1,9 @@ -# [tlsf](https://github.com/mattconte/tlsf) +# TLSF Allocator + Two-Level Segregated Fit memory allocator implementation. Written by Matthew Conte (matt@baisoku.org). Released under the BSD license. +https://github.com/mattconte/tlsf Features -------- diff --git a/ext/tlsf/module.lb b/ext/tlsf/module.lb index 5bc014bdc8..a416c95dfe 100644 --- a/ext/tlsf/module.lb +++ b/ext/tlsf/module.lb @@ -14,6 +14,7 @@ import math def init(module): module.name = "tlsf" + module.description = FileReader("README.md") def prepare(module, options): device = options[":target"] diff --git a/src/modm/architecture/architecture.hpp b/src/modm/architecture/architecture.hpp index 8d988cd7ad..7e1db5d867 100644 --- a/src/modm/architecture/architecture.hpp +++ b/src/modm/architecture/architecture.hpp @@ -12,12 +12,6 @@ */ // ---------------------------------------------------------------------------- -/** - * \defgroup architecture Architecture - * - * Supported platforms - */ - #ifndef MODM_ARCHITECTURE_HPP #define MODM_ARCHITECTURE_HPP diff --git a/src/modm/architecture/detect.hpp b/src/modm/architecture/detect.hpp index 34f457a448..d57709b412 100644 --- a/src/modm/architecture/detect.hpp +++ b/src/modm/architecture/detect.hpp @@ -16,50 +16,41 @@ #ifdef __DOXYGEN__ -/** - * \brief Compiler description - * \ingroup platform - */ + +/// Compiler description +/// @ingroup modm_architecture #define MODM_COMPILER_STRING -/** - * \brief Possible compilers - * \ingroup platform - */ -//@{ +/// Possible compilers +/// @ingroup modm_architecture +/// @{ #define MODM_COMPILER_GCC #define MODM_COMPILER_MSVC -//@} +/// @} -/** - * \brief Operating system description - * \ingroup platform - */ +/// Operating system description +/// @ingroup modm_architecture #define MODM_OS_STRING -/** - * \brief Possible operating systems - * \ingroup platform - */ -//@{ +/// Possible operating systems +/// @ingroup modm_architecture +/// @{ #define MODM_OS_UNIX #define MODM_OS_LINUX #define MODM_OS_OSX #define MODM_OS_WIN32 #define MODM_OS_WIN64 -//@} +#define MODM_OS_HOSTED +#define MODM_OS_HOSTED_64 +/// @} -/** - * \brief CPU description - * \ingroup platform - */ +/// CPU description +/// @ingroup modm_architecture #define MODM_CPU_STRING -//@{ -/** - * \brief Possible CPU definitions - * \ingroup platform - */ +/// Possible CPU definitions +/// @ingroup modm_architecture +/// @{ #define MODM_CPU_AVR #define MODM_CPU_ATXMEGA #define MODM_CPU_ATMEGA @@ -68,17 +59,13 @@ #define MODM_CPU_ARM #define MODM_CPU_ARM7TDMI #define MODM_CPU_CORTEX_M0 +#define MODM_CPU_CORTEX_M3 #define MODM_CPU_CORTEX_M4 -#define MODM_CPU_CORTEX_M4 +/// @} -#define MODM_OS_HOSTED -#define MODM_OS_HOSTED_64 - -//@{ -/** - * \brief Memory descriptions - * \ingroup platform - */ +/// Memory descriptions +/// @ingroup modm_architecture +/// @{ #define MODM_ALIGNMENT #define MODM_ORDER_BIG_ENDIAN @@ -91,7 +78,7 @@ #define MODM_IS_LITTLE_ENDIAN #define MODM_SIZEOF_POINTER -//@} +/// @} #else //!__DOXYGEN__ diff --git a/src/modm/architecture/driver/atomic.hpp b/src/modm/architecture/driver/atomic.hpp index 0f0a637c41..622cbaa87f 100644 --- a/src/modm/architecture/driver/atomic.hpp +++ b/src/modm/architecture/driver/atomic.hpp @@ -10,17 +10,6 @@ */ // ---------------------------------------------------------------------------- -namespace modm -{ - /** - * \ingroup atomic - * \brief Atomic operations and container - */ - namespace atomic - { - } -} - #include "atomic/flag.hpp" #include "atomic/container.hpp" #include "atomic/queue.hpp" diff --git a/src/modm/architecture/driver/atomic/container.hpp b/src/modm/architecture/driver/atomic/container.hpp index 5878da38d2..d7feef7f44 100644 --- a/src/modm/architecture/driver/atomic/container.hpp +++ b/src/modm/architecture/driver/atomic/container.hpp @@ -68,7 +68,7 @@ namespace modm * as it is the case here! * * \author Fabian Greif - * \ingroup atomic + * \ingroup modm_architecture_atomic */ template class Container diff --git a/src/modm/architecture/driver/atomic/flag.hpp b/src/modm/architecture/driver/atomic/flag.hpp index cf2be6c9ce..2494c60b98 100644 --- a/src/modm/architecture/driver/atomic/flag.hpp +++ b/src/modm/architecture/driver/atomic/flag.hpp @@ -41,7 +41,7 @@ namespace modm * } * \endcode * - * \ingroup atomic + * \ingroup modm_architecture_atomic * \author Fabian Greif */ class Flag diff --git a/src/modm/architecture/driver/atomic/queue.hpp b/src/modm/architecture/driver/atomic/queue.hpp index a3702d00d1..f667340696 100644 --- a/src/modm/architecture/driver/atomic/queue.hpp +++ b/src/modm/architecture/driver/atomic/queue.hpp @@ -26,7 +26,7 @@ namespace modm namespace atomic { /** - * \ingroup atomic + * \ingroup modm_architecture_atomic * \brief Interrupt save queue * * A maximum size of 254 is allowed for 8-bit mikrocontrollers. diff --git a/src/modm/architecture/driver/heap/block_allocator.hpp b/src/modm/architecture/driver/heap/block_allocator.hpp index 59b2771e11..c1931d296c 100644 --- a/src/modm/architecture/driver/heap/block_allocator.hpp +++ b/src/modm/architecture/driver/heap/block_allocator.hpp @@ -21,22 +21,22 @@ #include #include -/** - * Memory allocator. - * - * - * \tparam T - * TODO - * - * \tparam BLOCK_SIZE - * Size of one allocatable block in words (sizeof(T) bytes) - * (BLOCKSIZE * sizeof(T) * n) - 4 has to be dividable by 4 for every n - * - * \author Fabian Greif - */ - namespace modm { + /** + * Memory allocator. + * + * + * \tparam T + * TODO + * + * \tparam BLOCK_SIZE + * Size of one allocatable block in words (sizeof(T) bytes) + * (BLOCKSIZE * sizeof(T) * n) - 4 has to be dividable by 4 for every n + * + * \author Fabian Greif + * \ingroup modm_architecture_heap + */ template class BlockAllocator { diff --git a/src/modm/architecture/interface.hpp.in b/src/modm/architecture/interface.hpp.in index 7014d015cb..a3ad37e87b 100644 --- a/src/modm/architecture/interface.hpp.in +++ b/src/modm/architecture/interface.hpp.in @@ -14,13 +14,6 @@ #include -/** - * @ingroup architecture - * @defgroup interface Architecture Interfaces - * - * All hardware peripherals with common interfaces. - */ - %% for header in headers #include "{{header}}" %% endfor diff --git a/src/modm/architecture/interface/accessor.hpp b/src/modm/architecture/interface/accessor.hpp index bc049df473..9865989270 100644 --- a/src/modm/architecture/interface/accessor.hpp +++ b/src/modm/architecture/interface/accessor.hpp @@ -20,19 +20,12 @@ namespace modm { -/** - * @defgroup accessor Accessor classes - * @ingroup interface - * - * @author Fabian Greif - */ namespace accessor { /** * Add volatile modifier to T - * - * @ingroup accessor + * @ingroup modm_architecture_accessor */ template modm_always_inline volatile T& diff --git a/src/modm/architecture/interface/accessor_flash.hpp b/src/modm/architecture/interface/accessor_flash.hpp index c785e43044..ab598d83ed 100644 --- a/src/modm/architecture/interface/accessor_flash.hpp +++ b/src/modm/architecture/interface/accessor_flash.hpp @@ -20,23 +20,23 @@ #ifdef __DOXYGEN__ /// Define a flash variable -/// @ingroup accessor +/// @ingroup modm_architecture_accessor #define FLASH_STORAGE(var) /// Define a flash variable with external linkage -/// @ingroup accessor +/// @ingroup modm_architecture_accessor #define EXTERN_FLASH_STORAGE(var) /// Define a flash string -/// @ingroup accessor +/// @ingroup modm_architecture_accessor #define FLASH_STORAGE_STRING(s) /// Declare a flash string with external linkage -/// @ingroup accessor +/// @ingroup modm_architecture_accessor #define EXTERN_FLASH_STORAGE_STRING(s) /// Declare a flash string inline -/// @ingroup accessor +/// @ingroup modm_architecture_accessor #define PSTR(s) ((const char *)(s)) #else // !__DOXYGEN__ @@ -62,7 +62,7 @@ namespace accessor * Based on a implementation of Rolf Magnus, see * http://www.mikrocontroller.net/topic/78610#656695 * - * @ingroup accessor + * @ingroup modm_architecture_accessor * @author Fabian Greif */ template @@ -170,7 +170,7 @@ class Flash }; /// Convert a normal pointer to a accessor::Flash -/// @ingroup accessor +/// @ingroup modm_architecture_accessor template modm_always_inline ::modm::accessor::Flash asFlash(const T* ptr) @@ -191,7 +191,7 @@ operator << (modm::IOStream& os, modm::accessor::Flash ptr); /** * Streamoperator - specialization for `char` - * @ingroup accessor + * @ingroup modm_architecture_accessor */ static inline modm::IOStream& operator << (modm::IOStream& os, modm::accessor::Flash ptr) diff --git a/src/modm/architecture/interface/accessor_ram.hpp b/src/modm/architecture/interface/accessor_ram.hpp index b602f5bb38..897ca61785 100644 --- a/src/modm/architecture/interface/accessor_ram.hpp +++ b/src/modm/architecture/interface/accessor_ram.hpp @@ -26,7 +26,7 @@ namespace accessor /** * Pointer to RAM * - * @ingroup accessor + * @ingroup modm_architecture_accessor * @author Fabian Greif */ template diff --git a/src/modm/architecture/interface/adc.hpp b/src/modm/architecture/interface/adc.hpp index 6a2bc7d46b..2468c8836a 100644 --- a/src/modm/architecture/interface/adc.hpp +++ b/src/modm/architecture/interface/adc.hpp @@ -14,11 +14,6 @@ #include -/** - * @ingroup interface - * @defgroup adc Analog-to-Digital Converter - */ - namespace modm { @@ -51,7 +46,7 @@ namespace modm * @see AdcInterrupt for the asynchronous method. * * @author Niklas Hauser - * @ingroup adc + * @ingroup modm_architecture_adc */ class Adc : public ::modm::PeripheralDriver { diff --git a/src/modm/architecture/interface/adc_interrupt.hpp b/src/modm/architecture/interface/adc_interrupt.hpp index 08d7913abf..69649f6e0a 100644 --- a/src/modm/architecture/interface/adc_interrupt.hpp +++ b/src/modm/architecture/interface/adc_interrupt.hpp @@ -44,7 +44,7 @@ namespace modm * @see Adc for the synchronous method. * * @author Niklas Hauser - * @ingroup adc + * @ingroup modm_architecture_adc */ class AdcInterrupt : public modm::Adc { diff --git a/src/modm/architecture/interface/assert.hpp b/src/modm/architecture/interface/assert.hpp index 0dd4b7c321..4994de82a6 100644 --- a/src/modm/architecture/interface/assert.hpp +++ b/src/modm/architecture/interface/assert.hpp @@ -17,61 +17,12 @@ #include #include -/** - * @ingroup interface - * @defgroup assert Assertions - * - * These functions allow you to assert a condition at runtime and define - * failure handlers in your application that can decide what to do with this - * assertion and provide custom functionality. - * - * Each assertion has the form `modm_assert(condition, module, location, failure)`, - * where the condition is a boolean and rest are strings, so that a simple - * string compare can be used to match for module, location or failure. - * For example, the identifier `"can", "init", "timeout"` describes a timeout - * failure in the CAN initializer function. - * The assert `modm_assert_debug(condition, module, location, failure)` is only - * available on debug builds and is removed from the code for a release build. - * - * The user can define one or multiple assertion handlers in any part of the - * application using the `MODM_ASSERTION_HANDLER(function)` macro. - * All assertion handlers will be executed when an assertion fails anywhere in - * the code and get passed the identifier string. - * - * @note The order of assertion handler execution is undefined and must not be - * relied upon for any functionality! - * @warning Assertion handlers may be executed in interrupt context! - * - * Depending on the information in the failure identifier, the assertion handler - * returns `Abandonment::DontCare` if the failure is not of interest, or - * `Abandonment::Ignore` for recoverable failures, or `Abandonment::Fail` for - * failures that do not allow normal program continuation. - * The program is aborted, if any assertion handler returns `Abandonment::Fail`, - * all assertion handlers return `Abandonment::DontCare` or no assertion - * handlers have been defined in the application. - * Only if one or many assertion handlers return `Abandonment::Ignore` and the - * remainder returns `Abandonment::DontCare`, only then is the assertion ignored. - * - * @note It is intended that the assertion handlers do not block (forever), so - * that all assertion handlers can get called. - * - * On program abandonment `modm_abandon(module, location, failure)` is called, - * which exits the program silently by default. - * Only on hosted an formatted error string is output by default. - * It is therefore recommended to overwrite this function on embedded targets - * for custom behavior like blinking an LED and printing to a serial connection. - * - * @warning The abandonment handler may also be executed in interrupt context! - * - * @see driver - * @author Niklas Hauser - */ namespace modm { /// Describes abandonment type of assertions. -/// @ingroup assert +/// @ingroup modm_architecture_assert enum class Abandonment : uint8_t { @@ -81,7 +32,7 @@ Abandonment : uint8_t }; /// Signature of the assertion handlers -/// @ingroup assert +/// @ingroup modm_architecture_assert using AssertionHandler = Abandonment (*)(const char * module, const char * location, const char * failure, @@ -101,7 +52,7 @@ using AssertionHandler = Abandonment (*)(const char * module, * * @param handler A function of signature `AssertionHandler`. * - * @ingroup assert + * @ingroup modm_architecture_assert */ #define MODM_ASSERTION_HANDLER(handler) @@ -112,7 +63,7 @@ using AssertionHandler = Abandonment (*)(const char * module, * * @note On AVR targets the failure identifier string is placed in Flash memory! * - * @ingroup assert + * @ingroup modm_architecture_assert */ modm_extern_c bool modm_assert(bool condition, const char * module, const char * location, const char * failure); @@ -124,7 +75,7 @@ modm_assert(bool condition, const char * module, const char * location, const ch * * @note On AVR targets the failure identifier string is placed in Flash memory! * - * @ingroup assert + * @ingroup modm_architecture_assert */ modm_extern_c bool modm_assert(bool condition, const char * module, const char * location, const char * failure, uintptr_t context); @@ -136,7 +87,7 @@ modm_assert(bool condition, const char * module, const char * location, const ch * * @note On AVR targets the strings are placed in Flash memory! * - * @ingroup assert + * @ingroup modm_architecture_assert */ modm_extern_c bool modm_assert_debug(bool condition, const char * module, const char * location, const char * failure); @@ -148,7 +99,7 @@ modm_assert_debug(bool condition, const char * module, const char * location, co * * @note On AVR targets the strings are placed in Flash memory! * - * @ingroup assert + * @ingroup modm_architecture_assert */ modm_extern_c bool modm_assert_debug(bool condition, const char * module, const char * location, const char * failure, uintptr_t context); @@ -159,7 +110,7 @@ modm_assert_debug(bool condition, const char * module, const char * location, co * You should overwrite this handler for custom failure behaviour like blinking * LEDs and outputting the failure string via a serial connection. * - * @ingroup assert + * @ingroup modm_architecture_assert */ modm_extern_c void modm_abandon(const char * module, diff --git a/src/modm/architecture/interface/assert.md b/src/modm/architecture/interface/assert.md new file mode 100644 index 0000000000..094020656b --- /dev/null +++ b/src/modm/architecture/interface/assert.md @@ -0,0 +1,49 @@ +# Assertions + +These functions allow you to assert a condition at runtime and define +failure handlers in your application that can decide what to do with this +assertion and provide custom functionality. + +Each assertion has the form `modm_assert(condition, module, location, failure)`, +where the condition is a boolean and rest are strings, so that a simple +string compare can be used to match for module, location or failure. +For example, the identifier `"can", "init", "timeout"` describes a timeout +failure in the CAN initializer function. +The assert `modm_assert_debug(condition, module, location, failure)` is only +available on debug builds and is removed from the code for a release build. + +The user can define one or multiple assertion handlers in any part of the +application using the `MODM_ASSERTION_HANDLER(function)` macro. +All assertion handlers will be executed when an assertion fails anywhere in +the code and get passed the identifier string. + +!!!note + The order of assertion handler execution is undefined and must not been + relied upon for any functionality! + +!!!warning + Assertion handlers may be executed in interrupt context! + +Depending on the information in the failure identifier, the assertion handler +returns `Abandonment::DontCare` if the failure is not of interest, or +`Abandonment::Ignore` for recoverable failures, or `Abandonment::Fail` for +failures that do not allow normal program continuation. +The program is aborted, if any assertion handler returns `Abandonment::Fail`, +all assertion handlers return `Abandonment::DontCare` or no assertion +handlers have been defined in the application. +Only if one or many assertion handlers return `Abandonment::Ignore` and the +remainder returns `Abandonment::DontCare`, only then is the assertion ignored. + +!!!note + It is intended that the assertion handlers do not block (forever), so that + all assertion handlers can get called. + +On program abandonment `modm_abandon(module, location, failure)` is called, +which exits the program silently by default. +Only on hosted an formatted error string is output by default. +It is therefore recommended to overwrite this function on embedded targets +for custom behavior like blinking an LED and printing to a serial connection. + +!!!warning + The abandonment handler may also be executed in interrupt context! + diff --git a/src/modm/architecture/interface/atomic_lock.hpp b/src/modm/architecture/interface/atomic_lock.hpp index c80eb97aac..621f2632f7 100644 --- a/src/modm/architecture/interface/atomic_lock.hpp +++ b/src/modm/architecture/interface/atomic_lock.hpp @@ -15,11 +15,6 @@ #ifndef MODM_INTERFACE_ATOMIC_LOCK_HPP #define MODM_INTERFACE_ATOMIC_LOCK_HPP -/** - * @ingroup interface - * @defgroup atomic Atomic operations and container - */ - #ifdef __DOXYGEN__ namespace modm @@ -49,7 +44,7 @@ namespace atomic * // other code with interrupts enabled * } * @endcode - * @ingroup atomic + * @ingroup modm_architecture_atomic */ class Lock { @@ -66,7 +61,7 @@ class Lock * * Most of the time you won't need this class. But on some rare * times it is useful. The modm::Scheduler is an example for that. - * @ingroup atomic + * @ingroup modm_architecture_atomic */ class Unlock { diff --git a/src/modm/architecture/interface/block_device.hpp b/src/modm/architecture/interface/block_device.hpp index eb818ff84b..8f28d2e505 100644 --- a/src/modm/architecture/interface/block_device.hpp +++ b/src/modm/architecture/interface/block_device.hpp @@ -16,11 +16,6 @@ #include #include -/** - * @ingroup interface - * @defgroup storage Data storage - */ - namespace modm { @@ -30,7 +25,7 @@ namespace modm * Access to storage devices like flash chips * * @author Raphael Lehmann - * @ingroup storage + * @ingroup modm_architecture_block_device */ class BlockDevice { diff --git a/src/modm/architecture/interface/can.hpp b/src/modm/architecture/interface/can.hpp index b69309317c..d715f19004 100644 --- a/src/modm/architecture/interface/can.hpp +++ b/src/modm/architecture/interface/can.hpp @@ -17,24 +17,11 @@ #include #include "can_message.hpp" -/** - * @ingroup interface - * @defgroup can Controller Area Network (CAN) - * @brief Interface to the CAN-Communication BUS. - * - * Controller–area network (CAN or CAN-bus) is a vehicle bus standard designed - * to allow microcontrollers and devices to communicate with each other within - * a vehicle without a host computer. - * - * CAN is a message based protocol, designed specifically for automotive - * applications but now also used in other areas such as industrial automation - * and medical equipment. - */ - namespace modm { -/// @ingroup can +/// Interface to the CAN bus +/// @ingroup modm_architecture_can class Can : public ::modm::PeripheralDriver { public: diff --git a/src/modm/architecture/interface/can.md b/src/modm/architecture/interface/can.md new file mode 100644 index 0000000000..9edc16039a --- /dev/null +++ b/src/modm/architecture/interface/can.md @@ -0,0 +1,9 @@ +# Controller Area Network + +Controller–area network (CAN or CAN-bus) is a vehicle bus standard designed +to allow microcontrollers and devices to communicate with each other within +a vehicle without a host computer. + +CAN is a message based protocol, designed specifically for automotive +applications but now also used in other areas such as industrial automation +and medical equipment. diff --git a/src/modm/architecture/interface/can_message.hpp b/src/modm/architecture/interface/can_message.hpp index d705083084..5c2d98f65b 100644 --- a/src/modm/architecture/interface/can_message.hpp +++ b/src/modm/architecture/interface/can_message.hpp @@ -24,7 +24,7 @@ namespace can { /// Representation of a CAN message -/// @ingroup can +/// @ingroup modm_architecture_can struct Message { Message(const uint32_t& inIdentifier = 0, uint8_t inLength = 0) : diff --git a/src/modm/architecture/interface/clock.hpp b/src/modm/architecture/interface/clock.hpp index 434636d9c5..7ad6b12528 100644 --- a/src/modm/architecture/interface/clock.hpp +++ b/src/modm/architecture/interface/clock.hpp @@ -26,7 +26,6 @@ namespace modm * Interface to the system wide tick timer. * * This class maintains a 32-bit counter which is incremented every 1ms. - * This * * Example: * @code @@ -36,6 +35,7 @@ namespace modm * modm::Clock::increment(); * } * @endcode + * @ingroup modm_architecture_clock */ class Clock { @@ -70,6 +70,7 @@ namespace clock /** * Frequencies enum to make code more readable for common * frequencies (in kHz). + * @ingroup modm_architecture_clock */ enum Frequency { @@ -119,6 +120,8 @@ enum Frequency MHz432 = 432 * MHz1, }; +/// @ingroup modm_architecture_clock +/// @{ static constexpr int MHz(int f) { return (f == HzDontCare)? HzDontCare : (f / MHz1); } @@ -136,6 +139,7 @@ u32kHz(int f) { return static_cast(kHz(f)); } modm_unused static constexpr int Hz(int f) { return (f == HzDontCare)? HzDontCare : (f / Hz1); } +/// @} } // namespace clock diff --git a/src/modm/architecture/interface/delay.hpp b/src/modm/architecture/interface/delay.hpp index 8696630418..b60d9269b9 100644 --- a/src/modm/architecture/interface/delay.hpp +++ b/src/modm/architecture/interface/delay.hpp @@ -14,32 +14,6 @@ #include -/** - * @ingroup interface - * @defgroup delay Blocking delays - * - * These functions allow you to spin for a short time using only the CPU. - * - * You should always prefer Software Timers (@see software_timer) over these - * *blocking* delay functions. However, when `xpcc::Clock` is not set up yet, or - * when you need very small delays (for example to bit-bang a protocol), you need - * to use these delay functions. - * - * The only guarantee given to you is to delay for _at least_ the specified time. - * Note that invocation of interrupts during spinning may add delay too. - * - * @warning - * You must not rely on delay functions for ANY time-keeping! - * - * Delay functions work at any CPU clock speed, even if changed dynamically and - * are available very early in the startup process at hardware-init time. - * - * @warning - * Correct behavior is not guaranteed for delays over 1000ns, us or ms! - * Make sure to use the largest time unit possible. - * - * @author Niklas Hauser - */ #ifdef __DOXYGEN__ @@ -47,19 +21,19 @@ namespace modm { /// Spin for nanoseconds. -/// This function is implemented as best-effort and it's resolution will be very +/// This function is implemented as best-effort and its resolution will be very /// coarse especially on platforms with very slow clocks. -/// @ingroup delay +/// @ingroup modm_architecture_delay void delayNanoseconds(uint16_t ns); /// Spin for microseconds. -/// @ingroup delay +/// @ingroup modm_architecture_delay void delayMicroseconds(uint16_t us); /// Spin for milliseconds. -/// @ingroup delay +/// @ingroup modm_architecture_delay void delayMilliseconds(uint16_t ms); diff --git a/src/modm/architecture/interface/delay.md b/src/modm/architecture/interface/delay.md new file mode 100644 index 0000000000..302ca67ec0 --- /dev/null +++ b/src/modm/architecture/interface/delay.md @@ -0,0 +1,21 @@ +# Blocking Delays + +These functions allow you to spin for a short time using only the CPU. + +You should always prefer Software Timers (see `modm:processing:timer`) over these +*blocking* delay functions. However, when `modm::Clock` is not set up yet, or +when you need very small delays (for example to bit-bang a protocol), you need +to use these delay functions. + +The only guarantee given to you is to delay for _at least_ the specified time. +Note that invocation of interrupts during spinning may add delay too. + +!!!warning + You must not rely on delay functions for ANY time-keeping! + +Delay functions work at any CPU clock speed, even if changed dynamically and +are available very early in the startup process at hardware-init time. + +!!!warning + Correct behavior is not guaranteed for delays over 1000ns, us or ms! + Make sure to use the largest time unit possible. diff --git a/src/modm/architecture/interface/gpio.hpp b/src/modm/architecture/interface/gpio.hpp index b0ba12940e..cf015b6d9c 100644 --- a/src/modm/architecture/interface/gpio.hpp +++ b/src/modm/architecture/interface/gpio.hpp @@ -19,6 +19,7 @@ namespace modm { +/// @ingroup modm_architecture_gpio struct Gpio { /** @@ -46,6 +47,7 @@ struct Gpio * * The pin is not automatically set as an input after startup, * so remember to call `setInput()` after startup! + * @ingroup modm_architecture_gpio */ class GpioInput : public Gpio { @@ -69,6 +71,7 @@ class GpioInput : public Gpio * * The pin is not automatically set as an output after startup, * so remember to call `setOutput()` after startup! + * @ingroup modm_architecture_gpio */ class GpioOutput : public Gpio { @@ -110,6 +113,7 @@ class GpioOutput : public Gpio /** * Input/Output interface of an I/O pin. + * @ingroup modm_architecture_gpio */ class GpioIO : public GpioOutput, public GpioInput { @@ -132,6 +136,7 @@ class GpioIO : public GpioOutput, public GpioInput * mapping of the IOs. * For example, when a high octet `0xf400` is physically configured, the * data will still be written and read as a low octet `0x00f4`. + * @ingroup modm_architecture_gpio */ class GpioPort { diff --git a/src/modm/architecture/interface/gpio.md b/src/modm/architecture/interface/gpio.md index 6116a123e2..cf0440087a 100644 --- a/src/modm/architecture/interface/gpio.md +++ b/src/modm/architecture/interface/gpio.md @@ -3,9 +3,6 @@ GPIOs are modeled as individual classes with an interface consisting out of a common set of static methods. - - - ## Using GPIOs These classes are used to create architecture independent @@ -59,4 +56,3 @@ Led::reset(); Call `Gpio::setInput()` or `Gpio::setOutput()` before the first use, otherwise the GPIO state may be undefined! -## Passing GPIOs to drivers \ No newline at end of file diff --git a/src/modm/architecture/interface/gpio_expander.hpp b/src/modm/architecture/interface/gpio_expander.hpp index 2c5f7ad17d..8d0a36c2b7 100644 --- a/src/modm/architecture/interface/gpio_expander.hpp +++ b/src/modm/architecture/interface/gpio_expander.hpp @@ -42,7 +42,7 @@ namespace modm * @see modm::GpioIO * * @author Niklas Hauser - * @ingroup gpio + * @ingroup modm_architecture_gpio_expander */ class GpioExpander { @@ -190,7 +190,7 @@ class GpioExpander * @tparam expander instance of the expander * @tparam pin pin identifier of desired expander pin * - * @ingroup gpio + * @ingroup modm_architecture_gpio_expander * @author Sascha Schade * @author Niklas Hauser */ @@ -335,7 +335,7 @@ class GpioExpanderPin : public modm::GpioIO * @tparam Width width of the entire port in bits * @tparam DataOrder the bit order mapping of data * - * @ingroup gpio + * @ingroup modm_architecture_gpio_expander * @author Niklas Hauser */ template < diff --git a/src/modm/architecture/interface/i2c.hpp b/src/modm/architecture/interface/i2c.hpp index b722a9768e..d9578e01f0 100644 --- a/src/modm/architecture/interface/i2c.hpp +++ b/src/modm/architecture/interface/i2c.hpp @@ -19,15 +19,10 @@ #include #include -/** - * @ingroup interface - * @defgroup i2c Inter-Integrated Circuit (I2C) - */ - namespace modm { -/// @ingroup i2c +/// @ingroup modm_architecture_i2c struct I2c { static constexpr uint8_t Write = 0x00; ///< Add the Write bit to the slave address diff --git a/src/modm/architecture/interface/i2c_device.hpp b/src/modm/architecture/interface/i2c_device.hpp index 10d5b5ba27..6442b42328 100644 --- a/src/modm/architecture/interface/i2c_device.hpp +++ b/src/modm/architecture/interface/i2c_device.hpp @@ -38,7 +38,7 @@ namespace modm * * @author Georgi Grinshpun * @author Niklas Hauser - * @ingroup i2c + * @ingroup modm_architecture_i2c_device */ template < class I2cMaster, uint8_t NestingLevels = 10, class Transaction = I2cWriteReadTransaction > class I2cDevice : protected modm::NestedResumable< NestingLevels + 1 > diff --git a/src/modm/architecture/interface/i2c_master.hpp b/src/modm/architecture/interface/i2c_master.hpp index f037e049e5..a7847a0aa4 100644 --- a/src/modm/architecture/interface/i2c_master.hpp +++ b/src/modm/architecture/interface/i2c_master.hpp @@ -29,7 +29,7 @@ namespace modm * * @author Georgi Grinshpun * @author Niklas Hauser - * @ingroup i2c + * @ingroup modm_architecture_i2c */ class I2cMaster : public ::modm::PeripheralDriver, public ::modm::I2c { diff --git a/src/modm/architecture/interface/i2c_transaction.hpp b/src/modm/architecture/interface/i2c_transaction.hpp index 161c79aae5..719822f5b0 100644 --- a/src/modm/architecture/interface/i2c_transaction.hpp +++ b/src/modm/architecture/interface/i2c_transaction.hpp @@ -29,7 +29,7 @@ namespace modm * * @author Georgi Grinshpun * @author Niklas Hauser - * @ingroup i2c + * @ingroup modm_architecture_i2c */ class I2cTransaction : public ::modm::I2c { @@ -236,7 +236,7 @@ class I2cTransaction : public ::modm::I2c * * @author Georgi Grinshpun * @author Niklas Hauser - * @ingroup i2c + * @ingroup modm_architecture_i2c */ class I2cWriteReadTransaction : public I2cTransaction { @@ -404,7 +404,7 @@ class I2cWriteReadTransaction : public I2cTransaction * * @author Georgi Grinshpun * @author Niklas Hauser - * @ingroup i2c + * @ingroup modm_architecture_i2c */ class I2cWriteTransaction : public I2cTransaction { @@ -479,7 +479,7 @@ class I2cWriteTransaction : public I2cTransaction * * @author Georgi Grinshpun * @author Niklas Hauser - * @ingroup i2c + * @ingroup modm_architecture_i2c */ class I2cReadTransaction : public I2cTransaction { diff --git a/src/modm/architecture/interface/interrupt.hpp b/src/modm/architecture/interface/interrupt.hpp index 492fe357fa..62dc79367e 100644 --- a/src/modm/architecture/interface/interrupt.hpp +++ b/src/modm/architecture/interface/interrupt.hpp @@ -39,7 +39,7 @@ * @param vector * The name of the interrupt without any suffix (neither `_vect`, nor `_IRQHandler`). * - * @ingroup platform + * @ingroup modm_architecture_interrupt */ #define MODM_ISR_NAME(vector) @@ -52,7 +52,7 @@ * @param vector * The name of the interrupt without any suffix (neither `_vect`, nor `_IRQHandler`). * - * @ingroup platform + * @ingroup modm_architecture_interrupt */ #define MODM_ISR_DECL(vector) @@ -65,7 +65,7 @@ * @param vector * The name of the interrupt without any suffix (neither `_vect`, nor `_IRQHandler`). * - * @ingroup platform + * @ingroup modm_architecture_interrupt */ #define MODM_ISR_CALL(vector) @@ -84,7 +84,7 @@ * @param ... * Multiple compiler attributes can be added to an interrupt. For example `modm_fastcode`. * - * @ingroup platform + * @ingroup modm_architecture_interrupt */ #define MODM_ISR(vector, ...) diff --git a/src/modm/architecture/interface/memory.hpp b/src/modm/architecture/interface/memory.hpp index a1bbf4ee0e..2f5c63bc75 100644 --- a/src/modm/architecture/interface/memory.hpp +++ b/src/modm/architecture/interface/memory.hpp @@ -17,21 +17,12 @@ #include #include -/** - * @ingroup interface - * @defgroup memory_traits Memory traits - * - * Traits of dynamic memory. - * - * @see driver - * @author Niklas Hauser - */ namespace modm { /// Describes access and type of dynamic memory. -/// @ingroup memory_traits +/// @ingroup modm_architecture_memory enum class MemoryTrait : uint16_t { @@ -50,39 +41,39 @@ MemoryTrait : uint16_t }; /// A memory can have multiple traits. -/// @ingroup memory_traits +/// @ingroup modm_architecture_memory using MemoryTraits = Flags16; MODM_TYPE_FLAGS(MemoryTraits); /// Fast code memory is accessible by at least the I-Bus and it is core-coupled. /// Fallback memory on exhaustion is not core-coupled. -/// @ingroup memory_traits +/// @ingroup modm_architecture_memory constexpr MemoryTraits MemoryFastCode = (MemoryTrait::AccessIBus | MemoryTrait::TypeCoreCoupled); /// Fast data memory is accessible by at least the D-Bus and it is core coupled. /// Fallback memory on exhaustion is not core-coupled. -/// @ingroup memory_traits +/// @ingroup modm_architecture_memory constexpr MemoryTraits MemoryFastData = (MemoryTrait::AccessDBus | MemoryTrait::TypeCoreCoupled); /// DMA-able memory is accessible by at least the S-Bus and DMA. /// There is no fallback memory on exhaustion. -/// @ingroup memory_traits +/// @ingroup modm_architecture_memory constexpr MemoryTraits MemoryDMA = (MemoryTrait::AccessSBus | MemoryTrait::AccessDMA); /// DMA-able memory is accessible by at least the S-Bus and 2D DMA. /// There is no fallback memory on exhaustion. -/// @ingroup memory_traits +/// @ingroup modm_architecture_memory constexpr MemoryTraits MemoryDMA2D = (MemoryTrait::AccessSBus | MemoryTrait::AccessDMA2D); /// External memory is accessible by at least the S-Bus and it is external. /// Fallback memory on exhaustion is internal. -/// @ingroup memory_traits +/// @ingroup modm_architecture_memory constexpr MemoryTraits MemoryExternal = (MemoryTrait::AccessSBus | MemoryTrait::TypeExternal); /// Backup memory is accessible by at least the S-Bus and it is non-volatile. /// There is no fallback memory on exhaustion. -/// @ingroup memory_traits +/// @ingroup modm_architecture_memory constexpr MemoryTraits MemoryBackup = (MemoryTrait::AccessSBus | MemoryTrait::TypeNonVolatile); /// Default memory is DMA-able. -/// @ingroup memory_traits +/// @ingroup modm_architecture_memory constexpr MemoryTraits MemoryDefault = MemoryDMA; } // namespace modm @@ -93,7 +84,7 @@ constexpr MemoryTraits MemoryDefault = MemoryDMA; * @endcode * * @note Memory traits are ignored on AVRs. - * @ingroup memory_traits + * @ingroup modm_architecture_memory */ void * operator new(size_t size, modm::MemoryTraits traits) noexcept; @@ -104,7 +95,7 @@ operator new(size_t size, modm::MemoryTraits traits) noexcept; * @endcode * * @note Memory traits are ignored on AVRs. - * @ingroup memory_traits + * @ingroup modm_architecture_memory */ void * operator new[](size_t size, modm::MemoryTraits traits) noexcept; diff --git a/src/modm/architecture/interface/one_wire.hpp b/src/modm/architecture/interface/one_wire.hpp index d1aa80b6b3..0f35269c31 100644 --- a/src/modm/architecture/interface/one_wire.hpp +++ b/src/modm/architecture/interface/one_wire.hpp @@ -11,23 +11,6 @@ */ // ---------------------------------------------------------------------------- -/** - * @ingroup interface - * @defgroup 1-wire 1-Wire - * - * 1-Wire is a device communications bus system designed by - * Dallas Semiconductor Corp. that provides low-speed data, signaling and - * power over a single signal.[1] 1-Wire is similar in concept to I²C, but - * with lower data rates and longer range. It is typically used to communicate - * with small inexpensive devices such as digital thermometers and - * weather instruments. - * - * One distinctive feature of the bus is the possibility to use only two - * wires: data and ground. To accomplish this, 1-wire devices include an - * 800 pF capacitor to store charge, and power the device during periods where - * the data line is used for data. - */ - #ifndef MODM_ONE_WIRE_HPP #define MODM_ONE_WIRE_HPP @@ -37,7 +20,6 @@ namespace modm { -/// @ingroup 1-wire namespace one_wire { @@ -55,7 +37,7 @@ namespace one_wire * * There are five ROM commands, and each command is 8 bits long. * - * @ingroup 1-wire + * @ingroup modm_architecture_1_wire */ enum RomCommand { diff --git a/src/modm/architecture/interface/one_wire.md b/src/modm/architecture/interface/one_wire.md new file mode 100644 index 0000000000..d1bed797a6 --- /dev/null +++ b/src/modm/architecture/interface/one_wire.md @@ -0,0 +1,13 @@ +# 1-Wire + +1-Wire is a device communications bus system designed by +Dallas Semiconductor Corp. that provides low-speed data, signaling and +power over a single signal. 1-Wire is similar in concept to I²C, but +with lower data rates and longer range. It is typically used to communicate +with small inexpensive devices such as digital thermometers and +weather instruments. + +One distinctive feature of the bus is the possibility to use only two +wires: data and ground. To accomplish this, 1-wire devices include an +800 pF capacitor to store charge, and power the device during periods where +the data line is used for data. diff --git a/src/modm/architecture/interface/peripheral.hpp b/src/modm/architecture/interface/peripheral.hpp index d3869a3204..a2656763bc 100644 --- a/src/modm/architecture/interface/peripheral.hpp +++ b/src/modm/architecture/interface/peripheral.hpp @@ -39,13 +39,12 @@ namespace modm * There is no need to document the platform specific implementation, since * it is taken from the base class. * - * @ingroup peripheral + * @ingroup modm_architecture * @author Niklas Hauser */ class PeripheralDriver { #ifdef __DOXYGEN__ - /// @cond /// initializes the peripheral, must be called before use. static void initialize(); @@ -74,7 +73,6 @@ class PeripheralDriver */ static void acknowledgeInterruptFlag(); - /// @endcond #endif public: diff --git a/src/modm/architecture/interface/register.hpp b/src/modm/architecture/interface/register.hpp index 138c8e8c23..b56c26c3ec 100644 --- a/src/modm/architecture/interface/register.hpp +++ b/src/modm/architecture/interface/register.hpp @@ -19,174 +19,6 @@ #include #include -/** - * @ingroup interface - * @defgroup register General Purpose Register classes - * - * Data structures to provide a native register abstraction. - * - * These data structures are used to describe the relationship of single bits, - * bit groups and bit configurations in registers with type-safe access. - * - * Registers can be made up of three things: - * - * - Bits: a single bit (position N), - * - Configurations: a combination of bits where the meaning does not correspond to its numeric value (position [N, M]) - * - Values: a numeric value (position [N, M]) - * - * Example of an 8-bit register: Control - * -@verbatim - 7 6 5 4 3 2 1 0 -| EN | FS | PRE1 | PRE0 | DEL2 | DEL1 | DEL0 | | -@endverbatim - * - * - Bit 7: Enable - * - Bit 6: Full Scale - * - Configuration [5, 4]: Prescaler - * - 00: Divide by 1 - * - 01: Divide by 2 - * - 10: Divide by 4 - * - 11: Divide by 8 - * - Value [3, 1]: Start-Up Delay in ms - * - * #### Register Bits - * - * The bits can be modelled using Sascha Schade enums and the Flags template class as follows: - * @code - * enum class - * Control : uint8_t - * { - * EN = Bit7, ///< bit documentation - * FS = Bit6, - * - * PRE1 = Bit5, - * PRE0 = Bit4, - * - * DEL2 = Bit3, - * DEL1 = Bit2, - * DEL0 = Bit1, - * }; - * MODM_FLAGS8(Control); - * // expands to - * // typedef modm::Flags8< Control > Control_t; - * // and some enum operator overloading magic - * @endcode - * - * You can handle all its register bits as you would expect: - * @code - * Control_t control = Control::EN; - * control = Control::EN | Control::FS; - * control &= ~Control::FS; - * control |= Control::FS; - * control ^= Control::PRE1; - * bool isSet = control & Control::FS; - * - * control.reset(Control::PRE1 | Control::PRE0); - * control.set(Control::DEL0); - * - * bool noneSet = control.none(Control::PRE1 | Control::PRE0); - * bool allSet = control.all(Control::EN | Control::FS); - * @endcode - * - * You still get raw access if you really need it: - * @code - * uint8_t raw = control.value; // the underlying type - * control.value = 0x24; - * @endcode - * - * The access is type-safe, you cannot use bits from two different registers: - * @code - * enum class Control2 : uint8_t - * { - * DIS = Bit4, - * HS = Bit3, - * }; - * MODM_FLAGS8(Control2); - * - * auto control = Control::EN | Control2::HS; // compile error - * @endcode - * - * You can even overload functions on argument type now: - * @code - * void write(Control_t control); - * void write(Control2_t control); - * - * write(Control::EN | Control::FS); // calls #1 - * write(Control2::DIS); // calls #2 - * @endcode - * - * - * #### Register Configurations - * - * Configurations are also described as a strongly-typed enum and then wrapped into the Configuration template class. - * @code - * enum class - * Prescaler : uint8_t - * { - * Div1 = 0, ///< configuration documentation - * Div2 = int(Control::PRE0), - * Div4 = int(Control::PRE1), - * Div8 = int(Control::PRE1) | int(Control::PRE0), - * }; - * typedef Configuration< Control_t, Prescaler, (Bit5 | Bit4) > Prescaler_t; - * @endcode - * - * The `Prescaler` enum values are already shifted in this example (hence the `(Bit5 | Bit4)` mask), however you can also declare the prescaler values non-shifted and let the wrapper shift it: - * @code - * enum class Prescaler : uint8_t - * { - * Div1 = 0, - * Div2 = 1, - * Div4 = 2, - * Div8 = 3, - * }; - * typedef Configuration Prescaler_t; - * @endcode - * - * Why? If you have two or more configurations with the same selections in the same register, you can simply add another one: - * @code - * typedef Configuration< Control_t, Prescaler, 0b11, 6 > Prescaler2_t; - * @endcode - * - * Configurations can be used inline: - * @code - * Control_t control = Control::EN | Prescaler_t(Prescaler::Div2); - * Control_t control &= ~Prescaler_t::mask(); - * @endcode - * - * But do not have to: - * @code - * Prescaler_t::set(control, Prescaler::Div2); - * Prescaler_t::reset(control); - * Prescaler prescaler = Prescaler_t::get(control); - * @endcode - * - * - * #### Register Values - * - * Values are described using the Value template class which masks and shifts the value as required. - * In our example the value has a width of 3 bits and needs to be shifted 1 bit: - * @code - * typedef Value< Control_t, 3, 1 > Delay_t; - * @endcode - * - * This can be used the same way as the Configuration: - * @code - * Control_t control = Control::EN | Prescaler_t(Prescaler::Div2) | Delay_t(4); - * Control_t control &= ~Delay_t::mask(); - * - * Delay_t::set(control, 7); - * Delay_t::reset(control); - * uint8_t delay = Delay_t::get(control); - * @endcode - * - * @see [Typesafe Register Access in C++](http://blog.modm.io/2015/02/25/typesafe-register-access-in-c++) - * for a more detailed background on this implementation. - * - * @author Niklas Hauser - */ - namespace modm { @@ -219,7 +51,7 @@ namespace modm * @tparam T the (unsigned) underlying integer type: uint8_t, uint16_t, uint32_t * @see Register8, Register16, Register32 * - * @ingroup register + * @ingroup modm_architecture_register * @author Niklas Hauser */ template< typename T > @@ -261,7 +93,7 @@ struct Register : value(value) {} }; -/// @ingroup register +/// @ingroup modm_architecture_register /// @{ using Register8 = Register; ///< Register class with 8-bit wide underlying type using Register16 = Register; ///< Register class with 16-bit wide underlying type @@ -282,7 +114,7 @@ using Register32 = Register; ///< Register class with 32-bit wide unde * * @see Flags * - * @ingroup register + * @ingroup modm_architecture_register * @author Niklas Hauser */ template < typename Enum, typename T > @@ -447,7 +279,7 @@ struct FlagsOperators : public ::modm::Register * @see Flags8, Flags16, Flags32 * @see MODM_FLAGS8, MODM_FLAGS16, MODM_FLAGS32 * - * @ingroup register + * @ingroup modm_architecture_register * @author Niklas Hauser */ template < typename Enum, typename T > @@ -555,7 +387,7 @@ struct Flags : public ::modm::FlagsOperators /// @} } modm_packed; -/// @ingroup register +/// @ingroup modm_architecture_register /// @{ template < typename Enum = uint8_t > using Flags8 = Flags; ///< Flags class with 8-bit wide underlying type @@ -618,7 +450,7 @@ struct FlagsGroup : public FlagsGroup * * @tparam T... the Flags classes to be grouped. Must all have the same underlying types. * - * @ingroup register + * @ingroup modm_architecture_register * @author Niklas Hauser */ #ifdef __DOXYGEN__ @@ -721,7 +553,7 @@ struct FlagsGroup : public Register * @tparam Mask the (unshifted) bit mask corresponding to the enum values * @tparam Position how many bits the configuration values need to be shifted * - * @ingroup register + * @ingroup modm_architecture_register * @author Niklas Hauser */ template < typename Parent, typename Enum, typename Parent::UnderlyingType Mask, typename Parent::UnderlyingType Position = 0 > @@ -788,7 +620,7 @@ struct Configuration : public ::modm::FlagsOperators @@ -860,7 +692,7 @@ constexpr ::modm::Flags operator^(Enum const &a, Enum const &b) { return : * * @param Enum a strongly-typed enum containing the bit masks * - * @ingroup register + * @ingroup modm_architecture_register * @hideinitializer */ #define MODM_FLAGS8(Enum) \ @@ -878,7 +710,7 @@ constexpr ::modm::Flags operator^(Enum const &a, Enum const &b) { return : * * @param Enum a strongly-typed enum containing the bit masks * - * @ingroup register + * @ingroup modm_architecture_register * @hideinitializer */ #define MODM_FLAGS16(Enum) \ @@ -896,7 +728,7 @@ constexpr ::modm::Flags operator^(Enum const &a, Enum const &b) { return : * * @param Enum a strongly-typed enum containing the bit masks * - * @ingroup register + * @ingroup modm_architecture_register * @hideinitializer */ #define MODM_FLAGS32(Enum) \ @@ -912,7 +744,7 @@ constexpr ::modm::Flags operator^(Enum const &a, Enum const &b) { return : * * @param Parent a Flags class * - * @ingroup register + * @ingroup modm_architecture_register * @hideinitializer */ #define MODM_TYPE_FLAGS(Parent) \ diff --git a/src/modm/architecture/interface/register.md b/src/modm/architecture/interface/register.md new file mode 100644 index 0000000000..48964d91c3 --- /dev/null +++ b/src/modm/architecture/interface/register.md @@ -0,0 +1,174 @@ +# General Purpose Registers + +Data structures to provide a native register abstraction. + +These data structures are used to describe the relationship of single bits, +bit groups and bit configurations in registers with type-safe access. + +Registers can be made up of three things: + +- Bits: a single bit (position N), +- Configurations: a combination of bits where the meaning does not correspond to its numeric value (position [N, M]) +- Values: a numeric value (position [N, M]) + +Example of an 8-bit register called Control + +``` + 7 6 5 4 3 2 1 0 +| EN | FS | PRE1 | PRE0 | DEL2 | DEL1 | DEL0 | | +``` + +- Bit 7: Enable +- Bit 6: Full Scale +- Configuration [5, 4]: Prescaler + - 00: Divide by 1 + - 01: Divide by 2 + - 10: Divide by 4 + - 11: Divide by 8 +- Value [3, 1]: Start-Up Delay in ms + +## Register Bits + +The bits can be modelled using strongly-typed enums and the Flags template class as follows: + +```cpp +enum class +Control : uint8_t +{ + EN = Bit7, ///< bit documentation + FS = Bit6, + + PRE1 = Bit5, + PRE0 = Bit4, + + DEL2 = Bit3, + DEL1 = Bit2, + DEL0 = Bit1, +}; +MODM_FLAGS8(Control); +// expands to +// typedef modm::Flags8< Control > Control_t; +// and some enum operator overloading magic +``` + +You can handle all its register bits as you would expect: + +```cpp +Control_t control = Control::EN; +control = Control::EN | Control::FS; +control &= ~Control::FS; +control |= Control::FS; +control ^= Control::PRE1; +bool isSet = control & Control::FS; + +control.reset(Control::PRE1 | Control::PRE0); +control.set(Control::DEL0); + +bool noneSet = control.none(Control::PRE1 | Control::PRE0); +bool allSet = control.all(Control::EN | Control::FS); +``` + +You still get raw access if you really need it: + +```cpp +uint8_t raw = control.value; // the underlying type +control.value = 0x24; +``` + +The access is type-safe, you cannot use bits from two different registers: + +```cpp +enum class Control2 : uint8_t +{ + DIS = Bit4, + HS = Bit3, +}; +MODM_FLAGS8(Control2); + +auto control = Control::EN | Control2::HS; // compile error +``` + +You can even overload functions on argument type now: + +```cpp +void write(Control_t control); +void write(Control2_t control); + +write(Control::EN | Control::FS); // calls #1 +write(Control2::DIS); // calls #2 +``` + + +## Register Configurations + +Configurations are also described as a strongly-typed enum and then wrapped into the Configuration template class. + +```cpp +enum class +Prescaler : uint8_t +{ + Div1 = 0, ///< configuration documentation + Div2 = int(Control::PRE0), + Div4 = int(Control::PRE1), + Div8 = int(Control::PRE1) | int(Control::PRE0), +}; +typedef Configuration< Control_t, Prescaler, (Bit5 | Bit4) > Prescaler_t; +``` + +The `Prescaler` enum values are already shifted in this example (hence the `(Bit5 | Bit4)` mask), however you can also declare the prescaler values non-shifted and let the wrapper shift it: + +```cpp +enum class Prescaler : uint8_t +{ + Div1 = 0, + Div2 = 1, + Div4 = 2, + Div8 = 3, +}; +typedef Configuration Prescaler_t; +``` + +Why? If you have two or more configurations with the same selections in the same register, you can simply add another one: + +```cpp +typedef Configuration< Control_t, Prescaler, 0b11, 6 > Prescaler2_t; +``` + +Configurations can be used inline: + +```cpp +Control_t control = Control::EN | Prescaler_t(Prescaler::Div2); +Control_t control &= ~Prescaler_t::mask(); +``` + +But do not have to: + +```cpp +Prescaler_t::set(control, Prescaler::Div2); +Prescaler_t::reset(control); +Prescaler prescaler = Prescaler_t::get(control); +``` + + +## Register Values + +Values are described using the Value template class which masks and shifts the value as required. +In our example the value has a width of 3 bits and needs to be shifted 1 bit: + +```cpp +typedef Value< Control_t, 3, 1 > Delay_t; +``` + +This can be used the same way as the Configuration: + +```cpp +Control_t control = Control::EN | Prescaler_t(Prescaler::Div2) | Delay_t(4); +Control_t control &= ~Delay_t::mask(); + +Delay_t::set(control, 7); +Delay_t::reset(control); +uint8_t delay = Delay_t::get(control); +``` + +See [Typesafe Register Access in C++](http://blog.modm.io/2015/02/25/typesafe-register-access-in-c++) +for a more detailed background on this implementation. diff --git a/src/modm/architecture/interface/spi.hpp b/src/modm/architecture/interface/spi.hpp index 7976238397..9a0038ee66 100644 --- a/src/modm/architecture/interface/spi.hpp +++ b/src/modm/architecture/interface/spi.hpp @@ -17,15 +17,10 @@ #include -/** - * @ingroup interface - * @defgroup spi Serial Peripheral Interface (SPI) - */ - namespace modm { -/// @ingroup spi +/// @ingroup modm_architecture_spi struct Spi { /// The signature of the configuration function. diff --git a/src/modm/architecture/interface/spi_device.hpp b/src/modm/architecture/interface/spi_device.hpp index 15d1a00e81..89ac49b7b4 100644 --- a/src/modm/architecture/interface/spi_device.hpp +++ b/src/modm/architecture/interface/spi_device.hpp @@ -25,7 +25,7 @@ namespace modm * * @author Georgi Grinshpun * @author Niklas Hauser - * @ingroup spi + * @ingroup modm_architecture_spi_device */ template < class SpiMaster > class SpiDevice diff --git a/src/modm/architecture/interface/spi_master.hpp b/src/modm/architecture/interface/spi_master.hpp index 612fced95e..74a4c74e86 100644 --- a/src/modm/architecture/interface/spi_master.hpp +++ b/src/modm/architecture/interface/spi_master.hpp @@ -26,7 +26,7 @@ namespace modm * synchronize multiple drivers requesting hardware access. * * @author Niklas Hauser - * @ingroup spi + * @ingroup modm_architecture_spi */ class SpiMaster : public ::modm::PeripheralDriver, public Spi { diff --git a/src/modm/architecture/interface/uart.hpp b/src/modm/architecture/interface/uart.hpp index 86f19de11e..990a9c27cc 100644 --- a/src/modm/architecture/interface/uart.hpp +++ b/src/modm/architecture/interface/uart.hpp @@ -17,11 +17,6 @@ #include -/** - * @ingroup interface - * @defgroup uart Universal Asynchronous Receiver/Transmitter (UART) - */ - namespace modm { @@ -31,7 +26,7 @@ namespace modm * Asynchronous and synchronous, buffered access to the Uart. * * @author Niklas Hauser - * @ingroup uart + * @ingroup modm_architecture_uart */ class Uart : public ::modm::PeripheralDriver { diff --git a/src/modm/architecture/interface/unaligned.hpp b/src/modm/architecture/interface/unaligned.hpp index c97f1cfcdc..c8b192f87b 100644 --- a/src/modm/architecture/interface/unaligned.hpp +++ b/src/modm/architecture/interface/unaligned.hpp @@ -38,7 +38,7 @@ namespace modm * output = *u32; * @endcode * - * @ingroup interface + * @ingroup modm_architecture_unaligned * @author Niklas Hauser */ template< typename T > @@ -62,7 +62,7 @@ unaligned_t /** * Accesses a memory location using a unaligned-safe method. * - * @ingroup interface + * @ingroup modm_architecture_unaligned */ template< typename T, typename U> modm_always_inline unaligned_t* diff --git a/src/modm/architecture/module.lb b/src/modm/architecture/module.lb index a0b76c35ee..a9faafe426 100644 --- a/src/modm/architecture/module.lb +++ b/src/modm/architecture/module.lb @@ -14,6 +14,7 @@ class Accessor(Module): def init(self, module): module.name = "accessor" + module.description = "Memory Accessors" def prepare(self, module, options): module.depends(":io") @@ -30,6 +31,7 @@ class Accessor(Module): class Adc(Module): def init(self, module): module.name = "adc" + module.description = "Analog-to-Digital Converters" def prepare(self, module, options): return True @@ -43,6 +45,7 @@ class Adc(Module): class Assert(Module): def init(self, module): module.name = "assert" + module.description = FileReader("interface/assert.md") def prepare(self, module, options): module.depends(":utils", ":architecture:accessor") @@ -57,6 +60,7 @@ class Assert(Module): class Atomic(Module): def init(self, module): module.name = "atomic" + module.description = "Atomic Operations and Containers" def prepare(self, module, options): module.depends(":utils", ":architecture:accessor") @@ -73,6 +77,7 @@ class Atomic(Module): class BlockDevice(Module): def init(self, module): module.name = "block.device" + module.description = "Block Devices" def prepare(self, module, options): module.depends(":processing:resumable") @@ -86,6 +91,7 @@ class BlockDevice(Module): class Can(Module): def init(self, module): module.name = "can" + module.description = FileReader("interface/can.md") def prepare(self, module, options): module.depends(":io") @@ -102,6 +108,7 @@ class Can(Module): class Clock(Module): def init(self, module): module.name = "clock" + module.description = "System Tick" def prepare(self, module, options): module.depends(":processing:timer") @@ -115,6 +122,7 @@ class Clock(Module): class Delay(Module): def init(self, module): module.name = "delay" + module.description = FileReader("interface/delay.md") def prepare(self, module, options): # module.depends(":platform:core") @@ -141,6 +149,7 @@ class Gpio(Module): class GpioExpander(Module): def init(self, module): module.name = "gpio.expander" + module.description = "GPIO Expanders" def prepare(self, module, options): module.depends(":architecture:gpio", ":architecture:register", ":processing:resumable", ":math:utils") @@ -154,6 +163,7 @@ class GpioExpander(Module): class Heap(Module): def init(self, module): module.name = "heap" + module.description = "Memory Allocators" def prepare(self, module, options): module.depends(":utils") @@ -168,6 +178,7 @@ class Heap(Module): class I2c(Module): def init(self, module): module.name = "i2c" + module.description = "Inter-Integrated Circuit (I²C)" def prepare(self, module, options): module.depends(":architecture:gpio", ":architecture:delay", ":io") @@ -184,6 +195,7 @@ class I2c(Module): class I2cDevice(Module): def init(self, module): module.name = "i2c.device" + module.description = "I²C Devices" def prepare(self, module, options): module.depends(":architecture:i2c", ":processing:resumable") @@ -197,6 +209,7 @@ class I2cDevice(Module): class Interrupt(Module): def init(self, module): module.name = "interrupt" + module.description = "Interrupt Service Routines" def prepare(self, module, options): return True @@ -209,6 +222,7 @@ class Interrupt(Module): class Memory(Module): def init(self, module): module.name = "memory" + module.description = "Memory Traits" def prepare(self, module, options): module.depends(":architecture:register") @@ -222,6 +236,7 @@ class Memory(Module): class OneWire(Module): def init(self, module): module.name = "1-wire" + module.description = FileReader("interface/one_wire.md") def prepare(self, module, options): return True @@ -234,6 +249,7 @@ class OneWire(Module): class Register(Module): def init(self, module): module.name = "register" + module.description = FileReader("interface/register.md") def prepare(self, module, options): module.depends(":io", ":math:utils") @@ -247,6 +263,7 @@ class Register(Module): class Spi(Module): def init(self, module): module.name = "spi" + module.description = "Serial Peripheral Interface (SPI)" def prepare(self, module, options): module.depends(":processing:resumable") @@ -261,6 +278,7 @@ class Spi(Module): class SpiDevice(Module): def init(self, module): module.name = "spi.device" + module.description = "SPI Devices" def prepare(self, module, options): module.depends(":architecture:spi") @@ -274,6 +292,7 @@ class SpiDevice(Module): class Uart(Module): def init(self, module): module.name = "uart" + module.description = "Universal Asynchronous Receiver/Transmitter (UART)" def prepare(self, module, options): return True @@ -286,6 +305,7 @@ class Uart(Module): class Unaligned(Module): def init(self, module): module.name = "unaligned" + module.description = "Unaligned Memory Accessor" def prepare(self, module, options): # module.depends(":platform:core") @@ -300,6 +320,11 @@ import re def init(module): module.name = "architecture" + module.description = """\ +# Architecture Interfaces + +All hardware peripherals with common interfaces. +""" def prepare(module, options): module.depends(":math") # for tolerance.hpp diff --git a/src/modm/architecture/utils.hpp b/src/modm/architecture/utils.hpp index 9039d51b20..b71725d428 100644 --- a/src/modm/architecture/utils.hpp +++ b/src/modm/architecture/utils.hpp @@ -21,7 +21,7 @@ #include "detect.hpp" #ifdef __DOXYGEN__ - /// @ingroup platform + /// @ingroup modm_architecture /// @{ /// Convert the argument into a C-String @@ -33,15 +33,16 @@ /// Concatenate three arguments #define MODM_CONCAT3(a,b,c) a ## b ## c - /// Concatenate three arguments + /// Concatenate four arguments #define MODM_CONCAT4(a,b,c,d) a ## b ## c ## d - /// Concatenate three arguments + /// Concatenate five arguments #define MODM_CONCAT5(a,b,c,d,e) a ## b ## c ## d ## e /// Compute the size of a static (!) array. #define MODM_ARRAY_SIZE(x) (sizeof(x) / sizeof(x[0])) + /// @{ /** * Force inlining on functions if needed. Compiling with -Os does not * always inline them when declared only `inline` @@ -77,7 +78,7 @@ #define modm_unlikely(x) (x) /// @} - + /// @} #else // !__DOXYGEN__ #define MODM_STRINGIFY(s) MODM_STRINGIFYx(s) diff --git a/src/modm/board/al_avreb_can/board.hpp b/src/modm/board/al_avreb_can/board.hpp index 02b7fbfd27..f70b962f1e 100644 --- a/src/modm/board/al_avreb_can/board.hpp +++ b/src/modm/board/al_avreb_can/board.hpp @@ -22,12 +22,12 @@ using namespace modm::platform; +/// @ingroup modm_board_al_avreb_can namespace Board { using systemClock = modm::platform::SystemClock; -// Arduino Footprint using Led0 = GpioInverted; using Led1 = GpioInverted; using Led2 = GpioInverted; diff --git a/src/modm/board/al_avreb_can/module.lb b/src/modm/board/al_avreb_can/module.lb index 8875c9eccb..f7424cbdcd 100644 --- a/src/modm/board/al_avreb_can/module.lb +++ b/src/modm/board/al_avreb_can/module.lb @@ -13,6 +13,12 @@ def init(module): module.parent = "board" module.name = "al-avreb-can" + module.description = """\ +# AL-AVREB_CAN Board + +AVR breakout board with AT90CAN128: +https://www.alvidi.de/products/DE/AVR_Entwicklungsboards/avr_modul_avreb_can.phpAl-avreb-can +""" def prepare(module, options): if options[":target"].partname != "at90can128": diff --git a/src/modm/board/arduino_uno/board.hpp b/src/modm/board/arduino_uno/board.hpp index 09d9bb53a8..1d9026a1eb 100644 --- a/src/modm/board/arduino_uno/board.hpp +++ b/src/modm/board/arduino_uno/board.hpp @@ -10,19 +10,17 @@ */ // ---------------------------------------------------------------------------- -// -// Arduino UNO -// - #ifndef MODM_ARDUINO_UNO_HPP #define MODM_ARDUINO_UNO_HPP #include #include +/// @ingroup modm_board_arduino_uno #define MODM_BOARD_HAS_LOGGER using namespace modm::platform; +/// @ingroup modm_board_arduino_uno namespace Board { diff --git a/src/modm/board/arduino_uno/module.lb b/src/modm/board/arduino_uno/module.lb index c8438179c5..6854be76b4 100644 --- a/src/modm/board/arduino_uno/module.lb +++ b/src/modm/board/arduino_uno/module.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "board" module.name = "arduino-uno" + module.description = "Arduino UNO" def prepare(module, options): if options[":target"].partname != "atmega328p": diff --git a/src/modm/board/black_pill/board.hpp b/src/modm/board/black_pill/board.hpp index 2dde2b515c..fa3ea8e00d 100644 --- a/src/modm/board/black_pill/board.hpp +++ b/src/modm/board/black_pill/board.hpp @@ -10,15 +10,6 @@ */ // ---------------------------------------------------------------------------- -// -// STM32F103C8T6 "Black Pill" Minimum System Development Board -// -// Cheap and bread-board-friendly board for STM32 F1 series. -// Sold for less than 2 USD on well known Internet shops from China. -// -// http://wiki.stm32duino.com/index.php?title=Black_Pill -// - #ifndef MODM_STM32_F103C8T6_BLACK_PILL_HPP #define MODM_STM32_F103C8T6_BLACK_PILL_HPP @@ -27,7 +18,7 @@ using namespace modm::platform; - +/// @ingroup modm_board_black_pill namespace Board { diff --git a/src/modm/board/black_pill/module.lb b/src/modm/board/black_pill/module.lb index afa638a91b..f2b18f7cba 100644 --- a/src/modm/board/black_pill/module.lb +++ b/src/modm/board/black_pill/module.lb @@ -14,6 +14,16 @@ def init(module): module.parent = "board" module.name = "black-pill" + module.description = """\ +# Black Pill + +STM32F103C8T6 "Black Pill" Minimum System Development Board + +Cheap and bread-board-friendly board for STM32 F1 series. +Sold for less than 2 USD on well known Internet shops from China. + +http://wiki.stm32duino.com/index.php?title=Black_Pill +""" def prepare(module, options): if options[":target"].partname != "stm32f103c8t": diff --git a/src/modm/board/blue_pill/board.hpp b/src/modm/board/blue_pill/board.hpp index 2796daa787..77dd4e71f5 100644 --- a/src/modm/board/blue_pill/board.hpp +++ b/src/modm/board/blue_pill/board.hpp @@ -10,15 +10,6 @@ */ // ---------------------------------------------------------------------------- -// -// STM32F103C8T6 "Blue Pill" Minimum System Development Board -// -// Cheap and bread-board-friendly board for STM32 F1 series. -// Sold for less than 2 USD on well known Internet shops from China. -// -// http://wiki.stm32duino.com/index.php?title=Blue_Pill -// - #ifndef MODM_STM32_F103C8T6_BLUE_PILL_HPP #define MODM_STM32_F103C8T6_BLUE_PILL_HPP @@ -28,6 +19,7 @@ using namespace modm::platform; +/// @ingroup modm_board_blue_pill namespace Board { diff --git a/src/modm/board/blue_pill/module.lb b/src/modm/board/blue_pill/module.lb index adba2b9f73..f0ab509465 100644 --- a/src/modm/board/blue_pill/module.lb +++ b/src/modm/board/blue_pill/module.lb @@ -14,6 +14,16 @@ def init(module): module.parent = "board" module.name = "blue-pill" + module.description = """\ +# Blue Pill + +STM32F103C8T6 "Blue Pill" Minimum System Development Board + +Cheap and bread-board-friendly board for STM32 F1 series. +Sold for less than 2 USD on well known Internet shops from China. + +http://wiki.stm32duino.com/index.php?title=Blue_Pill +""" def prepare(module, options): if options[":target"].partname != "stm32f103c8t": diff --git a/src/modm/board/disco_f051r8/board.hpp b/src/modm/board/disco_f051r8/board.hpp index faf18fe2a6..c520155432 100644 --- a/src/modm/board/disco_f051r8/board.hpp +++ b/src/modm/board/disco_f051r8/board.hpp @@ -11,12 +11,6 @@ */ // ---------------------------------------------------------------------------- -// -// STM32F0DISCOVERY -// Discovery kit for STM32F0 series -// http://www.st.com/en/evaluation-tools/stm32f0discovery.html -// - #ifndef MODM_STM32_F0_DISCOVERY_HPP #define MODM_STM32_F0_DISCOVERY_HPP @@ -25,12 +19,11 @@ using namespace modm::platform; - +/// @ingroup modm_board_disco_f051r8 namespace Board { /// STM32F0 running at 48MHz generated from the internal 8MHz with PLL. - struct systemClock { static constexpr int Frequency = MHz48; diff --git a/src/modm/board/disco_f051r8/module.lb b/src/modm/board/disco_f051r8/module.lb index b783827b4d..9ae26b38ed 100644 --- a/src/modm/board/disco_f051r8/module.lb +++ b/src/modm/board/disco_f051r8/module.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "board" module.name = "disco-f051r8" + module.description = """\ +# STM32F0DISCOVERY + +Discovery kit for STM32F0 series +http://www.st.com/en/evaluation-tools/stm32f0discovery.html +""" def prepare(module, options): if options[":target"].partname != "stm32f051r8t": diff --git a/src/modm/board/disco_f072rb/board.hpp b/src/modm/board/disco_f072rb/board.hpp index 9c06f5de39..009572e24a 100644 --- a/src/modm/board/disco_f072rb/board.hpp +++ b/src/modm/board/disco_f072rb/board.hpp @@ -12,12 +12,6 @@ */ // ---------------------------------------------------------------------------- -// -// 32F072DISCOVERY -// Discovery kit for STM32F072 series -// http://www.st.com/en/evaluation-tools/32f072bdiscovery.html -// - #ifndef MODM_STM32_F072_DISCOVERY_HPP #define MODM_STM32_F072_DISCOVERY_HPP @@ -27,7 +21,7 @@ using namespace modm::platform; - +/// @ingroup modm_board_disco_f072rb namespace Board { diff --git a/src/modm/board/disco_f072rb/module.lb b/src/modm/board/disco_f072rb/module.lb index a6373b8eaa..56b63d6225 100644 --- a/src/modm/board/disco_f072rb/module.lb +++ b/src/modm/board/disco_f072rb/module.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "board" module.name = "disco-f072rb" + module.description = """\ +# STM32F072DISCOVERY + +Discovery kit for STM32F072 series +http://www.st.com/en/evaluation-tools/32f072bdiscovery.html +""" def prepare(module, options): if options[":target"].partname != "stm32f072rbt": diff --git a/src/modm/board/disco_f100rb/board.hpp b/src/modm/board/disco_f100rb/board.hpp index 8589bed136..c41d8dd32a 100644 --- a/src/modm/board/disco_f100rb/board.hpp +++ b/src/modm/board/disco_f100rb/board.hpp @@ -10,12 +10,6 @@ */ // ---------------------------------------------------------------------------- -// -// STM32F1DISCOVERY -// Discovery kit for STM32 F1 series -// http://www.st.com/en/evaluation-tools/stm32vldiscovery.html -// - #ifndef MODM_STM32_F1_DISCOVERY_HPP #define MODM_STM32_F1_DISCOVERY_HPP @@ -25,19 +19,12 @@ using namespace modm::platform; +/// @ingroup modm_board_disco_f100rb namespace Board { - -/// supplied by the on-board st-link -/* SystemClock generator is only available for selected STM32F1 devices. - * The idea is that it is generated automatically for you like the rest of the - * HAL, however, modm does not have this capability yet. See PR #36. - */ -// using systemClock = SystemClock, MHz24> >; - -// Instead this manual implementation of the system clock is used: /// STM32F100 running at 24MHz generated from the external 8MHz crystal +/// supplied by the on-board st-link struct systemClock { static constexpr uint32_t Frequency = 24 * MHz1; static constexpr uint32_t Ahb = Frequency; diff --git a/src/modm/board/disco_f100rb/module.lb b/src/modm/board/disco_f100rb/module.lb index 0b948c4887..ada76064a2 100644 --- a/src/modm/board/disco_f100rb/module.lb +++ b/src/modm/board/disco_f100rb/module.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "board" module.name = "disco-f100rb" + module.description = """\ +# STM32VLDISCOVERY + +Discovery kit for STM32 F1 series +http://www.st.com/en/evaluation-tools/stm32vldiscovery.html +""" def prepare(module, options): if options[":target"].partname != "stm32f100rbt": diff --git a/src/modm/board/disco_f303vc/board.hpp b/src/modm/board/disco_f303vc/board.hpp index 55d4402cbd..ba8e85fbbd 100644 --- a/src/modm/board/disco_f303vc/board.hpp +++ b/src/modm/board/disco_f303vc/board.hpp @@ -11,12 +11,6 @@ */ // ---------------------------------------------------------------------------- -// -// STM32F3DISCOVERY -// Discovery kit for STM32 F3 series -// http://www.st.com/en/evaluation-tools/stm32f3discovery.html -// - #ifndef MODM_STM32_F3_DISCOVERY_HPP #define MODM_STM32_F3_DISCOVERY_HPP @@ -27,17 +21,10 @@ using namespace modm::platform; - +/// @ingroup modm_board_disco_f303vc namespace Board { -/* SystemClock generator is only available for selected STM32F4 devices. - * The idea is that it is generated automatically for you like the rest of the - * HAL, however, modm does not have this capability yet. See PR #36. - */ -// using systemClock = SystemClock, MHz72> >; - -// Instead this manual implementation of the system clock is used: /// STM32F303 running at 72MHz generated from the external 8MHz clock /// supplied by the on-board st-link struct systemClock { diff --git a/src/modm/board/disco_f303vc/module.lb b/src/modm/board/disco_f303vc/module.lb index 054a2e1268..a21d11d747 100644 --- a/src/modm/board/disco_f303vc/module.lb +++ b/src/modm/board/disco_f303vc/module.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "board" module.name = "disco-f303vc" + module.description = """\ +# STM32F3DISCOVERY + +Discovery kit for STM32 F3 series +http://www.st.com/en/evaluation-tools/stm32f3discovery.html +""" def prepare(module, options): if options[":target"].partname != "stm32f303vct": diff --git a/src/modm/board/disco_f407vg/board.hpp b/src/modm/board/disco_f407vg/board.hpp index e4c6bf176f..811a02f759 100644 --- a/src/modm/board/disco_f407vg/board.hpp +++ b/src/modm/board/disco_f407vg/board.hpp @@ -12,12 +12,6 @@ */ // ---------------------------------------------------------------------------- -// -// STM32F4DISCOVERY -// Discovery kit for STM32F407/417 lines -// http://www.st.com/en/evaluation-tools/stm32f4discovery.html -// - #ifndef MODM_STM32_F4_DISCOVERY_HPP #define MODM_STM32_F4_DISCOVERY_HPP @@ -27,17 +21,10 @@ using namespace modm::platform; - +/// @ingroup modm_board_disco_f407vg namespace Board { -/* SystemClock generator is only available for selected STM32F4 devices. - * The idea is that it is generated automatically for you like the rest of the - * HAL, however, modm does not have this capability yet. See PR #36. - */ -// using systemClock = SystemClock, MHz168, MHz48> >; - -// Instead this manual implementation of the system clock is used: /// STM32F407 running at 168MHz generated from the external 8MHz crystal struct systemClock { static constexpr uint32_t Frequency = 168 * MHz1; diff --git a/src/modm/board/disco_f407vg/module.lb b/src/modm/board/disco_f407vg/module.lb index b793efe8c6..e849f2843b 100644 --- a/src/modm/board/disco_f407vg/module.lb +++ b/src/modm/board/disco_f407vg/module.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "board" module.name = "disco-f407vg" + module.description = """\ +# STM32F4DISCOVERY + +Discovery kit for STM32F407/417 lines +http://www.st.com/en/evaluation-tools/stm32f4discovery.html +""" def prepare(module, options): if options[":target"].partname != "stm32f407vgt": diff --git a/src/modm/board/disco_f429zi/board.hpp b/src/modm/board/disco_f429zi/board.hpp index d26b79b79c..a8f98dc162 100644 --- a/src/modm/board/disco_f429zi/board.hpp +++ b/src/modm/board/disco_f429zi/board.hpp @@ -11,12 +11,6 @@ */ // ---------------------------------------------------------------------------- -// -// STM32F429IDISCOVERY -// Discovery kit for STM32F429 line -// http://www.st.com/en/evaluation-tools/32f429idiscovery.html -// - #ifndef MODM_STM32_F429_DISCOVERY_HPP #define MODM_STM32_F429_DISCOVERY_HPP @@ -25,6 +19,7 @@ using namespace modm::platform; +/// @ingroup modm_board_disco_f429zi namespace Board { diff --git a/src/modm/board/disco_f429zi/module.lb b/src/modm/board/disco_f429zi/module.lb index d284c9406e..f1df12bdb0 100644 --- a/src/modm/board/disco_f429zi/module.lb +++ b/src/modm/board/disco_f429zi/module.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "board" module.name = "disco-f429zi" + module.description = """\ +# STM32F429IDISCOVERY + +Discovery kit for STM32F429 line +http://www.st.com/en/evaluation-tools/32f429idiscovery.html +""" def prepare(module, options): if options[":target"].partname != "stm32f429zit": diff --git a/src/modm/board/disco_f469ni/board.hpp b/src/modm/board/disco_f469ni/board.hpp index efbadde0e5..d675ff08b5 100644 --- a/src/modm/board/disco_f469ni/board.hpp +++ b/src/modm/board/disco_f469ni/board.hpp @@ -11,12 +11,6 @@ */ // ---------------------------------------------------------------------------- -// -// STM32F469I-DISCO -// Discovery kit for STM32F469 line -// http://www.st.com/en/evaluation-tools/32f469idiscovery.html -// - #ifndef MODM_STM32_F469_DISCOVERY_HPP #define MODM_STM32_F469_DISCOVERY_HPP @@ -25,10 +19,13 @@ #include #include #include + +/// @ingroup modm_board_disco_f469ni #define MODM_BOARD_HAS_LOGGER using namespace modm::platform; +/// @ingroup modm_board_disco_f469ni namespace Board { diff --git a/src/modm/board/disco_f469ni/module.md b/src/modm/board/disco_f469ni/module.md index 3abef214ee..0e7ad2a7bb 100644 --- a/src/modm/board/disco_f469ni/module.md +++ b/src/modm/board/disco_f469ni/module.md @@ -1,4 +1,6 @@ -Discovery kit with STM32F469NI MCU +# STM32F469IDISCOVERY + +Discovery kit with STM32F469NI MCU. This BSPs `Board::initialize()` sets the board up with these settings: diff --git a/src/modm/board/disco_f746ng/board.hpp b/src/modm/board/disco_f746ng/board.hpp index 063674201e..210e15cc50 100644 --- a/src/modm/board/disco_f746ng/board.hpp +++ b/src/modm/board/disco_f746ng/board.hpp @@ -12,22 +12,19 @@ */ // ---------------------------------------------------------------------------- -// -// STM32F7DISCOVERY -// Discovery kit for STM32F746 line -// http://www.st.com/en/evaluation-tools/32f746gdiscovery.html -// - #ifndef MODM_STM32_F746G_DISCOVERY_HPP #define MODM_STM32_F746G_DISCOVERY_HPP #include #include #include + +/// @ingroup modm_board_disco_f746ng #define MODM_BOARD_HAS_LOGGER using namespace modm::platform; +/// @ingroup modm_board_disco_f746ng namespace Board { diff --git a/src/modm/board/disco_f746ng/module.lb b/src/modm/board/disco_f746ng/module.lb index b758d94d94..83179d177c 100644 --- a/src/modm/board/disco_f746ng/module.lb +++ b/src/modm/board/disco_f746ng/module.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "board" module.name = "disco-f746ng" + module.description = """\ +# STM32F7DISCOVERY + +Discovery kit for STM32F746 line +http://www.st.com/en/evaluation-tools/32f746gdiscovery.html +""" def prepare(module, options): if options[":target"].partname != "stm32f746ngh": diff --git a/src/modm/board/disco_f769ni/board.hpp b/src/modm/board/disco_f769ni/board.hpp index 205107b0a3..35b91983d7 100644 --- a/src/modm/board/disco_f769ni/board.hpp +++ b/src/modm/board/disco_f769ni/board.hpp @@ -12,22 +12,19 @@ */ // ---------------------------------------------------------------------------- -// -// STM32F769I-DISCOVERY (MB1225B) -// Discovery kit for STM32F769 line -// http://www.st.com/en/evaluation-tools/32f769idiscovery.html -// - #ifndef MODM_STM32_F769I_DISCOVERY_HPP #define MODM_STM32_F769I_DISCOVERY_HPP #include #include #include + +/// @ingroup modm_board_disco_f769ni #define MODM_BOARD_HAS_LOGGER using namespace modm::platform; +/// @ingroup modm_board_disco_f769ni namespace Board { diff --git a/src/modm/board/disco_f769ni/module.lb b/src/modm/board/disco_f769ni/module.lb index 82b91403bd..f7d926d2b5 100644 --- a/src/modm/board/disco_f769ni/module.lb +++ b/src/modm/board/disco_f769ni/module.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "board" module.name = "disco-f769ni" + module.description = """\ +# STM32F769IDISCOVERY + +Discovery kit for STM32F769 line +http://www.st.com/en/evaluation-tools/32f769idiscovery.html +""" def prepare(module, options): if options[":target"].partname != "stm32f769nih": diff --git a/src/modm/board/disco_l476vg/board.hpp b/src/modm/board/disco_l476vg/board.hpp index a51c9fa5f6..9705ceba91 100644 --- a/src/modm/board/disco_l476vg/board.hpp +++ b/src/modm/board/disco_l476vg/board.hpp @@ -12,12 +12,6 @@ */ // ---------------------------------------------------------------------------- -// -// STM32L476DISCOVERY -// Discovery kit for STM32L476 -// http://www.st.com/en/evaluation-tools/32l476gdiscovery.html -// - #ifndef MODM_STM32_L476_DISCOVERY_HPP #define MODM_STM32_L476_DISCOVERY_HPP @@ -27,7 +21,7 @@ using namespace modm::platform; - +/// @ingroup modm_board_disco_l476vg namespace Board { diff --git a/src/modm/board/disco_l476vg/module.lb b/src/modm/board/disco_l476vg/module.lb index 6595587ed2..fcf763cb4c 100644 --- a/src/modm/board/disco_l476vg/module.lb +++ b/src/modm/board/disco_l476vg/module.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "board" module.name = "disco-l476vg" + module.description = """\ +# STM32L476DISCOVERY + +Discovery kit for STM32L476 +http://www.st.com/en/evaluation-tools/32l476gdiscovery.html +""" def prepare(module, options): if options[":target"].partname != "stm32l476vgt": diff --git a/src/modm/board/module.lb b/src/modm/board/module.lb index 310c8602b1..f610763dcf 100644 --- a/src/modm/board/module.lb +++ b/src/modm/board/module.lb @@ -12,6 +12,7 @@ def init(module): module.name = "board" + module.description = "Board Support Packages" def prepare(module, options): return True diff --git a/src/modm/board/nucleo_f031k6/board.hpp b/src/modm/board/nucleo_f031k6/board.hpp index e734d7ee60..4c74fcc838 100644 --- a/src/modm/board/nucleo_f031k6/board.hpp +++ b/src/modm/board/nucleo_f031k6/board.hpp @@ -10,23 +10,18 @@ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ -// -// NUCLEO-F031K6 -// Nucleo kit for STM32F031K6 -// http://www.st.com/en/evaluation-tools/nucleo-f031k6.html -// - #ifndef MODM_STM32_NUCLEO_F031K6_HPP #define MODM_STM32_NUCLEO_F031K6_HPP #include #include #include +/// @ingroup modm_board_nucleo_f031k6 #define MODM_BOARD_HAS_LOGGER using namespace modm::platform; - +/// @ingroup modm_board_nucleo_f031k6 namespace Board { diff --git a/src/modm/board/nucleo_f031k6/module.lb b/src/modm/board/nucleo_f031k6/module.lb index 7f64668dff..2607eabb4b 100644 --- a/src/modm/board/nucleo_f031k6/module.lb +++ b/src/modm/board/nucleo_f031k6/module.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "board" module.name = "nucleo-f031k6" + module.description = """\ +# NUCLEO-F031K6 + +Nucleo kit for STM32F031K6 +http://www.st.com/en/evaluation-tools/nucleo-f031k6.html +""" def prepare(module, options): if options[":target"].partname != "stm32f031k6t": diff --git a/src/modm/board/nucleo_f042k6/board.hpp b/src/modm/board/nucleo_f042k6/board.hpp index fa3bc31c1b..a07e09c840 100644 --- a/src/modm/board/nucleo_f042k6/board.hpp +++ b/src/modm/board/nucleo_f042k6/board.hpp @@ -11,23 +11,18 @@ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ -// -// NUCLEO-F042K6 -// Nucleo kit for STM32F042K6 -// http://www.st.com/en/evaluation-tools/nucleo-f042k6.html -// - #ifndef MODM_STM32_NUCLEO_F042K6_HPP #define MODM_STM32_NUCLEO_F042K6_HPP #include #include #include +/// @ingroup modm_board_nucleo_f042k6 #define MODM_BOARD_HAS_LOGGER using namespace modm::platform; - +/// @ingroup modm_board_nucleo_f042k6 namespace Board { diff --git a/src/modm/board/nucleo_f042k6/module.lb b/src/modm/board/nucleo_f042k6/module.lb index b8ab1b5916..f7a8b82732 100644 --- a/src/modm/board/nucleo_f042k6/module.lb +++ b/src/modm/board/nucleo_f042k6/module.lb @@ -15,6 +15,12 @@ def init(module): module.parent = "board" module.name = "nucleo-f042k6" + module.description = """\ +# NUCLEO-F042K6 + +Nucleo kit for STM32F042K6 +http://www.st.com/en/evaluation-tools/nucleo-f042k6.html +""" def prepare(module, options): if options[":target"].partname != "stm32f042k6t": diff --git a/src/modm/board/nucleo_f103rb/board.hpp b/src/modm/board/nucleo_f103rb/board.hpp index 1370eeb359..59eaced242 100644 --- a/src/modm/board/nucleo_f103rb/board.hpp +++ b/src/modm/board/nucleo_f103rb/board.hpp @@ -10,23 +10,18 @@ */ // ---------------------------------------------------------------------------- -// -// NUCLEO-F103RB -// Nucleo kit for STM32F103RB -// http://www.st.com/en/evaluation-tools/nucleo-f103rb.html -// - #ifndef MODM_STM32_NUCLEO_F103RB_HPP #define MODM_STM32_NUCLEO_F103RB_HPP #include #include #include +/// @ingroup modm_board_nucleo_f103rb #define MODM_BOARD_HAS_LOGGER using namespace modm::platform; - +/// @ingroup modm_board_nucleo_f103rb namespace Board { diff --git a/src/modm/board/nucleo_f103rb/module.lb b/src/modm/board/nucleo_f103rb/module.lb index e57705cc37..dad46f42bf 100644 --- a/src/modm/board/nucleo_f103rb/module.lb +++ b/src/modm/board/nucleo_f103rb/module.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "board" module.name = "nucleo-f103rb" + module.description = """\ +# NUCLEO-F103RB + +Nucleo kit for STM32F103RB +http://www.st.com/en/evaluation-tools/nucleo-f103rb.html +""" def prepare(module, options): if options[":target"].partname != "stm32f103rbt": diff --git a/src/modm/board/nucleo_f303k8/board.hpp b/src/modm/board/nucleo_f303k8/board.hpp index c04d0650f7..9ebbea5dcb 100644 --- a/src/modm/board/nucleo_f303k8/board.hpp +++ b/src/modm/board/nucleo_f303k8/board.hpp @@ -10,23 +10,18 @@ */ // ---------------------------------------------------------------------------- -// -// NUCLEO-F303K8 -// Nucleo kit for STM32F303K8 -// http://www.st.com/en/evaluation-tools/nucleo-f303k8.html -// - #ifndef MODM_STM32_NUCLEO_F303K8_HPP #define MODM_STM32_NUCLEO_F303K8_HPP #include #include #include +/// @ingroup modm_board_nucleo_f303k8 #define MODM_BOARD_HAS_LOGGER using namespace modm::platform; - +/// @ingroup modm_board_nucleo_f303k8 namespace Board { diff --git a/src/modm/board/nucleo_f303k8/module.lb b/src/modm/board/nucleo_f303k8/module.lb index 1e997fd885..03146360ca 100644 --- a/src/modm/board/nucleo_f303k8/module.lb +++ b/src/modm/board/nucleo_f303k8/module.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "board" module.name = "nucleo-f303k8" + module.description = """\ +# NUCLEO-F303K8 + +Nucleo kit for STM32F303K8 +http://www.st.com/en/evaluation-tools/nucleo-f303k8.html +""" def prepare(module, options): if options[":target"].partname != "stm32f303k8t": diff --git a/src/modm/board/nucleo_f401re/board.hpp b/src/modm/board/nucleo_f401re/board.hpp index 7e6f898818..1b2c7a4946 100644 --- a/src/modm/board/nucleo_f401re/board.hpp +++ b/src/modm/board/nucleo_f401re/board.hpp @@ -10,23 +10,18 @@ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ -// -// NUCLEO-F401RE -// Nucleo kit for STM32F401RE -// http://www.st.com/en/evaluation-tools/nucleo-f401re.html -// - #ifndef MODM_STM32_NUCLEO_F401RE_HPP #define MODM_STM32_NUCLEO_F401RE_HPP #include #include #include +/// @ingroup modm_board_nucleo_f401re #define MODM_BOARD_HAS_LOGGER using namespace modm::platform; - +/// @ingroup modm_board_nucleo_f401re namespace Board { diff --git a/src/modm/board/nucleo_f401re/module.lb b/src/modm/board/nucleo_f401re/module.lb index a94f3aa435..b8f95b58bf 100644 --- a/src/modm/board/nucleo_f401re/module.lb +++ b/src/modm/board/nucleo_f401re/module.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "board" module.name = "nucleo-f401re" + module.description = """\ +# NUCLEO-F401RE + +Nucleo kit for STM32F401RE +http://www.st.com/en/evaluation-tools/nucleo-f401re.html +""" def prepare(module, options): if options[":target"].partname != "stm32f401ret": diff --git a/src/modm/board/nucleo_f411re/board.hpp b/src/modm/board/nucleo_f411re/board.hpp index 49a0c7895d..25b659d329 100644 --- a/src/modm/board/nucleo_f411re/board.hpp +++ b/src/modm/board/nucleo_f411re/board.hpp @@ -11,23 +11,18 @@ */ // ---------------------------------------------------------------------------- -// -// NUCLEO-F411RE -// Nucleo kit for STM32F411RE -// http://www.st.com/en/evaluation-tools/nucleo-f411re.html -// - #ifndef MODM_STM32_NUCLEO_F411RE_HPP #define MODM_STM32_NUCLEO_F411RE_HPP #include #include #include +/// @ingroup modm_board_nucleo_f411re #define MODM_BOARD_HAS_LOGGER using namespace modm::platform; - +/// @ingroup modm_board_nucleo_f411re namespace Board { diff --git a/src/modm/board/nucleo_f411re/module.lb b/src/modm/board/nucleo_f411re/module.lb index 2e054d2f37..4ec603e48c 100644 --- a/src/modm/board/nucleo_f411re/module.lb +++ b/src/modm/board/nucleo_f411re/module.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "board" module.name = "nucleo-f411re" + module.description = """\ +# NUCLEO-F411RE + +Nucleo kit for STM32F411RE +http://www.st.com/en/evaluation-tools/nucleo-f411re.html +""" def prepare(module, options): if options[":target"].partname != "stm32f411ret": diff --git a/src/modm/board/nucleo_f429zi/board.hpp b/src/modm/board/nucleo_f429zi/board.hpp index e972e600e4..800dd2ce25 100644 --- a/src/modm/board/nucleo_f429zi/board.hpp +++ b/src/modm/board/nucleo_f429zi/board.hpp @@ -10,21 +10,18 @@ */ // ---------------------------------------------------------------------------- -// NUCLEO-F429ZI -// Nucleo kit for STM32F429ZI -// http://www.st.com/en/evaluation-tools/nucleo-f429zi.html -// - #ifndef MODM_STM32_NUCLEO_F429ZI_HPP #define MODM_STM32_NUCLEO_F429ZI_HPP #include #include #include +/// @ingroup modm_board_nucleo_f429zi #define MODM_BOARD_HAS_LOGGER using namespace modm::platform; +/// @ingroup modm_board_nucleo_f429zi namespace Board { diff --git a/src/modm/board/nucleo_f429zi/module.lb b/src/modm/board/nucleo_f429zi/module.lb index 14a6312265..fbf3f0fe3a 100644 --- a/src/modm/board/nucleo_f429zi/module.lb +++ b/src/modm/board/nucleo_f429zi/module.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "board" module.name = "nucleo-f429zi" + module.description = """\ +# NUCLEO-F429ZI + +Nucleo kit for STM32F429ZI +http://www.st.com/en/evaluation-tools/nucleo-f429zi.html +""" def prepare(module, options): if options[":target"].partname != "stm32f429zit": diff --git a/src/modm/board/nucleo_l432kc/board.hpp b/src/modm/board/nucleo_l432kc/board.hpp index 85ec76fafb..615849e0f7 100644 --- a/src/modm/board/nucleo_l432kc/board.hpp +++ b/src/modm/board/nucleo_l432kc/board.hpp @@ -9,22 +9,18 @@ */ // ---------------------------------------------------------------------------- -// -// NUCLEO-L432KC -// Nucleo kit for STM32L432KC -// http://www.st.com/en/evaluation-tools/nucleo-l432kc.html -// - #ifndef MODM_STM32_NUCLEO_L432KC_HPP #define MODM_STM32_NUCLEO_L432KC_HPP #include #include #include +/// @ingroup modm_board_nucleo_l432kc #define MODM_BOARD_HAS_LOGGER using namespace modm::platform; +/// @ingroup modm_board_nucleo_l432kc namespace Board { diff --git a/src/modm/board/nucleo_l432kc/module.lb b/src/modm/board/nucleo_l432kc/module.lb index c2c4482862..aefe5f05cf 100644 --- a/src/modm/board/nucleo_l432kc/module.lb +++ b/src/modm/board/nucleo_l432kc/module.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "board" module.name = "nucleo-l432kc" + module.description = """\ +# NUCLEO-L432KC + +Nucleo kit for STM32L432KC +http://www.st.com/en/evaluation-tools/nucleo-l432kc.html +""" def prepare(module, options): if options[":target"].partname != "stm32l432kcu": diff --git a/src/modm/board/nucleo_l476rg/board.hpp b/src/modm/board/nucleo_l476rg/board.hpp index d6e13dada8..4be6772aaa 100644 --- a/src/modm/board/nucleo_l476rg/board.hpp +++ b/src/modm/board/nucleo_l476rg/board.hpp @@ -11,22 +11,18 @@ */ // ---------------------------------------------------------------------------- -// -// NUCLEO-L476RG -// Nucleo kit for STM32L476RG -// http://www.st.com/en/evaluation-tools/nucleo-l476rg.html -// - #ifndef MODM_STM32_NUCLEO_L476RG_HPP #define MODM_STM32_NUCLEO_L476RG_HPP #include #include #include +/// @ingroup modm_board_nucleo_l476rg #define MODM_BOARD_HAS_LOGGER using namespace modm::platform; +/// @ingroup modm_board_nucleo_l476rg namespace Board { diff --git a/src/modm/board/nucleo_l476rg/module.lb b/src/modm/board/nucleo_l476rg/module.lb index ca6210f0d3..8e06215790 100644 --- a/src/modm/board/nucleo_l476rg/module.lb +++ b/src/modm/board/nucleo_l476rg/module.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "board" module.name = "nucleo-l476rg" + module.description = """\ +# NUCLEO-L476RG + +Nucleo kit for STM32L476RG +http://www.st.com/en/evaluation-tools/nucleo-l476rg.html +""" def prepare(module, options): if options[":target"].partname != "stm32l476rgt": diff --git a/src/modm/board/olimexino_stm32/board.hpp b/src/modm/board/olimexino_stm32/board.hpp index 392406000b..377df4446b 100644 --- a/src/modm/board/olimexino_stm32/board.hpp +++ b/src/modm/board/olimexino_stm32/board.hpp @@ -8,21 +8,18 @@ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ -// -// Olimexino STM32 (modified Maple board with STM32F103RBT6) -// https://www.olimex.com/Products/Duino/STM32/OLIMEXINO-STM32/open-source-hardware -// - #ifndef MODM_STM32_OLIMEXINO_STM32_HPP #define MODM_STM32_OLIMEXINO_STM32_HPP #include #include #include +/// @ingroup modm_board_olimexino_stm32 #define MODM_BOARD_HAS_LOGGER using namespace modm::platform; +/// @ingroup modm_board_olimexino_stm32 namespace Board { diff --git a/src/modm/board/olimexino_stm32/module.lb b/src/modm/board/olimexino_stm32/module.lb index f74594a06a..5af58e0477 100644 --- a/src/modm/board/olimexino_stm32/module.lb +++ b/src/modm/board/olimexino_stm32/module.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "board" module.name = "olimexino-stm32" + module.description = """\ +# Olimexino STM32 + +Modified Maple board with STM32F103RBT6: +https://www.olimex.com/Products/Duino/STM32/OLIMEXINO-STM32/open-source-hardware +""" def prepare(module, options): if options[":target"].partname != "stm32f103rbt": diff --git a/src/modm/board/stm32f030f4p6_demo/board.hpp b/src/modm/board/stm32f030f4p6_demo/board.hpp index 304a43b67d..26544424d5 100644 --- a/src/modm/board/stm32f030f4p6_demo/board.hpp +++ b/src/modm/board/stm32f030f4p6_demo/board.hpp @@ -10,16 +10,6 @@ */ // ---------------------------------------------------------------------------- -// -// STM32F030F4P6 "Demo Board" Minimum System Development Board -// -// Cheap and bread-board-friendly board for STM32 F0 series. -// Sold for less than 1.5 USD on well known Internet shops from China. -// -// http://www.hotmcu.com/stm32f030f4p6-minimum-systerm-boardcortexm0-p-208.html -// http://www.haoyuelectronics.com/Attachment/STM32F030-Dev-Board/STM32F030F4P6.pdf -// - #ifndef MODM_STM32_F030F4P6_DEMO_BOARD_HPP #define MODM_STM32_F030F4P6_DEMO_BOARD_HPP @@ -29,6 +19,7 @@ using namespace modm::platform; +/// @ingroup modm_board_stm32f030_demo namespace Board { diff --git a/src/modm/board/stm32f030f4p6_demo/module.lb b/src/modm/board/stm32f030f4p6_demo/module.lb index 487d555cb6..a09daf0810 100644 --- a/src/modm/board/stm32f030f4p6_demo/module.lb +++ b/src/modm/board/stm32f030f4p6_demo/module.lb @@ -14,6 +14,17 @@ def init(module): module.parent = "board" module.name = "stm32f030_demo" + module.description = """\ +# STM32F030 Demo Board + +STM32F030F4P6 Minimum System Development Board. + +Cheap and bread-board-friendly board for STM32 F0 series. +Sold for less than 1.5 USD on well known Internet shops from China. + +http://www.hotmcu.com/stm32f030f4p6-minimum-systerm-boardcortexm0-p-208.html +http://www.haoyuelectronics.com/Attachment/STM32F030-Dev-Board/STM32F030F4P6.pdf +""" def prepare(module, options): if options[":target"].partname != "stm32f030f4p": diff --git a/src/modm/communication/amnb.hpp b/src/modm/communication/amnb.hpp index e659e7c075..185e4e9043 100644 --- a/src/modm/communication/amnb.hpp +++ b/src/modm/communication/amnb.hpp @@ -11,7 +11,7 @@ // ---------------------------------------------------------------------------- /** - * @ingroup communication + * @ingroup modm_communication * @defgroup amnb Asynchronous Multi-Node Bus (AMNB) * * @section amnb_intro Introduction diff --git a/src/modm/communication/module.lb b/src/modm/communication/module.lb index acada26b27..ab51b8f015 100644 --- a/src/modm/communication/module.lb +++ b/src/modm/communication/module.lb @@ -13,6 +13,7 @@ def init(module): module.name = "communication" + module.description = "Communication Protocols" def prepare(module, options): return True diff --git a/src/modm/communication/ros.hpp b/src/modm/communication/ros.hpp index 2187d5057d..1710ebe7fb 100644 --- a/src/modm/communication/ros.hpp +++ b/src/modm/communication/ros.hpp @@ -11,9 +11,4 @@ */ // ---------------------------------------------------------------------------- -/** - * @ingroup communication - * @defgroup ros_comm ROS communication (rosserial) - */ - #include "ros/ros_modm_hardware.hpp" diff --git a/src/modm/communication/ros/module.lb b/src/modm/communication/ros/module.lb index 3d4e3c472c..f4cdf3fd8d 100644 --- a/src/modm/communication/ros/module.lb +++ b/src/modm/communication/ros/module.lb @@ -13,6 +13,7 @@ def init(module): module.parent = "communication" module.name = "ros" + module.description = "Drivers for rosserial" def prepare(module, options): module.depends( diff --git a/src/modm/communication/ros/ros_modm_hardware.hpp b/src/modm/communication/ros/ros_modm_hardware.hpp index a0b0dc9ee9..6ba0ab99b4 100644 --- a/src/modm/communication/ros/ros_modm_hardware.hpp +++ b/src/modm/communication/ros/ros_modm_hardware.hpp @@ -31,6 +31,7 @@ * unsigend long time() * Get time in milliseconds since start. Monotonic increasing clock. * + * @ingroup modm_communication_ros */ template < class Uart > class ModmHardware diff --git a/src/modm/communication/rpr.hpp b/src/modm/communication/rpr.hpp index ceca05b267..dfc02a13bb 100644 --- a/src/modm/communication/rpr.hpp +++ b/src/modm/communication/rpr.hpp @@ -9,79 +9,4 @@ */ // ---------------------------------------------------------------------------- -/** - * @ingroup communication - * @defgroup rpr Resilient Packet Ring (RPR) - * - * This is a simplified version of the [Resilient Packet Ring] - * ( http://en.wikipedia.org/wiki/Resilient_Packet_Ring ). - * - * Listener callbacks to received messaged can be defined. All messages are buffered. - * As an optional advanced feature, error handling callbacks can also be defined. - * - * - * Frame Format - * ------------ -@verbatim - |<------ FCS Coverage ----->| -+------+-------+-------+-----------+-------+------+ -| SD | DA | SA | Payload | FCS | ED | -+------+-------+-------+-----------+-------+------+ -| 8bit | 16bit | 16bit | >=0 bytes | 16bit | 8bit | -+------+-------+-------+-----------+-------+------+ -@endverbatim - * - * - * Frame Fields - * ------------ - * - * The Start Frame Delimiter (SD) and End Frame Delimiter (ED) are - * adapted from the [HDLC asynchronous framing] - * ( http://en.wikipedia.org/wiki/High-Level_Data_Link_Control#Asynchronous_framing ). - * - * - * The Desination Address (DA) and Source Address (DA) format are both 15 bit. - * This uses the official MAC scheme for 2 Byte addressing. - * - * The Destination Address (DA) byte format: -@verbatim - 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 -+-----+---+---+---+---+---+---+---+ +-----+---+---+---+---+---+---+---+ -| I/G | Upper (Group) Address | | Lower (Group) Address | -+-----+---+---+---+---+---+---+---+ +-----+---+---+---+---+---+---+---+ - |<----- (Ring Number) ----->| |<---- (Station Subaddress) ----->| -@endverbatim - * - I/G bit: address is an individual (0) or a group address (1). - * - * Individual Addresses identify a perticular station on the LAN and shall be - * distinct from all other individual stations addresses on the same LAN. - * - * Group Addresses are used to address a frame to multiple destination stations - * and may be associated with zero or more stations on a given LAN. - * - * Broadcast Address (0xffff) is used to address every station on the LAN. - * - * Null Address (0x0000) means the frame is not addressed to any particular station. - * - * It is recommended to use the 7bit Upper Address to identify the ring number, - * and the 8bit Lower Address as a station subaddress. - * - * The Source Address (SA) byte format: -@verbatim - 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 -+------+---+---+---+---+---+---+---+ +---+---+---+---+---+---+---+---+ -| Zero | Upper Address | | Lower Address | -+------+---+---+---+---+---+---+---+ +---+---+---+---+---+---+---+---+ -@endverbatim - * - * The Frame Check Sequence (FCS) uses CRC-16-IBM (0xa001) polynomial with the - * initial value of 0xffff. - * - * It is strongly recommended to keep the maximum payload length lower than 64 bytes, - * and break down longer payload into multiple frames. - * The longer the payload the more buffer each station has to allocate. - * - * @author Niklas Hauser - */ - #include "rpr/node.hpp" diff --git a/src/modm/communication/rpr/constants.hpp b/src/modm/communication/rpr/constants.hpp index dd39b1fdf8..ba1985a781 100644 --- a/src/modm/communication/rpr/constants.hpp +++ b/src/modm/communication/rpr/constants.hpp @@ -20,7 +20,7 @@ namespace modm { /** * \brief Message Types - * \ingroup token + * \ingroup modm_communication_rpr */ enum MessageType { @@ -65,7 +65,7 @@ namespace modm // private: // ? /** * \brief Bit Masks for the higher address byte - * \ingroup token + * \ingroup modm_communication_rpr */ enum Address { @@ -76,13 +76,13 @@ namespace modm /** * \brief Maximum length for the payload - * \ingroup token + * \ingroup modm_communication_rpr */ const uint8_t maxPayloadLength = 48; /** * \internal - * \ingroup token + * \ingroup modm_communication_rpr */ const uint8_t startDelimiterByte = 0x7e; const uint8_t endDelimiterByte = 0x7c; @@ -91,7 +91,7 @@ namespace modm /** * \internal * \brief Initial value for the CRC16 calculation - * \ingroup token + * \ingroup modm_communication_rpr */ const uint16_t crcInitialValue = 0xffff; } diff --git a/src/modm/communication/rpr/interface.hpp b/src/modm/communication/rpr/interface.hpp index 57b3b20764..cef0d5fca7 100644 --- a/src/modm/communication/rpr/interface.hpp +++ b/src/modm/communication/rpr/interface.hpp @@ -29,7 +29,7 @@ namespace modm { /** * \internal - * \ingroup token + * \ingroup modm_communication_rpr */ uint16_t crcUpdate(uint16_t crc, uint8_t data); @@ -39,7 +39,7 @@ namespace modm * * \author Fabian Greif * \author Niklas Hauser - * \ingroup token + * \ingroup modm_communication_rpr */ template class Interface diff --git a/src/modm/communication/rpr/node.hpp b/src/modm/communication/rpr/node.hpp index e6f7411563..cf710c7985 100644 --- a/src/modm/communication/rpr/node.hpp +++ b/src/modm/communication/rpr/node.hpp @@ -27,7 +27,7 @@ namespace modm * \internal * \brief Interface used to transmit data through a slave object * - * \ingroup rpr + * \ingroup modm_communication_rpr */ class Transmitter { @@ -58,7 +58,7 @@ namespace modm * \brief Possible Listener * * \see RPR_LISTEN() - * \ingroup rpr + * \ingroup modm_communication_rpr */ struct Listener { @@ -78,7 +78,7 @@ namespace modm * \brief Possible Error * * \see RPR_ERROR() - * \ingroup rpr + * \ingroup modm_communication_rpr */ struct Error { @@ -96,7 +96,7 @@ namespace modm * \brief Token Ring Node * * \author Niklas Hauser - * \ingroup rpr + * \ingroup modm_communication_rpr */ template class Node : protected Transmitter @@ -200,7 +200,7 @@ namespace modm * \param function Member function of object * * \see modm::rpr::Listener - * \ingroup rpr + * \ingroup modm_communication_rpr */ #define RPR_LISTEN(type, source, command, object, function) #else @@ -223,7 +223,7 @@ namespace modm * \param function Member function of object * * \see modm::rpr::ErrorHandler - * \ingroup rpr + * \ingroup modm_communication_rpr */ #define RPR_ERROR(address, command, object, function) #else diff --git a/src/modm/communication/sab.hpp b/src/modm/communication/sab.hpp index ce10be270e..2f57930b11 100644 --- a/src/modm/communication/sab.hpp +++ b/src/modm/communication/sab.hpp @@ -10,96 +10,6 @@ */ // ---------------------------------------------------------------------------- -/** - * @ingroup communication - * @defgroup sab Sensor Actuator Bus (SAB) - * - * @section sab_intro Introduction - * - * The SAB (**S**ensor **A**ctuator **B**us) is a simple - * master-slave bus system. It is primarily used to query simple sensors and - * control actuators inside our robots. - * - * One master can communicate with up to 32 slaves. The slaves are only allowed to - * transmit after a direct request by the master. They may signal an event by an - * extra IO line, but this depends on the slave. - * - * A complete example, explaining how to use the classes, is available in the - * `example/sab` folder. - * - * @section sab_protocol Protocol - * - * Features: - * - Baudrate is 115200 Baud. - * - Maximum payload length is 32 byte. - * - CRC8 (1-Wire) - * - * @subsection structure Structure - * -@verbatim -+------+--------+--------+---------+--------------+-----+ -| SYNC | LENGTH | HEADER | COMMAND | ... DATA ... | CRC | -+------+--------+--------+---------+--------------+-----+ -@endverbatim - * - * - `SYNC` - Synchronization byte (always 0x54) - * - `LENGTH` - Length of the payload (without header, command and CRC byte) - * - `HEADER` - Address of the slave and two flag bits - * - `COMMAND` - Command code - * - `DATA` - Up to 32 byte of payload - * - `CRC` - CRC-8 checksum (iButton) - * - * @subsubsection header Header - * -@verbatim - 7 6 5 4 3 2 1 0 -+---+---+---+---+---+---+---+---+ -| Flags | ADDRESS | -+---+---+---+---+---+---+---+---+ - - Flags | Meaning ---------+--------- - 0 0 | request by the master - 0 1 | reserved - 1 0 | negative response from the slave (NACK) - 1 1 | positive response from the slave (ACK) -@endverbatim - * - * The *second bit* is always `false` when the master is transmitting. In the other - * direction, when the slaves are responding, the second bit has to following - * meaning: - * - * - `true` - Message is an positive response and may contain a payload - * - `false` - Message signals an error condition and carries only one byte of - * payload. This byte is an error code. - * - * @section sab_electric Electrical characteristics - * - * Between different boards CAN transceivers are used. Compared to RS485 the - * CAN transceivers have the advantage to work without a separate direction input. - * You can just connected the transceiver directly to the UART of your - * microcontroller. - * - * @image html sab_external.png - * - * Within a single PCB, standard digital levels are used (either 0-3,3V or 0-5V) - * in a multi-drop configuration. Meaning it does not allow multiple drivers but - * multiple receivers. - * The idle state of a UART transmission line is high, so standard TTL-AND gates - * have to be used for bundling transmission lines from multiple slaves. - * - * @image html sab_internal.png - * - * Both approaches can be combined to reduce the number of needed CAN - * transceivers on a single board. Between two boards you should always use - * transceivers and therefore differential signaling to improve noise immunity. - * - * The signal lines to indicate events by the slave are strict optional, you may - * or may not use them (if the slave provides them). - * - * @author Fabian Greif - */ - #ifndef MODM_SAB_HPP #define MODM_SAB_HPP diff --git a/src/modm/communication/sab/constants.hpp b/src/modm/communication/sab/constants.hpp index 50c7cec8fa..001e5c8e91 100644 --- a/src/modm/communication/sab/constants.hpp +++ b/src/modm/communication/sab/constants.hpp @@ -27,7 +27,7 @@ namespace modm * Error codes below 0x20 are reserved for the system. Every other * code may be used by user. * - * \ingroup sab + * \ingroup modm_communication_sab */ enum Error { @@ -60,7 +60,7 @@ namespace modm /** * \brief Flags - * \ingroup sab + * \ingroup modm_communication_sab */ enum Flags { @@ -71,21 +71,21 @@ namespace modm /** * \brief Maximum length for the payload - * \ingroup sab + * \ingroup modm_communication_sab */ const uint8_t maxPayloadLength = 32; /** * \internal * \brief Universal base class for the SAB interface - * \ingroup sab + * \ingroup modm_communication_sab */ const uint8_t syncByte = 0x54; /** * \internal * \brief Initial value for the CRC8 calculation - * \ingroup sab + * \ingroup modm_communication_sab */ const uint8_t crcInitialValue = 0x00; } diff --git a/src/modm/communication/sab/interface.hpp b/src/modm/communication/sab/interface.hpp index 115e7d2e90..30f98f01db 100644 --- a/src/modm/communication/sab/interface.hpp +++ b/src/modm/communication/sab/interface.hpp @@ -31,7 +31,7 @@ namespace modm * * \see * Understanding and Using Cyclic Redundancy Checks with Maxim iButton Products - * \ingroup sab + * \ingroup modm_communication_sab */ uint8_t crcUpdate(uint8_t crc, uint8_t data); @@ -43,7 +43,7 @@ namespace modm * \include sab_interface.cpp * * \author Fabian Greif - * \ingroup sab + * \ingroup modm_communication_sab */ template class Interface diff --git a/src/modm/communication/sab/master.hpp b/src/modm/communication/sab/master.hpp index e49fc1ea44..69a62a1a83 100644 --- a/src/modm/communication/sab/master.hpp +++ b/src/modm/communication/sab/master.hpp @@ -31,7 +31,7 @@ namespace modm * \see modm::Clock * * \author Fabian Greif - * \ingroup sab + * \ingroup modm_communication_sab */ template class Master diff --git a/src/modm/communication/sab/module.lb b/src/modm/communication/sab/module.lb index cebefcfa0e..1194536172 100644 --- a/src/modm/communication/sab/module.lb +++ b/src/modm/communication/sab/module.lb @@ -13,6 +13,7 @@ def init(module): module.parent = "communication" module.name = "sab" + module.description = FileReader("module.md") def prepare(module, options): module.depends( diff --git a/src/modm/communication/sab/module.md b/src/modm/communication/sab/module.md new file mode 100644 index 0000000000..1d641bbcf4 --- /dev/null +++ b/src/modm/communication/sab/module.md @@ -0,0 +1,75 @@ +# Sensor Actuator Bus (SAB) + +The SAB (**S**ensor **A**ctuator **B**us) is a simple +master-slave bus system. It is primarily used to query simple sensors and +control actuators inside our robots. + +One master can communicate with up to 32 slaves. The slaves are only allowed to +transmit after a direct request by the master. They may signal an event by an +extra IO line, but this depends on the slave. + +## Protocol + +Features: +- Baudrate is 115200 Baud. +- Maximum payload length is 32 byte. +- CRC8 (1-Wire) + +### Structure + +``` ++------+--------+--------+---------+--------------+-----+ +| SYNC | LENGTH | HEADER | COMMAND | ... DATA ... | CRC | ++------+--------+--------+---------+--------------+-----+ +``` + +- `SYNC` - Synchronization byte (always 0x54) +- `LENGTH` - Length of the payload (without header, command and CRC byte) +- `HEADER` - Address of the slave and two flag bits +- `COMMAND` - Command code +- `DATA` - Up to 32 byte of payload +- `CRC` - CRC-8 checksum (iButton) + +### Header + +``` + 7 6 5 4 3 2 1 0 ++---+---+---+---+---+---+---+---+ +| Flags | ADDRESS | ++---+---+---+---+---+---+---+---+ + + Flags | Meaning +--------+--------- + 0 0 | request by the master + 0 1 | reserved + 1 0 | negative response from the slave (NACK) + 1 1 | positive response from the slave (ACK) +``` + +The *second bit* is always `false` when the master is transmitting. In the other +direction, when the slaves are responding, the second bit has to following +meaning: + +- `true` - Message is an positive response and may contain a payload +- `false` - Message signals an error condition and carries only one byte of + payload. This byte is an error code. + +## Electrical characteristics + +Between different boards CAN transceivers are used. Compared to RS485 the +CAN transceivers have the advantage to work without a separate direction input. +You can just connected the transceiver directly to the UART of your +microcontroller. + +Within a single PCB, standard digital levels are used (either 0-3,3V or 0-5V) +in a multi-drop configuration. Meaning it does not allow multiple drivers but +multiple receivers. +The idle state of a UART transmission line is high, so standard TTL-AND gates +have to be used for bundling transmission lines from multiple slaves. + +Both approaches can be combined to reduce the number of needed CAN +transceivers on a single board. Between two boards you should always use +transceivers and therefore differential signaling to improve noise immunity. + +The signal lines to indicate events by the slave are strict optional, you may +or may not use them (if the slave provides them). diff --git a/src/modm/communication/sab/slave.hpp b/src/modm/communication/sab/slave.hpp index 83e397d5e6..617dc1199f 100644 --- a/src/modm/communication/sab/slave.hpp +++ b/src/modm/communication/sab/slave.hpp @@ -28,7 +28,7 @@ namespace modm * \internal * \brief Interface used to transmit data through a slave object * - * \ingroup sab + * \ingroup modm_communication_sab */ class Transmitter { @@ -43,7 +43,7 @@ namespace modm /** * \brief Response object for an action call * - * \ingroup sab + * \ingroup modm_communication_sab */ class Response { @@ -122,7 +122,7 @@ namespace modm * A complete example is available in the \c example/avr/sab folder. * * \see modm::sab::Slave - * \ingroup sab + * \ingroup modm_communication_sab */ struct Callable { @@ -132,7 +132,7 @@ namespace modm * \brief Possible Action * * \see SAB_ACTION() - * \ingroup sab + * \ingroup modm_communication_sab */ struct Action { @@ -177,7 +177,7 @@ namespace modm * A complete example is available in the \c example/sab folder. * * \author Fabian Greif - * \ingroup sab + * \ingroup modm_communication_sab */ template class Slave : protected Transmitter @@ -266,7 +266,7 @@ namespace modm * \param length Parameter size in bytes * * \see modm::sab::Action - * \ingroup sab + * \ingroup modm_communication_sab */ #define SAB_ACTION(command, object, function, length) #else diff --git a/src/modm/communication/sab2.hpp b/src/modm/communication/sab2.hpp index 73ba6ee626..5d29408fb9 100644 --- a/src/modm/communication/sab2.hpp +++ b/src/modm/communication/sab2.hpp @@ -10,96 +10,6 @@ */ // ---------------------------------------------------------------------------- -/** - * @ingroup communication - * @defgroup sab2 Sensor Actuator Bus v2 (SAB2) - * - * @section sab_intro Introduction - * - * The SAB (**S**ensor **A**ctuator **B**us) is a simple - * master-slave bus system. It is primarily used to query simple sensors and - * control actuators inside our robots. - * - * One master can communicate with up to 32 slaves. The slaves are only allowed to - * transmit after a direct request by the master. They may signal an event by an - * extra IO line, but this depends on the slave. - * - * A complete example, explaining how to use the classes, is available in the - * `example/sab` folder. - * - * @section sab_protocol Protocol - * - * Features: - * - Baudrate is 115200 Baud. - * - Maximum payload length is 32 byte. - * - CRC8 (1-Wire) - * - * @subsection structure Structure - * - @verbatim - +------+--------+--------+---------+--------------+-----+ - | SYNC | LENGTH | HEADER | COMMAND | ... DATA ... | CRC | - +------+--------+--------+---------+--------------+-----+ - @endverbatim - * - * - `SYNC` - Synchronization byte (always 0x54) - * - `LENGTH` - Length of the payload (without header, command and CRC byte) - * - `HEADER` - Address of the slave and two flag bits - * - `COMMAND` - Command code - * - `DATA` - Up to 32 byte of payload - * - `CRC` - CRC-8 checksum (iButton) - * - * @subsubsection header Header - * - @verbatim - 7 6 5 4 3 2 1 0 - +---+---+---+---+---+---+---+---+ - | Flags | ADDRESS | - +---+---+---+---+---+---+---+---+ - - Flags | Meaning - --------+--------- - 0 0 | request by the master - 0 1 | reserved - 1 0 | negative response from the slave (NACK) - 1 1 | positive response from the slave (ACK) - @endverbatim - * - * The *second bit* is always `false` when the master is transmitting. In the other - * direction, when the slaves are responding, the second bit has to following - * meaning: - * - * - `true` - Message is an positive response and may contain a payload - * - `false` - Message signals an error condition and carries only one byte of - * payload. This byte is an error code. - * - * @section sab_electric Electrical characteristics - * - * Between different boards CAN transceivers are used. Compared to RS485 the - * CAN transceivers have the advantage to work without a separate direction input. - * You can just connected the transceiver directly to the UART of your - * microcontroller. - * - * @image html sab_external.png - * - * Within a single PCB, standard digital levels are used (either 0-3,3V or 0-5V) - * in a multi-drop configuration. Meaning it does not allow multiple drivers but - * multiple receivers. - * The idle state of a UART transmission line is high, so standard TTL-AND gates - * have to be used for bundling transmission lines from multiple slaves. - * - * @image html sab_internal.png - * - * Both approaches can be combined to reduce the number of needed CAN - * transceivers on a single board. Between two boards you should always use - * transceivers and therefore differential signaling to improve noise immunity. - * - * The signal lines to indicate events by the slave are strict optional, you may - * or may not use them (if the slave provides them). - * - * @author Fabian Greif - */ - #ifndef MODM_SAB2_HPP #define MODM_SAB2_HPP diff --git a/src/modm/communication/sab2/constants.hpp b/src/modm/communication/sab2/constants.hpp index cc16fc58f1..a57e68c21c 100644 --- a/src/modm/communication/sab2/constants.hpp +++ b/src/modm/communication/sab2/constants.hpp @@ -28,7 +28,7 @@ namespace modm * Error codes below 0x20 are reserved for the system. Every other * code may be used by user. * - * \ingroup sab2 + * \ingroup modm_communication_sab2 */ enum Error { @@ -61,19 +61,19 @@ namespace modm /** * \brief Flags - * \ingroup sab2 + * \ingroup modm_communication_sab2 */ using sab::Flags; /** * \brief Maximum length for the payload - * \ingroup sab2 + * \ingroup modm_communication_sab2 */ const uint8_t maxPayloadLength = 32; /** * \internal - * \ingroup sab2 + * \ingroup modm_communication_sab2 */ const uint8_t frameBounderyByte = 0x7e; const uint8_t controlEscapeByte = 0x7d; @@ -81,7 +81,7 @@ namespace modm /** * \internal * \brief Initial value for the CRC8 calculation - * \ingroup sab2 + * \ingroup modm_communication_sab2 */ const uint16_t crcInitialValue = 0xffff; } diff --git a/src/modm/communication/sab2/interface.hpp b/src/modm/communication/sab2/interface.hpp index e4c677de67..0db36e2b58 100644 --- a/src/modm/communication/sab2/interface.hpp +++ b/src/modm/communication/sab2/interface.hpp @@ -29,7 +29,7 @@ namespace modm { /** * \internal - * \ingroup sab2 + * \ingroup modm_communication_sab2 */ uint16_t crcUpdate(uint16_t crc, uint8_t data); @@ -41,7 +41,7 @@ namespace modm * See http://en.wikipedia.org/wiki/High-Level_Data_Link_Control#Asynchronous_framing * * \author Fabian Greif - * \ingroup sab2 + * \ingroup modm_communication_sab2 */ template class Interface diff --git a/src/modm/communication/sab2/module.lb b/src/modm/communication/sab2/module.lb index 8072f6f3a1..f34b2127d8 100644 --- a/src/modm/communication/sab2/module.lb +++ b/src/modm/communication/sab2/module.lb @@ -13,6 +13,10 @@ def init(module): module.parent = "communication" module.name = "sab2" + description = str(FileReader("../sab/module.md")).replace( + "# Sensor Actuator Bus (SAB)", + "# Sensor Actuator Bus Version 2 (SAB2)") + module.description = description def prepare(module, options): module.depends( diff --git a/src/modm/communication/xpcc.hpp b/src/modm/communication/xpcc.hpp index e5e9216d00..9e9848da60 100644 --- a/src/modm/communication/xpcc.hpp +++ b/src/modm/communication/xpcc.hpp @@ -11,12 +11,6 @@ */ // ---------------------------------------------------------------------------- -/** - * @ingroup communication - * @defgroup modm_comm Cross Platform Component Communication (XPCC) - * @brief XPCC communication system - */ - #include "xpcc/communicatable.hpp" #include "xpcc/abstract_component.hpp" #include "xpcc/dispatcher.hpp" diff --git a/src/modm/communication/xpcc/abstract_component.hpp b/src/modm/communication/xpcc/abstract_component.hpp index acea69346d..06640534b9 100644 --- a/src/modm/communication/xpcc/abstract_component.hpp +++ b/src/modm/communication/xpcc/abstract_component.hpp @@ -46,7 +46,7 @@ namespace xpcc * \see modm::Task * \see xpcc::Communicatable * - * \ingroup xpcc_comm + * \ingroup modm_communication_xpcc */ class AbstractComponent : public Communicatable { diff --git a/src/modm/communication/xpcc/backend/backend_interface.hpp b/src/modm/communication/xpcc/backend/backend_interface.hpp index 7b77766f81..04b8c6e469 100644 --- a/src/modm/communication/xpcc/backend/backend_interface.hpp +++ b/src/modm/communication/xpcc/backend/backend_interface.hpp @@ -21,8 +21,8 @@ #include "header.hpp" /** - * \ingroup xpcc_comm - * \defgroup backend Backend + * \ingroup modm_communication_xpcc + * \defgroup modm_communication_xpcc_backend Backend * \brief The backend provides connection to different hardware modules * to transmit the communication. * @@ -37,7 +37,7 @@ namespace xpcc * * All backends have to implement this interface. * - * \ingroup xpcc_comm + * \ingroup modm_communication_xpcc_backend * \author Martin Rosekeit, Fabian Greif */ class BackendInterface diff --git a/src/modm/communication/xpcc/backend/can/connector.hpp b/src/modm/communication/xpcc/backend/can/connector.hpp index eb734e89cb..f5c7d8fefa 100644 --- a/src/modm/communication/xpcc/backend/can/connector.hpp +++ b/src/modm/communication/xpcc/backend/can/connector.hpp @@ -118,7 +118,7 @@ namespace xpcc * * \todo timeout * - * \ingroup backend + * \ingroup modm_communication_xpcc_backend */ template class CanConnector : protected CanConnectorBase, public BackendInterface diff --git a/src/modm/communication/xpcc/backend/header.hpp b/src/modm/communication/xpcc/backend/header.hpp index 2e380d6a56..89da3c6cd7 100644 --- a/src/modm/communication/xpcc/backend/header.hpp +++ b/src/modm/communication/xpcc/backend/header.hpp @@ -24,7 +24,7 @@ namespace xpcc /** * \brief Header of a packet * - * \ingroup backend + * \ingroup modm_communication_xpcc_backend * \author Martin Rosekeit * \author Fabian Greif */ diff --git a/src/modm/communication/xpcc/backend/tipc.hpp b/src/modm/communication/xpcc/backend/tipc.hpp index 09bef77893..a827e0b622 100644 --- a/src/modm/communication/xpcc/backend/tipc.hpp +++ b/src/modm/communication/xpcc/backend/tipc.hpp @@ -12,7 +12,7 @@ // ---------------------------------------------------------------------------- /** - * \ingroup backend + * \ingroup modm_communication_xpcc_backend * \defgroup tipc (TIPC) Transparent Inter-Process Communication * \brief Interface to the Linux-TIPC. * diff --git a/src/modm/communication/xpcc/backend/zeromq/connector.hpp b/src/modm/communication/xpcc/backend/zeromq/connector.hpp index 3aa91d4a4e..1473ed040d 100644 --- a/src/modm/communication/xpcc/backend/zeromq/connector.hpp +++ b/src/modm/communication/xpcc/backend/zeromq/connector.hpp @@ -41,7 +41,7 @@ class ZeroMQConnectorBase /** * @brief ZeroMQ communication backend for hosted * - * @ingroup backend + * @ingroup modm_communication_xpcc_backend * * @author strongly-typed * @author Christopher Durand diff --git a/src/modm/communication/xpcc/backend/zeromq/reader.hpp b/src/modm/communication/xpcc/backend/zeromq/reader.hpp index 34526711c7..b89b5ea380 100644 --- a/src/modm/communication/xpcc/backend/zeromq/reader.hpp +++ b/src/modm/communication/xpcc/backend/zeromq/reader.hpp @@ -34,7 +34,7 @@ namespace xpcc /** * @brief Reads packets from a zmqpp socket in a background thread * - * @ingroup backend + * @ingroup modm_communication_xpcc_backend * * @author Christopher Durand * @author strongly-typed diff --git a/src/modm/communication/xpcc/communicatable.hpp b/src/modm/communication/xpcc/communicatable.hpp index 3df1b2723c..427474eae9 100644 --- a/src/modm/communication/xpcc/communicatable.hpp +++ b/src/modm/communication/xpcc/communicatable.hpp @@ -23,7 +23,7 @@ namespace xpcc * * Needed to have a common base class for the callback classes. * - * \ingroup xpcc_comm + * \ingroup modm_communication_xpcc */ class Communicatable { diff --git a/src/modm/communication/xpcc/communicatable_task.hpp b/src/modm/communication/xpcc/communicatable_task.hpp index 881b7f8bf9..2bc5b62c75 100644 --- a/src/modm/communication/xpcc/communicatable_task.hpp +++ b/src/modm/communication/xpcc/communicatable_task.hpp @@ -29,7 +29,7 @@ namespace xpcc * @see xpcc::Communicator * @see xpcc::Communicatable * - * @ingroup xpcc_com + * @ingroup modm_communication_xpcc * @author Fabian Greif */ class CommunicatableTask : public modm::Task, public Communicatable diff --git a/src/modm/communication/xpcc/communicator.hpp b/src/modm/communication/xpcc/communicator.hpp index 24e70bfd65..d92095f050 100644 --- a/src/modm/communication/xpcc/communicator.hpp +++ b/src/modm/communication/xpcc/communicator.hpp @@ -34,7 +34,7 @@ namespace xpcc * This class is just a forwarder to the Dispatcher like AbstractComponent * it also does. * - * \ingroup xpcc_comm + * \ingroup modm_communication_xpcc */ class Communicator : public Communicatable { diff --git a/src/modm/communication/xpcc/dispatcher.hpp.in b/src/modm/communication/xpcc/dispatcher.hpp.in index 1cb936bba1..a61318a81b 100644 --- a/src/modm/communication/xpcc/dispatcher.hpp.in +++ b/src/modm/communication/xpcc/dispatcher.hpp.in @@ -34,7 +34,7 @@ namespace xpcc * \todo Documentation * * \author Georgi Grinshpun - * \ingroup xpcc_comm + * \ingroup modm_communication_xpcc */ class Dispatcher { diff --git a/src/modm/communication/xpcc/module.lb b/src/modm/communication/xpcc/module.lb index cbb1b8acca..3647451215 100644 --- a/src/modm/communication/xpcc/module.lb +++ b/src/modm/communication/xpcc/module.lb @@ -13,6 +13,7 @@ def init(module): module.parent = "communication" module.name = "xpcc" + module.description = "Cross Platform Component Communication (XPCC)" def prepare(module, options): module.depends( diff --git a/src/modm/communication/xpcc/postman/dynamic_postman.hpp b/src/modm/communication/xpcc/postman/dynamic_postman.hpp index 0a91800591..bd22ebc46b 100644 --- a/src/modm/communication/xpcc/postman/dynamic_postman.hpp +++ b/src/modm/communication/xpcc/postman/dynamic_postman.hpp @@ -36,7 +36,7 @@ namespace xpcc * * On hosted however, this class allows for much easier registering of callbacks. * - * @ingroup xpcc_comm + * @ingroup modm_communication_xpcc * @author Niklas Hauser */ class DynamicPostman : public Postman diff --git a/src/modm/communication/xpcc/postman/postman.hpp b/src/modm/communication/xpcc/postman/postman.hpp index b2b7f3860f..48728d99f8 100644 --- a/src/modm/communication/xpcc/postman/postman.hpp +++ b/src/modm/communication/xpcc/postman/postman.hpp @@ -28,7 +28,7 @@ namespace xpcc * The Postman class is responsible of delivering messages the the * components. * - * \ingroup xpcc_comm + * \ingroup modm_communication_xpcc */ class Postman { diff --git a/src/modm/communication/xpcc/postman/response.hpp b/src/modm/communication/xpcc/postman/response.hpp index a15f9bd052..bc03004b4e 100644 --- a/src/modm/communication/xpcc/postman/response.hpp +++ b/src/modm/communication/xpcc/postman/response.hpp @@ -22,7 +22,7 @@ namespace xpcc /** * Response to an action call. * - * @ingroup xpcc_comm + * @ingroup modm_communication_xpcc */ enum class Response : bool @@ -34,7 +34,7 @@ Response : bool /** * Action Response with optional return data. * - * @ingroup xpcc_comm + * @ingroup modm_communication_xpcc */ template< typename T = void> class ActionResult diff --git a/src/modm/communication/xpcc/response_callback.hpp b/src/modm/communication/xpcc/response_callback.hpp index 289e36db94..02a51687a6 100644 --- a/src/modm/communication/xpcc/response_callback.hpp +++ b/src/modm/communication/xpcc/response_callback.hpp @@ -31,7 +31,7 @@ namespace xpcc * * Is a \b Functor. * - * \ingroup xpcc_comm + * \ingroup modm_communication_xpcc */ class ResponseCallback { diff --git a/src/modm/communication/xpcc/response_handle.hpp b/src/modm/communication/xpcc/response_handle.hpp index 72bd8fd1ec..ec93cd303e 100644 --- a/src/modm/communication/xpcc/response_handle.hpp +++ b/src/modm/communication/xpcc/response_handle.hpp @@ -23,7 +23,7 @@ namespace xpcc /** * \brief Response to an action call * - * \ingroup xpcc_comm + * \ingroup modm_communication_xpcc */ class ResponseHandle { diff --git a/src/modm/container/container.hpp b/src/modm/container/container.hpp index 9b32c5c885..bf3d1b6c61 100644 --- a/src/modm/container/container.hpp +++ b/src/modm/container/container.hpp @@ -10,89 +10,6 @@ */ // ---------------------------------------------------------------------------- -/** -\defgroup container Containers -\brief Common data structures (list, queue etc.) - -A container is a holder object that stores a collection other objects -(its elements). They are implemented as class templates, which allows a great -flexibility in the types supported as elements. - -Many containers have several member functions in common, and share -functionalities. The decision of which type of container to use for a specific -need does not generally depend only on the functionality offered by the -container, but also on the efficiency of some of its members (complexity). -This is especially true for sequence containers, which offer different -trade-offs in complexity between inserting/removing elements and accessing -them. - -modm::Stack and modm::Queue are implemented as container adaptors. Container -adaptors are not full container classes, but classes that provide a specific interface -relying on an object of one of the container classes (such as modm::BoundedDeque or -modm::LinkedList) to handle the elements. The underlying container is encapsulated -in such a way that its elements are accessed by the members of the container -class independently of the underlying container class used. - -Sequence containers: - - modm::DynamicArray - - modm::LinkedList - - modm::DoublyLinkedList - - modm::BoundedDeque - -Container adaptors: - - modm::Queue - - modm::Stack - - - modm::BoundedStack - - modm::BoundedQueue - -Other: - - modm::SmartPointer - - modm::Pair - -Two special containers worth mentioning hide in \ref atomic "atomic" section: - - modm::atomic::Queue - - modm::atomic::Container - -The first is a simple, interrupt-save queue (but only for the AVRs). -Whenever you need an to exchange data between a interrupt routine and -the normal program consider using this queue. - -The atomic container wraps objects and provides atomic access to -them. This comes in handy when simple objects are accessed by an interrupt -and the main program. The container provides secure access without much work -in this case. - -

Generic Interface

- -All implementation share a common set of function. Not every container implement -every one of it, only a subset which is sufficient for the container. - - - append - - prepend - - (insert) - - removeFront - - removeBack - - (remove) - - getFront - - getBack - - - push (only Stack and Queue) - - pop (only Stack and Queue) - - get (only Stack and Queue) - - - at - - operator [] - - - clear - - - isEmpty - - isFull - - getSize - - getMaxSize - - getCapacity -*/ - #include "container/deque.hpp" #include "container/queue.hpp" #include "container/stack.hpp" diff --git a/src/modm/container/deque.hpp b/src/modm/container/deque.hpp index fe7ad6d5f6..8840d37a8b 100644 --- a/src/modm/container/deque.hpp +++ b/src/modm/container/deque.hpp @@ -49,7 +49,7 @@ namespace modm * a pop-operation. You have to do this by yourself! * * \author Fabian Greif - * \ingroup container + * \ingroup modm_container */ template diff --git a/src/modm/container/doubly_linked_list.hpp b/src/modm/container/doubly_linked_list.hpp index c636a22ddf..e7f8eb4920 100644 --- a/src/modm/container/doubly_linked_list.hpp +++ b/src/modm/container/doubly_linked_list.hpp @@ -27,7 +27,7 @@ namespace modm * \tparam T type of list entries * * \author Fabian Greif - * \ingroup container + * \ingroup modm_container */ template > class DoublyLinkedList diff --git a/src/modm/container/dynamic_array.hpp b/src/modm/container/dynamic_array.hpp index 93ff455e61..83b1359520 100644 --- a/src/modm/container/dynamic_array.hpp +++ b/src/modm/container/dynamic_array.hpp @@ -41,7 +41,7 @@ namespace modm * function DynamicArray::reserve(). * * \author Fabian Greif - * \ingroup container + * \ingroup modm_container */ template > class DynamicArray diff --git a/src/modm/container/linked_list.hpp b/src/modm/container/linked_list.hpp index 7b92f416ee..9a4984d095 100644 --- a/src/modm/container/linked_list.hpp +++ b/src/modm/container/linked_list.hpp @@ -32,7 +32,7 @@ namespace modm * classes from modm::allocator namespace. * * \author Fabian Greif - * \ingroup container + * \ingroup modm_container */ template > class LinkedList diff --git a/src/modm/container/module.lb b/src/modm/container/module.lb index c592cd2043..ae756d9ab2 100644 --- a/src/modm/container/module.lb +++ b/src/modm/container/module.lb @@ -14,6 +14,7 @@ def init(module): module.name = "container" + module.description = FileReader("module.md") def prepare(module, options): diff --git a/src/modm/container/module.md b/src/modm/container/module.md new file mode 100644 index 0000000000..acb27138ba --- /dev/null +++ b/src/modm/container/module.md @@ -0,0 +1,83 @@ +# Containers + +A container is a holder object that stores a collection other objects (its +elements). They are implemented as class templates, which allows a great +flexibility in the types supported as elements. + +Many containers have several member functions in common, and share +functionalities. The decision of which type of container to use for a specific +need does not generally depend only on the functionality offered by the +container, but also on the efficiency of some of its members (complexity). +This is especially true for sequence containers, which offer different +trade-offs in complexity between inserting/removing elements and accessing +them. + +`modm::Stack` and `modm::Queue` are implemented as container adapters. Container +adapters are not full container classes, but classes that provide a specific +interface relying on an object of one of the container classes (such as +`modm::BoundedDeque` or `modm::LinkedList`) to handle the elements. +The underlying container is encapsulated in such a way that its elements are +accessed by the members of the container class independently of the underlying +container class used. + +Sequence containers: + +- `modm::DynamicArray` +- `modm::LinkedList` +- `modm::DoublyLinkedList` +- `modm::BoundedDeque` + +Container adapters: + +- `modm::Queue` +- `modm::Stack` +- `modm::BoundedStack` +- `modm::BoundedQueue` + +Other: + +- `modm::SmartPointer` +- `modm::Pair` + +Two special containers hiding in the `modm:architecture:atomic` module: + +- `modm::atomic::Queue` +- `modm::atomic::Container` + +The first is a simple, interrupt-safe queue (but only for the AVRs). +Whenever you need to exchange data between a interrupt routine and the normal +program consider using this queue. + +The atomic container wraps objects and provides atomic access to +them. This comes in handy when simple objects are accessed by an interrupt +and the main program. The container provides secure access without much work +in this case. + +## Generic Interface + +All implementation share a common set of function. Not every container implement +every one of it, only a subset which is sufficient for the container. + +- append +- prepend +- (insert) +- removeFront +- removeBack +- (remove) +- getFront +- getBack + +- push (only Stack and Queue) +- pop (only Stack and Queue) +- get (only Stack and Queue) + +- at +- operator[] + +- clear + +- isEmpty +- isFull +- getSize +- getMaxSize +- getCapacity \ No newline at end of file diff --git a/src/modm/container/pair.hpp b/src/modm/container/pair.hpp index 4d67b54757..fce0703e03 100644 --- a/src/modm/container/pair.hpp +++ b/src/modm/container/pair.hpp @@ -60,7 +60,7 @@ namespace modm * Until then just ignore that you can access them directly ;-) * * \author Fabian Greif - * \ingroup container + * \ingroup modm_container */ template class Pair diff --git a/src/modm/container/queue.hpp b/src/modm/container/queue.hpp index e5bacc6b46..dc98bc42ec 100644 --- a/src/modm/container/queue.hpp +++ b/src/modm/container/queue.hpp @@ -32,7 +32,7 @@ namespace modm * \see Deque() * * \author Fabian Greif - * \ingroup container + * \ingroup modm_container */ template @@ -109,7 +109,7 @@ namespace modm // ------------------------------------------------------------------------ /** * \brief Bounded queue - * \ingroup container + * \ingroup modm_container */ template @@ -97,7 +97,7 @@ namespace modm /** * \brief Bounded stack * - * \ingroup container + * \ingroup modm_container */ template */ class Logger : public ::modm::IOStream @@ -96,7 +96,7 @@ namespace modm * MODM_LOG_DEBUG, MODM_LOG_INFO, MODM_LOG_WARNING and * MODM_LOG_ERROR macros. * - * \ingroup logger + * \ingroup modm_debug */ //\{ extern Logger debug; ///< log device to take messages on DEBUG level @@ -115,7 +115,7 @@ namespace modm /** * \brief Turn off messages print - * \ingroup logger + * \ingroup modm_debug */ #define MODM_LOG_OFF \ if ( true ){} \ @@ -123,7 +123,7 @@ namespace modm /** * \brief Output stream for debug messages - * \ingroup logger + * \ingroup modm_debug */ #define MODM_LOG_DEBUG \ if (MODM_LOG_LEVEL > modm::log::DEBUG){} \ @@ -131,7 +131,7 @@ namespace modm /** * \brief Output stream for info messages - * \ingroup logger + * \ingroup modm_debug */ #define MODM_LOG_INFO \ if (MODM_LOG_LEVEL > modm::log::INFO){} \ @@ -139,7 +139,7 @@ namespace modm /** * \brief Output stream for warnings - * \ingroup logger + * \ingroup modm_debug */ #define MODM_LOG_WARNING \ if (MODM_LOG_LEVEL > modm::log::WARNING){} \ @@ -147,7 +147,7 @@ namespace modm /** * \brief Output stream for error messages - * \ingroup logger + * \ingroup modm_debug */ #define MODM_LOG_ERROR \ if (MODM_LOG_LEVEL > modm::log::ERROR){} \ @@ -161,7 +161,7 @@ namespace modm * In contrast to \c __FILE__ the path to the file is omitted (if this feature * is available, otherwise this macro will resolve to \c __FILE__). * - * \ingroup logger + * \ingroup modm_debug */ #define FILENAME @@ -185,7 +185,7 @@ namespace modm * file.cpp (123) >> ... something has happened ... * \endcode * - * \ingroup logger + * \ingroup modm_debug */ #define MODM_FILE_INFO diff --git a/src/modm/debug/logger/style.hpp b/src/modm/debug/logger/style.hpp index 7a188adf8b..0a202a4450 100644 --- a/src/modm/debug/logger/style.hpp +++ b/src/modm/debug/logger/style.hpp @@ -24,7 +24,7 @@ namespace modm /** * \brief This is an empty style. * - * \ingroup logger + * \ingroup modm_debug * \author Martin Rosekeit */ class DefaultStyle @@ -72,7 +72,7 @@ namespace modm * the given way and pass it to the next style class or device. * * - * \ingroup logger + * \ingroup modm_debug * \author Martin Rosekeit */ template < typename STYLE = DefaultStyle > diff --git a/src/modm/debug/logger/style/prefix.hpp b/src/modm/debug/logger/style/prefix.hpp index 97ecdd7586..bc399211f1 100644 --- a/src/modm/debug/logger/style/prefix.hpp +++ b/src/modm/debug/logger/style/prefix.hpp @@ -33,7 +33,7 @@ namespace modm * modm::log::Logger loggerPrefix( loggerDevicePrefix ); * \endcode * - * \ingroup logger + * \ingroup modm_debug * \author Martin Rosekeit */ template diff --git a/src/modm/debug/logger/style/std_colour.hpp b/src/modm/debug/logger/style/std_colour.hpp index 975d1b771a..6fea3a3837 100644 --- a/src/modm/debug/logger/style/std_colour.hpp +++ b/src/modm/debug/logger/style/std_colour.hpp @@ -41,7 +41,7 @@ namespace modm * * \see http://mathias-kettner.de/lw_farbige_ausgabe_auf_der_konsole.html * - * \ingroup logger + * \ingroup modm_debug * \author Martin Rosekeit */ template diff --git a/src/modm/debug/logger/style_wrapper.hpp b/src/modm/debug/logger/style_wrapper.hpp index 402bbb64d0..c9c2af1926 100644 --- a/src/modm/debug/logger/style_wrapper.hpp +++ b/src/modm/debug/logger/style_wrapper.hpp @@ -25,7 +25,7 @@ namespace modm /** * \brief Wrapper to use the Style as a IODevice in the Logger * - * \ingroup logger + * \ingroup modm_debug * \author Martin Rosekeit */ template < typename STYLE > diff --git a/src/modm/debug/module.lb b/src/modm/debug/module.lb index a5727d8319..c7488572a1 100644 --- a/src/modm/debug/module.lb +++ b/src/modm/debug/module.lb @@ -14,6 +14,7 @@ def init(module): module.name = "debug" + module.description = FileReader("module.md") def prepare(module, options): diff --git a/src/modm/debug/module.md b/src/modm/debug/module.md new file mode 100644 index 0000000000..627300dcb9 --- /dev/null +++ b/src/modm/debug/module.md @@ -0,0 +1,56 @@ +# Logging + +The `modm::log::Logger` uses a `modm::IOStream` to read messages and write them +to a given output device. + +Write a log message with streams: + +```cpp +MODM_LOG_DEBUG << "i=" << i << ", y=" << y << modm::flush; +``` + +The name of the stream represents the log level of the message. Available are: + +- `MODM_LOG_DEBUG` +- `MODM_LOG_INFO` +- `MODM_LOG_WARNING` +- `MODM_LOG_ERROR` + +A log message can also be generated separately: + +```cpp +int a[3] = {1,2,3}; +MODM_LOG_DEBUG << "a = "; +for(int i = 0; i < sizeof(a); ++i) { + MODM_LOG_DEBUG << a[i] << ", "; +} +MODM_LOG_DEBUG << modm::flush; +``` + +### Flow of a call + +This is to give an estimation how many resources a call of the logger use. +All considerations are for a PC program. + +The given call is: + +```cpp +MODM_LOG_DEBUG << 123456; +``` + +The macro resolves to: + +```cpp +if (MODM_LOG_LEVEL <= modm::log::DEBUG) + modm::log::debug +``` + +- `modm::log::debug` is an instance of `modm::Logger`: + Call of `modm::Logger::operator << (T)` (with `T = int32_t`) which is inline + - `IOStream::operator << (T)` (with `T = int32_t`) is inline + - `IOStream::writeInteger(int32_t)` +- `IOStream::writeInteger(int32_t)` will create the formatted string +- virtual call of `IODevice::write(const char*)` +- redirect to `std::cout` + +In sum there are two nested method calls with one of them being virtual. diff --git a/src/modm/driver/adc/ad7280a.hpp b/src/modm/driver/adc/ad7280a.hpp index 2d5d6ef836..005d65a889 100644 --- a/src/modm/driver/adc/ad7280a.hpp +++ b/src/modm/driver/adc/ad7280a.hpp @@ -25,6 +25,7 @@ class Ad7280aTest; namespace modm { + /// @ingroup modm_driver_ad7280a namespace ad7280a { enum Cell @@ -135,30 +136,12 @@ namespace modm } /** - * Lithium Ion Battery Monitoring System. - * - * The AD7280A is monitor for lithium ion battery packs with up to six - * cells. It contains six 12-ADCs with 1µs conversion per channel and - * a cell balancing interface. - * Up to 7 devices can be added through a Daisy-Chain interface (chain of - * 8 devices). - * - * - cell voltage accuracy of ±1.6 mV. - * - Supply voltage 8-30V - * - six auxiliary ADC input channels - * - * Recommended SPI Clk frequency is 1 MHz. With a 1 MHz Clk, it takes - * approximately 1.54 ms to read back the voltage conversions on 48 channels. - * - * When addressing devices in the chain directly the frequency needs to - * be lower than 1 MHz because delays introduced in each stage of the chain. - * * \tparam Spi SPI interface * \tparam Cs Chip-Select Pin * \tparam Cnvst Conversion Start Pin * \tparam N Number of devices in a daisy chain (1..8) * - * @ingroup driver_adc + * @ingroup modm_driver_ad7280a */ template class Ad7280a diff --git a/src/modm/driver/adc/ad7280a.lb b/src/modm/driver/adc/ad7280a.lb index f83415546b..df60264348 100644 --- a/src/modm/driver/adc/ad7280a.lb +++ b/src/modm/driver/adc/ad7280a.lb @@ -14,6 +14,25 @@ def init(module): module.parent = "driver" module.name = "ad7280a" + module.description = """\ +# AD7280A Lithium Ion Battery Monitoring System + +The AD7280A is monitor for lithium ion battery packs with up to six +cells. It contains six 12-ADCs with 1µs conversion per channel and +a cell balancing interface. +Up to 7 devices can be added through a Daisy-Chain interface (chain of +8 devices). + +- cell voltage accuracy of ±1.6 mV. +- Supply voltage 8-30V +- six auxiliary ADC input channels + +Recommended SPI Clk frequency is 1 MHz. With a 1 MHz Clk, it takes +approximately 1.54 ms to read back the voltage conversions on 48 channels. + +When addressing devices in the chain directly the frequency needs to +be lower than 1 MHz because delays introduced in each stage of the chain. +""" def prepare(module, options): diff --git a/src/modm/driver/adc/ad7928.hpp b/src/modm/driver/adc/ad7928.hpp index 8a59a8202c..26d0c94cdc 100644 --- a/src/modm/driver/adc/ad7928.hpp +++ b/src/modm/driver/adc/ad7928.hpp @@ -26,6 +26,7 @@ namespace modm { +/// @ingroup modm_driver_ad7928 struct ad7928 { public: @@ -147,17 +148,11 @@ struct ad7928 }; // struct ad7928 /** - * Driver for AD7928/AD7918/AD7908 ADC - * - * The AD7928/AD7918/AD7908 are, respectively, 12/10/8 bit analog-digital converters. - * The conversion time is determined by the Spi clock frequency. A maximum Spi clock - * of 20 Mhz is supported. - * * @tparam SpiMaster SpiMaster interface * @tparam Cs Chip-select pin * * @author Christopher Durand - * @ingroup driver_adc + * @ingroup modm_driver_ad7928 */ template class Ad7928 : public ad7928, public modm::SpiDevice, protected modm::NestedResumable<3> diff --git a/src/modm/driver/adc/ad7928.lb b/src/modm/driver/adc/ad7928.lb index 12b7e2b781..edeb3e423e 100644 --- a/src/modm/driver/adc/ad7928.lb +++ b/src/modm/driver/adc/ad7928.lb @@ -14,6 +14,13 @@ def init(module): module.parent = "driver" module.name = "ad7928" + module.description = """\ +# AD79x8 ADC + +The AD7928/AD7918/AD7908 are, respectively, 12/10/8 bit analog-digital converters. +The conversion time is determined by the Spi clock frequency. A maximum Spi clock +of 20 Mhz is supported. +""" def prepare(module, options): diff --git a/src/modm/driver/adc/adc_sampler.hpp b/src/modm/driver/adc/adc_sampler.hpp index 00237db35d..957c86117a 100644 --- a/src/modm/driver/adc/adc_sampler.hpp +++ b/src/modm/driver/adc/adc_sampler.hpp @@ -21,33 +21,11 @@ namespace modm { /** - * Generic ADC wrapper for (over-)sampling analog inputs. - * - * This template class stores 8, 16 or 32bit ADC values in a buffer and - * provides an easy interface for managing that data. - * - * The code will read the ADC channels you specify in an array. - * This means you can remap the ADC channels in the order that they - * should appear in the buffer. - * The array must obviously have as many elements as channels! - * For example, if channels 0,2,7 are connected, but the sensors - * are in the wrong order, just remap them with the array {7,0,2}. - * - * To make use of oversampling and averaging, set `Oversamples > 0`. - * This will loop `Oversamples` times through the ADC channels, adding - * the average of each result to the buffer. - * - * This class will choose the smallest data width for you. - * It decides this by adding the ADC resolution and the oversample size - * and choosing the next smallest size (not larger than 32bit though!). - * - * @warning The averaging algorithm only works for unsigned ADC data! - * * @tparam AdcInterrupt a class implementing the AdcInterrupt interface * @tparam Channels number of ADC channels connected to sensor(s) >= 1 * @tparam Oversamples # of samples to average for each channel * - * @ingroup driver_adc + * @ingroup modm_driver_adc_sampler * @author Niklas Hauser */ template < class AdcInterrupt, uint8_t Channels, uint32_t Oversamples=1 > diff --git a/src/modm/driver/adc/adc_sampler.lb b/src/modm/driver/adc/adc_sampler.lb index 5d5e65c59e..89e5d31cda 100644 --- a/src/modm/driver/adc/adc_sampler.lb +++ b/src/modm/driver/adc/adc_sampler.lb @@ -15,6 +15,30 @@ def init(module): module.parent = "driver" module.name = "adc_sampler" + module.description = """\ +# Oversampling of ADC inputs + +This template class stores 8, 16 or 32bit ADC values in a buffer and +provides an easy interface for managing that data. + +The code will read the ADC channels you specify in an array. +This means you can remap the ADC channels in the order that they +should appear in the buffer. +The array must obviously have as many elements as channels! +For example, if channels 0,2,7 are connected, but the sensors +are in the wrong order, just remap them with the array {7,0,2}. + +To make use of oversampling and averaging, set `Oversamples > 0`. +This will loop `Oversamples` times through the ADC channels, adding +the average of each result to the buffer. + +This class will choose the smallest data width for you. +It decides this by adding the ADC resolution and the oversample size +and choosing the next smallest size (not larger than 32bit though!). + +!!!warning + The averaging algorithm only works for unsigned ADC data! +""" def prepare(module, options): diff --git a/src/modm/driver/bus/bitbang_memory_interface.hpp b/src/modm/driver/bus/bitbang_memory_interface.hpp index 076ec41f2b..4886840228 100644 --- a/src/modm/driver/bus/bitbang_memory_interface.hpp +++ b/src/modm/driver/bus/bitbang_memory_interface.hpp @@ -30,7 +30,7 @@ namespace modm * \tparam WR Write strobe GPIO pin * * \author strongly typed - * \ingroup driver_bus + * \ingroup modm_driver_memory_bus */ template < typename PORT, typename CS, diff --git a/src/modm/driver/bus/memory_bus.lb b/src/modm/driver/bus/memory_bus.lb index e45c365f8e..86d3f1d99a 100644 --- a/src/modm/driver/bus/memory_bus.lb +++ b/src/modm/driver/bus/memory_bus.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "driver" module.name = "memory_bus" + module.description = "Parallel Busses" def prepare(module, options): diff --git a/src/modm/driver/bus/tft_memory_bus.hpp b/src/modm/driver/bus/tft_memory_bus.hpp index 3ad0e73a7a..2992a290b3 100644 --- a/src/modm/driver/bus/tft_memory_bus.hpp +++ b/src/modm/driver/bus/tft_memory_bus.hpp @@ -20,7 +20,7 @@ namespace modm { /** * @author Fabian Greif - * @ingroup driver_bus + * @ingroup modm_driver_memory_bus */ class TftMemoryBus16Bit { @@ -69,7 +69,7 @@ class TftMemoryBus16Bit volatile uint16_t * const ptrData; }; -/// @ingroup driver_bus +/// @ingroup modm_driver_memory_bus class TftMemoryBus8Bit { public: @@ -123,7 +123,7 @@ class TftMemoryBus8Bit * 8080-style parallel bus made of a parallel PORT, chip select CS, read strobe RD and write strobe WR * * @author Sascha Schade - * @ingroup driver_bus + * @ingroup modm_driver_memory_bus */ template < typename PORT, /* Port */ @@ -186,7 +186,7 @@ class MemoryBus } }; -/// @ingroup driver_bus +/// @ingroup modm_driver_memory_bus template < typename PORT, /* Port */ typename CS, /* Chip select */ diff --git a/src/modm/driver/can/can_lawicel_formatter.hpp b/src/modm/driver/can/can_lawicel_formatter.hpp index 757211dbca..dadae2d6cd 100644 --- a/src/modm/driver/can/can_lawicel_formatter.hpp +++ b/src/modm/driver/can/can_lawicel_formatter.hpp @@ -21,19 +21,7 @@ namespace modm { -/** - * Converts MODM CAN messages (modm::can::Message) to and from the Lawicel string format (char *). - * - * Lawicel AB offers medium sized CAN to USB - * and CAN to RS232 converters. Their data format is widely used, including - * RCA's BotControl Java GUI and Fabian's USB2CAN dongle. - * - * This converter only understands messages of type 'r', 't', 'R' and 'T' which - * transmits CAN frames. It does not understand commands to change the baud rate et cetera. - * - * @ingroup driver_can - * @see http://www.lawicel.com/ - */ +/// @ingroup modm_driver_lawicel class CanLawicelFormatter { public: diff --git a/src/modm/driver/can/lawicel.lb b/src/modm/driver/can/lawicel.lb index 96fa8d4884..18d7f07e33 100644 --- a/src/modm/driver/can/lawicel.lb +++ b/src/modm/driver/can/lawicel.lb @@ -14,7 +14,17 @@ def init(module): module.parent = "driver" module.name = "lawicel" + module.description = """\ +# Lawicel Format Converter +Converts `modm::can::Message` to and from the Lawicel string format (`char *`). + +Lawicel AB (http://www.lawicel.com) offers medium sized CAN to USB and CAN to +RS232 converters. Their data format is widely used. + +This converter only understands messages of type 'r', 't', 'R' and 'T' which +transmits CAN frames. It does not understand commands to change the baud rate. +""" def prepare(module, options): module.depends(":architecture:can") diff --git a/src/modm/driver/can/mcp2515.cpp.in b/src/modm/driver/can/mcp2515.cpp.in index 8c7aaa069f..82ec183df2 100644 --- a/src/modm/driver/can/mcp2515.cpp.in +++ b/src/modm/driver/can/mcp2515.cpp.in @@ -19,7 +19,7 @@ namespace mcp2515 FLASH_STORAGE(uint8_t configuration[24]) = { -%% if options[":::MCP2515_clock"] == "16MHz" +%% if options["clock"] == "16MHz" // 10 kbps 0x04, // CNF3 @@ -61,7 +61,7 @@ FLASH_STORAGE(uint8_t configuration[24]) = BTLMODE | PHSEG11, 0, -%% elif options[":::MCP2515_clock"] == "20MHz" +%% elif options["clock"] == "20MHz" // 10 kbps 0x04, // CNF3 diff --git a/src/modm/driver/can/mcp2515.hpp b/src/modm/driver/can/mcp2515.hpp index 29b29eb248..c59089ae7f 100644 --- a/src/modm/driver/can/mcp2515.hpp +++ b/src/modm/driver/can/mcp2515.hpp @@ -24,11 +24,6 @@ #include "mcp2515_definitions.hpp" -/** - * \defgroup mcp2515 MCP2515 - * \ingroup driver_can - */ - /** * \name Restructure filter and mask bits for the MCP2515 * @@ -59,7 +54,7 @@ * * \warning Do not use this macro for variables, only for static values * known at compile-time. - * \ingroup mcp2515 + * \ingroup modm_driver_mcp2515 */ //\{ #if defined(__DOXYGEN__) @@ -115,7 +110,7 @@ namespace modm * need to do this by yourself before calling the initialize method! * * \author Fabian Greif - * \ingroup mcp2515 + * \ingroup modm_driver_mcp2515 */ template < typename SPI, typename CS, diff --git a/src/modm/driver/can/mcp2515.lb b/src/modm/driver/can/mcp2515.lb index a6de5f205f..6962a522d3 100644 --- a/src/modm/driver/can/mcp2515.lb +++ b/src/modm/driver/can/mcp2515.lb @@ -14,15 +14,15 @@ def init(module): module.parent = "driver" module.name = "mcp2515" + module.description = "MPC2515 External CAN Controller" def prepare(module, options): module.add_option( EnumerationOption( - name="MCP2515_clock", + name="clock", enumeration=["16MHz", "20MHz"], - description= - "Used clock for the MCP2515. The device configuration " + description="Used clock for the MCP2515. The device configuration " "is selected according to the clock speed.", default="16MHz")) diff --git a/src/modm/driver/can/mcp2515_definitions.hpp b/src/modm/driver/can/mcp2515_definitions.hpp index 76dc4223de..0f88b41b0e 100644 --- a/src/modm/driver/can/mcp2515_definitions.hpp +++ b/src/modm/driver/can/mcp2515_definitions.hpp @@ -25,7 +25,7 @@ namespace modm * Die Redundanten Adressen von z.B. dem Register CANSTAT * (0x0E, 0x1E, 0x2E, ...) wurden dabei nicht mit aufgelistet. * - * \ingroup mcp2515 + * \ingroup modm_driver_mcp2515 */ enum Register { @@ -154,7 +154,7 @@ namespace modm /** * \brief Bitdefinition von BFPCTRL - * \ingroup mcp2515 + * \ingroup modm_driver_mcp2515 */ enum BFPCTRL { @@ -168,7 +168,7 @@ namespace modm /** * \brief Bitdefinition von TXRTSCTRL - * \ingroup mcp2515 + * \ingroup modm_driver_mcp2515 */ enum TXRTSCTRL { @@ -182,7 +182,7 @@ namespace modm /** * \brief Bitdefinition von CANSTAT - * \ingroup mcp2515 + * \ingroup modm_driver_mcp2515 */ enum CANSTAT { @@ -196,7 +196,7 @@ namespace modm /** * \brief Bitdefinition von CANCTRL - * \ingroup mcp2515 + * \ingroup modm_driver_mcp2515 */ enum CANCTRL { @@ -211,7 +211,7 @@ namespace modm /** * \brief Bitdefinition von CNF3 - * \ingroup mcp2515 + * \ingroup modm_driver_mcp2515 */ enum CNF3 { @@ -223,7 +223,7 @@ namespace modm /** * \brief Bitdefinition von CNF2 - * \ingroup mcp2515 + * \ingroup modm_driver_mcp2515 */ enum CNF2 { @@ -239,7 +239,7 @@ namespace modm /** * \brief Bitdefinition von CNF1 - * \ingroup mcp2515 + * \ingroup modm_driver_mcp2515 */ enum CNF1 { @@ -255,7 +255,7 @@ namespace modm /** * \brief Bitdefinition von CANINTE - * \ingroup mcp2515 + * \ingroup modm_driver_mcp2515 */ enum CANINTE { @@ -271,7 +271,7 @@ namespace modm /** * \brief Bitdefinition von CANINTF - * \ingroup mcp2515 + * \ingroup modm_driver_mcp2515 */ enum CANINTF { @@ -287,7 +287,7 @@ namespace modm /** * \brief Bitdefinition von EFLG - * \ingroup mcp2515 + * \ingroup modm_driver_mcp2515 */ enum EFLG { @@ -303,7 +303,7 @@ namespace modm /** * \brief Bitdefinition von TXBnCTRL (n = 0, 1), 2) - * \ingroup mcp2515 + * \ingroup modm_driver_mcp2515 */ enum TXBnCTRL { @@ -317,7 +317,7 @@ namespace modm /** * \brief Bitdefinition von RXB0CTRL - * \ingroup mcp2515 + * \ingroup modm_driver_mcp2515 */ enum RXB0CTRL { @@ -331,7 +331,7 @@ namespace modm /** * \brief Bitdefinition von TXBnSIDL (n = 0, 1) - * \ingroup mcp2515 + * \ingroup modm_driver_mcp2515 */ enum TXBnSIDL { @@ -343,7 +343,7 @@ namespace modm * * \see RXM1, RXM0, RXRTR und FILHIT0 sind schon * für RXB0CTRL definiert - * \ingroup mcp2515 + * \ingroup modm_driver_mcp2515 */ enum RXB1CTRL { @@ -353,7 +353,7 @@ namespace modm /** * \brief Bitdefinition von RXBnSIDL (n = 0, 1) - * \ingroup mcp2515 + * \ingroup modm_driver_mcp2515 */ enum RXBnSIDL { @@ -365,7 +365,7 @@ namespace modm * \brief Bitdefinition von RXBnDLC (n = 0, 1) * * \see TXBnDLC (gleiche Bits) - * \ingroup mcp2515 + * \ingroup modm_driver_mcp2515 */ enum RXBnDLC { @@ -378,7 +378,7 @@ namespace modm /** * \brief Definition of the status register - * \ingroup mcp2515 + * \ingroup modm_driver_mcp2515 */ enum Status { @@ -394,7 +394,7 @@ namespace modm /** * \brief Definition of the receive status register - * \ingroup mcp2515 + * \ingroup modm_driver_mcp2515 */ enum RxStatus { diff --git a/src/modm/driver/color/tcs3414.hpp b/src/modm/driver/color/tcs3414.hpp index ce8d2afe61..82c01d78b3 100644 --- a/src/modm/driver/color/tcs3414.hpp +++ b/src/modm/driver/color/tcs3414.hpp @@ -30,7 +30,7 @@ namespace modm /** * \brief Settings to configure the digital color sensor TCS3414 / TCS3413 / TCS3415 / TCS3416. * \see Tcs3414 - * \ingroup driver_other + * \ingroup modm_driver_tcs3414 * * Device Address * TCS3413 0x29 @@ -148,7 +148,7 @@ struct tcs3414 * modm::i2c::Master * \see tcs3414 * \author David Hebbeker - * \ingroup driver_other + * \ingroup modm_driver_tcs3414 */ template < typename I2cMaster > class Tcs3414 : public tcs3414, public modm::I2cDevice< I2cMaster, 2 > diff --git a/src/modm/driver/color/tcs3414.lb b/src/modm/driver/color/tcs3414.lb index 6c961b813d..11b95caa24 100644 --- a/src/modm/driver/color/tcs3414.lb +++ b/src/modm/driver/color/tcs3414.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "driver" module.name = "tcs3414" + module.description = "TCS3414 Digital Color Sensor" def prepare(module, options): diff --git a/src/modm/driver/color/tcs3472.hpp b/src/modm/driver/color/tcs3472.hpp index 80cc4dde2d..e985251795 100644 --- a/src/modm/driver/color/tcs3472.hpp +++ b/src/modm/driver/color/tcs3472.hpp @@ -30,7 +30,7 @@ namespace modm /** * \brief Settings to configure the ams digital color sensor family tcs34721, -13, -15, 17 * \see tcs3472 - * \ingroup driver_other + * \ingroup modm_driver_tcs3472 * * Device Address * tcs34721 0x39 (with IR filter) @@ -110,7 +110,7 @@ struct tcs3472 * modm::i2c::Master * \see tcs3472 * \author David Hebbeker, Arjun Sarin - * \ingroup driver_other + * \ingroup modm_driver_tcs3472 */ template < typename I2cMaster > class Tcs3472 : public tcs3472, public modm::I2cDevice< I2cMaster, 2 > diff --git a/src/modm/driver/color/tcs3472.lb b/src/modm/driver/color/tcs3472.lb index ca40c9d32a..aa203a46f7 100644 --- a/src/modm/driver/color/tcs3472.lb +++ b/src/modm/driver/color/tcs3472.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "driver" module.name = "tcs3472" + module.description = "TCS3472X Digital Color Sensor" def prepare(module, options): diff --git a/src/modm/driver/dac/mcp4922.hpp b/src/modm/driver/dac/mcp4922.hpp index 464e442b89..304277b88a 100644 --- a/src/modm/driver/dac/mcp4922.hpp +++ b/src/modm/driver/dac/mcp4922.hpp @@ -32,7 +32,7 @@ namespace modm * * \see Datasheet * - * \ingroup driver_dac + * \ingroup modm_driver_mcp4922 * \author Fabian Greif */ template diff --git a/src/modm/driver/display.hpp b/src/modm/driver/display.hpp deleted file mode 100644 index 115c1b0ed4..0000000000 --- a/src/modm/driver/display.hpp +++ /dev/null @@ -1,35 +0,0 @@ -/* - * Copyright (c) 2009, Martin Rosekeit - * Copyright (c) 2009-2011, Fabian Greif - * Copyright (c) 2012-2014, Niklas Hauser - * Copyright (c) 2012, 2016, Sascha Schade - * - * This file is part of the modm project. - * - * This Source Code Form is subject to the terms of the Mozilla Public - * License, v. 2.0. If a copy of the MPL was not distributed with this - * file, You can obtain one at http://mozilla.org/MPL/2.0/. - */ -// ---------------------------------------------------------------------------- - -/** - * \defgroup driver_display Displays - * \brief Drivers to transfer bitmaps onto displays. - * - * \ingroup driver - */ - -#include "display/ea_dog.hpp" -#include "display/hd44780.hpp" -#include "display/ks0108.hpp" -#include "display/max7219matrix.hpp" -#include "display/nokia5110.hpp" -#include "display/nokia6610.hpp" -#include "display/parallel_tft.hpp" -#include "display/seven_segment.hpp" -#include "display/siemens_m55.hpp" -#include "display/siemens_s65.hpp" -#include "display/siemens_s75.hpp" -#include "display/ssd1306.hpp" -#include "display/st7036.hpp" -#include "display/st7565.hpp" diff --git a/src/modm/driver/display/ea_dog.hpp b/src/modm/driver/display/ea_dog.hpp index 642fd286c4..b023265d6a 100644 --- a/src/modm/driver/display/ea_dog.hpp +++ b/src/modm/driver/display/ea_dog.hpp @@ -32,7 +32,7 @@ namespace modm * SPI needs to operate in Mode 3. Maximum SPI frequency is 33 MHz. * * \see Datasheet - * \ingroup driver_display + * \ingroup modm_driver_ea_dog */ template class DogS102 : public St7565 @@ -57,7 +57,7 @@ namespace modm * \brief EA DOGM132x-5 * * \see Datasheet - * \ingroup lcd + * \ingroup modm_driver_ea_dog */ template class DogM132 : public St7565 @@ -82,7 +82,7 @@ namespace modm * \brief EA DOGM128x-6 * * \see Datasheet - * \ingroup lcd + * \ingroup modm_driver_ea_dog */ template class DogM128 : public St7565 @@ -107,7 +107,7 @@ namespace modm * \brief EA DOGL128x-6 * * \see Datasheet - * \ingroup lcd + * \ingroup modm_driver_ea_dog */ template class DogL128 : public St7565 @@ -137,7 +137,7 @@ namespace modm * * \todo Initialization * \see Datasheet - * \ingroup lcd + * \ingroup modm_driver_ea_dog */ template class DogM081 : public St7036 @@ -149,7 +149,7 @@ namespace modm * * \todo Initialization * \see Datasheet - * \ingroup lcd + * \ingroup modm_driver_ea_dog */ template class DogM162 : public St7036 @@ -161,7 +161,7 @@ namespace modm * * \todo Initialization * \see Datasheet - * \ingroup lcd + * \ingroup modm_driver_ea_dog */ template class DogM163 : public St7036 diff --git a/src/modm/driver/display/ea_dog.lb b/src/modm/driver/display/ea_dog.lb index 61f3aef5fb..090e474d34 100644 --- a/src/modm/driver/display/ea_dog.lb +++ b/src/modm/driver/display/ea_dog.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "driver" module.name = "ea_dog" + module.description = "EA-DOG Displays" def prepare(module, options): module.add_option( diff --git a/src/modm/driver/display/hd44780.hpp b/src/modm/driver/display/hd44780.hpp index 030818bbda..22007c5c03 100644 --- a/src/modm/driver/display/hd44780.hpp +++ b/src/modm/driver/display/hd44780.hpp @@ -22,7 +22,7 @@ namespace modm { /** - * Driver for HD447800 compatible displays + * Driver for HD44780 compatible displays * * This driver supports only one controller, with any configuration up to 80 * characters (most common: 8x1, 16x2, 20x4). @@ -38,7 +38,7 @@ namespace modm * * @author Fabian Greif * @author Niklas Hauser - * @ingroup driver_display + * @ingroup modm_driver_hd44780 */ template class Hd44780 : public CharacterDisplay @@ -98,7 +98,7 @@ class Hd44780 : public CharacterDisplay * @see http://en.wikipedia.org/wiki/HD44780_Character_LCD * * @author Niklas Hauser - * @ingroup driver_display + * @ingroup modm_driver_hd44780 */ template class Hd44780Dual : public CharacterDisplay diff --git a/src/modm/driver/display/hd44780.lb b/src/modm/driver/display/hd44780.lb index 03c9093147..ad9aa0f6db 100644 --- a/src/modm/driver/display/hd44780.lb +++ b/src/modm/driver/display/hd44780.lb @@ -15,6 +15,7 @@ def init(module): module.parent = "driver" module.name = "hd44780" + module.description = "HD44780 Displays" def prepare(module, options): module.depends( diff --git a/src/modm/driver/display/hd44780_base.hpp b/src/modm/driver/display/hd44780_base.hpp index 35b8045bc6..0b39e74127 100644 --- a/src/modm/driver/display/hd44780_base.hpp +++ b/src/modm/driver/display/hd44780_base.hpp @@ -36,7 +36,7 @@ namespace modm * @see http://en.wikipedia.org/wiki/HD44780_Character_LCD * * @author Niklas Hauser - * @ingroup lcd + * @ingroup modm_driver_hd44780 */ template class Hd44780Base diff --git a/src/modm/driver/display/ks0108.hpp b/src/modm/driver/display/ks0108.hpp index c45d20a54b..dbe12d4672 100644 --- a/src/modm/driver/display/ks0108.hpp +++ b/src/modm/driver/display/ks0108.hpp @@ -37,7 +37,7 @@ namespace modm * GPIO_PORT() for more details. * * \author Fabian Greif - * \ingroup driver_display + * \ingroup modm_driver_ks0108 */ template < typename E, typename RW, typename RS, typename PIN_CS1, typename PIN_CS2, typename PORT > diff --git a/src/modm/driver/display/max7219.lb b/src/modm/driver/display/max7219.lb index 60f1e5b821..b1679c164c 100644 --- a/src/modm/driver/display/max7219.lb +++ b/src/modm/driver/display/max7219.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "driver" module.name = "max7219" + module.description = "MAX7219 Display" def prepare(module, options): module.depends( diff --git a/src/modm/driver/display/max7219matrix.hpp b/src/modm/driver/display/max7219matrix.hpp index 703ec18459..c6a00486a6 100644 --- a/src/modm/driver/display/max7219matrix.hpp +++ b/src/modm/driver/display/max7219matrix.hpp @@ -28,7 +28,7 @@ namespace modm * An arbitrary number of these chips can be daisy-chained * * @author Sascha Schade - * @ingroup driver_display + * @ingroup modm_driver_max7219 */ template < typename SPI, typename CS, uint8_t MODULES = 1 > class Max7219 @@ -153,7 +153,7 @@ class Max7219 * @tparam ROW Number of modules placed vertically * * 8x8 LED modules with MAX7219 are easily and cheaply available. - * + * @ingroup modm_driver_max7219 */ template < typename SPI, typename CS, uint8_t COLUMNS = 1, uint8_t ROWS = 1 > class Max7219matrix : public BufferedGraphicDisplay< 8 * COLUMNS, 8 * ROWS > diff --git a/src/modm/driver/display/nokia5110.hpp b/src/modm/driver/display/nokia5110.hpp index 876a02a7dc..7fe6512a56 100644 --- a/src/modm/driver/display/nokia5110.hpp +++ b/src/modm/driver/display/nokia5110.hpp @@ -25,7 +25,7 @@ namespace modm * Cheap, monochrome graphical display with SPI interface. * Maximum SPI frequency is 4 MHz. * - * \ingroup driver_display + * \ingroup modm_driver_nokia5110 */ template < typename Spi, typename Ce, typename Dc, typename Reset > class Nokia5110 : public BufferedGraphicDisplay< 84, 48 > diff --git a/src/modm/driver/display/nokia5110.lb b/src/modm/driver/display/nokia5110.lb index 476a5e92e7..f7332edf03 100644 --- a/src/modm/driver/display/nokia5110.lb +++ b/src/modm/driver/display/nokia5110.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "driver" module.name = "nokia5110" + module.description = "Nokia 5110 Displays" def prepare(module, options): module.depends( diff --git a/src/modm/driver/display/nokia6610.hpp b/src/modm/driver/display/nokia6610.hpp index 3b3d89ec87..003fdf3ca1 100644 --- a/src/modm/driver/display/nokia6610.hpp +++ b/src/modm/driver/display/nokia6610.hpp @@ -31,7 +31,7 @@ namespace modm * * GE12 not implemented yet * - * \ingroup driver_display + * \ingroup modm_driver_nokia6610 */ template class Nokia6610 : public BufferedGraphicDisplay<130, 128> diff --git a/src/modm/driver/display/parallel_tft.hpp b/src/modm/driver/display/parallel_tft.hpp index f437c29b53..ca2c6539ac 100644 --- a/src/modm/driver/display/parallel_tft.hpp +++ b/src/modm/driver/display/parallel_tft.hpp @@ -27,7 +27,7 @@ namespace modm * - WaveShare 3,2" TFT (Model B), Controller SSD1289 * * @author Fabian Greif - * @ingroup driver_display + * @ingroup modm_driver_parallel_tft_display */ template class ParallelTft : public GraphicDisplay diff --git a/src/modm/driver/display/parallel_tft.lb b/src/modm/driver/display/parallel_tft.lb index e2c055174d..3f2c2e9c51 100644 --- a/src/modm/driver/display/parallel_tft.lb +++ b/src/modm/driver/display/parallel_tft.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "driver" module.name = "parallel_tft_display" + module.description = "Parallel Bus TFT Display" def prepare(module, options): module.depends( diff --git a/src/modm/driver/display/sdl_display.hpp b/src/modm/driver/display/sdl_display.hpp index d14260ce1e..1dc5ecb440 100644 --- a/src/modm/driver/display/sdl_display.hpp +++ b/src/modm/driver/display/sdl_display.hpp @@ -30,6 +30,7 @@ namespace modm * * \warning SDL_Init( SDL_INIT_EVERYTHING ); needs to be called, before * any instance of the SDLDisplay can be used + * @ingroup modm_driver_sdl_display */ class SDLDisplay: public modm::GraphicDisplay { diff --git a/src/modm/driver/display/sdl_display.lb b/src/modm/driver/display/sdl_display.lb index a3cde11f1e..dd60b76718 100644 --- a/src/modm/driver/display/sdl_display.lb +++ b/src/modm/driver/display/sdl_display.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "driver" module.name = "sdl_display" + module.description = "SDL Display" def prepare(module, options): if options[":target"].identifier["platform"] not in ["hosted"]: diff --git a/src/modm/driver/display/seven_segment.hpp b/src/modm/driver/display/seven_segment.hpp index 848bc1c434..c8fe073177 100644 --- a/src/modm/driver/display/seven_segment.hpp +++ b/src/modm/driver/display/seven_segment.hpp @@ -64,7 +64,7 @@ namespace modm * It because the Load signal must be strobe when all data is shifted out * this blocks until the SPI has finished. * - * \ingroup driver_display + * \ingroup modm_driver_seven_segment */ template< typename Spi, diff --git a/src/modm/driver/display/siemens_m55.hpp b/src/modm/driver/display/siemens_m55.hpp index 2dfeed9bb6..5a1be8bb59 100644 --- a/src/modm/driver/display/siemens_m55.hpp +++ b/src/modm/driver/display/siemens_m55.hpp @@ -26,7 +26,7 @@ namespace modm * * (also shared with A60, A65, C60, MC60 and S55 models) * - * \ingroup driver_display + * \ingroup modm_driver_siemens_m55 */ template class SiemensM55 : public BufferedGraphicDisplay<101, 80> diff --git a/src/modm/driver/display/siemens_s65.hpp b/src/modm/driver/display/siemens_s65.hpp index a168115d4e..f293b78f6a 100644 --- a/src/modm/driver/display/siemens_s65.hpp +++ b/src/modm/driver/display/siemens_s65.hpp @@ -40,7 +40,7 @@ namespace modm * In portrait mode the connector is at the bottom. * In landscape mode the connector is at the right border. * - * \ingroup driver_display + * \ingroup modm_driver_siemens_s65 */ // common for landscape and portrait @@ -65,6 +65,7 @@ namespace modm }; + /// \ingroup modm_driver_siemens_s65 template class SiemensS65Portrait : public BufferedGraphicDisplay<132, 176>, @@ -82,12 +83,12 @@ namespace modm }; - /** - * The display in landscape mode does not match the required - * alignment of BufferedGraphicDisplay which requests that - * the vertical resolution can be divided by 8. - * - */ + /** + * The display in landscape mode does not match the required + * alignment of BufferedGraphicDisplay which requests that + * the vertical resolution can be divided by 8. + * \ingroup modm_driver_siemens_s65 + */ template class SiemensS65Landscape : public BufferedGraphicDisplay<176, 136>, diff --git a/src/modm/driver/display/siemens_s65.lb b/src/modm/driver/display/siemens_s65.lb index 8c8c213836..9b4ef16792 100644 --- a/src/modm/driver/display/siemens_s65.lb +++ b/src/modm/driver/display/siemens_s65.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "driver" module.name = "siemens_s65" + module.description = "Siemens S65 Display" def prepare(module, options): module.depends( diff --git a/src/modm/driver/display/siemens_s75.hpp b/src/modm/driver/display/siemens_s75.hpp index 79c1996f46..817e1db8ae 100644 --- a/src/modm/driver/display/siemens_s75.hpp +++ b/src/modm/driver/display/siemens_s75.hpp @@ -22,51 +22,7 @@ namespace modm { - /** - * \brief Driver for Siemens S75/CX75/C81/M75 displays - * - * The controller in displays manufactured by Alps is a - * SOLOMON SYSTECH SSD1286 which can drive color - * displays of up to 132 x 176 pixels in 18 bit colour. - * - * The portrait mode is a bit more 'native' for this display because - * modm::BufferedGraphicDisplay requests that the vertical resolution is - * dividable by 8. - * - * In portrait mode the connector is at top. - * In landscapeLeft mode the connector is at the left border. - * In landscapeRight mode the connector is at the right border. - * - * Pinout at LCD: - * 1 IN CD Command / Data Low = Command (Register) High = Data. - * 2 IN RESET Resets the display. Active low. Low = Reset, High = No reset. - * 3 IN CS Chip select. Active low. Low = Chip is selected, High = Chip is not selected. - * 4 OUT VD Sync Output. Unused. - * 5 GND Supply - * 6 IN D0 Bit 0 of parallel data - * 7 3V3 (2V9) Supply - * 8 GND Supply - * 9 VLED + Supply Backlight - * 10 VLED - Supply Backlight - * 11 GND Supply - * 12 IN RD Read Strobe. Must be tied high. - * 13 IN WR Write Strobe. High-to-Low strobe write data to display memory. - * 14 IN D1 Bit 1 of parallel data. - * 15 IN D2 Bit 2 of parallel data. - * 16 IN D3 Bit 3 of parallel data. - * 17 IN D4 Bit 4 of parallel data. - * 18 IN D5 Bit 5 of parallel data. - * 19 IN D6 Bit 6 of parallel data. - * 20 IN D7 Bit 7 of parallel data. - * - * Pin 1 is unmarked. Pin 5 can be recognised by a thicker trace which is GND. - * - * The backlight (VLED +, VLED -) consists of four white - * LEDs in series. The forward voltage is about 12 volts. - * - * \ingroup driver_display - */ - + /// @ingroup modm_driver_siemens_s75 enum class Orientation : uint8_t { Portrait, //< Connector top @@ -75,6 +31,7 @@ namespace modm PortraitUpsideDown, //< Connector bottom }; + /// @ingroup modm_driver_siemens_s75 template < typename MEMORY, typename RESET, @@ -107,12 +64,14 @@ namespace modm MEMORY& interface; }; + /// @ingroup modm_driver_siemens_s75 template class SiemensS75Portrait : public SiemensS75Common { }; + /// @ingroup modm_driver_siemens_s75 template class SiemensS75PortraitUpsideDown: public SiemensS75Common @@ -124,6 +83,7 @@ namespace modm * alignment of BufferedGraphicDisplay which requests that * the vertical resolution can be divided by 8. * + * @ingroup modm_driver_siemens_s75 */ template class SiemensS75LandscapeLeft : @@ -134,6 +94,7 @@ namespace modm SiemensS75Common(interface) { } }; + /// @ingroup modm_driver_siemens_s75 template class SiemensS75LandscapeRight : public SiemensS75Common diff --git a/src/modm/driver/display/siemens_s75.lb b/src/modm/driver/display/siemens_s75.lb index 14bc6ffdbd..a23ad03f65 100644 --- a/src/modm/driver/display/siemens_s75.lb +++ b/src/modm/driver/display/siemens_s75.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "driver" module.name = "siemens_s75" + module.description = FileReader("siemens_s75.md") def prepare(module, options): module.depends( diff --git a/src/modm/driver/display/siemens_s75.md b/src/modm/driver/display/siemens_s75.md new file mode 100644 index 0000000000..79b72c35f7 --- /dev/null +++ b/src/modm/driver/display/siemens_s75.md @@ -0,0 +1,42 @@ +# Siemens S75/CX75/C81/M75 Display + +The controller in displays manufactured by Alps is a SOLOMON SYSTECH SSD1286 +which can drive color displays of up to 132 x 176 pixels in 18 bit color. + +The portrait mode is a bit more 'native' for this display because +`modm::BufferedGraphicDisplay` requests that the vertical resolution is +divisible by 8. + +In portrait mode the connector is at the top. +In landscapeLeft mode the connector is at the left border. +In landscapeRight mode the connector is at the right border. + +Pinout at LCD: + +``` + 1 IN CD Command / Data Low = Command (Register) High = Data. + 2 IN RESET Resets the display. Active low. Low = Reset, High = No reset. + 3 IN CS Chip select. Active low. Low = Chip is selected, High = Chip is not selected. + 4 OUT VD Sync Output. Unused. + 5 GND Supply + 6 IN D0 Bit 0 of parallel data + 7 3V3 (2V9) Supply + 8 GND Supply + 9 VLED + Supply Backlight +10 VLED - Supply Backlight +11 GND Supply +12 IN RD Read Strobe. Must be tied high. +13 IN WR Write Strobe. High-to-Low strobe write data to display memory. +14 IN D1 Bit 1 of parallel data. +15 IN D2 Bit 2 of parallel data. +16 IN D3 Bit 3 of parallel data. +17 IN D4 Bit 4 of parallel data. +18 IN D5 Bit 5 of parallel data. +19 IN D6 Bit 6 of parallel data. +20 IN D7 Bit 7 of parallel data. +``` + +Pin 1 is unmarked. Pin 5 can be recognized by a thicker trace which is GND. + +The backlight (VLED +, VLED -) consists of four white LEDs in series. +The forward voltage is about 12 volts. \ No newline at end of file diff --git a/src/modm/driver/display/ssd1306.hpp b/src/modm/driver/display/ssd1306.hpp index 3639ed2ae3..25fe0e8c95 100644 --- a/src/modm/driver/display/ssd1306.hpp +++ b/src/modm/driver/display/ssd1306.hpp @@ -21,6 +21,7 @@ namespace modm { +/// @ingroup modm_driver_ssd1306 struct ssd1306 { protected: @@ -149,7 +150,7 @@ struct ssd1306 * the frame rate to about 40Hz. * * @author Niklas Hauser - * @ingroup driver_display + * @ingroup modm_driver_ssd1306 */ template < class I2cMaster, uint8_t Height = 64 > class Ssd1306 : public ssd1306, public BufferedGraphicDisplay<128, Height>, diff --git a/src/modm/driver/display/ssd1306.lb b/src/modm/driver/display/ssd1306.lb index b694ac1a4b..d58bc54414 100644 --- a/src/modm/driver/display/ssd1306.lb +++ b/src/modm/driver/display/ssd1306.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "driver" module.name = "ssd1306" + module.description = "SSD1306 Display" def prepare(module, options): module.depends( diff --git a/src/modm/driver/display/st7036.hpp b/src/modm/driver/display/st7036.hpp index 07d6da6b2c..fa3c2b4fde 100644 --- a/src/modm/driver/display/st7036.hpp +++ b/src/modm/driver/display/st7036.hpp @@ -30,7 +30,7 @@ namespace modm * \see Lcd * * \author Fabian Greif - * \ingroup driver_display + * \ingroup modm_driver_ea_dog */ template class St7036 : public CharacterDisplay diff --git a/src/modm/driver/display/st7565.hpp b/src/modm/driver/display/st7565.hpp index d37e7b0cb9..cb27b73620 100644 --- a/src/modm/driver/display/st7565.hpp +++ b/src/modm/driver/display/st7565.hpp @@ -25,7 +25,7 @@ namespace modm * \brief Driver for ST7565 based LC-displays * * \author Fabian Greif - * \ingroup driver_display + * \ingroup modm_driver_ea_dog */ template diff --git a/src/modm/driver/display/st7565_defines.hpp b/src/modm/driver/display/st7565_defines.hpp index 0e6f661638..7546512f91 100644 --- a/src/modm/driver/display/st7565_defines.hpp +++ b/src/modm/driver/display/st7565_defines.hpp @@ -22,6 +22,9 @@ namespace modm { + /// @ingroup modm_driver_ea_dog + /// @{ + // (1) Display ON/OFF #define ST7565_ON 0xAF #define ST7565_OFF 0xAE @@ -103,6 +106,8 @@ namespace modm // (22) NOP #define ST7565_NOP 0xE3 + + /// @} } #endif // MODM_ST7565_DEFINES_HPP diff --git a/src/modm/driver/driver.dox b/src/modm/driver/driver.dox deleted file mode 100644 index 0a8069c1c8..0000000000 --- a/src/modm/driver/driver.dox +++ /dev/null @@ -1,91 +0,0 @@ -// coding: utf-8 -// - -/** - * \defgroup driver Device drivers - * \brief Drivers to control external devices - */ - -/** - * \ingroup driver - * \defgroup driver_adc Analog/Digital Converters - */ - -/** - * \ingroup driver - * \defgroup driver_dac Digital/Analog Converters - */ - -/** - * \ingroup driver - * \defgroup driver_can CAN drivers - */ - -/** - * \ingroup driver - * \defgroup driver_gpio IO-Expander - */ - -/** - * \ingroup driver - * \defgroup driver_inertial Inertial measurement - * - * Gyroscopes, Acceleration sensors and compasses - */ - -/** - * \ingroup driver - * \defgroup driver_storage Storage - * - * Driver for SPI Flash, SPI RAM, I2C Eeprom, SD card etc. - */ - -/** - * \ingroup driver - * \defgroup driver_bus Busses - * - * Interfaces and software implementations of memory busses. - */ - -/** - * \ingroup driver - * \defgroup driver_other Other - * - * Everything without a distinct group yet. - */ - -/** - * \ingroup driver - * \defgroup driver_touch Touch Detection - * - * Resistive or capacitive touchbuttons, touchsliders or touchscreens. - */ - -/** - * \ingroup driver - * \defgroup driver_radio Radio - * - * Wireless communication drivers - */ - -/** - * \ingroup driver - * \defgroup driver_position Position sensors - * - * Absolute or relative position and distance sensors. - */ - -/** - * \ingroup driver - * \defgroup driver_pressure Pressure sensors - */ - -/** - * \ingroup driver - * \defgroup driver_temperature Temperature sensors - */ - -/** - * \ingroup driver - * \defgroup driver_pwm PWM Drivers - */ diff --git a/src/modm/driver/fpga/xilinx_spartan3.hpp b/src/modm/driver/fpga/xilinx_spartan3.hpp index b2cbc34c5a..4bf3781a29 100644 --- a/src/modm/driver/fpga/xilinx_spartan3.hpp +++ b/src/modm/driver/fpga/xilinx_spartan3.hpp @@ -29,7 +29,7 @@ namespace modm * readPageFromMemory(pos, buffer, sizeof(buffer) method. * Appropriate data sources can be external SPI flashes. * - * @ingroup driver_other + * @ingroup modm_driver_spartan_3 */ template < typename Cclk, ///< Clock output to FPGA typename Din, ///< Data output to FPGA diff --git a/src/modm/driver/fpga/xilinx_spartan6.hpp b/src/modm/driver/fpga/xilinx_spartan6.hpp index ca1bac3e06..53e97f67f1 100644 --- a/src/modm/driver/fpga/xilinx_spartan6.hpp +++ b/src/modm/driver/fpga/xilinx_spartan6.hpp @@ -42,7 +42,7 @@ namespace modm * * Adapter between SPI flash and DataSource * - * @ingroup driver_other + * @ingroup modm_driver_spartan_6 */ template < typename Cclk, ///< Clock output to FPGA typename DataLow, ///< Data output to FPGA, 8 bit parallel port diff --git a/src/modm/driver/gpio/mcp23_transport.hpp b/src/modm/driver/gpio/mcp23_transport.hpp index 322c1a4280..6c10a8cf27 100644 --- a/src/modm/driver/gpio/mcp23_transport.hpp +++ b/src/modm/driver/gpio/mcp23_transport.hpp @@ -29,7 +29,7 @@ namespace modm * @see modm::Mcp23x08 * @see modm::Mcp23x17 * - * @ingroup driver_gpio + * @ingroup modm_driver_mcp23x17 * @author Niklas Hauser */ template < class I2cMaster > @@ -74,7 +74,7 @@ class Mcp23TransportI2c : public modm::I2cDevice< I2cMaster, 2 > * * @tparam Cs connected Chip Select Pin * - * @ingroup driver_gpio + * @ingroup modm_driver_mcp23x17 * @author Niklas Hauser */ template < class SpiMaster, class Cs > diff --git a/src/modm/driver/gpio/mcp23s08.hpp b/src/modm/driver/gpio/mcp23s08.hpp index 04dea7d5ad..bb90cae912 100644 --- a/src/modm/driver/gpio/mcp23s08.hpp +++ b/src/modm/driver/gpio/mcp23s08.hpp @@ -25,7 +25,7 @@ namespace modm * A1 and A0 need to be tided low. * * \author Fabian Greif - * \ingroup driver_gpio + * \ingroup modm_driver_mcp23s08 */ template class Mcp23s08 diff --git a/src/modm/driver/gpio/mcp23x17.hpp b/src/modm/driver/gpio/mcp23x17.hpp index a291fbf23f..d359734c8e 100644 --- a/src/modm/driver/gpio/mcp23x17.hpp +++ b/src/modm/driver/gpio/mcp23x17.hpp @@ -19,6 +19,7 @@ namespace modm { +/// @ingroup modm_driver_mcp23x17 struct mcp23x17 { protected: @@ -84,19 +85,6 @@ struct mcp23x17 }; // struct mcp23x17 /** - * MCP23X15 16-Bit I/O Expander with Serial Interface. - * - * GPB is the high byte, GPA the low byte. - * The lower three address bits can be configured: 0100abc. - * - * Notice that you can specify multiple pins at the same time for functions - * with argument type `Pins`, either by ORing the according pins, or - * converting a 16bit value using the `Pins(uint16_t)` converting constructor. - * - * Other functions with argument type `Pin` can only take one pin. - * If you want to operate on all 16bit, use the `get(Inputs|Outputs|Directions|Polarities)()` - * getters. - * * @see Mcp23TransportI2c * @see Mcp23TransportSpi * @@ -105,7 +93,7 @@ struct mcp23x17 * @author Fabian Greif * @author Niklas Hauser * - * @ingroup driver_gpio + * @ingroup modm_driver_mcp23x17 */ template class Mcp23x17 : public mcp23x17, public Transport, public modm::GpioExpander diff --git a/src/modm/driver/gpio/mcp23x17.lb b/src/modm/driver/gpio/mcp23x17.lb index 50d684cb3e..c99223ae14 100644 --- a/src/modm/driver/gpio/mcp23x17.lb +++ b/src/modm/driver/gpio/mcp23x17.lb @@ -14,6 +14,20 @@ def init(module): module.parent = "driver" module.name = "mcp23x17" + module.description = """\ +# MCP23x17 16-Bit I/O Expander + +Port GPB is the high byte, GPA the low byte. +The lower three address bits can be configured: `0100abc`. + +Notice that you can specify multiple pins at the same time for functions +with argument type `Pins`, either by ORing the according pins, or +converting a 16bit value using the `Pins(uint16_t)` converting constructor. + +Other functions with argument type `Pin` can only take one pin. +If you want to operate on all 16bit, use the `get(Inputs|Outputs|Directions|Polarities)()` +getters. +""" def prepare(module, options): module.depends( diff --git a/src/modm/driver/gpio/pca8574.hpp b/src/modm/driver/gpio/pca8574.hpp index c697d01138..bec6bc32ba 100644 --- a/src/modm/driver/gpio/pca8574.hpp +++ b/src/modm/driver/gpio/pca8574.hpp @@ -21,6 +21,7 @@ namespace modm { +/// @ingroup modm_driver_pca8574 struct pca8574 { public: @@ -45,7 +46,7 @@ struct pca8574 * * This IO-Expander only has open-drain outputs with weak internal pull-ups. * - * @ingroup driver_gpio + * @ingroup modm_driver_pca8574 * * @author Sascha Schade * @author Niklas Hauser diff --git a/src/modm/driver/gpio/pca8574.lb b/src/modm/driver/gpio/pca8574.lb index bd022eeb2d..5c7f66f266 100644 --- a/src/modm/driver/gpio/pca8574.lb +++ b/src/modm/driver/gpio/pca8574.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "driver" module.name = "pca8574" + module.description = "PCA8574 8-Bit I/O Expander" def prepare(module, options): module.depends( diff --git a/src/modm/driver/gpio/pca9535.hpp b/src/modm/driver/gpio/pca9535.hpp index f598f3d02c..04a0627c0e 100644 --- a/src/modm/driver/gpio/pca9535.hpp +++ b/src/modm/driver/gpio/pca9535.hpp @@ -20,6 +20,7 @@ namespace modm { +/// @ingroup modm_driver_pca9535 struct pca9535 { protected: @@ -66,37 +67,8 @@ struct pca9535 }; // struct pca9535 /** - * PCA9535 I2C GPIO expander. - * - * Also software-compatible with PCA9555. - * The lower three address bits can be configured: 0100abc. - * - * Notice that you can specify multiple pins at the same time for functions - * with argument type `Pins`, either by ORing the according pins, or - * converting a 16bit value using the `Pins(uint16_t)` converting constructor. - * - * Other functions with argument type `Pin` can only take one pin. - * If you want to operate on all 16bit, use the `get(Inputs|Outputs|Directions|Polarities)()` - * getters. - * - * @code - * typedef modm::pca9535::Pin Pin; - * typedef modm::pca9535::Pins Pins; - * - * RF_CALL_BLOCKING(expander.setOutput(Pins(0xff)); // set all lower 8 pins to output - * RF_CALL_BLOCKING(expander.set(Pin::P0_0)); // set only pin 00 high - * RF_CALL_BLOCKING(expander.reset(Pin::P0_1 | Pin::P0_2)); // reset 2 pins - * RF_CALL_BLOCKING(expander.toggle(Pin::P0_3 | Pin::P0_4 | Pin::P0_5)); // toggle 3 pins - * - * RF_CALL_BLOCKING(expander.readInput()); // transfer input states from the external chip - * bool high = expander.read(Pin::P1_0); // check a single pin - * - * Pins input = expander.getInputs(); // get all 16 input states - * bool isAnyPinHigh = input.any(Pin::P1_1 | Pin::P1_2 | Pin::P1_3); // check if any of 3 pins is high - * @endcode - * * @author Niklas Hauser - * @ingroup driver_gpio + * @ingroup modm_driver_pca9535 */ template < typename I2cMaster > class Pca9535 : public pca9535, public modm::I2cDevice< I2cMaster, 2 >, public modm::GpioExpander diff --git a/src/modm/driver/gpio/pca9535.lb b/src/modm/driver/gpio/pca9535.lb index 72ef44ec9c..1fe13acb9f 100644 --- a/src/modm/driver/gpio/pca9535.lb +++ b/src/modm/driver/gpio/pca9535.lb @@ -14,6 +14,36 @@ def init(module): module.parent = "driver" module.name = "pca9535" + module.description = """\ +# PCA9535 16-Bit I/O Expander + +Also software-compatible with PCA9555. +The lower three address bits can be configured: `0100abc`. + +Notice that you can specify multiple pins at the same time for functions +with argument type `Pins`, either by ORing the according pins, or +converting a 16-bit value using the `Pins(uint16_t)` converting constructor. + +Other functions with argument type `Pin` can only take one pin. +If you want to operate on all 16-bit, use the `get(Inputs|Outputs|Directions|Polarities)()` +getters. + +```cpp +using Pin = expander.Pin; +using Pins = expander.Pins; + +RF_CALL_BLOCKING(expander.setOutput(Pins(0xff)); // set all lower 8 pins to output +RF_CALL_BLOCKING(expander.set(Pin::P0_0)); // set only pin 00 high +RF_CALL_BLOCKING(expander.reset(Pin::P0_1 | Pin::P0_2)); // reset 2 pins +RF_CALL_BLOCKING(expander.toggle(Pin::P0_3 | Pin::P0_4 | Pin::P0_5)); // toggle 3 pins + +RF_CALL_BLOCKING(expander.readInput()); // transfer input states from the external chip +bool high = expander.read(Pin::P1_0); // check a single pin + +Pins input = expander.getInputs(); // get all 16 input states +bool isAnyPinHigh = input.any(Pin::P1_1 | Pin::P1_2 | Pin::P1_3); // check if any of 3 pins is high +``` +""" def prepare(module, options): module.depends( diff --git a/src/modm/driver/gpio/shift_register_input.hpp b/src/modm/driver/gpio/shift_register_input.hpp index c0474ee01a..93aa84963a 100644 --- a/src/modm/driver/gpio/shift_register_input.hpp +++ b/src/modm/driver/gpio/shift_register_input.hpp @@ -49,7 +49,7 @@ namespace modm * \tparam N Number of HC165 Chips * * \author Fabian Greif - * \ingroup driver_gpio + * \ingroup modm_driver_shift_register */ template class ShiftRegisterInput diff --git a/src/modm/driver/gpio/shift_register_output.hpp b/src/modm/driver/gpio/shift_register_output.hpp index 8126d38444..0938d86386 100644 --- a/src/modm/driver/gpio/shift_register_output.hpp +++ b/src/modm/driver/gpio/shift_register_output.hpp @@ -45,7 +45,7 @@ namespace modm * \tparam N Number of HC595 Chips * * \author Fabian Greif - * \ingroup driver_gpio + * \ingroup modm_driver_shift_register */ template class ShiftRegisterOutput diff --git a/src/modm/driver/inertial/adxl345.hpp b/src/modm/driver/inertial/adxl345.hpp index 50c9068032..7be2b482c9 100644 --- a/src/modm/driver/inertial/adxl345.hpp +++ b/src/modm/driver/inertial/adxl345.hpp @@ -18,6 +18,7 @@ namespace modm { + /// @ingroup modm_driver_adxl345 namespace adxl345 { /// The addresses of the Configuration and Data Registers @@ -152,7 +153,7 @@ namespace modm * datasheet. * * \author Niklas Hauser - * \ingroup driver_inertial + * \ingroup modm_driver_adxl345 * * \tparam I2cMaster Asynchronous Two Wire interface */ diff --git a/src/modm/driver/inertial/bma180.hpp b/src/modm/driver/inertial/bma180.hpp index 75995db129..2b0a4a577d 100644 --- a/src/modm/driver/inertial/bma180.hpp +++ b/src/modm/driver/inertial/bma180.hpp @@ -17,6 +17,7 @@ namespace modm { + /// @ingroup modm_driver_bma180 namespace bma180 { // MARK: Registers @@ -386,7 +387,7 @@ namespace modm * datasheet. * * \author Niklas Hauser - * \ingroup driver_inertial + * \ingroup modm_driver_bma180 * * \tparam I2cMaster Asynchronous Two Wire interface */ diff --git a/src/modm/driver/inertial/hmc5843.hpp b/src/modm/driver/inertial/hmc5843.hpp index ac601fc6db..a45426b9e0 100644 --- a/src/modm/driver/inertial/hmc5843.hpp +++ b/src/modm/driver/inertial/hmc5843.hpp @@ -20,6 +20,7 @@ namespace modm { +/// @ingroup modm_driver_hmc58x struct hmc5843 : public hmc58x3 { enum class @@ -61,7 +62,7 @@ struct hmc5843 : public hmc58x3 * * @see Hmc58x3 * - * @ingroup driver_inertial + * @ingroup modm_driver_hmc58x * @author Niklas Hauser */ template < typename I2cMaster > diff --git a/src/modm/driver/inertial/hmc5883l.hpp b/src/modm/driver/inertial/hmc5883l.hpp index 91c1d0c32e..d8fe5095ae 100644 --- a/src/modm/driver/inertial/hmc5883l.hpp +++ b/src/modm/driver/inertial/hmc5883l.hpp @@ -20,6 +20,7 @@ namespace modm { +/// @ingroup modm_driver_hmc58x struct hmc5883 : public hmc58x3 { enum class @@ -69,7 +70,7 @@ struct hmc5883 : public hmc58x3 * * @see Hmc58x3 * - * @ingroup driver_inertial + * @ingroup modm_driver_hmc58x * @author Niklas Hauser */ template < typename I2cMaster > diff --git a/src/modm/driver/inertial/hmc58x.lb b/src/modm/driver/inertial/hmc58x.lb index e62cb527c1..eb1aac08c1 100644 --- a/src/modm/driver/inertial/hmc58x.lb +++ b/src/modm/driver/inertial/hmc58x.lb @@ -14,6 +14,16 @@ def init(module): module.parent = "driver" module.name = "hmc58x" + module.description = """\ +# HMC58x3 3-Axis Digital Magnetometer + +The HMC58x3 is a surface-mount, multi-chip module designed for low-field +magnetic sensing with a digital interface for applications such as +low-cost compassing and magnetometry. The HMC58x3 includes high-resolution +magneto-resistive sensors plus an ASIC containing amplification, +automatic degaussing strap drivers, offset cancellation, and a 12-bit +ADC that enables 1-2 degrees compass heading accuracy. +""" def prepare(module, options): module.depends( diff --git a/src/modm/driver/inertial/hmc58x3.hpp b/src/modm/driver/inertial/hmc58x3.hpp index 3e27b0ae2e..5a900e48d0 100644 --- a/src/modm/driver/inertial/hmc58x3.hpp +++ b/src/modm/driver/inertial/hmc58x3.hpp @@ -28,6 +28,7 @@ class Hmc5843; template < class I2cMaster > class Hmc5883; +/// @ingroup modm_driver_hmc58x struct hmc58x3 { protected: @@ -180,16 +181,7 @@ struct hmc58x3 }; // struct hmc58x3 /** - * HMC58x3 3-axis digital magnetometer family driver. - * - * The HMC58x3 is a surface-mount, multi-chip module designed for low-field - * magnetic sensing with a digital interface for applications such as - * low-cost compassing and magnetometry. The HMC58x3 includes high-resolution - * magneto-resistive sensors plus an ASIC containing amplification, - * automatic degaussing strap drivers, offset cancellation, and a 12-bit - * ADC that enables 1-2 degrees compass heading accuracy. - * - * @ingroup driver_inertial + * @ingroup modm_driver_hmc58x * @author Niklas Hauser */ template < typename I2cMaster > diff --git a/src/modm/driver/inertial/hmc6343.hpp b/src/modm/driver/inertial/hmc6343.hpp index 66d5f49179..3e1f4ac371 100644 --- a/src/modm/driver/inertial/hmc6343.hpp +++ b/src/modm/driver/inertial/hmc6343.hpp @@ -22,6 +22,7 @@ namespace modm template < class I2cMaster > class Hmc6343; +/// @ingroup modm_driver_hmc6343 struct hmc6343 { enum class @@ -202,16 +203,7 @@ struct hmc6343 }; // struct hmc6343 /** - * HMC6343 3-Axis Compass with algorithms driver. - * - * The Honeywell HMC6343 is a fully integrated compass module that - * includes firmware for heading computation and calibration for - * magnetic distortions. The module combines 3-axis magneto-resistive - * sensors and 3-axis MEMS accelerometers, analog and digital - * support circuits, microprocessor and algorithms required for - * heading computation. - * - * @ingroup driver_inertial + * @ingroup modm_driver_hmc6343 * @author Niklas Hauser */ template < class I2cMaster > diff --git a/src/modm/driver/inertial/hmc6343.lb b/src/modm/driver/inertial/hmc6343.lb index 3f0b3a0d96..72b68ee2a4 100644 --- a/src/modm/driver/inertial/hmc6343.lb +++ b/src/modm/driver/inertial/hmc6343.lb @@ -14,6 +14,16 @@ def init(module): module.parent = "driver" module.name = "hmc6343" + module.description = """\ +# HMC6343 3-Axis Compass + +The Honeywell HMC6343 is a fully integrated compass module that +includes firmware for heading computation and calibration for +magnetic distortions. The module combines 3-axis magneto-resistive +sensors and 3-axis MEMS accelerometers, analog and digital +support circuits, microprocessor and algorithms required for +heading computation. +""" def prepare(module, options): module.depends( diff --git a/src/modm/driver/inertial/itg3200.hpp b/src/modm/driver/inertial/itg3200.hpp index dbda45f627..1e4d6cf20d 100644 --- a/src/modm/driver/inertial/itg3200.hpp +++ b/src/modm/driver/inertial/itg3200.hpp @@ -22,6 +22,7 @@ namespace modm template < class I2cMaster > class Itg3200; +/// @ingroup modm_driver_itg3200 struct itg3200 { protected: @@ -185,14 +186,8 @@ struct itg3200 }; // struct itg3200 /** - * Basic ITG3200 digital gyroscope sensor driver - * - * For further information on the special sensing functions, consult the - * - * datasheet. - * * @author Niklas Hauser - * @ingroup driver_inertial + * @ingroup modm_driver_itg3200 */ template < typename I2cMaster > class Itg3200 : public itg3200, public modm::I2cDevice< I2cMaster, 2 > diff --git a/src/modm/driver/inertial/itg3200.lb b/src/modm/driver/inertial/itg3200.lb index 754025ad18..8921394251 100644 --- a/src/modm/driver/inertial/itg3200.lb +++ b/src/modm/driver/inertial/itg3200.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "driver" module.name = "itg3200" + module.description = """\ +# ITG3200 Digital Gyroscope + +For further information on the special sensing functions, consult the +[datasheet](http://invensense.com/mems/gyro/documents/PS-ITG-3200-00-01.4.pdf). +""" def prepare(module, options): module.depends( diff --git a/src/modm/driver/inertial/l3gd20.hpp b/src/modm/driver/inertial/l3gd20.hpp index 5702d5b7bc..efb3d942ec 100644 --- a/src/modm/driver/inertial/l3gd20.hpp +++ b/src/modm/driver/inertial/l3gd20.hpp @@ -24,6 +24,7 @@ namespace modm template < class Transport > class L3gd20; +/// @ingroup modm_driver_l3gd20 struct l3gd20 { enum class @@ -319,17 +320,11 @@ struct l3gd20 }; // struct l3gd20 /** - * L3GD20 3-Axis gyroscope. - * - * The L3GD20 is a low-power three-axis angular rate sensor. - * The L3GD20 has a full scale of ±250/±500/±2000 dps and is capable of - * measuring rates with a user-selectable bandwidth. - * * @tparam Transport Either the I2C or SPI Transport Layer. * @see Lis3TransportI2c * @see Lis3TransportSpi * - * @ingroup driver_inertial + * @ingroup modm_driver_l3gd20 * @author Niklas Hauser */ template < class Transport > diff --git a/src/modm/driver/inertial/l3gd20.lb b/src/modm/driver/inertial/l3gd20.lb index 79cf25635d..67d4ebb207 100644 --- a/src/modm/driver/inertial/l3gd20.lb +++ b/src/modm/driver/inertial/l3gd20.lb @@ -14,6 +14,13 @@ def init(module): module.parent = "driver" module.name = "l3gd20" + module.description = """\ +# L3GD20 3-Axis Gyroscope + +The L3GD20 is a low-power three-axis angular rate sensor. +The L3GD20 has a full scale of ±250/±500/±2000 dps and is capable of +measuring rates with a user-selectable bandwidth. +""" def prepare(module, options): module.depends( diff --git a/src/modm/driver/inertial/lis302dl.hpp b/src/modm/driver/inertial/lis302dl.hpp index d05f8daa69..e088f63990 100644 --- a/src/modm/driver/inertial/lis302dl.hpp +++ b/src/modm/driver/inertial/lis302dl.hpp @@ -23,6 +23,7 @@ namespace modm template < class Transport > class Lis302dl; +/// @ingroup modm_driver_lis302dl struct lis302dl { protected: @@ -297,17 +298,11 @@ struct lis302dl }; // struct lis302 /** - * LIS302DL 3-Axis accelerometer. - * - * The LIS302DL is an ultra compact low-power three axes linear accelerometer. - * It includes a sensing element and an IC interface able to provide the measured - * acceleration to the external world through an I2C/SPI serial interface. - * * @tparam Transport Either the I2C or SPI Transport Layer. * @see Lis3TransportI2c * @see Lis3TransportSpi * - * @ingroup driver_inertial + * @ingroup modm_driver_lis302dl * @author Niklas Hauser */ template < class Transport > diff --git a/src/modm/driver/inertial/lis302dl.lb b/src/modm/driver/inertial/lis302dl.lb index d7f1b18cf1..d5cce9dee0 100644 --- a/src/modm/driver/inertial/lis302dl.lb +++ b/src/modm/driver/inertial/lis302dl.lb @@ -14,6 +14,13 @@ def init(module): module.parent = "driver" module.name = "lis302dl" + module.description = """\ +# LIS302DL 3-Axis Accelerometer + +The LIS302DL is an ultra compact low-power three axes linear accelerometer. +It includes a sensing element and an IC interface able to provide the measured +acceleration to the external world through an I2C/SPI serial interface. +""" def prepare(module, options): module.depends( diff --git a/src/modm/driver/inertial/lis3_transport.hpp b/src/modm/driver/inertial/lis3_transport.hpp index 9b96edfaed..1cda301211 100644 --- a/src/modm/driver/inertial/lis3_transport.hpp +++ b/src/modm/driver/inertial/lis3_transport.hpp @@ -32,7 +32,7 @@ namespace modm * @see Lis302dl * @see Lis3dsh * - * @ingroup driver_inertial + * @ingroup modm_driver_lis3_transport * @author Niklas Hauser */ template < class I2cMaster > @@ -79,7 +79,7 @@ class Lis3TransportI2c : public modm::I2cDevice< I2cMaster, 2 > * * @tparam Cs connected Chip Select Pin * - * @ingroup driver_inertial + * @ingroup modm_driver_lis3_transport * @author Niklas Hauser */ template < class SpiMaster, class Cs > diff --git a/src/modm/driver/inertial/lis3_transport.lb b/src/modm/driver/inertial/lis3_transport.lb index 772b2dca2a..e9afedc65b 100644 --- a/src/modm/driver/inertial/lis3_transport.lb +++ b/src/modm/driver/inertial/lis3_transport.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "driver" module.name = "lis3.transport" + module.description = "LIS3xx Transport Layer" def prepare(module, options): module.depends( diff --git a/src/modm/driver/inertial/lis3dsh.hpp b/src/modm/driver/inertial/lis3dsh.hpp index cb54470db6..bf424cb571 100644 --- a/src/modm/driver/inertial/lis3dsh.hpp +++ b/src/modm/driver/inertial/lis3dsh.hpp @@ -24,6 +24,7 @@ namespace modm template < class Transport > class Lis3dsh; +/// @ingroup modm_driver_lis3dsh struct lis3dsh { enum class @@ -503,18 +504,11 @@ struct lis3dsh }; // struct lis3dsh /** - * LIS3DSH 3-Axis accelerometer. - * - * The LIS3DSH is an ultra low-power high performance three-axis linear accelerometer belonging to the - * "nano" family with embedded state machine that can be programmed to implement autonomous applications. - * The LIS3DSH has dynamically selectable full scales of ±2g/±4g/±6g/±8g/±16g and it is capable - * of measuring accelerations with output data rates from 3.125 Hz to 1.6 kHz. - * * @tparam Transport Either the I2C or SPI Transport Layer. * @see Lis3TransportI2c * @see Lis3TransportSpi * - * @ingroup driver_inertial + * @ingroup modm_driver_lis3dsh * @author Niklas Hauser */ template < class Transport > diff --git a/src/modm/driver/inertial/lis3dsh.lb b/src/modm/driver/inertial/lis3dsh.lb index b7bf74cbc2..fef953c420 100644 --- a/src/modm/driver/inertial/lis3dsh.lb +++ b/src/modm/driver/inertial/lis3dsh.lb @@ -14,6 +14,15 @@ def init(module): module.parent = "driver" module.name = "lis3dsh" + module.description = """\ +# LIS3DSH 3-Axis Accelerometer + +The LIS3DSH is an ultra low-power high performance three-axis linear +accelerometer belonging to the "nano" family with embedded state machine +that can be programmed to implement autonomous applications. The LIS3DSH has +dynamically selectable full scales of ±2g/±4g/±6g/±8g/±16g and it is capable +of measuring accelerations with output data rates from 3.125 Hz to 1.6 kHz. +""" def prepare(module, options): module.depends( diff --git a/src/modm/driver/inertial/lsm303a.hpp b/src/modm/driver/inertial/lsm303a.hpp index 3753d2d13f..2fb93e6a28 100644 --- a/src/modm/driver/inertial/lsm303a.hpp +++ b/src/modm/driver/inertial/lsm303a.hpp @@ -24,6 +24,7 @@ namespace modm template < class I2cMaster > class Lsm303a; +/// @ingroup modm_driver_lsm303a struct lsm303a { enum class @@ -369,23 +370,9 @@ struct lsm303a }; // struct lsm303a /** - * LSM303DLHC 3-Axis accelerometer. - * - * The LSM303DLHC is a system-in-package featuring a 3D digital linear - * acceleration sensor and a 3D digital magnetic sensor. - * The sensor has linear acceleration full scales of ±2g/±4g/±8g/±16g and a - * magnetic field full scale of ±1.3/±1.9/±2.5/±4.0/±4.7/±5.6/±8.1 gauss. - * The LSM303DLHC includes an I2C serial bus interface that supports standard and fast mode 100 kHz and 400 kHz. - * - * Since the device actually features two I2C devices which are just placed in the same - * package, this class only implements the acceleration sensor. - * For the magnetic field sensor see the `Lsm303m` class! - * - * @see Lsm303m - * * @tparam I2cMaster A class conforming to the I2cMaster interface * - * @ingroup driver_inertial + * @ingroup modm_driver_lsm303a * @author Niklas Hauser */ template < class I2cMaster > diff --git a/src/modm/driver/inertial/lsm303a.lb b/src/modm/driver/inertial/lsm303a.lb index 9e47f4b34e..6cd2b09589 100644 --- a/src/modm/driver/inertial/lsm303a.lb +++ b/src/modm/driver/inertial/lsm303a.lb @@ -14,6 +14,19 @@ def init(module): module.parent = "driver" module.name = "lsm303a" + module.description = """\ +# LSM303DLHC 3-Axis Accelerometer + +The LSM303DLHC is a system-in-package featuring a 3D digital linear +acceleration sensor and a 3D digital magnetic sensor. +The sensor has linear acceleration full scales of ±2g/±4g/±8g/±16g and a +magnetic field full scale of ±1.3/±1.9/±2.5/±4.0/±4.7/±5.6/±8.1 gauss. +The LSM303DLHC includes an I2C serial bus interface that supports standard and +fast mode 100 kHz and 400 kHz. + +Since the device actually features two I2C devices which are just placed in the same +package, this class only implements the acceleration sensor. +""" def prepare(module, options): module.depends( diff --git a/src/modm/driver/module.lb b/src/modm/driver/module.lb index 83c7eae94f..bb94124f80 100644 --- a/src/modm/driver/module.lb +++ b/src/modm/driver/module.lb @@ -13,10 +13,10 @@ def init(module): module.name = "driver" + module.description = "External Device Drivers" def prepare(module, options): return True def build(env): - env.outbasepath = "modm/src/modm/driver" - env.copy("driver.dox") + pass diff --git a/src/modm/driver/motion/adns9800.hpp b/src/modm/driver/motion/adns9800.hpp index 5dd6b87fb4..56e0e74679 100644 --- a/src/modm/driver/motion/adns9800.hpp +++ b/src/modm/driver/motion/adns9800.hpp @@ -9,17 +9,13 @@ */ // ---------------------------------------------------------------------------- -/** - * Based on work of Alexander Entinger, MSc / LXRobotics - * Based on https://github.com/mrjohnk/ADNS-9800 - */ - #ifndef MODM_ADNS9800_HPP #define MODM_ADNS9800_HPP namespace modm { +/// @ingroup modm_driver_adns9800 struct adns9800 { public: @@ -75,6 +71,7 @@ struct adns9800 }; }; +/// @ingroup modm_driver_adns9800 template < typename Spi, typename Cs > class Adns9800 : public adns9800 { diff --git a/src/modm/driver/motion/adns9800.lb b/src/modm/driver/motion/adns9800.lb index 6fa168d872..d9f12b4fbe 100644 --- a/src/modm/driver/motion/adns9800.lb +++ b/src/modm/driver/motion/adns9800.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "driver" module.name = "adns9800" + module.description = """\ +# ADNS-9800 Laser Motion Sensor + +Based on work of Alexander Entinger, MSc / LXRobotics +Based on https://github.com/mrjohnk/ADNS-9800 +""" def prepare(module, options): module.add_option( @@ -33,4 +39,4 @@ def build(env): env.outbasepath = "modm/src/modm/driver/motion" env.copy("adns9800.hpp") env.copy("adns9800_impl.hpp") - env.copy("adns9800_srom_{}.hpp".format(env[":::firmware"]), "adns9800_srom.hpp") + env.copy("adns9800_srom_{}.hpp".format(env["firmware"]), "adns9800_srom.hpp") diff --git a/src/modm/driver/motor/drv832x_spi.hpp b/src/modm/driver/motor/drv832x_spi.hpp index 3c5c4b54e1..fecd687cf3 100644 --- a/src/modm/driver/motor/drv832x_spi.hpp +++ b/src/modm/driver/motor/drv832x_spi.hpp @@ -21,6 +21,7 @@ namespace modm { +/// @ingroup modm_driver_drv832x_spi struct drv832xSpi { enum class @@ -292,13 +293,7 @@ struct drv832xSpi }; /** - * \brief DRV832xS: 6 to 60-V Three-Phase Smart Gate Driver - * - * This driver only covers the gate driver configuration accessible via SPI interface. - * - * \see DRV832x Datasheet - * - * \ingroup driver_motor + * \ingroup modm_driver_drv832x_spi * \author Raphael Lehmann */ template < class SpiMaster, class Cs > diff --git a/src/modm/driver/motor/drv832x_spi.lb b/src/modm/driver/motor/drv832x_spi.lb index c26feb04e3..7945d6e487 100644 --- a/src/modm/driver/motor/drv832x_spi.lb +++ b/src/modm/driver/motor/drv832x_spi.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "driver" module.name = "drv832x_spi" + module.description = """\ +# DRV832xS: Three-Phase Smart Gate Driver + +This driver only covers the gate driver configuration accessible via SPI interface. +[DRV832x Datasheet](http://www.ti.com/lit/ds/symlink/drv8320.pdf). +""" def prepare(module, options): module.depends( diff --git a/src/modm/driver/other/ad840x.hpp b/src/modm/driver/other/ad840x.hpp index fa1f198a9d..10bd56b0ca 100644 --- a/src/modm/driver/other/ad840x.hpp +++ b/src/modm/driver/other/ad840x.hpp @@ -25,8 +25,8 @@ namespace modm * \brief Definition of the AD8400/2/3 channels * * \see AD840x - * \ingroup driver_other * + * \ingroup modm_driver_ad840x * \hideinitializer */ enum Channel @@ -91,7 +91,7 @@ namespace modm * * \see ad840x * \author Fabian Greif - * \ingroup driver_other + * \ingroup modm_driver_ad840x */ template< typename Spi, typename Cs, diff --git a/src/modm/driver/position/vl53l0.hpp b/src/modm/driver/position/vl53l0.hpp index fdeef9c91e..aa7129751b 100644 --- a/src/modm/driver/position/vl53l0.hpp +++ b/src/modm/driver/position/vl53l0.hpp @@ -41,6 +41,7 @@ namespace vl53l0_private template < class I2cMaster > class Vl53l0; +/// @ingroup modm_driver_vl53l0 struct vl53l0 { public: @@ -332,12 +333,10 @@ IOStream& operator << (IOStream& os, const vl53l0::RangeErrorCode& c); /** - * VL53L0X: Proximity sensor module - * * The class is build for single-shot measurements. * * @author Christopher Durand - * @ingroup driver_position + * @ingroup modm_driver_vl53l0 */ template < typename I2cMaster > class Vl53l0 : public vl53l0, public modm::I2cDevice< I2cMaster, 5 > diff --git a/src/modm/driver/position/vl53l0.lb b/src/modm/driver/position/vl53l0.lb index 4351ac8edf..a809ae44b6 100644 --- a/src/modm/driver/position/vl53l0.lb +++ b/src/modm/driver/position/vl53l0.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "driver" module.name = "vl53l0" + module.description = "VL53L0X Proximity Sensor" def prepare(module, options): module.depends( diff --git a/src/modm/driver/position/vl6180.hpp b/src/modm/driver/position/vl6180.hpp index 2aac22c03a..9d57a85217 100644 --- a/src/modm/driver/position/vl6180.hpp +++ b/src/modm/driver/position/vl6180.hpp @@ -44,6 +44,7 @@ namespace vl6180_private template < class I2cMaster > class Vl6180; +/// @ingroup modm_driver_vl6180 struct vl6180 { public: @@ -349,7 +350,7 @@ struct vl6180 * For custom settings use the `updateRegister()` function. * * @author Niklas Hauser - * @ingroup driver_position + * @ingroup modm_driver_vl6180 */ template < typename I2cMaster > class Vl6180 : public vl6180, public modm::I2cDevice< I2cMaster, 2 > diff --git a/src/modm/driver/position/vl6180.lb b/src/modm/driver/position/vl6180.lb index 52f4578c4d..c78cd6d7df 100644 --- a/src/modm/driver/position/vl6180.lb +++ b/src/modm/driver/position/vl6180.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "driver" module.name = "vl6180" + module.description = "VL6180X Proximity Sensor" def prepare(module, options): module.depends( diff --git a/src/modm/driver/pressure/amsys5915.hpp b/src/modm/driver/pressure/amsys5915.hpp index 93f19bb12a..e74c36b46c 100644 --- a/src/modm/driver/pressure/amsys5915.hpp +++ b/src/modm/driver/pressure/amsys5915.hpp @@ -24,6 +24,7 @@ namespace modm template < typename I2cMaster > class Amsys5915; +/// @ingroup modm_driver_amsys5915 struct amsys5915 { struct modm_packed @@ -91,14 +92,7 @@ struct amsys5915 }; /** - * Driver for the AMSYS 5915 differential and absolute pressure sensors. - * - * The device runs a cyclic program, which will store a corrected pressure value with - * 12 bit resolution about every 500 μs within the output registers of the internal ASIC. - * - * Datasheet: http://www.amsys.de/sheets/amsys.de.ams5915.pdf - * - * @ingroup driver_pressure + * @ingroup modm_driver_amsys5915 * @author Raphael Lehman, Niklas Hauser */ template < typename I2cMaster > diff --git a/src/modm/driver/pressure/amsys5915.lb b/src/modm/driver/pressure/amsys5915.lb index 8957290926..b4223eaaf5 100644 --- a/src/modm/driver/pressure/amsys5915.lb +++ b/src/modm/driver/pressure/amsys5915.lb @@ -14,6 +14,15 @@ def init(module): module.parent = "driver" module.name = "amsys5915" + module.description = """\ +# AMSYS 5915 Pressure Sensor + +Driver for the AMSYS 5915 differential and absolute pressure sensors. +The device runs a cyclic program, which will store a corrected pressure value with +12 bit resolution about every 500 μs within the output registers of the internal ASIC. + +[Datasheet](http://www.amsys.de/sheets/amsys.de.ams5915.pdf) +""" def prepare(module, options): module.depends( diff --git a/src/modm/driver/pressure/bme280.hpp b/src/modm/driver/pressure/bme280.hpp index e64939498f..0f2f188099 100644 --- a/src/modm/driver/pressure/bme280.hpp +++ b/src/modm/driver/pressure/bme280.hpp @@ -27,6 +27,7 @@ namespace modm template < typename I2cMaster > class Bme280; +/// @ingroup modm_driver_bme280 struct bme280 { @@ -194,16 +195,8 @@ using DataDouble = modm::bme280data::DataDouble; }; /** - * BME280 digital absolute pressure sensor driver - * - * The BME280 is a high precision digital temperature, pressure and humidity sensor with I2C interface. - * - * It is known that many BME280-modules suffer from self-heating (I2C pull-ups?). - * So the reported temperature is about 1 to 3 degree higher than with other sensors. - * Forced ventilation can drop the temperature by 2 to 3 degrees. - * * @author Sascha Schade - * @ingroup driver_pressure + * @ingroup modm_driver_bme280 * * @tparam I2cMaster I2C interface */ diff --git a/src/modm/driver/pressure/bme280.lb b/src/modm/driver/pressure/bme280.lb index 8a95448b31..5f07b6e1a8 100644 --- a/src/modm/driver/pressure/bme280.lb +++ b/src/modm/driver/pressure/bme280.lb @@ -14,6 +14,16 @@ def init(module): module.parent = "driver" module.name = "bme280" + module.description = """\ +# BME280 Pressure Sensor + +The BME280 is a high precision digital temperature, pressure and humidity +sensor with I2C interface. + +It is known that many BME280-modules suffer from self-heating (I2C pull-ups?). +So the reported temperature is about 1 to 3 degree higher than with other sensors. +Forced ventilation can drop the temperature by 2 to 3 degrees. +""" def prepare(module, options): module.depends( diff --git a/src/modm/driver/pressure/bme280_data.hpp b/src/modm/driver/pressure/bme280_data.hpp index aa62254568..e4d0784307 100644 --- a/src/modm/driver/pressure/bme280_data.hpp +++ b/src/modm/driver/pressure/bme280_data.hpp @@ -64,6 +64,7 @@ Calibration int8_t H6; // e7 }; +/// @ingroup modm_driver_bme280 struct modm_packed DataBase { @@ -125,6 +126,7 @@ DataBase }; }; +/// @ingroup modm_driver_bme280 class modm_packed Data : public DataBase { @@ -198,6 +200,7 @@ Data : public DataBase }; #ifndef __AVR__ +/// @ingroup modm_driver_bme280 class modm_packed DataDouble : public DataBase { diff --git a/src/modm/driver/pressure/bmp085.hpp b/src/modm/driver/pressure/bmp085.hpp index c35198bebe..0c299bec49 100644 --- a/src/modm/driver/pressure/bmp085.hpp +++ b/src/modm/driver/pressure/bmp085.hpp @@ -23,6 +23,7 @@ namespace modm { +/// @ingroup modm_driver_bmp085 struct bmp085 { @@ -96,23 +97,9 @@ using DataDouble = modm::bmp085data::DataDouble; }; /** - * BMP085 digital absolute pressure sensor driver - * - * The BMP085 is a high precision digital pressure sensor with I2C interface. - * Unfortunately this sensor is so sensitive, it will give you wrong results - * when there is traffic on the I2C during either temperature or pressure - * conversion. So during that time make sure no other sensors on the bus - * are read out. - * - * For further information, consult the - * - * datasheet. - * - * Also compatible to and tested with BMP180. - * * @author Niklas Hauser * @author Sascha Schade - * @ingroup driver_pressure + * @ingroup modm_driver_bmp085 * * @tparam I2cMaster I2C interface */ diff --git a/src/modm/driver/pressure/bmp085.lb b/src/modm/driver/pressure/bmp085.lb index 7813a48d05..2fc0769ac2 100644 --- a/src/modm/driver/pressure/bmp085.lb +++ b/src/modm/driver/pressure/bmp085.lb @@ -14,6 +14,20 @@ def init(module): module.parent = "driver" module.name = "bmp085" + module.description = """\ +# BMP085 Pressure Sensor + +The BMP085 is a high precision digital pressure sensor with I2C interface. +Unfortunately this sensor is so sensitive, it will give you wrong results +when there is traffic on the I2C during either temperature or pressure +conversion. So during that time make sure no other sensors on the bus +are read out. + +For further information, consult the [datasheet][]. +Also compatible to and tested with BMP180. + +[datasheet]: http://www.bosch-sensortec.com/content/language1/downloads/BST-BMP085-DS000-06.pdf +""" def prepare(module, options): module.depends( diff --git a/src/modm/driver/pressure/bmp085_data.hpp b/src/modm/driver/pressure/bmp085_data.hpp index 18ce7eb0be..8c075d9e55 100644 --- a/src/modm/driver/pressure/bmp085_data.hpp +++ b/src/modm/driver/pressure/bmp085_data.hpp @@ -56,6 +56,7 @@ Calibration int16_t md; }; +/// @ingroup modm_driver_bmp085 class modm_packed DataBase { @@ -108,6 +109,7 @@ DataBase }; }; +/// @ingroup modm_driver_bmp085 class modm_packed Data : public DataBase { @@ -169,6 +171,7 @@ Data : public DataBase }; #ifndef __AVR__ +/// @ingroup modm_driver_bmp085 class modm_packed DataDouble : public DataBase { diff --git a/src/modm/driver/pressure/hclax.hpp b/src/modm/driver/pressure/hclax.hpp index f3d6f6ed82..76f36d89c9 100644 --- a/src/modm/driver/pressure/hclax.hpp +++ b/src/modm/driver/pressure/hclax.hpp @@ -24,6 +24,7 @@ namespace modm template < typename I2cMaster > class HclaX; +/// @ingroup modm_driver_hclax struct hclax { struct modm_packed @@ -59,12 +60,7 @@ struct hclax }; /** - * Driver for the HCLA differential pressure sensors. - * - * The device runs a cyclic program, which will store a corrected pressure value with - * 12 bit resolution about every 250 μs within the output registers of the internal ASIC. - * - * @ingroup driver_pressure + * @ingroup modm_driver_hclax * @author Niklas Hauser */ template < typename I2cMaster > diff --git a/src/modm/driver/pressure/hclax.lb b/src/modm/driver/pressure/hclax.lb index 3f3dd68798..bd017ab91f 100644 --- a/src/modm/driver/pressure/hclax.lb +++ b/src/modm/driver/pressure/hclax.lb @@ -14,6 +14,14 @@ def init(module): module.parent = "driver" module.name = "hclax" + module.description = """\ +# HCLA Pressure Sensor + +Driver for the HCLA differential pressure sensors. + +The device runs a cyclic program, which will store a corrected pressure value with +12 bit resolution about every 250 μs within the output registers of the internal ASIC. +""" def prepare(module, options): module.depends( diff --git a/src/modm/driver/pressure/scp1000.hpp b/src/modm/driver/pressure/scp1000.hpp index 4dbcd16cd9..2406e0631e 100644 --- a/src/modm/driver/pressure/scp1000.hpp +++ b/src/modm/driver/pressure/scp1000.hpp @@ -18,6 +18,7 @@ namespace modm { + /// @ingroup modm_driver_scp1000 namespace scp1000 { /// The addresses of the Direct Access Registers. @@ -104,7 +105,7 @@ Ultra Low Power : ~1Hz | 15bit | 14bit * datasheet. * * \author Niklas Hauser - * \ingroup driver_pressure + * \ingroup modm_driver_scp1000 * * \tparam Spi software or hardware Spi interface * \tparam Cs Chip Select pin diff --git a/src/modm/driver/pwm/max6966.hpp b/src/modm/driver/pwm/max6966.hpp index c0672e4c4f..476a60ca56 100644 --- a/src/modm/driver/pwm/max6966.hpp +++ b/src/modm/driver/pwm/max6966.hpp @@ -20,6 +20,7 @@ namespace modm { + /// @ingroup modm_driver_max6966 namespace max6966 { static const uint8_t WRITE = 0x00; @@ -112,7 +113,7 @@ namespace modm * \tparam DRIVERS Number of daisy-chained chips * * \author Niklas Hauser - * \ingroup driver_pwm + * \ingroup modm_driver_max6966 */ template< typename Spi, diff --git a/src/modm/driver/pwm/max6966.lb b/src/modm/driver/pwm/max6966.lb index 83d7802813..8d3201e3e0 100644 --- a/src/modm/driver/pwm/max6966.lb +++ b/src/modm/driver/pwm/max6966.lb @@ -14,6 +14,11 @@ def init(module): module.parent = "driver" module.name = "max6966" + module.description = """\ +# MAX6966 8-bit PWM Driver + +10-channel, daisy-chainable, constant-current sink, 8bit PWM LED driver. +""" def prepare(module, options): module.depends( diff --git a/src/modm/driver/pwm/pca9685.hpp b/src/modm/driver/pwm/pca9685.hpp index 7f934db2e7..803c04f5eb 100644 --- a/src/modm/driver/pwm/pca9685.hpp +++ b/src/modm/driver/pwm/pca9685.hpp @@ -18,6 +18,7 @@ namespace modm { +/// @ingroup modm_driver_pca9685 struct pca9685 { enum Register @@ -142,7 +143,7 @@ struct pca9685 * @tparam I2cMaster I2C interface * * @author Christian Menard - * @ingroup driver_pwm + * @ingroup modm_driver_pca9685 */ template class Pca9685 : public pca9685, public modm::I2cDevice< I2cMaster, 1, I2cWriteTransaction > diff --git a/src/modm/driver/pwm/pca9685.lb b/src/modm/driver/pwm/pca9685.lb index 3889ae26cc..4b8520e2da 100644 --- a/src/modm/driver/pwm/pca9685.lb +++ b/src/modm/driver/pwm/pca9685.lb @@ -14,6 +14,11 @@ def init(module): module.parent = "driver" module.name = "pca9685" + module.description = """\ +# PCA9685 12-bit PWM Driver + +PCA9685 16-channel, 12-bit PWM LED controller via I2C-Bus. +""" def prepare(module, options): module.depends( diff --git a/src/modm/driver/pwm/tlc594x.hpp b/src/modm/driver/pwm/tlc594x.hpp index 99d2286eb1..d7b92e6b96 100644 --- a/src/modm/driver/pwm/tlc594x.hpp +++ b/src/modm/driver/pwm/tlc594x.hpp @@ -57,7 +57,7 @@ namespace modm * @tparam Xerr Error pin, use modm::platform::GpioUnused if not connected * * @author Niklas Hauser - * @ingroup driver_pwm + * @ingroup modm_driver_tlc594x */ template< uint16_t CHANNELS, diff --git a/src/modm/driver/radio/nrf24/nrf24.dox b/src/modm/driver/radio/nrf24/nrf24.dox deleted file mode 100644 index 936fe3cf3d..0000000000 --- a/src/modm/driver/radio/nrf24/nrf24.dox +++ /dev/null @@ -1,7 +0,0 @@ -// coding: utf-8 -// - -/** - * \ingroup driver_radio - * \defgroup nrf24 NRF24 - */ diff --git a/src/modm/driver/radio/nrf24/nrf24.lb b/src/modm/driver/radio/nrf24/nrf24.lb index 68d23996f8..abb0a7ab7d 100644 --- a/src/modm/driver/radio/nrf24/nrf24.lb +++ b/src/modm/driver/radio/nrf24/nrf24.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "driver" module.name = "nrf24" + module.description = "NRF24 Drivers" def prepare(module, options): module.depends( diff --git a/src/modm/driver/radio/nrf24/nrf24_config.hpp b/src/modm/driver/radio/nrf24/nrf24_config.hpp index f9df1d7dd0..8da0a8aa4a 100644 --- a/src/modm/driver/radio/nrf24/nrf24_config.hpp +++ b/src/modm/driver/radio/nrf24/nrf24_config.hpp @@ -33,7 +33,7 @@ namespace modm * wireless modules. It doesn't implement every aspect, but hopefully * all the often used ones. * - * @ingroup nrf24 + * @ingroup modm_driver_nrf24 * @author Daniel Krebs */ template diff --git a/src/modm/driver/radio/nrf24/nrf24_data.hpp b/src/modm/driver/radio/nrf24/nrf24_data.hpp index 795da6d17d..51fd046a3c 100644 --- a/src/modm/driver/radio/nrf24/nrf24_data.hpp +++ b/src/modm/driver/radio/nrf24/nrf24_data.hpp @@ -39,7 +39,7 @@ namespace modm * */ -/// @ingroup nrf24 +/// @ingroup modm_driver_nrf24 /// @author Daniel Krebs template class Nrf24Data : modm::Nrf24Register diff --git a/src/modm/driver/radio/nrf24/nrf24_definitions.hpp b/src/modm/driver/radio/nrf24/nrf24_definitions.hpp index 51a3e3a416..bdb6ecf5e6 100644 --- a/src/modm/driver/radio/nrf24/nrf24_definitions.hpp +++ b/src/modm/driver/radio/nrf24/nrf24_definitions.hpp @@ -21,6 +21,7 @@ namespace modm { +/// @ingroup modm_driver_nrf24 struct Nrf24Register { /* Commands */ diff --git a/src/modm/driver/radio/nrf24/nrf24_phy.hpp b/src/modm/driver/radio/nrf24/nrf24_phy.hpp index 6ea552e2a8..63ec3b9c0f 100644 --- a/src/modm/driver/radio/nrf24/nrf24_phy.hpp +++ b/src/modm/driver/radio/nrf24/nrf24_phy.hpp @@ -33,7 +33,7 @@ namespace modm /** * Hardware abstraction layer for nRF24L01+ * - * @ingroup nrf24 + * @ingroup modm_driver_nrf24 * @author Daniel Krebs */ template diff --git a/src/modm/driver/rtc/ds1302.hpp b/src/modm/driver/rtc/ds1302.hpp index b7b34b2ab5..93fcfdc45b 100644 --- a/src/modm/driver/rtc/ds1302.hpp +++ b/src/modm/driver/rtc/ds1302.hpp @@ -13,13 +13,10 @@ #ifndef MODM_DS1302_HPP #define MODM_DS1302_HPP -/** - * \ingroup driver_rtc - * \defgroup ds1302 DS1302 - */ - namespace modm { + +/// @ingroup modm_driver_ds1302 struct ds1302 { struct Config @@ -110,7 +107,7 @@ struct ds1302 /** * Realtime clock DS1302 * - * @ingroup ds1302 + * @ingroup modm_driver_ds1302 * @author Sascha Schade (strongly-typed) */ template < class PinSet > diff --git a/src/modm/driver/rtc/ds1302.lb b/src/modm/driver/rtc/ds1302.lb index 010a676c9a..65e2b9c444 100644 --- a/src/modm/driver/rtc/ds1302.lb +++ b/src/modm/driver/rtc/ds1302.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "driver" module.name = "ds1302" + module.description = "DS1302 Real-Time Clock" def prepare(module, options): module.depends( diff --git a/src/modm/driver/storage/at45db0x1d.hpp b/src/modm/driver/storage/at45db0x1d.hpp index 25a7e8d7fe..3168402bc8 100644 --- a/src/modm/driver/storage/at45db0x1d.hpp +++ b/src/modm/driver/storage/at45db0x1d.hpp @@ -17,7 +17,7 @@ namespace modm { /** * \see At45db0x1d - * \ingroup driver_storage + * \ingroup modm_driver_at45db */ namespace at45db { @@ -54,7 +54,7 @@ namespace modm * \see at45db * \see Datasheet * - * \ingroup driver_storage + * \ingroup modm_driver_at45db * \author Fabian Greif */ template diff --git a/src/modm/driver/storage/block_device.lb b/src/modm/driver/storage/block_device.lb index 278258ca9c..d54319eb6d 100644 --- a/src/modm/driver/storage/block_device.lb +++ b/src/modm/driver/storage/block_device.lb @@ -10,6 +10,7 @@ class BlockDeviceFile(Module): def init(self, module): module.name = "file" + module.description = "File Block Device" def prepare(self, module, options): module.depends(":architecture:block.device") @@ -24,6 +25,7 @@ class BlockDeviceFile(Module): class BlockDeviceHeap(Module): def init(self, module): module.name = "heap" + module.description = "Heap Block Device" def prepare(self, module, options): module.depends(":architecture:block.device", ":utils") @@ -38,6 +40,7 @@ class BlockDeviceHeap(Module): class BlockDeviceMirror(Module): def init(self, module): module.name = "mirror" + module.description = "Mirroring Block Device" def prepare(self, module, options): module.depends(":architecture:block.device") @@ -52,6 +55,11 @@ class BlockDeviceMirror(Module): class BlockDeviceSpiFlash(Module): def init(self, module): module.name = "spi.flash" + module.description = """\ +# SPI Flash Block Device + +Microchip SST26VF064B 64MBit flash chip in SOIJ-8, WDFN-8 or SOIC-16. +""" def prepare(self, module, options): module.depends(":architecture:block.device", ":architecture:spi.device", ":architecture:register") @@ -66,6 +74,7 @@ class BlockDeviceSpiFlash(Module): def init(module): module.parent = "driver" module.name = "block.device" + module.description = "Block Devices" def prepare(module, options): module.add_submodule(BlockDeviceFile()) diff --git a/src/modm/driver/storage/block_device_file.hpp b/src/modm/driver/storage/block_device_file.hpp index 5b7bc7e953..67e08d9254 100644 --- a/src/modm/driver/storage/block_device_file.hpp +++ b/src/modm/driver/storage/block_device_file.hpp @@ -28,7 +28,7 @@ namespace modm * * Persistant and useful for testing and hosted code * - * \ingroup driver_storage + * \ingroup modm_driver_block_device_file * \author Raphael Lehmann */ template diff --git a/src/modm/driver/storage/block_device_heap.hpp b/src/modm/driver/storage/block_device_heap.hpp index b5c809e808..0955e2ef51 100644 --- a/src/modm/driver/storage/block_device_heap.hpp +++ b/src/modm/driver/storage/block_device_heap.hpp @@ -29,7 +29,7 @@ namespace modm * \tparam DeviceSize The size of the block device * \tparam externalMemory Set to true to use an external supplied memory block (see `initialize(uint8_t*)`) * - * \ingroup driver_storage + * \ingroup modm_driver_block_device_heap * \author Raphael Lehmann */ template diff --git a/src/modm/driver/storage/block_device_mirror.hpp b/src/modm/driver/storage/block_device_mirror.hpp index 4398d8f507..888fb16191 100644 --- a/src/modm/driver/storage/block_device_mirror.hpp +++ b/src/modm/driver/storage/block_device_mirror.hpp @@ -30,7 +30,7 @@ namespace modm * \tparam BlockDeviceA First block device of the mirrored block devices * \tparam BlockDeviceB Second block device * - * \ingroup driver_storage + * \ingroup modm_driver_block_device_mirror * \author Raphael Lehmann */ template diff --git a/src/modm/driver/storage/block_device_spiflash.hpp b/src/modm/driver/storage/block_device_spiflash.hpp index 7412a53c03..30b90f200c 100644 --- a/src/modm/driver/storage/block_device_spiflash.hpp +++ b/src/modm/driver/storage/block_device_spiflash.hpp @@ -35,7 +35,7 @@ namespace modm * The `read()`, `erase()`,`program()` and `write()` methodes wait for * the chip to finish writing to the flash. * - * \ingroup driver_storage + * \ingroup modm_driver_block_device_spi_flash * \author Raphael Lehmann */ template diff --git a/src/modm/driver/storage/fat.hpp b/src/modm/driver/storage/fat.hpp index fa06ab58ff..a888210398 100644 --- a/src/modm/driver/storage/fat.hpp +++ b/src/modm/driver/storage/fat.hpp @@ -21,6 +21,7 @@ namespace modm { + /// @ingroup modm_driver_fat namespace fat { typedef DRESULT Result; diff --git a/src/modm/driver/storage/fat.lb b/src/modm/driver/storage/fat.lb index 6233bdd496..91f06b6cd1 100644 --- a/src/modm/driver/storage/fat.lb +++ b/src/modm/driver/storage/fat.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "driver" module.name = "fat" + module.description = "FAT File System" def prepare(module, options): if options[":target"].identifier["platform"] == "avr": diff --git a/src/modm/driver/storage/i2c_eeprom.hpp b/src/modm/driver/storage/i2c_eeprom.hpp index ac71b1d911..228b3fc061 100644 --- a/src/modm/driver/storage/i2c_eeprom.hpp +++ b/src/modm/driver/storage/i2c_eeprom.hpp @@ -56,7 +56,7 @@ struct i2cEeprom * I2C eeprom with an 16-bit address pointer. * Base address for most 24xxyyyy eeproms is 0x50. * - * @ingroup driver_storage + * @ingroup modm_driver_i2c_eeprom * @author Fabian Greif * @author Niklas Hauser */ diff --git a/src/modm/driver/storage/i2c_eeprom.lb b/src/modm/driver/storage/i2c_eeprom.lb index f7dd65963b..a5047b08b4 100644 --- a/src/modm/driver/storage/i2c_eeprom.lb +++ b/src/modm/driver/storage/i2c_eeprom.lb @@ -14,6 +14,13 @@ def init(module): module.parent = "driver" module.name = "i2c.eeprom" + module.description = """\ +# I2C Eeprom + +Compatible with the 24C256 (ST) and 24FC1025 (Microchip) family and other +I2C eeprom with an 16-bit address pointer. +Base address for most 24xxyyyy eeproms is 0x50. +""" def prepare(module, options): module.depends(":architecture:i2c.device") diff --git a/src/modm/driver/storage/spi_ram.hpp b/src/modm/driver/storage/spi_ram.hpp index a653c62a53..7605cadfa1 100644 --- a/src/modm/driver/storage/spi_ram.hpp +++ b/src/modm/driver/storage/spi_ram.hpp @@ -28,7 +28,7 @@ namespace modm * * \see Datasheet * - * \ingroup driver_storage + * \ingroup modm_driver_spi_ram * \author Fabian Greif */ template diff --git a/src/modm/driver/temperature/ds1631.hpp b/src/modm/driver/temperature/ds1631.hpp index 5d9c2347ff..4ef609c41b 100644 --- a/src/modm/driver/temperature/ds1631.hpp +++ b/src/modm/driver/temperature/ds1631.hpp @@ -23,6 +23,7 @@ namespace modm { +/// @ingroup modm_driver_ds1631 struct ds1631 { protected: @@ -103,7 +104,7 @@ struct ds1631 * * @see ds1631 * - * @ingroup driver_temperature + * @ingroup modm_driver_ds1631 * @author Fabian Greif * @author Niklas Hauser */ diff --git a/src/modm/driver/temperature/ds1631.lb b/src/modm/driver/temperature/ds1631.lb index 03f78044cc..dc2b6393b4 100644 --- a/src/modm/driver/temperature/ds1631.lb +++ b/src/modm/driver/temperature/ds1631.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "driver" module.name = "ds1631" + module.description = "DS1x31 Temperature Sensor" def prepare(module, options): module.depends( diff --git a/src/modm/driver/temperature/ds18b20.hpp b/src/modm/driver/temperature/ds18b20.hpp index cb94270702..16c879eb6f 100644 --- a/src/modm/driver/temperature/ds18b20.hpp +++ b/src/modm/driver/temperature/ds18b20.hpp @@ -18,31 +18,11 @@ namespace modm { /** - * \brief Programmable resolution 1-wire digital thermometer - * - * The DS18B20 digital thermometer provides 9-bit to 12-bit Celsius - * temperature measurements and has an alarm function with non-volatile - * user-programmable upper and lower trigger points. The DS18B20 - * communicates over a 1-Wire bus that by definition requires only one - * data line (and ground) for communication with a central microprocessor. - * - * It has an operating temperature range of -55°C to +125°C and is - * accurate to ±0.5°C over the range of -10°C to +85°C. - * - * In addition, the DS18B20 can derive power directly from the data line - * ("parasite power"), eliminating the need for an external power supply. - * - * Features: - * - Power Supply Range is 3.0V to 5.5V - * - Each device has a unique 64-Bit Serial Code Stored in an On-Board ROM - * - Thermometer Resolution is User Selectable from 9 to 12 Bits - * - Converts Temperature to 12-Bit Digital Word in 750ms (Max) - * * \todo Implement the configure() method to set the resolution * and the temperature alarm functionality * * \author Fabian Greif - * \ingroup driver_temperature + * \ingroup modm_driver_ds18b20 */ template class Ds18b20 diff --git a/src/modm/driver/temperature/ds18b20.lb b/src/modm/driver/temperature/ds18b20.lb index bdc9ac61dd..4ca4e1941c 100644 --- a/src/modm/driver/temperature/ds18b20.lb +++ b/src/modm/driver/temperature/ds18b20.lb @@ -14,6 +14,29 @@ def init(module): module.parent = "driver" module.name = "ds18b20" + module.description = """\ +# 1-Wire Thermometer + +Programmable resolution 1-wire digital thermometer. + +The DS18B20 digital thermometer provides 9-bit to 12-bit Celsius +temperature measurements and has an alarm function with non-volatile +user-programmable upper and lower trigger points. The DS18B20 +communicates over a 1-Wire bus that by definition requires only one +data line (and ground) for communication with a central microprocessor. + +It has an operating temperature range of -55°C to +125°C and is +accurate to ±0.5°C over the range of -10°C to +85°C. + +In addition, the DS18B20 can derive power directly from the data line +("parasite power"), eliminating the need for an external power supply. + +Features: +- Power Supply Range is 3.0V to 5.5V +- Each device has a unique 64-Bit Serial Code Stored in an On-Board ROM +- Thermometer Resolution is User Selectable from 9 to 12 Bits +- Converts Temperature to 12-Bit Digital Word in 750ms (Max) +""" def prepare(module, options): module.depends(":architecture:1-wire") diff --git a/src/modm/driver/temperature/lm75.hpp b/src/modm/driver/temperature/lm75.hpp index 21f1d4089b..96099546e2 100644 --- a/src/modm/driver/temperature/lm75.hpp +++ b/src/modm/driver/temperature/lm75.hpp @@ -32,6 +32,7 @@ class Tmp102; template < class I2cMaster > class Tmp175; +/// @ingroup modm_driver_lm75 struct lm75 { protected: @@ -114,16 +115,7 @@ struct lm75 }; /** - * LM75 digital temperature sensor driver. - * - * The LM75 is a digital temperature sensor with an I2C interface - * and measures temperature over a range of -55 to +125 deg Celsius with - * a resolution of 0.5 deg C and an accuracy of up to 2 deg C. - * - * The sensor has a default refresh rate between 3Hz and 10Hz which is - * hardcoded into the sensor and cannot be changed. - * - * @ingroup driver_temperature + * @ingroup modm_driver_lm75 * * @author Fabian Greif * @author Niklas Hauser diff --git a/src/modm/driver/temperature/lm75.lb b/src/modm/driver/temperature/lm75.lb index 029c17a089..10882d2656 100644 --- a/src/modm/driver/temperature/lm75.lb +++ b/src/modm/driver/temperature/lm75.lb @@ -14,6 +14,18 @@ def init(module): module.parent = "driver" module.name = "lm75" + module.description = """\ +# LM75 Thermometer + +LM75 digital temperature sensor driver. + +The LM75 is a digital temperature sensor with an I2C interface +and measures temperature over a range of -55 to +125 deg Celsius with +a resolution of 0.5 deg C and an accuracy of up to 2 deg C. + +The sensor has a default refresh rate between 3Hz and 10Hz which is +hardcoded into the sensor and cannot be changed. +""" def prepare(module, options): module.depends( diff --git a/src/modm/driver/temperature/ltc2984.hpp b/src/modm/driver/temperature/ltc2984.hpp index f0227af13a..fdeae17d29 100644 --- a/src/modm/driver/temperature/ltc2984.hpp +++ b/src/modm/driver/temperature/ltc2984.hpp @@ -21,6 +21,7 @@ namespace modm { +/// @ingroup modm_driver_ltc2984 struct ltc2984 { struct modm_packed @@ -335,14 +336,7 @@ inline ltc2984::CommandStatus operator |(ltc2984::CommandStatus r, ltc2984::Chan } /** - * \brief LTC2983/LTC2984: Integrated temperature measurement system (20 channel) - * - * The integrated EEPROM of the LTC2984 is not supported by now. - * LTC2984 and LTC2983 are 100% compatible except the LTC2983 has no integrated EEPROM. - * - * \see Datasheet - * - * \ingroup driver_temperature + * \ingroup modm_driver_ltc2984 * \author Raphael Lehmann */ template < class SpiMaster, class Cs > diff --git a/src/modm/driver/temperature/ltc2984.lb b/src/modm/driver/temperature/ltc2984.lb index 87bf271a1a..94552377d3 100644 --- a/src/modm/driver/temperature/ltc2984.lb +++ b/src/modm/driver/temperature/ltc2984.lb @@ -14,6 +14,16 @@ def init(module): module.parent = "driver" module.name = "ltc2984" + module.description = """\ +# LTC298x Thermometer + +LTC2983/LTC2984: Integrated temperature measurement system (20 channel) + +The integrated EEPROM of the LTC2984 is not supported by now. +LTC2984 and LTC2983 are 100%% compatible except the LTC2983 has no integrated EEPROM. + +[Datasheet](http://cds.linear.com/docs/en/datasheet/2984fb.pdf) +""" def prepare(module, options): module.depends( diff --git a/src/modm/driver/temperature/tmp102.hpp b/src/modm/driver/temperature/tmp102.hpp index fe2d83b557..0011ec8df8 100644 --- a/src/modm/driver/temperature/tmp102.hpp +++ b/src/modm/driver/temperature/tmp102.hpp @@ -28,6 +28,7 @@ namespace modm template < class I2cMaster > class Tmp102; +/// @ingroup modm_driver_tmp102 struct tmp102 : public lm75 { protected: @@ -105,22 +106,7 @@ struct tmp102 : public lm75 }; /** - * TMP102 digital temperature sensor driver - * - * The TMP102 is a digital temperature sensor with an I2C interface - * and measures temperature over a range of -40 to +125 deg Celsius with a - * resolution of 1/16 (0.0625) deg C and an accuracy of up to 0.5 deg C. - * - * The sensor has a default refresh rate of 4Hz but can be set from - * 0.25Hz up to 33Hz using `setUpdateRate(rate)`. - * The sensor will then read itself when calling the `update()` method - * frequently. - * - * However, you may manually start a conversion with `startConversion()`, wait - * for 30ms and then `readTemperature()` to achieve other (less frequent) - * update rates. - * - * @ingroup driver_temperature + * @ingroup modm_driver_tmp102 * @author Niklas Hauser */ template < class I2cMaster > diff --git a/src/modm/driver/temperature/tmp102.lb b/src/modm/driver/temperature/tmp102.lb index 2b05813d4c..ff0d12fc11 100644 --- a/src/modm/driver/temperature/tmp102.lb +++ b/src/modm/driver/temperature/tmp102.lb @@ -14,6 +14,22 @@ def init(module): module.parent = "driver" module.name = "tmp102" + module.description = """\ +# TMP102 Thermometer + +The TMP102 is a digital temperature sensor with an I2C interface +and measures temperature over a range of -40 to +125 deg Celsius with a +resolution of 1/16 (0.0625) deg C and an accuracy of up to 0.5 deg C. + +The sensor has a default refresh rate of 4Hz but can be set from +0.25Hz up to 33Hz using `setUpdateRate(rate)`. +The sensor will then read itself when calling the `update()` method +frequently. + +However, you may manually start a conversion with `startConversion()`, wait +for 30ms and then `readTemperature()` to achieve other (less frequent) +update rates. +""" def prepare(module, options): module.depends( diff --git a/src/modm/driver/temperature/tmp175.hpp b/src/modm/driver/temperature/tmp175.hpp index e19146e1bd..83bc4fe9e2 100644 --- a/src/modm/driver/temperature/tmp175.hpp +++ b/src/modm/driver/temperature/tmp175.hpp @@ -26,6 +26,7 @@ namespace modm template < class I2cMaster > class Tmp175; +/// @ingroup modm_driver_tmp175 struct tmp175 : public lm75 { protected: @@ -59,17 +60,7 @@ struct tmp175 : public lm75 }; /** - * TMP175 digital temperature sensor driver. - * - * The TMP175 is a digital temperature sensor with a two-wire interface - * and measures temperature over a range of -40 to +125 deg Celsius with a - * resolution of 1/16 (0.0625) deg C and an accuracy of up to 1.5 deg C. - * - * The sensor has a default refresh rate of 4Hz but can be raised up to - * 30Hz by repeatedly manually starting a conversion (with startConversion()), - * which lasts between 30ms and 240ms depending on resolution. - * - * @ingroup driver_temperature + * @ingroup modm_driver_tmp175 * @author Niklas Hauser * * @tparam I2cMaster Asynchronous Interface diff --git a/src/modm/driver/temperature/tmp175.lb b/src/modm/driver/temperature/tmp175.lb index 17759ba312..d7bafabbc2 100644 --- a/src/modm/driver/temperature/tmp175.lb +++ b/src/modm/driver/temperature/tmp175.lb @@ -14,6 +14,19 @@ def init(module): module.parent = "driver" module.name = "tmp175" + module.description = """\ +# TMP175 Thermometer + +TMP175 digital temperature sensor driver. + +The TMP175 is a digital temperature sensor with a two-wire interface +and measures temperature over a range of -40 to +125 deg Celsius with a +resolution of 1/16 (0.0625) deg C and an accuracy of up to 1.5 deg C. + +The sensor has a default refresh rate of 4Hz but can be raised up to +30Hz by repeatedly manually starting a conversion (with startConversion()), +which lasts between 30ms and 240ms depending on resolution. +""" def prepare(module, options): module.depends( diff --git a/src/modm/driver/touch/ads7843.hpp b/src/modm/driver/touch/ads7843.hpp index bc98a93537..bba284d609 100644 --- a/src/modm/driver/touch/ads7843.hpp +++ b/src/modm/driver/touch/ads7843.hpp @@ -22,17 +22,8 @@ namespace modm { /** - * ADS7843 Touch Screen Controller. - * - * The ADS7843 by Texas Instruments is the de-facto standard for cheap - * resistive touch screens. - * - * There are many compatible devices from other manufacturers available, - * such as the UH7843 by Zilltek, the TSC2046 and the XPT2046 by XPTEK. - * All of these are 100% compatible with the ADS7843. - * * @author Fabian Greif - * @ingroup driver_touch + * @ingroup modm_driver_ads7843 */ template class Ads7843 diff --git a/src/modm/driver/touch/ads7843.lb b/src/modm/driver/touch/ads7843.lb index 8ac98a5403..ad9055bf56 100644 --- a/src/modm/driver/touch/ads7843.lb +++ b/src/modm/driver/touch/ads7843.lb @@ -14,6 +14,16 @@ def init(module): module.parent = "driver" module.name = "ads7843" + module.description = """\ +# ADS7843 Resistive Touch Controller + +The ADS7843 by Texas Instruments is the de-facto standard for cheap +resistive touch screens. + +There are many compatible devices from other manufacturers available, +such as the UH7843 by Zilltek, the TSC2046 and the XPT2046 by XPTEK. +All of these are 100%% compatible with the ADS7843. +""" def prepare(module, options): module.depends( diff --git a/src/modm/driver/touch/ft6x06.hpp b/src/modm/driver/touch/ft6x06.hpp index 4184205930..dc7022d548 100644 --- a/src/modm/driver/touch/ft6x06.hpp +++ b/src/modm/driver/touch/ft6x06.hpp @@ -21,6 +21,7 @@ namespace modm template < class I2cMaster > class Ft6x06; +/// @ingroup modm_driver_ft6x06 struct ft6x06 { protected: @@ -163,7 +164,7 @@ struct ft6x06 * descriptive. * * @author Niklas Hauser - * @ingroup driver_touch + * @ingroup modm_driver_ft6x06 */ template < typename I2cMaster > class Ft6x06 : public ft6x06, public modm::I2cDevice< I2cMaster, 3 > diff --git a/src/modm/driver/touch/ft6x06.lb b/src/modm/driver/touch/ft6x06.lb index 95d13b5a69..9fe05dadad 100644 --- a/src/modm/driver/touch/ft6x06.lb +++ b/src/modm/driver/touch/ft6x06.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "driver" module.name = "ft6x06" + module.description = "FT6x06 Capacitive Touch Controller" def prepare(module, options): module.depends(":architecture:i2c.device") diff --git a/src/modm/driver/usb/ft245.hpp b/src/modm/driver/usb/ft245.hpp index 177949dfa7..0d0f41b1c0 100644 --- a/src/modm/driver/usb/ft245.hpp +++ b/src/modm/driver/usb/ft245.hpp @@ -19,45 +19,7 @@ namespace modm { /** - * FT245 USB FIFO - * - * The FT245R USB FIFO from Future Technology Devices International is a - * single chip USB to parallel FIFO bidirectional data transfer interface. - * - * Wr and Rd must be GpioOutputs and set to output mode before. - * Rxf and Txe must be GpioInputs. - * Port is switched between input and output mode. - * - * \section ft245_example Example - * - * \code - * #include - * #include - * - * typedef modm::platform::GpioPort myPort; - * typedef modm::platform::GpioInputC11 Rxf; - * typedef modm::platform::GpioInputC10 Txe; - * typedef modm::platform::GpioOutputA15 Rd; - * typedef modm::platform::GpioOutputA9 Wr; - * - * typedef modm::Ft245 myFt; - * - * int - * main() - * { - * Rd::setOutput(modm::Gpio::High); - * Wr::setOutput(modm::Gpio::Low); - * - * while (1) - * { - * uint8_t c; - * if (myFt::read(c)) { - * myFt::write(c + 1); - * } - * } - * \endcode - * - * \ingroup driver_other + * \ingroup modm_driver_ft245 */ template < typename PORT, typename RD, diff --git a/src/modm/driver/usb/ft245.lb b/src/modm/driver/usb/ft245.lb index 09b4e5709d..9a3839fd26 100644 --- a/src/modm/driver/usb/ft245.lb +++ b/src/modm/driver/usb/ft245.lb @@ -14,6 +14,47 @@ def init(module): module.parent = "driver" module.name = "ft245" + module.description = """\ +# FT245 USB FIFO + +The FT245R USB FIFO from Future Technology Devices International is a +single chip USB to parallel FIFO bidirectional data transfer interface. + +Wr and Rd must be GpioOutputs and set to output mode before. +Rxf and Txe must be GpioInputs. +Port is switched between input and output mode. + +## Example + +```cpp +#include +#include +using namespace modm::platform; + +using myPort = GpioPort; +using Rxf = GpioInputC11; +using Txe = GpioInputC10; +using Rd = GpioOutputA15; +using Wr = GpioOutputA9; + +using myFt = modm::Ft245; + +int +main() +{ + Rd::setOutput(modm::Gpio::High); + Wr::setOutput(modm::Gpio::Low); + + while (1) + { + uint8_t c; + if (myFt::read(c)) { + myFt::write(c + 1); + } + } +} +``` +""" def prepare(module, options): module.depends(":architecture:gpio") diff --git a/src/modm/io/io.hpp b/src/modm/io/io.hpp index 60558af942..335f9f9315 100644 --- a/src/modm/io/io.hpp +++ b/src/modm/io/io.hpp @@ -11,12 +11,6 @@ */ // ---------------------------------------------------------------------------- -/** - * \defgroup io IO-Classes - * \brief A modul of IOStream and IODevices - * - */ - #include "io/iostream.hpp" #include "io/iodevice.hpp" #include "io/iodevice_wrapper.hpp" diff --git a/src/modm/io/iodevice.hpp b/src/modm/io/iodevice.hpp index 82825e31da..56177c7d84 100644 --- a/src/modm/io/iodevice.hpp +++ b/src/modm/io/iodevice.hpp @@ -20,7 +20,7 @@ namespace modm /** * Abstract calls of IO devices * - * @ingroup io + * @ingroup modm_io * @author Martin Rosekeit */ class IODevice diff --git a/src/modm/io/iodevice_wrapper.hpp b/src/modm/io/iodevice_wrapper.hpp index 1f03b741cc..68d6e8120f 100644 --- a/src/modm/io/iodevice_wrapper.hpp +++ b/src/modm/io/iodevice_wrapper.hpp @@ -23,7 +23,7 @@ namespace modm { /// The preferred behavior when the IODevice buffer is full -/// @ingroup io +/// @ingroup modm_io enum class IOBuffer { @@ -32,51 +32,7 @@ IOBuffer }; /** - * Wrapper to use any peripheral device that supports static - * write() and read() as an IODevice. - * - * You have to decide what happens when the device buffer is full - * and you cannot write to it at the moment. - * There are two options: - * 1. busy wait until the buffer is free, or - * 2. discard the bytes that cannot be written. - * - * Option 1 has the advantage, that none of your data will be lost, - * however, busy-waiting can take a long time and can mess up your - * program timings. - * There is also a **high risk of deadlock**, when writing to a - * IODevice inside of an interrupt and then busy-waiting forever - * because the IODevice requires interrupts itself to send out - * the data. - * - * It is therefore highly recommended to use option 2, where surplus - * data will be discarded. - * You should increase the IODevice buffer size, if you experience - * missing data from your connection. - * This behavior is also deadlock safe when called from inside another - * interrupt, and your program timing is minimally affected (essentially - * only coping data into the buffer). - * - * There is no default template argument, so that you hopefully make - * a concious decision and be aware of this behavior. - * - * Example: - * @code - * // configure a UART - * Uart0 uart; - * - * // wrap it into an IODevice - * modm::IODeviceWrapper device; - * - * // use this device to print a message - * device.write("Hello"); - * - * // or create a IOStream and use the stream to print something - * modm::IOStream stream(device); - * stream << " World!"; - * @endcode - * - * @ingroup io + * @ingroup modm_io * @tparam Device Peripheral which should be wrapped * @tparam behavior preferred behavior when the Device buffer is full */ diff --git a/src/modm/io/iostream.hpp b/src/modm/io/iostream.hpp index eeb7d2dff2..582bfe47e5 100644 --- a/src/modm/io/iostream.hpp +++ b/src/modm/io/iostream.hpp @@ -36,7 +36,7 @@ namespace modm * output or it reads values from a input and converts them to * a given type; * - * @ingroup io + * @ingroup modm_io * @author Martin Rosekeit */ class IOStream @@ -388,83 +388,6 @@ class IOStream } /** - * Simple printf() implemenation - * - * The format string is composed of zero or more directives: ordinary - * characters (not %), which are copied unchanged to the output stream; - * and conversion specifications, each of which results in fetching zero - * or more subsequent arguments. Each conversion specification is - * introduced by the % character. The arguments must properly correspond - * (after type promotion) with the conversion specifier. After the %, - * the following appear in sequence: - * - * - Zero or more of the following flags: - * - `-` A negative field width flag; the converted value is to be - * left adjusted on the field boundary. The converted value is - * padded on the right with blanks, rather than on the left with - * blanks. - * - `' '` (space) A blank should be left before a positive number - * produced by a signed conversion (d). - * - `+` A sign must always be placed before a number produced by a - * signed conversion. A `+` overrides a space if both are used. - * - An optional decimal digit string specifying a minimum field width. - * If the converted value has fewer characters than the field width, - * it will be padded with spaces on the left (or right, if the - * left-adjustment flag has been given) to fill out the field width. - * - An optional `h`, `l` or `ll` length modifier, that specifies that the argument - * for the `d`, `u`, or `x` conversion is a 8-bit ("h"), 32-bit ("l") or - * 64-bit ("ll") rather than 16-bit. - * - * The conversion specifiers and their meanings are: - * - `c` char (8-bit) - * - `s` string (char *) - * - `p` pointer (void *) - * - `d` signed decimal - * - `u` unsigned decimal - * - `x` hex - * - `f` float - * - `%` % - * - * Combined with the length modifiers you get: - * - `d` signed 16-bit - * - `ld` signed 32-bit - * - `lld` signed 64-bit (not yet) - * - `u` unsigned 16-bit - * - `lu` unsigned 32-bit - * - `llu` unsigned 64-bit (not yet) - * - `hx` 8-bit hex - * - `x` 16-bit hex - * - `lx` 32-bit hex - * - `llx` 64-bit hex (not yet) - * - * Examples, given `-100` as argument in the right type: - * \code - * %c: - * %s: - * %p: 0x0100 - * %d: -100 - * %ld: -100 - * %u: 65436 - * %lu: - * %hx: 0x9c - * %x: 0xff9c - * %lx: 0xffffff9c - * \endcode - * - * - `s` The "char *" argument is expected to be a pointer to an array - * of character type (pointer to a string). Characters from the array - * are written up to (but not including) a terminating NULL character; - * if a precision is specified, no more than the number specified are - * written. If a precision is given, no null character need be present; - * if the precision is not specified, or is greater than the size of - * the array, the array must contain a terminating NULL character. - * - `%` A `%` is written. No argument is converted. The complete conversion - * specification is "%%". - * - * In no case does a non-existent or small field width cause truncation - * of a numeric field; if the result of a conversion is wider than the - * field width, the field is expanded to contain the conversion result. - * * @param fmt Format string */ IOStream& @@ -542,9 +465,11 @@ class IOStream Mode mode; }; +/// @ingroup modm_io +/// @{ + /// Flushes the output stream. /// This manipulator simply calls the stream's flush() member function. -/// @ingroup io inline IOStream& flush(IOStream& ios) { @@ -552,7 +477,6 @@ flush(IOStream& ios) } //// Write a newline and flush the stream. -/// @ingroup io inline IOStream& endl(IOStream& ios) { @@ -560,7 +484,6 @@ endl(IOStream& ios) } /// set the output mode to binary style for `char` and `char*` -/// @ingroup io inline IOStream& bin(IOStream& ios) { @@ -568,7 +491,6 @@ bin(IOStream& ios) } /// set the output mode to hexadecimal style for `char` and `char*` -/// @ingroup io inline IOStream& hex(IOStream& ios) { @@ -576,16 +498,13 @@ hex(IOStream& ios) } /// set the output mode to ASCII style for `char` and `char*` -/// @ingroup io inline IOStream& ascii(IOStream& ios) { return ios.ascii(); } -/// @{ /// Set the foreground colour on ANSI terminals. -/// @ingroup io inline IOStream& black(IOStream& ios) { diff --git a/src/modm/io/module.lb b/src/modm/io/module.lb index 49857f1389..014c005f4c 100644 --- a/src/modm/io/module.lb +++ b/src/modm/io/module.lb @@ -13,6 +13,7 @@ def init(module): module.name = "io" + module.description = FileReader("module.md") def prepare(module, options): module.depends( diff --git a/src/modm/io/module.md b/src/modm/io/module.md new file mode 100644 index 0000000000..307a1bb96f --- /dev/null +++ b/src/modm/io/module.md @@ -0,0 +1,142 @@ +# Input/Output Streams + +The `modm::IOStream` class contains efficient formatting that supports both +C++ `std::basic_ostream`-like formatting via `operator <<` as well as +implementing a reasonably large subset of `printf`. + +```cpp +modm::IOStream stream(device); +stream << "format number 8: " << uint8_t(8) << " or as signed -100: " << int8_t(-100); +stream << modm::endl; + +stream.printf("format number 8: %u or as signed -100: %d", 8, -100); +``` + +## Using printf + +The format string is composed of zero or more directives: ordinary +characters (not %), which are copied unchanged to the output stream; +and conversion specifications, each of which results in fetching zero +or more subsequent arguments. Each conversion specification is +introduced by the % character. The arguments must properly correspond +(after type promotion) with the conversion specifier. After the %, +the following appear in sequence: + +Zero or more of the following flags: + +- `-` A negative field width flag; the converted value is to be + left adjusted on the field boundary. The converted value is + padded on the right with blanks, rather than on the left with + blanks. +- `' '` (space) A blank should be left before a positive number + produced by a signed conversion (d). +- `+` A sign must always be placed before a number produced by a + signed conversion. A `+` overrides a space if both are used. +- An optional decimal digit string specifying a minimum field width. + If the converted value has fewer characters than the field width, + it will be padded with spaces on the left (or right, if the + left-adjustment flag has been given) to fill out the field width. +- An optional `h`, `l` or `ll` length modifier, that specifies that the argument + for the `d`, `u`, or `x` conversion is a 8-bit ("h"), 32-bit ("l") or + 64-bit ("ll") rather than 16-bit. + +The conversion specifiers and their meanings are: + +- `c`: char (8-bit) +- `s`: string (`char *`) +- `p`: pointer (`void *`) +- `d`: signed decimal +- `u`: unsigned decimal +- `x`: hex +- `f`: float +- `%`: % + +Combined with the length modifiers you get: + +- `d`: signed 16-bit +- `ld`: signed 32-bit +- `lld`: signed 64-bit (not yet) +- `u`: unsigned 16-bit +- `lu`: unsigned 32-bit +- `llu`: unsigned 64-bit (not yet) +- `hx`: 8-bit hex +- `x`: 16-bit hex +- `lx`: 32-bit hex +- `llx`: 64-bit hex (not yet) + +Examples, given `-100` as argument in the right type: + +``` +%c: +%s: +%p: 0x0100 +%d: -100 +%ld: -100 +%u: 65436 +%lu: +%hx: 0x9c +%x: 0xff9c +%lx: 0xffffff9c +``` + +- `s`: The "char *" argument is expected to be a pointer to an array + of character type (pointer to a string). Characters from the array + are written up to (but not including) a terminating NULL character; + if a precision is specified, no more than the number specified are + written. If a precision is given, no null character need be present; + if the precision is not specified, or is greater than the size of + the array, the array must contain a terminating NULL character. +- `%`: A `%` is written. No argument is converted. The complete conversion + specification is `%%`. + +In no case does a non-existent or small field width cause truncation +of a numeric field; if the result of a conversion is wider than the +field width, the field is expanded to contain the conversion result. + + +## Redirecting IOStreams + +The `modm::IODeviceWrapper` transforms any peripheral device that provides static +`write()` and `read()` functions into an `IODevice`. + +You have to decide what happens when the device buffer is full and you cannot +write to it at the moment. There are two options: + +1. busy wait until the buffer is free, or +2. discard the bytes that cannot be written. + +Option 1 has the advantage, that none of your data will be lost, +however, busy-waiting can take a long time and can mess up your +program timings. +There is also a **high risk of deadlock**, when writing to a +IODevice inside of an interrupt and then busy-waiting forever +because the IODevice requires interrupts itself to send out +the data. + +It is therefore highly recommended to use option 2, where surplus +data will be discarded. +You should increase the IODevice buffer size, if you experience +missing data from your connection. +This behavior is also deadlock safe when called from inside another +interrupt, and your program timing is minimally affected (essentially +only coping data into the buffer). + +There is no default template argument, so that you hopefully make +a conscious decision and be aware of this behavior. + +Example: + +```cpp +// configure a UART +using Uart = Uart0; + +// wrap it into an IODevice +modm::IODeviceWrapper device; + +// use this device to print a message +device.write("Hello"); + +// or create a IOStream and use the stream to print something +modm::IOStream stream(device); +stream << " World!"; +``` \ No newline at end of file diff --git a/src/modm/math/filter.hpp b/src/modm/math/filter.hpp index 9f52db5d87..d869ef3b6b 100644 --- a/src/modm/math/filter.hpp +++ b/src/modm/math/filter.hpp @@ -12,12 +12,13 @@ */ // ---------------------------------------------------------------------------- -/** - * \ingroup math - * \defgroup filter Filter - * \brief Filters, Interpolators, Averages, PID controller - * - */ +namespace modm +{ + /// @ingroup modm_math_filter + namespace filter + { + } +} #include "filter/debounce.hpp" #include "filter/fir.hpp" diff --git a/src/modm/math/filter/debounce.hpp b/src/modm/math/filter/debounce.hpp index 036faa9616..ec81f2d2e1 100644 --- a/src/modm/math/filter/debounce.hpp +++ b/src/modm/math/filter/debounce.hpp @@ -23,7 +23,7 @@ namespace modm /** * \brief Debouncing binary signals * - * \ingroup filter + * \ingroup modm_math_filter */ template class Debounce diff --git a/src/modm/math/filter/fir.hpp b/src/modm/math/filter/fir.hpp index 611a1e1247..cad18c10be 100644 --- a/src/modm/math/filter/fir.hpp +++ b/src/modm/math/filter/fir.hpp @@ -27,7 +27,7 @@ namespace modm * \todo * * \author Kevin Laeufer - * \ingroup filter + * \ingroup modm_math_filter */ namespace filter { diff --git a/src/modm/math/filter/median.hpp b/src/modm/math/filter/median.hpp index 75be1e5336..fbbbd2a65f 100644 --- a/src/modm/math/filter/median.hpp +++ b/src/modm/math/filter/median.hpp @@ -48,7 +48,7 @@ namespace modm * \tparam T Input type * \tparam N Number of samples * - * \ingroup filter + * \ingroup modm_math_filter */ template class Median diff --git a/src/modm/math/filter/module.lb b/src/modm/math/filter/module.lb index a1b06a35cb..50166fa267 100644 --- a/src/modm/math/filter/module.lb +++ b/src/modm/math/filter/module.lb @@ -13,6 +13,7 @@ def init(module): module.parent = "math" module.name = "filter" + module.description = "Filters" def prepare(module, options): module.depends( diff --git a/src/modm/math/filter/moving_average.hpp b/src/modm/math/filter/moving_average.hpp index ce9ad1154c..fc20a80eb7 100644 --- a/src/modm/math/filter/moving_average.hpp +++ b/src/modm/math/filter/moving_average.hpp @@ -51,7 +51,7 @@ namespace modm * \tparam T Input type * \tparam N Number of samples (maximum is 65356 or 2**16) * - * \ingroup filter + * \ingroup modm_math_filter */ template class MovingAverage diff --git a/src/modm/math/filter/pid.hpp b/src/modm/math/filter/pid.hpp index de0fb61d1c..e0700738a8 100644 --- a/src/modm/math/filter/pid.hpp +++ b/src/modm/math/filter/pid.hpp @@ -50,7 +50,7 @@ namespace modm * \todo use the faster avr::mul and avr::mac functions * * \author Fabian Greif - * \ingroup filter + * \ingroup modm_math_filter */ template class Pid diff --git a/src/modm/math/filter/ramp.hpp b/src/modm/math/filter/ramp.hpp index 77ec5e9ead..64e560b551 100644 --- a/src/modm/math/filter/ramp.hpp +++ b/src/modm/math/filter/ramp.hpp @@ -32,7 +32,7 @@ namespace modm * \todo example * * \todo documentation - * \ingroup filter + * \ingroup modm_math_filter */ template class Ramp diff --git a/src/modm/math/filter/s_curve_controller.hpp b/src/modm/math/filter/s_curve_controller.hpp index cea7935920..fa5ca41270 100644 --- a/src/modm/math/filter/s_curve_controller.hpp +++ b/src/modm/math/filter/s_curve_controller.hpp @@ -38,7 +38,7 @@ namespace modm * \author Fabian Greif * \author Georgi Grinshpun * - * \ingroup filter + * \ingroup modm_math_filter */ template class SCurveController diff --git a/src/modm/math/filter/s_curve_generator.hpp b/src/modm/math/filter/s_curve_generator.hpp index 7b0af206ea..4874fd6121 100644 --- a/src/modm/math/filter/s_curve_generator.hpp +++ b/src/modm/math/filter/s_curve_generator.hpp @@ -22,7 +22,7 @@ namespace modm * * \todo documentation * \todo implementation - * \ingroup filter + * \ingroup modm_math_filter */ template class SCurveGenerator diff --git a/src/modm/math/geometry.hpp b/src/modm/math/geometry.hpp index c95b678e75..c4929a8662 100644 --- a/src/modm/math/geometry.hpp +++ b/src/modm/math/geometry.hpp @@ -11,13 +11,6 @@ */ // ---------------------------------------------------------------------------- -/** - * \ingroup math - * \defgroup geometry Geometry - * \brief Geometric classes and operations - * - */ - #ifndef MODM_GEOMETRY_HPP #define MODM_GEOMETRY_HPP diff --git a/src/modm/math/geometry/angle.hpp b/src/modm/math/geometry/angle.hpp index 56f3204bb7..76a9147253 100644 --- a/src/modm/math/geometry/angle.hpp +++ b/src/modm/math/geometry/angle.hpp @@ -51,12 +51,14 @@ namespace modm { + /// @ingroup modm_math_geometry static constexpr float toRadian(float angle) { return (angle * M_PI) / 180.f; } + /// @ingroup modm_math_geometry static constexpr float toDegree(float angle) { @@ -69,7 +71,7 @@ namespace modm * Angles are always represented by float values in the range * from -Pi to Pi. * - * \ingroup geometry + * @ingroup modm_math_geometry */ class Angle { diff --git a/src/modm/math/geometry/circle_2d.hpp b/src/modm/math/geometry/circle_2d.hpp index c75d1d3af5..d03e2f6fce 100644 --- a/src/modm/math/geometry/circle_2d.hpp +++ b/src/modm/math/geometry/circle_2d.hpp @@ -35,7 +35,7 @@ namespace modm * \brief Circle * * \author Fabian Greif - * \ingroup geometry + * \ingroup modm_math_geometry */ template class Circle2D diff --git a/src/modm/math/geometry/geometric_traits.hpp b/src/modm/math/geometry/geometric_traits.hpp index 2d5624d702..7bea64b480 100644 --- a/src/modm/math/geometry/geometric_traits.hpp +++ b/src/modm/math/geometry/geometric_traits.hpp @@ -23,7 +23,7 @@ namespace modm * \brief Traits for all geometric classes * * - * \ingroup geometry + * \ingroup modm_math_geometry * \author Fabian Greif */ template diff --git a/src/modm/math/geometry/line_2d.hpp b/src/modm/math/geometry/line_2d.hpp index 22ee853f5c..63efed0f98 100644 --- a/src/modm/math/geometry/line_2d.hpp +++ b/src/modm/math/geometry/line_2d.hpp @@ -28,7 +28,7 @@ namespace modm * \brief Line * * \author Fabian Greif - * \ingroup geometry + * \ingroup modm_math_geometry */ template class Line2D diff --git a/src/modm/math/geometry/line_segment_2d.hpp b/src/modm/math/geometry/line_segment_2d.hpp index 13f2796903..94bfe965aa 100644 --- a/src/modm/math/geometry/line_segment_2d.hpp +++ b/src/modm/math/geometry/line_segment_2d.hpp @@ -32,7 +32,7 @@ namespace modm * \brief Line segment * * \author Fabian Greif - * \ingroup geometry + * \ingroup modm_math_geometry */ template class LineSegment2D diff --git a/src/modm/math/geometry/location_2d.hpp b/src/modm/math/geometry/location_2d.hpp index 88c228ee3c..7bc9d2a8e7 100644 --- a/src/modm/math/geometry/location_2d.hpp +++ b/src/modm/math/geometry/location_2d.hpp @@ -31,7 +31,7 @@ namespace modm * on the field. The robot has a position (x- and y-coordinate) and a * orientation (absolute angle in the range (-pi, pi)). * - * \ingroup geometry + * \ingroup modm_math_geometry */ template class Location2D @@ -123,7 +123,7 @@ namespace modm /** * \brief Stream operator to \b modm::Location * - * \ingroup geometry + * \ingroup modm_math_geometry */ template IOStream& diff --git a/src/modm/math/geometry/module.lb b/src/modm/math/geometry/module.lb index 3b5f0fbb74..58a30fd1f3 100644 --- a/src/modm/math/geometry/module.lb +++ b/src/modm/math/geometry/module.lb @@ -13,6 +13,7 @@ def init(module): module.parent = "math" module.name = "geometry" + module.description = "Geometric Operations" def prepare(module, options): module.depends( diff --git a/src/modm/math/geometry/point_set_2d.hpp b/src/modm/math/geometry/point_set_2d.hpp index 6cd7fdd6e1..023f306126 100644 --- a/src/modm/math/geometry/point_set_2d.hpp +++ b/src/modm/math/geometry/point_set_2d.hpp @@ -30,7 +30,7 @@ namespace modm * is an expensive operation it should be avoid if possible. * * \author Fabian Greif - * \ingroup geometry + * \ingroup modm_math_geometry */ template class PointSet2D diff --git a/src/modm/math/geometry/polygon_2d.hpp b/src/modm/math/geometry/polygon_2d.hpp index 3fa5275860..d50f6486eb 100644 --- a/src/modm/math/geometry/polygon_2d.hpp +++ b/src/modm/math/geometry/polygon_2d.hpp @@ -36,7 +36,7 @@ namespace modm * implicit closed, which means the first and the last point are connected. * * \author Fabian Greif - * \ingroup geometry + * \ingroup modm_math_geometry */ template class Polygon2D : public PointSet2D diff --git a/src/modm/math/geometry/quaternion.hpp b/src/modm/math/geometry/quaternion.hpp index 5ea7ef10b3..a68679be28 100644 --- a/src/modm/math/geometry/quaternion.hpp +++ b/src/modm/math/geometry/quaternion.hpp @@ -35,7 +35,7 @@ namespace modm * \see Homepage * * \author Fabian Greif - * \ingroup geometry + * \ingroup modm_math_geometry */ template class Quaternion diff --git a/src/modm/math/geometry/ray_2d.hpp b/src/modm/math/geometry/ray_2d.hpp index de18fd4505..5752fe74fa 100644 --- a/src/modm/math/geometry/ray_2d.hpp +++ b/src/modm/math/geometry/ray_2d.hpp @@ -37,7 +37,7 @@ namespace modm * A ray is composed of a starting point and a direction vector. * * \author Fabian Greif - * \ingroup geometry + * \ingroup modm_math_geometry */ template class Ray2D diff --git a/src/modm/math/geometry/vector.hpp b/src/modm/math/geometry/vector.hpp index 2faf4906e6..4a8fff9c92 100644 --- a/src/modm/math/geometry/vector.hpp +++ b/src/modm/math/geometry/vector.hpp @@ -50,7 +50,7 @@ namespace modm * * \see Homepage * - * \ingroup geometry + * \ingroup modm_math_geometry * \author Niklas Hauser */ template diff --git a/src/modm/math/geometry/vector1.hpp b/src/modm/math/geometry/vector1.hpp index 2355c6a924..15d77295d2 100644 --- a/src/modm/math/geometry/vector1.hpp +++ b/src/modm/math/geometry/vector1.hpp @@ -29,7 +29,7 @@ namespace modm * * \see Homepage * - * \ingroup geometry + * \ingroup modm_math_geometry * \author Niklas Hauser */ template diff --git a/src/modm/math/geometry/vector2.hpp b/src/modm/math/geometry/vector2.hpp index 900c705a76..3d35b5cce1 100644 --- a/src/modm/math/geometry/vector2.hpp +++ b/src/modm/math/geometry/vector2.hpp @@ -50,7 +50,7 @@ namespace modm * \author Fabian Greif * \author Niklas Hauser * - * \ingroup geometry + * \ingroup modm_math_geometry */ template class Vector @@ -319,7 +319,7 @@ namespace modm // ------------------------------------------------------------------------ /** * \brief Stream operator for \b modm::Vector - * \ingroup geometry + * \ingroup modm_math_geometry */ template IOStream& @@ -327,7 +327,7 @@ namespace modm /** * \brief Scalar multiplication - * \ingroup geometry + * \ingroup modm_math_geometry */ template Vector @@ -335,7 +335,7 @@ namespace modm /** * \brief Scalar division - * \ingroup geometry + * \ingroup modm_math_geometry */ template Vector diff --git a/src/modm/math/geometry/vector3.hpp b/src/modm/math/geometry/vector3.hpp index ac40a1a2fe..2069ea7549 100644 --- a/src/modm/math/geometry/vector3.hpp +++ b/src/modm/math/geometry/vector3.hpp @@ -32,7 +32,7 @@ namespace modm * * \see Homepage * - * \ingroup geometry + * \ingroup modm_math_geometry * \author Niklas Hauser */ template diff --git a/src/modm/math/geometry/vector4.hpp b/src/modm/math/geometry/vector4.hpp index 5c5d5dad73..dcbffc6ef4 100644 --- a/src/modm/math/geometry/vector4.hpp +++ b/src/modm/math/geometry/vector4.hpp @@ -31,7 +31,7 @@ namespace modm * * \see Homepage * - * \ingroup geometry + * \ingroup modm_math_geometry * \author Niklas Hauser */ template diff --git a/src/modm/math/interpolation.hpp b/src/modm/math/interpolation.hpp index 0b27dc58ce..ee9b341963 100644 --- a/src/modm/math/interpolation.hpp +++ b/src/modm/math/interpolation.hpp @@ -11,21 +11,12 @@ */ // ---------------------------------------------------------------------------- -/** - * \ingroup math - * \defgroup interpolation Interpolation - * \brief Interpolation methods - * - */ - #ifndef MODM_INTERPOLATION_HPP #define MODM_INTERPOLATION_HPP namespace modm { - /** - * \ingroup interpolation - */ + /// @ingroup modm_math_interpolation namespace interpolation { } diff --git a/src/modm/math/interpolation/lagrange.hpp b/src/modm/math/interpolation/lagrange.hpp index 887f8bd44c..0f8936ce15 100644 --- a/src/modm/math/interpolation/lagrange.hpp +++ b/src/modm/math/interpolation/lagrange.hpp @@ -27,29 +27,6 @@ namespace modm namespace interpolation { /** - * \brief Lagrange Interpolation - * - * Example: - * \code - * typedef modm::Pair Point; - * - * // interpolate x^2 over the range of 1 <= x <= 3 - * Point points[3] = - * { - * { 1, 1 }, - * { 2, 4 }, - * { 3, 9 } - * }; - * - * modm::interpolation::Lagrange value(points, 3); - * - * ... - * float output = value.interpolate(1.5f); - * // output => 2.25; - * \endcode - * - * \see http://en.wikipedia.org/wiki/Lagrange_interpolation - * * \warning Only floating points types are allowed as second type of * modm::Pair, otherwise the calculation will deliver wrong * results! @@ -61,7 +38,7 @@ namespace modm * accessor class. * Default is modm::accessor::Ram. * - * \ingroup interpolation + * \ingroup modm_math_interpolation */ template class Accessor = ::modm::accessor::Ram> diff --git a/src/modm/math/interpolation/linear.hpp b/src/modm/math/interpolation/linear.hpp index 296c93ad8b..95c9cefef7 100644 --- a/src/modm/math/interpolation/linear.hpp +++ b/src/modm/math/interpolation/linear.hpp @@ -25,68 +25,13 @@ namespace modm namespace interpolation { /** - * \brief Linear interpolation between supporting points - * - * Example: - * \code - * // Definition of the supporting points. The first type is the - * // input type, the second the output type - * typedef modm::Pair Point; - * - * // Create a array of supporting points describing the curve. - * Point supportingPoints[6] = - * { - * { 30, -200 }, - * { 50, 0 }, - * { 90, 50 }, - * { 150, 2050 }, - * { 200, 3000 }, - * { 220, 20000 } - * }; - * - * modm::interpolation::Linear - * value(supportingPoints, 6); - * - * ... - * - * int8_t a = 20; - * int16_t b = value.interpolate(a); - * \endcode - * - * Example with supporting points read from flash: - * \code - * // Definition of a supporting point - * typedef modm::Pair Point; - * - * // Array of supporting points in flash - * FLASH_STORAGE(Point supportingPoints[6]) = - * { - * { 30, -200 }, - * { 50, 0 }, - * { 90, 50 }, - * { 150, 2050 }, - * { 200, 3000 }, - * { 220, 20000 } - * }; - * - * // Create an interpolator object which reads the - * // supporting points from flash. - * modm::interpolation::Linear - * value(modm::accessor::asFlash(supportingPoints), 6); - * - * ... - * - * int8_t a = 20; - * int16_t b = value.interpolate(a); - * \endcode - * * \tparam T Any specialization of modm::Pair<> * \tparam Accessor Accessor class. Can be modm::accessor::Ram, * modm::accessor::Flash or any self defined * accessor class. * Default is modm::accessor::Ram. * - * \ingroup interpolation + * \ingroup modm_math_interpolation */ template class Accessor = ::modm::accessor::Ram> diff --git a/src/modm/math/interpolation/module.lb b/src/modm/math/interpolation/module.lb index a4e757104a..79773aeecc 100644 --- a/src/modm/math/interpolation/module.lb +++ b/src/modm/math/interpolation/module.lb @@ -13,6 +13,7 @@ def init(module): module.parent = "math" module.name = "interpolation" + module.description = FileReader("module.md") def prepare(module, options): module.depends( diff --git a/src/modm/math/interpolation/module.md b/src/modm/math/interpolation/module.md new file mode 100644 index 0000000000..f07dbf16a2 --- /dev/null +++ b/src/modm/math/interpolation/module.md @@ -0,0 +1,86 @@ +# Interpolation Methods + +Simple interpolation methods between a list of points. + +## Linear Interpolation + +Example: + +```cpp +// Definition of the supporting points. The first type is the +// input type, the second the output type +using Point = modm::Pair; + +// Create a array of supporting points describing the curve. +const Point supportingPoints[6] = +{ + { 30, -200 }, + { 50, 0 }, + { 90, 50 }, + { 150, 2050 }, + { 200, 3000 }, + { 220, 20000 } +}; + +modm::interpolation::Linear value(supportingPoints, 6); +// ... + +int8_t a = 40; +int16_t b = value.interpolate(a); +``` + +Example with supporting points read from flash: + +```cpp +// Definition of a supporting point +using Point = modm::Pair; + +// Array of supporting points in flash +FLASH_STORAGE(Point supportingPoints[6]) = +{ + { 30, -200 }, + { 50, 0 }, + { 90, 50 }, + { 150, 2050 }, + { 200, 3000 }, + { 220, 20000 } +}; + +// Create an interpolator object which reads the +// supporting points from flash. +modm::interpolation::Linear + value(modm::accessor::asFlash(supportingPoints), 6); +// ... + +int8_t a = 20; +int16_t b = value.interpolate(a); +``` + + +## Lagrange Interpolation + +Example: + +```cpp +using Point = modm::Pair; + +// interpolate x^2 over the range of 1 <= x <= 3 +Point points[3] = +{ + { 1, 1 }, + { 2, 4 }, + { 3, 9 } +}; + +modm::interpolation::Lagrange value(points, 3); +// ... + +float output = value.interpolate(1.5f); +// output => 2.25; +``` + +!!!warning + Only floating points types are allowed as second type of `modm::Pair`, + otherwise the calculation will deliver wrong results! + +See [Wikipedia](http://en.wikipedia.org/wiki/Lagrange_interpolation). \ No newline at end of file diff --git a/src/modm/math/lu_decomposition.hpp b/src/modm/math/lu_decomposition.hpp index a8df702987..f45454f13a 100644 --- a/src/modm/math/lu_decomposition.hpp +++ b/src/modm/math/lu_decomposition.hpp @@ -33,7 +33,7 @@ namespace modm * * \see Homepage * - * \ingroup matrix + * \ingroup modm_math_matrix * \author Niklas Hauser */ class LUDecomposition diff --git a/src/modm/math/math.lb b/src/modm/math/math.lb index 43f5400aaa..f2e396e31d 100644 --- a/src/modm/math/math.lb +++ b/src/modm/math/math.lb @@ -13,6 +13,7 @@ def init(module): module.name = "math" + module.description = "Math" def prepare(module, options): return True diff --git a/src/modm/math/matrix.hpp b/src/modm/math/matrix.hpp index 884fd1e02a..56932a50ab 100644 --- a/src/modm/math/matrix.hpp +++ b/src/modm/math/matrix.hpp @@ -11,13 +11,6 @@ */ // ---------------------------------------------------------------------------- -/** - * \ingroup math - * \defgroup matrix Matrix - * \brief Common matrix operations - * - */ - #ifndef MODM_MATRIX_HPP #define MODM_MATRIX_HPP @@ -52,7 +45,7 @@ namespace modm * \tparam ROWS Number of rows * \tparam COLUMNS Number of columns * - * \ingroup matrix + * \ingroup modm_math_matrix * \author Niklas Hauser * \author Fabian Greif */ @@ -258,7 +251,7 @@ namespace modm * \brief Calculate the determinant * * \param m Matrix - * \ingroup matrix + * \ingroup modm_math_matrix */ template T diff --git a/src/modm/math/matrix.lb b/src/modm/math/matrix.lb index c87a5c22e4..cef7fe54dd 100644 --- a/src/modm/math/matrix.lb +++ b/src/modm/math/matrix.lb @@ -13,6 +13,7 @@ def init(module): module.parent = "math" module.name = "matrix" + module.description = "Matrix Math" def prepare(module, options): module.depends( diff --git a/src/modm/math/saturated/module.lb b/src/modm/math/saturated/module.lb index 00eb6015ab..de73c1a761 100644 --- a/src/modm/math/saturated/module.lb +++ b/src/modm/math/saturated/module.lb @@ -13,6 +13,7 @@ def init(module): module.parent = "math" module.name = "saturated" + module.description = "Saturated Arithmetics" def prepare(module, options): module.depends(":utils") diff --git a/src/modm/math/saturated/saturated.hpp b/src/modm/math/saturated/saturated.hpp index 5dc907a45d..de043341dc 100644 --- a/src/modm/math/saturated/saturated.hpp +++ b/src/modm/math/saturated/saturated.hpp @@ -19,7 +19,6 @@ namespace modm { /** - * \ingroup math * \brief Saturated arithmetics * * \see http://www.mikrocontroller.net/articles/AVR_Arithmetik/Saturierung @@ -29,6 +28,7 @@ namespace modm * \todo extend implementation (multiplication etc.) * \todo add 16-bit datetype assembler implementations for AVRs * \todo documentation + * \ingroup modm_math_saturated */ template class Saturated diff --git a/src/modm/math/tolerance.hpp b/src/modm/math/tolerance.hpp index 23a23e3ff2..8384eabb33 100644 --- a/src/modm/math/tolerance.hpp +++ b/src/modm/math/tolerance.hpp @@ -23,7 +23,7 @@ namespace modm * This can be used to guarantee the quality of certain parameters, * mostly baudrate or datarate. * - * @ingroup math + * @ingroup modm_math */ class Tolerance diff --git a/src/modm/math/utils/bit_operation.hpp b/src/modm/math/utils/bit_operation.hpp index 92e6df8932..7e1fdddc30 100644 --- a/src/modm/math/utils/bit_operation.hpp +++ b/src/modm/math/utils/bit_operation.hpp @@ -24,14 +24,15 @@ namespace modm { + /// @ingroup modm_math_utils + /// @{ + /** * \brief Exchange the two nibbles of a byte * * \code * 0xab => 0xba * \endcode - * - * \ingroup math */ modm_always_inline uint8_t swap(uint8_t n) @@ -50,11 +51,7 @@ namespace modm #endif } - /** - * \brief Exchange two byte - * - * \ingroup math - */ + /// Exchange two byte modm_always_inline void swap(uint8_t& a, uint8_t& b) { @@ -69,8 +66,6 @@ namespace modm * \code * 0xabcd => 0xcdab * \endcode - * - * \ingroup math */ modm_always_inline uint16_t swap(uint16_t n) @@ -108,8 +103,6 @@ namespace modm * \code * 0xabcdefgh => 0xghefcdab * \endcode - * - * \ingroup math */ modm_always_inline uint32_t swap(uint32_t n) @@ -144,8 +137,6 @@ namespace modm * \endcode * * 15 clock cycles on an AVR, without call + return. - * - * \ingroup math */ inline uint8_t bitReverse(uint8_t n) @@ -168,8 +159,6 @@ namespace modm /** * \brief Reverse the bits in a 16-bit integer - * - * \ingroup math */ inline uint16_t bitReverse(uint16_t n) @@ -194,8 +183,6 @@ namespace modm /** * \brief Reverse the bits in a 32-bit integer - * - * \ingroup math */ inline uint32_t bitReverse(uint32_t n) @@ -229,7 +216,6 @@ namespace modm /// Returns position of leftmost bit at compile time. /// @retval -1 if no bit set in value /// @retval n position of leftmost bit - /// @ingroup math constexpr int8_t leftmostBit(uint32_t value) { @@ -241,8 +227,6 @@ namespace modm * \brief Count the number of bits set * * 16 clock cycles on an AVR, without call + return. - * - * \ingroup math */ std::size_t bitCount(uint8_t n); @@ -251,19 +235,15 @@ namespace modm * \brief Count the number of bits set * * 33 clock cycles on an AVR, without call + return. - * - * \ingroup math */ std::size_t bitCount(uint16_t n); - /** - * \brief Count the number of bits set - * - * \ingroup math - */ + /// Count the number of bits set std::size_t bitCount(uint32_t n); + + /// @} } #endif // MODM_BIT_OPERATION_HPP diff --git a/src/modm/math/utils/endianness.hpp b/src/modm/math/utils/endianness.hpp index 5c0ab3d82d..9f40e8bd20 100644 --- a/src/modm/math/utils/endianness.hpp +++ b/src/modm/math/utils/endianness.hpp @@ -20,8 +20,10 @@ namespace modm { +/// @ingroup modm_math_utils +/// @{ + /// checks if current architecture is big endian -/// @ingroup math constexpr bool isBigEndian() { @@ -29,7 +31,6 @@ isBigEndian() } /// checks if current architecture is little endian -/// @ingroup math constexpr bool isLittleEndian() { @@ -37,8 +38,6 @@ isLittleEndian() } // MARK: - to host -/// @{ -/// @ingroup math inline uint16_t fromLittleEndian(uint16_t value) { @@ -167,6 +166,7 @@ toBigEndian(int32_t value) { return int32_t(toBigEndian(uint32_t(value))); } + /// @} } // namespace modm diff --git a/src/modm/math/utils/misc.hpp b/src/modm/math/utils/misc.hpp index 0f0204e3ec..dcadb92130 100644 --- a/src/modm/math/utils/misc.hpp +++ b/src/modm/math/utils/misc.hpp @@ -24,12 +24,13 @@ namespace modm { +/// @addtogroup modm_math_utils +/// @{ + /** * Fast check if a float variable is positive * * Checks only the sign bit for the AVR. - * - * @ingroup math */ inline bool isPositive(const float& a) @@ -49,8 +50,6 @@ isPositive(const float& a) * @code * constexpr int value = modm::pow(10, 2); * @endcode - * - * @ingroup math */ constexpr uint32_t pow(uint32_t base, uint8_t exponent) @@ -60,7 +59,7 @@ pow(uint32_t base, uint8_t exponent) /** * @brief This does what you think it does. - * @ingroup sorting_algorithms + * * @param a A thing of arbitrary type. * @param b Another thing of arbitrary type. * @return The lesser of the parameters. @@ -81,7 +80,7 @@ min(const T& a, const T& b) /** * @brief This does what you think it does. - * @ingroup sorting_algorithms + * * @param a A thing of arbitrary type. * @param b Another thing of arbitrary type. * @return The greater of the parameters. @@ -102,7 +101,7 @@ max(const T& a, const T& b) /** * @brief This does what you think it does. - * @ingroup sorting_algorithms + * * @param a A thing of arbitrary type. * @param b Another thing of arbitrary type. * @param c Something else of arbitrary type. @@ -122,7 +121,7 @@ max(const T a, const T b, const T c) /** * @brief This does what you think it does. - * @ingroup sorting_algorithms + * * @param a A thing of arbitrary type. * @param b Another thing of arbitrary type. * @param compare A comparison functor. @@ -143,7 +142,7 @@ min(const T& a, const T& b, Compare compare) /** * @brief This does what you think it does. - * @ingroup sorting_algorithms + * * @param a A thing of arbitrary type. * @param b Another thing of arbitrary type. * @param compare A comparison functor. @@ -162,6 +161,8 @@ max(const T& a, const T& b, Compare compare) return a; } +/// @} + } // namespace modm #endif diff --git a/src/modm/math/utils/module.lb b/src/modm/math/utils/module.lb index 1019d005ca..986d45ff08 100644 --- a/src/modm/math/utils/module.lb +++ b/src/modm/math/utils/module.lb @@ -13,6 +13,7 @@ def init(module): module.parent = "math" module.name = "utils" + module.description = "Utilities" def prepare(module, options): module.depends(":architecture") diff --git a/src/modm/math/utils/operator.hpp b/src/modm/math/utils/operator.hpp index cf2927461e..f847b88319 100644 --- a/src/modm/math/utils/operator.hpp +++ b/src/modm/math/utils/operator.hpp @@ -36,7 +36,7 @@ namespace modm * \see * Original implementation * - * \ingroup math + * \ingroup modm_math_utils */ inline uint16_t sqrt(uint32_t a) @@ -48,7 +48,7 @@ namespace modm * \brief unsigned 16bit x 16bit = 32bit multiplication * * \see AVR201 - * \ingroup math + * \ingroup modm_math_utils */ inline uint32_t mul(uint16_t a, uint16_t b); @@ -57,7 +57,7 @@ namespace modm * \brief signed 16bit x 16bit = 32bit multiplication * * \see AVR201 - * \ingroup math + * \ingroup modm_math_utils */ inline int32_t mul(int16_t a, int16_t b); @@ -71,7 +71,7 @@ namespace modm * \endcode * * \see AVR201 - * \ingroup math + * \ingroup modm_math_utils */ inline int32_t mac(int32_t result, int16_t a, int16_t b); diff --git a/src/modm/platform/adc/at90_tiny_mega/adc_interrupt.hpp.in b/src/modm/platform/adc/at90_tiny_mega/adc_interrupt.hpp.in index 89186841ba..2d5238524f 100644 --- a/src/modm/platform/adc/at90_tiny_mega/adc_interrupt.hpp.in +++ b/src/modm/platform/adc/at90_tiny_mega/adc_interrupt.hpp.in @@ -27,7 +27,7 @@ namespace platform /** * @author Niklas Hauser * - * @ingroup {{partname}}_adc + * @ingroup modm_platform_adc */ class AdcInterrupt : public modm::platform::Adc, public modm::AdcInterrupt { diff --git a/src/modm/platform/adc/at90_tiny_mega/adc_mega.hpp.in b/src/modm/platform/adc/at90_tiny_mega/adc_mega.hpp.in index 4dd1b5e209..5781af9281 100644 --- a/src/modm/platform/adc/at90_tiny_mega/adc_mega.hpp.in +++ b/src/modm/platform/adc/at90_tiny_mega/adc_mega.hpp.in @@ -11,11 +11,6 @@ */ // ---------------------------------------------------------------------------- -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_adc ADC - */ - #ifndef MODM_ATMEGA_ADC_HPP #define MODM_ATMEGA_ADC_HPP @@ -69,7 +64,7 @@ namespace platform * needed the frequency can be higher. * * @author Niklas Hauser - * @ingroup {{partname}}_adc + * @ingroup modm_platform_adc */ class Adc : public modm::Adc { diff --git a/src/modm/platform/adc/at90_tiny_mega/adc_tiny.hpp.in b/src/modm/platform/adc/at90_tiny_mega/adc_tiny.hpp.in index bc49bb607b..23b174cc47 100644 --- a/src/modm/platform/adc/at90_tiny_mega/adc_tiny.hpp.in +++ b/src/modm/platform/adc/at90_tiny_mega/adc_tiny.hpp.in @@ -10,11 +10,6 @@ */ // ---------------------------------------------------------------------------- -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_adc ADC - */ - #ifndef MODM_ATTINY_ADC_HPP #define MODM_ATTINY_ADC_HPP @@ -105,7 +100,7 @@ namespace platform * needed the frequency can be higher. * * @author Niklas Hauser - * @ingroup {{partname}}_adc + * @ingroup modm_platform_adc */ class Adc : public modm::Adc { diff --git a/src/modm/platform/adc/at90_tiny_mega/module.lb b/src/modm/platform/adc/at90_tiny_mega/module.lb index b009d9db24..7e7b37055a 100644 --- a/src/modm/platform/adc/at90_tiny_mega/module.lb +++ b/src/modm/platform/adc/at90_tiny_mega/module.lb @@ -14,6 +14,7 @@ def init(module): module.name = "adc" module.parent = "platform" + module.description = "Analog-to-Digital Converter (ADC)" def prepare(module, options): device = options[":target"] diff --git a/src/modm/platform/adc/stm32/adc.hpp.in b/src/modm/platform/adc/stm32/adc.hpp.in index 2bdab52220..59b0a38f4c 100644 --- a/src/modm/platform/adc/stm32/adc.hpp.in +++ b/src/modm/platform/adc/stm32/adc.hpp.in @@ -20,11 +20,6 @@ #include #include -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_adc ADC - */ - namespace modm { @@ -43,7 +38,7 @@ namespace platform * @author Stephan Kugelmann * @author David Hebbeker * @author ekiwi - * @ingroup {{partname}}_adc + * @ingroup modm_platform_adc modm_platform_adc_{{id}} */ class Adc{{ id }} : public modm::Adc { diff --git a/src/modm/platform/adc/stm32/adc_interrupt.hpp.in b/src/modm/platform/adc/stm32/adc_interrupt.hpp.in index 43d3fccc61..c95d58af54 100644 --- a/src/modm/platform/adc/stm32/adc_interrupt.hpp.in +++ b/src/modm/platform/adc/stm32/adc_interrupt.hpp.in @@ -35,7 +35,7 @@ namespace platform * * @see AnalogSensors uses this implemenation. * - * @ingroup {{partname}}_adc + * @ingroup modm_platform_adc_{{id}} * @author Niklas Hauser */ class AdcInterrupt{{ id }} : public Adc{{ id }}, public modm::AdcInterrupt diff --git a/src/modm/platform/adc/stm32/module.lb b/src/modm/platform/adc/stm32/module.lb index 27257d80f3..c11b184942 100644 --- a/src/modm/platform/adc/stm32/module.lb +++ b/src/modm/platform/adc/stm32/module.lb @@ -19,7 +19,7 @@ class Instance(Module): def init(self, module): module.name = str(self.instance) - module.description = "ADC {} instance".format(self.instance) + module.description = "Instance {}".format(self.instance) def prepare(self, module, options): module.depends(":platform:adc") @@ -64,6 +64,7 @@ class Instance(Module): def init(module): module.name = "adc" module.parent = "platform" + module.description = "Analog-to-Digital Converter (ADC)" def prepare(module, options): device = options[":target"] diff --git a/src/modm/platform/adc/stm32f0/adc.hpp.in b/src/modm/platform/adc/stm32f0/adc.hpp.in index 24dde9b106..d1b660c71a 100644 --- a/src/modm/platform/adc/stm32f0/adc.hpp.in +++ b/src/modm/platform/adc/stm32f0/adc.hpp.in @@ -19,10 +19,7 @@ #include "../../../device.hpp" #include -/** - * @ingroup {{target.string}} - * @defgroup {{target.string}}_adc ADC -*/ + namespace modm { namespace stm32 @@ -39,7 +36,7 @@ namespace stm32 * This API is designed for the internal ADCs of STM32F0x1/STM32F0x2/STM32F0x8 * * \author Álan Crístoffer - * \ingroup {{target.string}}_adc + * \ingroup modm_platform_adc */ class Adc { diff --git a/src/modm/platform/adc/stm32f3/adc.hpp.in b/src/modm/platform/adc/stm32f3/adc.hpp.in index 60c6d58501..c6a1836293 100644 --- a/src/modm/platform/adc/stm32f3/adc.hpp.in +++ b/src/modm/platform/adc/stm32f3/adc.hpp.in @@ -36,7 +36,7 @@ namespace platform * * \author Kevin Laeufer * \author Sascha Schade (strongly-typed) - * \ingroup stm32 + * \ingroup modm_platform_adc modm_platform_adc_{{id}} */ class Adc{{ id }} { diff --git a/src/modm/platform/adc/stm32f3/module.lb b/src/modm/platform/adc/stm32f3/module.lb index 1444e058f5..4bab364ff8 100644 --- a/src/modm/platform/adc/stm32f3/module.lb +++ b/src/modm/platform/adc/stm32f3/module.lb @@ -17,7 +17,7 @@ class Instance(Module): def init(self, module): module.name = str(self.instance) - module.description = "ADC {} instance".format(self.instance) + module.description = "Instance {}".format(self.instance) def prepare(self, module, options): module.depends(":platform:adc") @@ -96,6 +96,7 @@ class Instance(Module): def init(module): module.name = "adc" module.parent = "platform" + module.description = "Analog-to-Digital Converter (ADC)" def prepare(module, options): device = options[":target"] diff --git a/src/modm/platform/can/canusb/canusb.hpp b/src/modm/platform/can/canusb/canusb.hpp index f2f308c959..38be071d38 100644 --- a/src/modm/platform/can/canusb/canusb.hpp +++ b/src/modm/platform/can/canusb/canusb.hpp @@ -34,7 +34,7 @@ namespace platform * * @see http://www.canusb.com/ * @see http://www.can232.com/ - * @ingroup hosted + * @ingroup modm_platform_canusb */ template class CanUsb : public ::modm::Can diff --git a/src/modm/platform/can/canusb/module.lb b/src/modm/platform/can/canusb/module.lb index fe81cc344e..bc05cd7803 100644 --- a/src/modm/platform/can/canusb/module.lb +++ b/src/modm/platform/can/canusb/module.lb @@ -15,6 +15,7 @@ def init(module): module.name = "canusb" module.parent = "platform" + module.description = "CANUSB Driver" def prepare(module, options): diff --git a/src/modm/platform/can/common/can_bit_timings.hpp b/src/modm/platform/can/common/can_bit_timings.hpp index 1fcbbc710a..ad642be30b 100644 --- a/src/modm/platform/can/common/can_bit_timings.hpp +++ b/src/modm/platform/can/common/can_bit_timings.hpp @@ -41,7 +41,7 @@ namespace modm * * * @author Kevin Laeufer - * @ingroup can + * @ingroup modm_platform_can_common */ template class CanBitTiming diff --git a/src/modm/platform/can/common/module.lb b/src/modm/platform/can/common/module.lb index 3a40b14a68..9c5811dba2 100644 --- a/src/modm/platform/can/common/module.lb +++ b/src/modm/platform/can/common/module.lb @@ -14,6 +14,7 @@ def init(module): module.name = "can.common" module.parent = "platform" + module.description = "CAN Common" def prepare(module, options): module.depends(":architecture:clock") diff --git a/src/modm/platform/can/socketcan/module.lb b/src/modm/platform/can/socketcan/module.lb index e07ab8e0f3..feaac8602f 100644 --- a/src/modm/platform/can/socketcan/module.lb +++ b/src/modm/platform/can/socketcan/module.lb @@ -14,6 +14,7 @@ def init(module): module.name = "socketcan" module.parent = "platform" + module.description = "SocketCAN" def prepare(module, options): if not options[":target"].has_driver("can:socketcan"): diff --git a/src/modm/platform/can/socketcan/socketcan.hpp b/src/modm/platform/can/socketcan/socketcan.hpp index 789f0589e6..6b3203fda8 100644 --- a/src/modm/platform/can/socketcan/socketcan.hpp +++ b/src/modm/platform/can/socketcan/socketcan.hpp @@ -23,6 +23,7 @@ namespace modm namespace platform { +/// @ingroup modm_platform_socketcan class SocketCan : public ::modm::Can { public: diff --git a/src/modm/platform/can/stm32/can.hpp.in b/src/modm/platform/can/stm32/can.hpp.in index 641b760eff..39c7337e01 100644 --- a/src/modm/platform/can/stm32/can.hpp.in +++ b/src/modm/platform/can/stm32/can.hpp.in @@ -26,11 +26,6 @@ using namespace modm::clock; // for MHzxx -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_can CAN - */ - namespace modm { @@ -57,7 +52,7 @@ namespace platform * You can set the buffer size using the `tx_buffer` and `rx_buffer` parameters. * * @author Fabian Greif - * @ingroup {{partname}}_can + * @ingroup modm_platform_can{% if id | length %} modm_platform_can_{{id}}{% endif %} */ class Can{{ id }} : public ::modm::Can { diff --git a/src/modm/platform/can/stm32/can_filter.hpp.in b/src/modm/platform/can/stm32/can_filter.hpp.in index 729a61f5a4..507b6be8c2 100644 --- a/src/modm/platform/can/stm32/can_filter.hpp.in +++ b/src/modm/platform/can/stm32/can_filter.hpp.in @@ -26,7 +26,7 @@ namespace platform * @brief Filters for the Basic Extended CAN Module * * @author Fabian Greif - * @ingroup {{partname}}_can + * @ingroup modm_platform_can */ class CanFilter { diff --git a/src/modm/platform/can/stm32/error_code.hpp b/src/modm/platform/can/stm32/error_code.hpp index 02c3bd2c4d..2999c1b6e9 100644 --- a/src/modm/platform/can/stm32/error_code.hpp +++ b/src/modm/platform/can/stm32/error_code.hpp @@ -20,7 +20,7 @@ namespace modm { namespace platform { - /// @ingroup {{partname}}_can + /// @ingroup modm_platform_can enum ErrorCode { CAN_ERROR_PASSIVE_MODE = 0x0010, diff --git a/src/modm/platform/can/stm32/module.lb b/src/modm/platform/can/stm32/module.lb index 44d4ed5281..70d2a21985 100644 --- a/src/modm/platform/can/stm32/module.lb +++ b/src/modm/platform/can/stm32/module.lb @@ -102,7 +102,7 @@ class Instance(Module): def init(self, module): module.name = str(self.instance) - module.description = "CAN {} instance".format(self.instance) + module.description = "Instance {}".format(self.instance) def prepare(self, module, options): load_options(module) @@ -127,6 +127,7 @@ class Instance(Module): def init(module): module.name = "can" module.parent = "platform" + module.description = "Controller Area Network (CAN)" def prepare(module, options): device = options[":target"] diff --git a/src/modm/platform/clock/avr/module.lb b/src/modm/platform/clock/avr/module.lb index 4b06a9f36b..da42139a92 100644 --- a/src/modm/platform/clock/avr/module.lb +++ b/src/modm/platform/clock/avr/module.lb @@ -14,6 +14,7 @@ def init(module): module.name = "clock" module.parent = "platform" + module.description = "System Clock" def prepare(module, options): if not options[":target"].has_driver("clock:avr"): diff --git a/src/modm/platform/clock/avr/static.hpp b/src/modm/platform/clock/avr/static.hpp index c1314dc454..e2c0608b2b 100644 --- a/src/modm/platform/clock/avr/static.hpp +++ b/src/modm/platform/clock/avr/static.hpp @@ -23,7 +23,7 @@ namespace modm namespace platform { -/// @ingroup avr +/// @ingroup modm_platform_clock class SystemClock { diff --git a/src/modm/platform/clock/common/common_clock.hpp b/src/modm/platform/clock/common/common_clock.hpp index 8cc8988521..275abca939 100644 --- a/src/modm/platform/clock/common/common_clock.hpp +++ b/src/modm/platform/clock/common/common_clock.hpp @@ -23,6 +23,7 @@ namespace clock /** * Errors that might prevent using a certain clock configuration + * @ingroup modm_platform_clock */ enum class StartupError : uint8_t @@ -41,10 +42,12 @@ StartupError : uint8_t WatchdogClock }; +/// @cond extern uint32_t modm_fastdata fcpu; extern uint32_t modm_fastdata fcpu_kHz; extern uint16_t modm_fastdata fcpu_MHz; extern uint16_t modm_fastdata ns_per_loop; +/// @endcond } // namespace clock diff --git a/src/modm/platform/clock/cortex/module.lb b/src/modm/platform/clock/cortex/module.lb index 46b603d69f..33c80439ea 100644 --- a/src/modm/platform/clock/cortex/module.lb +++ b/src/modm/platform/clock/cortex/module.lb @@ -16,6 +16,7 @@ import os def init(module): module.parent = "platform" module.name = "clock.cortex" + module.description = "ARM Cortex-M SysTick" def prepare(module, options): if not options[":target"].has_driver("core:cortex-m*"): diff --git a/src/modm/platform/clock/cortex/systick_timer.hpp.in b/src/modm/platform/clock/cortex/systick_timer.hpp.in index e7c3ae145f..b4de782d17 100644 --- a/src/modm/platform/clock/cortex/systick_timer.hpp.in +++ b/src/modm/platform/clock/cortex/systick_timer.hpp.in @@ -27,7 +27,7 @@ typedef void (*InterruptHandler)(void); /** * @brief SysTick Timer - * @ingroup cortex + * @ingroup modm_platform_clock_cortex */ class SysTickTimer { diff --git a/src/modm/platform/clock/stm32/clock.hpp.in b/src/modm/platform/clock/stm32/clock.hpp.in index 8609162405..762e58fa7b 100644 --- a/src/modm/platform/clock/stm32/clock.hpp.in +++ b/src/modm/platform/clock/stm32/clock.hpp.in @@ -16,11 +16,6 @@ #ifndef MODM_STM32_CLOCK_HPP #define MODM_STM32_CLOCK_HPP -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_clock System Clock - */ - #include #include "../device.hpp" #include "common_clock.hpp" @@ -42,7 +37,7 @@ namespace platform * Don't forget to set the flash latencies. * * @author Niklas Hauser - * @ingroup {{partname}}_clock + * @ingroup modm_platform_clock */ class ClockControl { diff --git a/src/modm/platform/clock/stm32/module.lb b/src/modm/platform/clock/stm32/module.lb index 7d9aa0f35f..3b77aee428 100644 --- a/src/modm/platform/clock/stm32/module.lb +++ b/src/modm/platform/clock/stm32/module.lb @@ -14,6 +14,7 @@ def init(module): module.name = "clock" module.parent = "platform" + module.description = "Reset and Clock Control (RCC)" def prepare(module, options): if not options[":target"].has_driver("rcc:stm32*"): diff --git a/src/modm/platform/comp/stm32/base.hpp.in b/src/modm/platform/comp/stm32/base.hpp.in index ac049b51b1..2b7a70b9f9 100644 --- a/src/modm/platform/comp/stm32/base.hpp.in +++ b/src/modm/platform/comp/stm32/base.hpp.in @@ -12,12 +12,10 @@ #ifndef MODM_STM32_COMP_BASE_HPP #define MODM_STM32_COMP_BASE_HPP -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_comp Comparator - */ + namespace modm::platform { + /// @ingroup modm_platform_comp class CompBase { public: diff --git a/src/modm/platform/comp/stm32/comp.hpp.in b/src/modm/platform/comp/stm32/comp.hpp.in index 52ff7d1a62..da39b81873 100644 --- a/src/modm/platform/comp/stm32/comp.hpp.in +++ b/src/modm/platform/comp/stm32/comp.hpp.in @@ -16,19 +16,13 @@ #include -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_comp Comparator - */ - - namespace modm::platform { /** * @brief Comparator Class for STM32 * * @internal - * @ingroup {{partname}}_comp + * @ingroup modm_platform_comp modm_platform_comp_{{id}} */ class Comp{{ id }} : public CompBase { diff --git a/src/modm/platform/comp/stm32/module.lb b/src/modm/platform/comp/stm32/module.lb index 61aad09cf2..5b2d9f4343 100644 --- a/src/modm/platform/comp/stm32/module.lb +++ b/src/modm/platform/comp/stm32/module.lb @@ -16,7 +16,7 @@ class Instance(Module): def init(self, module): module.name = str(self.instance) - module.description = "COMP {} instance".format(self.instance) + module.description = "Instance {}".format(self.instance) def prepare(self, module, options): module.depends(":platform:comp") @@ -41,6 +41,7 @@ class Instance(Module): def init(module): module.name = "comp" module.parent = "platform" + module.description = "Comparator (COMP)" def prepare(module, options): device = options[":target"] diff --git a/src/modm/platform/core/avr/atomic_lock.hpp b/src/modm/platform/core/avr/atomic_lock.hpp index d80e85c98e..64f9b53cba 100644 --- a/src/modm/platform/core/avr/atomic_lock.hpp +++ b/src/modm/platform/core/avr/atomic_lock.hpp @@ -25,6 +25,8 @@ namespace modm namespace atomic { +// documented in :architecture:atomic +/// @cond class Lock { public: @@ -64,6 +66,7 @@ class Unlock private: uint8_t sreg; }; +/// @endcond } // namespace atomic diff --git a/src/modm/platform/core/avr/flash_reader.hpp b/src/modm/platform/core/avr/flash_reader.hpp index 2795647239..9a06c8ca33 100644 --- a/src/modm/platform/core/avr/flash_reader.hpp +++ b/src/modm/platform/core/avr/flash_reader.hpp @@ -13,6 +13,8 @@ #ifndef MODM_PLATFORM_FLASH_READER_HPP #define MODM_PLATFORM_FLASH_READER_HPP +// Already documented in :architecture:accessor +/// @cond #include #include @@ -96,4 +98,6 @@ struct FlashReader } // namespace modm +/// @endcond + #endif // MODM_PLATFORM_FLASH_READER_HPP diff --git a/src/modm/platform/core/avr/interrupts.hpp.in b/src/modm/platform/core/avr/interrupts.hpp.in index 9aee01b074..ebf2d1bb9b 100644 --- a/src/modm/platform/core/avr/interrupts.hpp.in +++ b/src/modm/platform/core/avr/interrupts.hpp.in @@ -16,18 +16,15 @@ #include -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_core Core - */ - namespace modm { -/// @ingroup {{partname}}_core namespace platform { +/// @ingroup modm_platform_core +/// @{ + /// enables global interrupts static modm_always_inline void enableInterrupts() @@ -44,7 +41,6 @@ disableInterrupts() %% if "xmega" in driver["type"] /// Used to set the interrupt level of all modules. -/// @ingroup xmega enum class InterruptLevel : uint8_t { @@ -54,7 +50,6 @@ InterruptLevel : uint8_t High = 0x03, }; -/// @ingroup xmega enum class InterruptControlLevel : uint8_t { @@ -64,13 +59,12 @@ InterruptControlLevel : uint8_t All = PMIC_HILVLEN_bm | PMIC_MEDLVLEN_bm | PMIC_LOLVLEN_bm, }; -/// @private -/// @{ +/// @cond static constexpr uint8_t i(InterruptLevel level) { return static_cast(level); } static constexpr uint8_t i(InterruptControlLevel level) { return static_cast(level); } -/// @} +/// @endcond /** * Enable one or more of the three Interrupt levels. @@ -89,8 +83,6 @@ i(InterruptControlLevel level) { return static_cast(level); } * setInterruptLevel(InterruptControlLevel::Medium); * enableInterrupts(); * @endcode - * - * @ingroup xmega */ static inline void enableInterruptLevel(InterruptControlLevel level) @@ -100,8 +92,6 @@ enableInterruptLevel(InterruptControlLevel level) /** * Disable interrupt levels. - * - * @ingroup xmega */ static inline void disableInterruptLevel(InterruptControlLevel level) @@ -110,6 +100,8 @@ disableInterruptLevel(InterruptControlLevel level) } %% endif +/// @} + } // namespace platform } // namespace modm diff --git a/src/modm/platform/core/avr/main.hpp b/src/modm/platform/core/avr/main.hpp index 91ec5b7816..8c01abef49 100644 --- a/src/modm/platform/core/avr/main.hpp +++ b/src/modm/platform/core/avr/main.hpp @@ -16,7 +16,9 @@ #include +/// @cond // saves a couple of bytes of stack and program. int main(void) __attribute__((OS_main)); +/// @endcond #endif // MODM_AVR_MAIN_HPP diff --git a/src/modm/platform/core/avr/module.lb b/src/modm/platform/core/avr/module.lb index 4e8505bff8..98adbb62f3 100644 --- a/src/modm/platform/core/avr/module.lb +++ b/src/modm/platform/core/avr/module.lb @@ -14,6 +14,7 @@ def init(module): module.name = "core" module.parent = "platform" + module.description = "AVR Core" def prepare(module, options): if not options[":target"].has_driver("core:avr*"): diff --git a/src/modm/platform/core/avr/ram.hpp b/src/modm/platform/core/avr/ram.hpp index 0a070fa212..919b3bb6b5 100644 --- a/src/modm/platform/core/avr/ram.hpp +++ b/src/modm/platform/core/avr/ram.hpp @@ -23,11 +23,13 @@ namespace modm namespace platform { +/// @cond void * allocateMemory(std::size_t requestedSize); void freeMemory(void *ptr); +/// @endcond // TODO functions to retrieve status informations about used memory diff --git a/src/modm/platform/core/avr/unaligned.hpp b/src/modm/platform/core/avr/unaligned.hpp index 4aca1a9fc9..591adae273 100644 --- a/src/modm/platform/core/avr/unaligned.hpp +++ b/src/modm/platform/core/avr/unaligned.hpp @@ -12,6 +12,9 @@ #ifndef MODM_PLATFORM_ACCESSOR_UNALIGNED_HPP #define MODM_PLATFORM_ACCESSOR_UNALIGNED_HPP +// already documented in :architecture:unaligned +/// @cond + #include namespace modm @@ -50,4 +53,6 @@ unaligned_t } // namespace modm +/// @endcond + #endif // MODM_PLATFORM_ACCESSOR_UNALIGNED_HPP diff --git a/src/modm/platform/core/cortex/atomic_lock.hpp b/src/modm/platform/core/cortex/atomic_lock.hpp index c8a6c554ee..9038a1869e 100644 --- a/src/modm/platform/core/cortex/atomic_lock.hpp +++ b/src/modm/platform/core/cortex/atomic_lock.hpp @@ -15,6 +15,7 @@ #ifndef MODM_PLATFORM_ATOMIC_LOCK_HPP #define MODM_PLATFORM_ATOMIC_LOCK_HPP +/// @cond #include "../device.hpp" #include @@ -66,4 +67,5 @@ class Unlock } // namespace modm +/// @endcond #endif // MODM_PLATFORM_ATOMIC_LOCK_HPP diff --git a/src/modm/platform/core/cortex/flash_reader.hpp b/src/modm/platform/core/cortex/flash_reader.hpp index 3957fa41a9..968c777316 100644 --- a/src/modm/platform/core/cortex/flash_reader.hpp +++ b/src/modm/platform/core/cortex/flash_reader.hpp @@ -14,6 +14,7 @@ #ifndef MODM_PLATFORM_FLASH_READER_HPP #define MODM_PLATFORM_FLASH_READER_HPP +/// @cond #include #include @@ -47,4 +48,5 @@ struct FlashReader } // namespace modm +/// @endcond #endif // MODM_PLATFORM_FLASH_READER_HPP diff --git a/src/modm/platform/core/cortex/heap_block_allocator.cpp.in b/src/modm/platform/core/cortex/heap_block_allocator.cpp.in index 725629616d..a372d1d4b2 100644 --- a/src/modm/platform/core/cortex/heap_block_allocator.cpp.in +++ b/src/modm/platform/core/cortex/heap_block_allocator.cpp.in @@ -9,11 +9,6 @@ */ // ---------------------------------------------------------------------------- -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_core Core - */ - #include #include #include diff --git a/src/modm/platform/core/cortex/heap_newlib.c.in b/src/modm/platform/core/cortex/heap_newlib.c.in index 6ab816f1cf..b8ab1c8ac5 100644 --- a/src/modm/platform/core/cortex/heap_newlib.c.in +++ b/src/modm/platform/core/cortex/heap_newlib.c.in @@ -9,11 +9,6 @@ */ // ---------------------------------------------------------------------------- -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_core Core - */ - #include #include #include diff --git a/src/modm/platform/core/cortex/heap_table.c b/src/modm/platform/core/cortex/heap_table.c index 4a5a38445a..8ebdadaf74 100644 --- a/src/modm/platform/core/cortex/heap_table.c +++ b/src/modm/platform/core/cortex/heap_table.c @@ -9,11 +9,6 @@ */ // ---------------------------------------------------------------------------- -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_core Core - */ - #include #include diff --git a/src/modm/platform/core/cortex/heap_tlsf.c.in b/src/modm/platform/core/cortex/heap_tlsf.c.in index 0719b85619..eabe2cca96 100644 --- a/src/modm/platform/core/cortex/heap_tlsf.c.in +++ b/src/modm/platform/core/cortex/heap_tlsf.c.in @@ -9,11 +9,6 @@ */ // ---------------------------------------------------------------------------- -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_core Core - */ - #include #include #include diff --git a/src/modm/platform/core/cortex/module.md b/src/modm/platform/core/cortex/module.md index 28a754009f..0c0dd54376 100644 --- a/src/modm/platform/core/cortex/module.md +++ b/src/modm/platform/core/cortex/module.md @@ -1,7 +1,13 @@ -# ARM Cortex-M startup +# ARM Cortex-M Core + +This module generates the startup code, the vector table, the linkerscript and +provides runtime support for dynamic memory allocations on the heap and +assertion handling. ## Linkerscript +The linkerscript is generated for the devices memory map. + ### Placement of `.fastcode` section From the Cortex-M3 Technical Reference Manual: diff --git a/src/modm/platform/core/cortex/unaligned.hpp.in b/src/modm/platform/core/cortex/unaligned.hpp.in index 568bcb5c78..9dfd409f74 100644 --- a/src/modm/platform/core/cortex/unaligned.hpp.in +++ b/src/modm/platform/core/cortex/unaligned.hpp.in @@ -12,6 +12,7 @@ #ifndef MODM_PLATFORM_ACCESSOR_UNALIGNED_HPP #define MODM_PLATFORM_ACCESSOR_UNALIGNED_HPP +/// @cond #include namespace modm @@ -80,4 +81,5 @@ protected: } // namespace modm +/// @endcond #endif // MODM_PLATFORM_ACCESSOR_UNALIGNED_HPP diff --git a/src/modm/platform/core/hosted/atomic_lock.hpp b/src/modm/platform/core/hosted/atomic_lock.hpp index 8c24ca0ee2..18a16b7160 100644 --- a/src/modm/platform/core/hosted/atomic_lock.hpp +++ b/src/modm/platform/core/hosted/atomic_lock.hpp @@ -15,6 +15,7 @@ #ifndef MODM_PLATFORM_ATOMIC_LOCK_HPP #define MODM_PLATFORM_ATOMIC_LOCK_HPP +/// @cond namespace modm { @@ -37,4 +38,5 @@ class Unlock } // namespace modm +/// @endcond #endif // MODM_PLATFORM_ATOMIC_LOCK_HPP diff --git a/src/modm/platform/core/hosted/delay.hpp.in b/src/modm/platform/core/hosted/delay.hpp.in index a4922812ee..a588649963 100644 --- a/src/modm/platform/core/hosted/delay.hpp.in +++ b/src/modm/platform/core/hosted/delay.hpp.in @@ -17,8 +17,8 @@ #ifndef MODM_PLATFORM_DELAY_HPP #define MODM_PLATFORM_DELAY_HPP +/// @cond #include - #include %% if target["family"] in ["darwin", "linux"] @@ -92,4 +92,5 @@ delayMilliseconds(int) } // namespace modm +/// @endcond #endif // MODM_PLATFORM_DELAY_HPP diff --git a/src/modm/platform/core/hosted/module.lb b/src/modm/platform/core/hosted/module.lb index 3fddd5e1ce..94620f4fc5 100644 --- a/src/modm/platform/core/hosted/module.lb +++ b/src/modm/platform/core/hosted/module.lb @@ -14,6 +14,7 @@ def init(module): module.name = "core" module.parent = "platform" + module.description = "Hosted Core" def prepare(module, options): device = options[":target"] diff --git a/src/modm/platform/core/windows/windows.hpp b/src/modm/platform/core/windows/windows.hpp index 8aac9071ab..b0c037ce64 100644 --- a/src/modm/platform/core/windows/windows.hpp +++ b/src/modm/platform/core/windows/windows.hpp @@ -23,7 +23,7 @@ * Provides some defines and functions which are missing in a default * windows environment. * - * \ingroup windows + * \ingroup modm_platform_core */ #include #include diff --git a/src/modm/platform/dma/stm32/dma.hpp.in b/src/modm/platform/dma/stm32/dma.hpp.in index 5a6d3ece9c..39068a1b9b 100644 --- a/src/modm/platform/dma/stm32/dma.hpp.in +++ b/src/modm/platform/dma/stm32/dma.hpp.in @@ -17,11 +17,6 @@ #include "../device.hpp" #include "dma_base.hpp" -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_dma DMA - */ - %% if target["family"] == "f4" %% set streams = range(0,8) %% elif target["family"] == "f3" @@ -44,7 +39,7 @@ namespace platform * Does not support - among other things - double buffering or FIFO usage * * @author Kevin Laeufer - * @ingroup {{partname}}_dma + * @ingroup modm_platform_dma modm_platform_dma_{{id}} */ class Dma{{ id }} { diff --git a/src/modm/platform/dma/stm32/dma_base.hpp.in b/src/modm/platform/dma/stm32/dma_base.hpp.in index 87d84e578f..0a89008f73 100644 --- a/src/modm/platform/dma/stm32/dma_base.hpp.in +++ b/src/modm/platform/dma/stm32/dma_base.hpp.in @@ -32,7 +32,7 @@ namespace platform * DMA * * @author Kevin Laeufer - * @ingroup {{partname}}_dma + * @ingroup modm_platform_dma */ class DmaBase { diff --git a/src/modm/platform/dma/stm32/module.lb b/src/modm/platform/dma/stm32/module.lb index 217fd8766a..83a039be47 100644 --- a/src/modm/platform/dma/stm32/module.lb +++ b/src/modm/platform/dma/stm32/module.lb @@ -17,7 +17,7 @@ class Instance(Module): def init(self, module): module.name = str(self.instance) - module.description = "DMA {} instance".format(self.instance) + module.description = "Instance {}".format(self.instance) def prepare(self, module, options): module.depends(":platform:dma") @@ -39,6 +39,7 @@ class Instance(Module): def init(module): module.name = "dma" module.parent = "platform" + module.description = "Direct Memory Access (DMA)" def prepare(module, options): device = options[":target"] diff --git a/src/modm/platform/fault/cortex/module.lb b/src/modm/platform/fault/cortex/module.lb index 034d921ef7..0172622d25 100644 --- a/src/modm/platform/fault/cortex/module.lb +++ b/src/modm/platform/fault/cortex/module.lb @@ -16,6 +16,11 @@ import os def init(module): module.parent = "platform" module.name = "fault.cortex" + module.description = """\ +# ARM Cortex-M Fault Handling + +Dealing with Fault handlers. +""" def prepare(module, options): if not options[":target"].has_driver("core:cortex-m*"): diff --git a/src/modm/platform/fsmc/stm32/fsmc.hpp.in b/src/modm/platform/fsmc/stm32/fsmc.hpp.in index 736737d2d2..16d004813c 100644 --- a/src/modm/platform/fsmc/stm32/fsmc.hpp.in +++ b/src/modm/platform/fsmc/stm32/fsmc.hpp.in @@ -21,11 +21,6 @@ #include #include "../device.hpp" -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_fsmc FSMC - */ - namespace modm { namespace platform @@ -97,7 +92,7 @@ namespace modm * Synchronous => burst mode? * NOR Flash and burst write? * - * @ingroup {{partname}}_fsmc + * @ingroup modm_platform_fsmc */ class NorSram { @@ -288,6 +283,7 @@ namespace modm * * * \author Fabian Greif + * \ingroup modm_platform_fsmc */ class Fsmc { diff --git a/src/modm/platform/fsmc/stm32/module.lb b/src/modm/platform/fsmc/stm32/module.lb index e1f049f336..143be13edd 100644 --- a/src/modm/platform/fsmc/stm32/module.lb +++ b/src/modm/platform/fsmc/stm32/module.lb @@ -14,6 +14,7 @@ def init(module): module.name = "fsmc" module.parent = "platform" + module.description = "Flexible (Static) Memory Controller (FSMC/FMC)" def prepare(module, options): device = options[":target"] diff --git a/src/modm/platform/gpio/at90_tiny_mega/base.hpp.in b/src/modm/platform/gpio/at90_tiny_mega/base.hpp.in index 46f41b8e7b..48541ade10 100644 --- a/src/modm/platform/gpio/at90_tiny_mega/base.hpp.in +++ b/src/modm/platform/gpio/at90_tiny_mega/base.hpp.in @@ -15,24 +15,13 @@ #include "define.h" #include -/** - * @ingroup platform - * @defgroup {{partname}} - */ - -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_gpio GPIO - */ - - namespace modm { namespace platform { -/// @ingroup {{partname}}_gpio +/// @ingroup modm_platform_gpio enum class Peripheral { @@ -42,7 +31,7 @@ Peripheral %% endfor }; -/// @ingroup {{partname}}_gpio +/// @ingroup modm_platform_gpio struct Gpio { /// Each Input Pin can be configured in one of these states. @@ -101,8 +90,7 @@ protected: * simulate an open-drain output (with internal pullups if needed). * * @see BitBangI2cMaster - * @ingroup {{partname}}_gpio - * @{ + * @ingroup modm_platform_gpio */ template< class Pin > class GpioOpenDrain : public Pin @@ -155,8 +143,6 @@ public: } }; -/// @} - } // namespace platform } // namespace modm diff --git a/src/modm/platform/gpio/at90_tiny_mega/define.h b/src/modm/platform/gpio/at90_tiny_mega/define.h index 06c85b948d..111d74691d 100644 --- a/src/modm/platform/gpio/at90_tiny_mega/define.h +++ b/src/modm/platform/gpio/at90_tiny_mega/define.h @@ -13,6 +13,7 @@ #ifndef MODM_AT90_ATTINY_ATMEGA_GPIO_DEFINES_H #define MODM_AT90_ATTINY_ATMEGA_GPIO_DEFINES_H +/// @cond #include @@ -74,4 +75,5 @@ # endif #endif +/// @endcond #endif // MODM_AT90_ATTINY_ATMEGA_GPIO_DEFINES_H diff --git a/src/modm/platform/gpio/at90_tiny_mega/module.lb b/src/modm/platform/gpio/at90_tiny_mega/module.lb index 0a0309e2dc..0eb4e78016 100644 --- a/src/modm/platform/gpio/at90_tiny_mega/module.lb +++ b/src/modm/platform/gpio/at90_tiny_mega/module.lb @@ -48,6 +48,7 @@ def extract_signals(signals): def init(module): module.name = "gpio" module.parent = "platform" + module.description = "General Purpose I/O (GPIO)" def prepare(module, options): if not options[":target"].has_driver("gpio:avr"): diff --git a/src/modm/platform/gpio/at90_tiny_mega/pin.hpp.in b/src/modm/platform/gpio/at90_tiny_mega/pin.hpp.in index 64cea41ba8..41987a2248 100644 --- a/src/modm/platform/gpio/at90_tiny_mega/pin.hpp.in +++ b/src/modm/platform/gpio/at90_tiny_mega/pin.hpp.in @@ -18,17 +18,6 @@ #include "base.hpp" #include "set.hpp" -/** - * @ingroup platform - * @defgroup {{partname}} - */ - -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_gpio GPIO - */ - - namespace modm { @@ -42,7 +31,7 @@ using GpioInput{{ port ~ pin }} = Gpio{{ port ~ pin }}; /// @endcond /// IO class for Pin {{port ~ pin}} -/// @ingroup {{partname}}_gpio +/// @ingroup modm_platform_gpio class Gpio{{ port ~ pin }} : public Gpio, public ::modm::GpioIO { template< class... Gpios > @@ -151,6 +140,17 @@ public: } public: +#ifdef __DOXYGEN__ + /// @{ + /// Connect to any software peripheral + struct BitBang; + %% for name, group in signals.items() + /// Connect to {% for sig in group %}{{ sig.driver }}{{ "" if loop.last else " or "}}{% endfor %} + using {{ name }} = GpioSignal; + %% endfor + /// @} +#endif + /// @cond template< Peripheral peripheral > struct BitBang { static void connect(); static_assert( @@ -167,8 +167,10 @@ public: "Gpio{{ port ~ pin }}::{{ signal_name }} only connects to {% for signal in signal_group %}{{signal.driver}}{% if not loop.last %} or {% endif %}{% endfor %}!"); }; %% endfor + /// @endcond }; +/// @cond template<> struct Gpio{{ port ~ pin }}::BitBang { @@ -187,6 +189,7 @@ struct Gpio{{ port ~ pin }}::{{ signal.name }} }; %% endfor %% endfor +/// @endcond } // namespace platform diff --git a/src/modm/platform/gpio/at90_tiny_mega/port.hpp.in b/src/modm/platform/gpio/at90_tiny_mega/port.hpp.in index 5c20bc25b9..8728f4e9a5 100644 --- a/src/modm/platform/gpio/at90_tiny_mega/port.hpp.in +++ b/src/modm/platform/gpio/at90_tiny_mega/port.hpp.in @@ -23,6 +23,7 @@ namespace modm namespace platform { +/// @cond template< Gpio::Port port > struct GpioPortInfo; template< class StartGpio, int8_t Width > @@ -30,9 +31,11 @@ struct GpioSetShim { static typename GpioPortInfo::template check check; }; +/// @endcond +/// @ingroup modm_platform_gpio template< class StartGpio, int8_t Width > -class GpioPort : public ::modm::GpioPort, public GpioSetShim +class GpioPort : public ::modm::GpioPort/** @cond */, public GpioSetShim/** @endcond */ { using PinSet = GpioSetShim; public: @@ -81,6 +84,7 @@ public: } }; +/// @cond // ------ Port Width Information ------ %% for port in ranges template<> @@ -131,6 +135,7 @@ struct GpioSetShim : public GpioSet< %% endfor > { static typename GpioPortInfo::template check check; }; %% endfor +/// @endcond } // namespace platform diff --git a/src/modm/platform/gpio/at90_tiny_mega/set.hpp.in b/src/modm/platform/gpio/at90_tiny_mega/set.hpp.in index 47f7c5c53f..8b4bf09c48 100644 --- a/src/modm/platform/gpio/at90_tiny_mega/set.hpp.in +++ b/src/modm/platform/gpio/at90_tiny_mega/set.hpp.in @@ -20,6 +20,7 @@ namespace modm namespace platform { +/// @ingroup modm_platform_gpio template< class... Gpios > class GpioSet : public Gpio { diff --git a/src/modm/platform/gpio/at90_tiny_mega/software_port.hpp.in b/src/modm/platform/gpio/at90_tiny_mega/software_port.hpp.in index 4902a2c008..2051e29819 100644 --- a/src/modm/platform/gpio/at90_tiny_mega/software_port.hpp.in +++ b/src/modm/platform/gpio/at90_tiny_mega/software_port.hpp.in @@ -34,7 +34,7 @@ namespace platform * @tparam Gpios Up to 16 GpioIO classes, ordered MSB to LSB * * @author Niklas Hauser - * @ingroup gpio + * @ingroup modm_platform_gpio */ template< class... Gpios > class SoftwareGpioPort : public ::modm::GpioPort, public GpioSet diff --git a/src/modm/platform/gpio/at90_tiny_mega/unused.hpp.in b/src/modm/platform/gpio/at90_tiny_mega/unused.hpp.in index 6049d67ba3..f708c0587d 100644 --- a/src/modm/platform/gpio/at90_tiny_mega/unused.hpp.in +++ b/src/modm/platform/gpio/at90_tiny_mega/unused.hpp.in @@ -51,7 +51,7 @@ namespace platform * * @author Fabian Greif * @author Niklas Hauser - * @ingroup {{partname}}_gpio + * @ingroup modm_platform_gpio */ class GpioUnused : public Gpio, public ::modm::GpioIO { @@ -92,6 +92,7 @@ public: static void disconnect() {} public: + /// @cond %% for name in all_signals template< Peripheral _ > struct {{ name }} @@ -101,6 +102,7 @@ public: static void connect() {} }; %% endfor + /// @endcond }; } // namespace platform diff --git a/src/modm/platform/gpio/common/connector.hpp b/src/modm/platform/gpio/common/connector.hpp index 83fb9aad2e..251bbe2585 100644 --- a/src/modm/platform/gpio/common/connector.hpp +++ b/src/modm/platform/gpio/common/connector.hpp @@ -21,6 +21,7 @@ namespace modm namespace platform { +/// @cond template< Peripheral peripheral, template class... Signals > struct GpioConnector { @@ -42,6 +43,7 @@ struct GpioConnector detail::GpioSignalConnect::disconnect(); } }; +/// @endcond } // namespace platform diff --git a/src/modm/platform/gpio/common/inverted.hpp b/src/modm/platform/gpio/common/inverted.hpp index a465578f33..96fb642356 100644 --- a/src/modm/platform/gpio/common/inverted.hpp +++ b/src/modm/platform/gpio/common/inverted.hpp @@ -34,7 +34,7 @@ namespace platform * @endcode * * @author Fabian Greif - * @ingroup gpio + * @ingroup modm_platform_gpio */ template < class Pin > class GpioInverted : public Pin diff --git a/src/modm/platform/gpio/common/module.lb b/src/modm/platform/gpio/common/module.lb index 67e4c42439..c897c49e07 100644 --- a/src/modm/platform/gpio/common/module.lb +++ b/src/modm/platform/gpio/common/module.lb @@ -13,6 +13,7 @@ def init(module): module.name = "gpio.common" module.parent = "platform" + module.description = "GPIO Common" def prepare(module, options): if not options[":target"].has_driver("gpio"): diff --git a/src/modm/platform/gpio/hosted/base.hpp.in b/src/modm/platform/gpio/hosted/base.hpp.in index 4f25084b9e..a14249ed19 100644 --- a/src/modm/platform/gpio/hosted/base.hpp.in +++ b/src/modm/platform/gpio/hosted/base.hpp.in @@ -15,22 +15,14 @@ #include -/** - * @ingroup platform - * @defgroup {{target.family}} - */ -/** - * @ingroup {{target.family}} - * @defgroup {{target.family}}_gpio GPIO - */ namespace modm { namespace platform { -/// @ingroup {{target.family}}_gpio +/// @ingroup modm_platform_gpio enum class Peripheral { @@ -38,7 +30,7 @@ Peripheral // ... }; -/// @ingroup {{target.family}}_gpio +/// @ingroup modm_platform_gpio struct Gpio { /// Each Input Pin can be configured in one of these states. @@ -93,7 +85,7 @@ protected: * simulate an open-drain output (with internal pullups if needed). * * @see BitBangI2cMaster - * @ingroup {{target.family}}_gpio + * @ingroup modm_platform_gpio * @{ */ template< class Pin > diff --git a/src/modm/platform/gpio/hosted/module.lb b/src/modm/platform/gpio/hosted/module.lb index 3977401ca5..e12e1a2450 100644 --- a/src/modm/platform/gpio/hosted/module.lb +++ b/src/modm/platform/gpio/hosted/module.lb @@ -15,6 +15,7 @@ def init(module): module.name = "gpio" module.parent = "platform" + module.description = "Hosted GPIO" def prepare(module, options): diff --git a/src/modm/platform/gpio/hosted/unused.hpp.in b/src/modm/platform/gpio/hosted/unused.hpp.in index 6215813597..d708393815 100644 --- a/src/modm/platform/gpio/hosted/unused.hpp.in +++ b/src/modm/platform/gpio/hosted/unused.hpp.in @@ -46,13 +46,13 @@ namespace platform * * modm::SoftwareSpiMaster< pin::Clk, pin::Mosi, GpioUnused > Spi; * - * ...partname + * ... * Spi::write(0xaa); * @endcode * * @author Fabian Greif * @author Niklas Hauser - * @ingroup {{target.family}}_gpio + * @ingroup modm_platform_gpio */ class GpioUnused : public Gpio, public ::modm::GpioIO { diff --git a/src/modm/platform/gpio/stm32/base.hpp.in b/src/modm/platform/gpio/stm32/base.hpp.in index 2ad906cbad..59ded6843f 100644 --- a/src/modm/platform/gpio/stm32/base.hpp.in +++ b/src/modm/platform/gpio/stm32/base.hpp.in @@ -16,23 +16,13 @@ #include #include -/** - * @ingroup platform - * @defgroup {{partname}} - */ - -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_gpio GPIO - */ - namespace modm { namespace platform { -/// @ingroup {{partname}}_gpio +/// @cond enum class Peripheral { @@ -41,8 +31,9 @@ Peripheral {{ per }}, %% endfor }; +/// @endcond -/// @ingroup {{partname}}_gpio +/// @ingroup modm_platform_gpio struct Gpio { enum class @@ -116,6 +107,7 @@ struct Gpio %% endfor }; + /// @cond enum class Signal { @@ -124,6 +116,7 @@ struct Gpio {{ signal }}, %% endfor }; + /// @endcond protected: /// @cond diff --git a/src/modm/platform/gpio/stm32/module.lb b/src/modm/platform/gpio/stm32/module.lb index 02b42a2ac0..6e5dd9dd4c 100644 --- a/src/modm/platform/gpio/stm32/module.lb +++ b/src/modm/platform/gpio/stm32/module.lb @@ -135,6 +135,7 @@ bprops = {} def init(module): module.name = "gpio" module.parent = "platform" + module.description = "General Purpose I/O (GPIO)" def prepare(module, options): device = options[":target"] diff --git a/src/modm/platform/gpio/stm32/pin.hpp.in b/src/modm/platform/gpio/stm32/pin.hpp.in index 8a78ff00b1..09d3f7e52b 100644 --- a/src/modm/platform/gpio/stm32/pin.hpp.in +++ b/src/modm/platform/gpio/stm32/pin.hpp.in @@ -33,7 +33,7 @@ using GpioInput{{ port ~ pin }} = Gpio{{ port ~ pin }}; /// @endcond /// IO class for Pin {{port ~ pin}} -/// @ingroup {{partname}}_gpio +/// @ingroup modm_platform_gpio class Gpio{{ port ~ pin }} : public Gpio, public ::modm::GpioIO { template @@ -65,6 +65,7 @@ protected: static constexpr IRQn_Type ExternalInterruptIRQ = EXTI{{ exti_irqn }}_IRQn; public: + /// @cond inline static void setAlternateFunction(uint8_t af) { {{reg}}->AFR[af_id] = ({{reg}}->AFR[af_id] & ~af_mask) | ((af & 0xf) << af_offset); {{reg}}->MODER = ({{reg}}->MODER & ~mask2) | (i(Mode::AlternateFunction) << (pin * 2)); @@ -72,6 +73,7 @@ public: /// Enable Analog Mode which is needed to use this pin as an ADC input. inline static void setAnalogInput() { PinSet::setAnalogInput(); } + /// @endcond public: // GpioOutput @@ -164,6 +166,17 @@ public: } public: +#ifdef __DOXYGEN__ + /// @{ + /// Connect to any software peripheral + struct BitBang; + %% for name, group in signals.items() + /// Connect to {% for sig in group %}{{ sig.driver }}{{ "" if loop.last else " or "}}{% endfor %} + using {{ name }} = GpioSignal; + %% endfor + /// @} +#endif + /// @cond template< Peripheral peripheral > struct BitBang { static void connect(); static_assert( @@ -180,8 +193,10 @@ public: "Gpio{{ port ~ pin }}::{{ signal_name }} only connects to {% for signal in signal_group %}{{signal.driver}}{% if not loop.last %} or {% endif %}{% endfor %}!"); }; %% endfor + /// @endcond }; +/// @cond template<> struct Gpio{{ port ~ pin }}::BitBang { @@ -212,6 +227,7 @@ struct Gpio{{ port ~ pin }}::{{ signal.name }} }; %% endfor %% endfor +/// @endcond } // namespace platform diff --git a/src/modm/platform/gpio/stm32/pin_f1.hpp.in b/src/modm/platform/gpio/stm32/pin_f1.hpp.in index 91faf20481..48c2566e7f 100644 --- a/src/modm/platform/gpio/stm32/pin_f1.hpp.in +++ b/src/modm/platform/gpio/stm32/pin_f1.hpp.in @@ -35,7 +35,7 @@ using GpioInput{{ port ~ pin }} = Gpio{{ port ~ pin }}; /// @endcond /// IO class for Pin {{port ~ pin}} -/// @ingroup {{partname}}_gpio +/// @ingroup modm_platform_gpio struct Gpio{{ port ~ pin }} : public Gpio, ::modm::GpioIO { template @@ -62,8 +62,10 @@ protected: static constexpr IRQn_Type ExternalInterruptIRQ = EXTI{{ exti_irqn }}_IRQn; public: + /// @cond /// Enable Analog Mode which is needed to use this pin as an ADC input. inline static void setAnalogInput() { PinSet::setAnalogInput(); } + /// @endcond public: // GpioOutput @@ -150,6 +152,17 @@ public: inline static void disconnect() { setInput(); }; public: +#ifdef __DOXYGEN__ + /// @{ + /// Connect to any software peripheral + using BitBang = GpioSignal; + %% for name, group in signals.items() + /// Connect to {% for sig in group %}{{ sig.driver }}{{ "" if loop.last else " or "}}{% endfor %} + using {{ name }} = GpioSignal; + %% endfor + /// @} +#endif + /// @cond template< Peripheral peripheral > struct BitBang { static void connect(); static_assert( @@ -166,8 +179,10 @@ public: "Gpio{{ port ~ pin }}::{{ signal_name }} only connects to {% for signal in signal_group %}{{signal.driver}}{% if not loop.last %} or {% endif %}{% endfor %}!"); }; %% endfor + /// @endcond }; +/// @cond template<> struct Gpio{{ port ~ pin }}::BitBang { @@ -202,6 +217,7 @@ struct Gpio{{ port ~ pin }}::{{ signal.name }} }; %% endfor %% endfor +/// @endcond } // namespace platform diff --git a/src/modm/platform/gpio/stm32/port.hpp.in b/src/modm/platform/gpio/stm32/port.hpp.in index 015828f3c0..bac8d143e5 100644 --- a/src/modm/platform/gpio/stm32/port.hpp.in +++ b/src/modm/platform/gpio/stm32/port.hpp.in @@ -23,6 +23,7 @@ namespace modm namespace platform { +/// @cond template< Gpio::Port port > struct GpioPortInfo; template< class StartGpio, int8_t Width > @@ -30,9 +31,11 @@ struct GpioSetShim { static typename GpioPortInfo::template check check; }; +/// @endcond +/// @ingroup modm_platform_gpio template< class StartGpio, int8_t Width > -class GpioPort : public ::modm::GpioPort, public GpioSetShim +class GpioPort : public ::modm::GpioPort/** @cond */, public GpioSetShim /** @endcond */ { using PinSet = GpioSetShim; public: @@ -87,6 +90,7 @@ public: } }; +/// @cond // ------ Port Width Information ------ %% for port in ranges template<> @@ -137,6 +141,7 @@ struct GpioSetShim : public GpioSet< %% endfor > { static typename GpioPortInfo::template check check; }; %% endfor +/// @endcond } // namespace platform diff --git a/src/modm/platform/gpio/stm32/set.hpp.in b/src/modm/platform/gpio/stm32/set.hpp.in index a8472457c5..9b643af7ee 100644 --- a/src/modm/platform/gpio/stm32/set.hpp.in +++ b/src/modm/platform/gpio/stm32/set.hpp.in @@ -21,6 +21,7 @@ namespace modm namespace platform { +/// @ingroup modm_platform_gpio template< class... Gpios > class GpioSet : public Gpio { diff --git a/src/modm/platform/gpio/stm32/software_port.hpp.in b/src/modm/platform/gpio/stm32/software_port.hpp.in index 94ac2d38a8..5307804263 100644 --- a/src/modm/platform/gpio/stm32/software_port.hpp.in +++ b/src/modm/platform/gpio/stm32/software_port.hpp.in @@ -35,7 +35,7 @@ namespace platform * @tparam Gpios Up to 32 GpioIO classes, ordered MSB to LSB * * @author Niklas Hauser - * @ingroup gpio + * @ingroup modm_platform_gpio */ template< class... Gpios > class SoftwareGpioPort : public ::modm::GpioPort, public GpioSet diff --git a/src/modm/platform/gpio/stm32/unused.hpp.in b/src/modm/platform/gpio/stm32/unused.hpp.in index ec390d07d3..c37b665c16 100644 --- a/src/modm/platform/gpio/stm32/unused.hpp.in +++ b/src/modm/platform/gpio/stm32/unused.hpp.in @@ -51,7 +51,7 @@ namespace platform * * @author Fabian Greif * @author Niklas Hauser - * @ingroup {{partname}}_gpio + * @ingroup modm_platform_gpio */ class GpioUnused : public Gpio, public ::modm::GpioIO { @@ -66,8 +66,10 @@ public: static constexpr uint16_t mask = 0; protected: + /// @cond static void setAlternateFunction(uint8_t) {} static void setAnalogInput() {} + /// @endcond public: // GpioOutput @@ -108,6 +110,7 @@ public: static void disconnect() {} public: + /// @cond %% for name in all_signals template< Peripheral _ > struct {{ name }} @@ -117,6 +120,7 @@ public: static void connect() {} }; %% endfor + /// @endcond }; } // namespace platform diff --git a/src/modm/platform/i2c/at90_tiny_mega/i2c.hpp.in b/src/modm/platform/i2c/at90_tiny_mega/i2c.hpp.in index 7281757ad1..6dd074c091 100644 --- a/src/modm/platform/i2c/at90_tiny_mega/i2c.hpp.in +++ b/src/modm/platform/i2c/at90_tiny_mega/i2c.hpp.in @@ -15,18 +15,13 @@ #include -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_i2c I2C - */ - namespace modm { namespace platform { -/// @ingroup {{partname}}_i2c +/// @ingroup modm_platform_i2c struct I2c { enum class diff --git a/src/modm/platform/i2c/at90_tiny_mega/i2c_master.hpp.in b/src/modm/platform/i2c/at90_tiny_mega/i2c_master.hpp.in index ba377910fa..b3185a34be 100644 --- a/src/modm/platform/i2c/at90_tiny_mega/i2c_master.hpp.in +++ b/src/modm/platform/i2c/at90_tiny_mega/i2c_master.hpp.in @@ -32,7 +32,7 @@ namespace platform * Interrupts must be enabled. * * @author Niklas Hauser - * @ingroup {{partname}}_i2c + * @ingroup modm_platform_i2c */ class I2cMaster : public ::modm::I2cMaster, I2c { diff --git a/src/modm/platform/i2c/at90_tiny_mega/module.lb b/src/modm/platform/i2c/at90_tiny_mega/module.lb index 34afb04651..a6a8725f5d 100644 --- a/src/modm/platform/i2c/at90_tiny_mega/module.lb +++ b/src/modm/platform/i2c/at90_tiny_mega/module.lb @@ -14,6 +14,7 @@ def init(module): module.name = "i2c" module.parent = "platform" + module.description = "Inter-Integrated Circuit (I²C)" def prepare(module, options): target = options[":target"] diff --git a/src/modm/platform/i2c/bitbang/bitbang_i2c_master.hpp.in b/src/modm/platform/i2c/bitbang/bitbang_i2c_master.hpp.in index 119f94463e..4a98e40d5e 100644 --- a/src/modm/platform/i2c/bitbang/bitbang_i2c_master.hpp.in +++ b/src/modm/platform/i2c/bitbang/bitbang_i2c_master.hpp.in @@ -30,7 +30,7 @@ namespace platform /** * Software emulation of a I2C master implementation * - * @ingroup i2c + * @ingroup modm_platform_i2c_bitbang * @author Niklas Hauser * @see gpio */ diff --git a/src/modm/platform/i2c/bitbang/module.lb b/src/modm/platform/i2c/bitbang/module.lb index 0cfcd21904..c91f499005 100644 --- a/src/modm/platform/i2c/bitbang/module.lb +++ b/src/modm/platform/i2c/bitbang/module.lb @@ -13,6 +13,7 @@ def init(module): module.name = "i2c.bitbang" module.parent = "platform" + module.description = "Software Inter-Integrated Circuit (I²C)" def prepare(module, options): if not options[":target"].has_driver("gpio"): diff --git a/src/modm/platform/i2c/stm32/i2c_master.hpp.in b/src/modm/platform/i2c/stm32/i2c_master.hpp.in index 480eebfd69..851ec6dc1e 100644 --- a/src/modm/platform/i2c/stm32/i2c_master.hpp.in +++ b/src/modm/platform/i2c/stm32/i2c_master.hpp.in @@ -18,11 +18,6 @@ #include #include -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_i2c I2C - */ - namespace modm { @@ -36,7 +31,7 @@ namespace platform * * @author Georgi Grinshpun * @author Niklas Hauser - * @ingroup {{partname}}_i2c + * @ingroup modm_platform_i2c modm_platform_i2c_{{id}} */ class I2cMaster{{ id }} : public ::modm::I2cMaster { diff --git a/src/modm/platform/i2c/stm32/module.lb b/src/modm/platform/i2c/stm32/module.lb index 61bde9b4e7..2a864f7dd7 100644 --- a/src/modm/platform/i2c/stm32/module.lb +++ b/src/modm/platform/i2c/stm32/module.lb @@ -17,7 +17,7 @@ class Instance(Module): def init(self, module): module.name = str(self.instance) - module.description = "I2C {} instance".format(self.instance) + module.description = "Instance {}".format(self.instance) def prepare(self, module, options): module.depends(":platform:i2c") @@ -54,6 +54,7 @@ class Instance(Module): def init(module): module.name = "i2c" module.parent = "platform" + module.description = "Inter-Integrated Circuit (I²C)" def prepare(module, options): device = options[":target"] diff --git a/src/modm/platform/i2c/stm32l4/i2c_master.hpp.in b/src/modm/platform/i2c/stm32l4/i2c_master.hpp.in index d1f96d991c..024578d7b3 100644 --- a/src/modm/platform/i2c/stm32l4/i2c_master.hpp.in +++ b/src/modm/platform/i2c/stm32l4/i2c_master.hpp.in @@ -18,11 +18,6 @@ #include #include -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_i2c I2C - */ - namespace modm { @@ -37,7 +32,7 @@ namespace platform * @author Georgi Grinshpun * @author Niklas Hauser * @author Sascha Schade (strongly-typed) - * @ingroup {{partname}}_i2c + * @ingroup modm_platform_i2c modm_platform_i2c_{{id}} */ class I2cMaster{{ id }} : public ::modm::I2cMaster { diff --git a/src/modm/platform/i2c/stm32l4/module.lb b/src/modm/platform/i2c/stm32l4/module.lb index 9b7e668149..d2ba8aefac 100644 --- a/src/modm/platform/i2c/stm32l4/module.lb +++ b/src/modm/platform/i2c/stm32l4/module.lb @@ -16,7 +16,7 @@ class Instance(Module): def init(self, module): module.name = str(self.instance) - module.description = "I2C {} instance".format(self.instance) + module.description = "Instance {}".format(self.instance) def prepare(self, module, options): module.depends(":platform:i2c") @@ -54,6 +54,7 @@ class Instance(Module): def init(module): module.name = "i2c" module.parent = "platform" + module.description = "Inter-Integrated Circuit (I²C)" def prepare(module, options): device = options[":target"] diff --git a/src/modm/platform/id/stm32/id.hpp.in b/src/modm/platform/id/stm32/id.hpp.in index cb232a7c2d..f9bc1c39b1 100644 --- a/src/modm/platform/id/stm32/id.hpp.in +++ b/src/modm/platform/id/stm32/id.hpp.in @@ -26,6 +26,7 @@ namespace platform * * @param offset 0..2 * @return 32-bit of the unique id + * @ingroup modm_platform_id */ static inline uint32_t getUniqueId(uint8_t offset) diff --git a/src/modm/platform/id/stm32/module.lb b/src/modm/platform/id/stm32/module.lb index 05a572182d..d994325e2f 100644 --- a/src/modm/platform/id/stm32/module.lb +++ b/src/modm/platform/id/stm32/module.lb @@ -13,6 +13,7 @@ def init(module): module.name = "id" module.parent = "platform" + module.description = "Unique ID" def prepare(module, options): if options[":target"].identifier["family"] not in ["f1", "f2", "f3", "f4", "f7"]: diff --git a/src/modm/platform/module.lb b/src/modm/platform/module.lb index 6267f254bd..ade0766db4 100644 --- a/src/modm/platform/module.lb +++ b/src/modm/platform/module.lb @@ -15,6 +15,11 @@ from os.path import join def init(module): module.name = "platform" + module.description = """\ +# Platform HAL + +Target-specific implementation of the Hardware Abstraction Layer. +""" def prepare(module, options): return True diff --git a/src/modm/platform/one_wire/bitbang/bitbang_master.hpp.in b/src/modm/platform/one_wire/bitbang/bitbang_master.hpp.in index fe7e928c50..501652c57d 100644 --- a/src/modm/platform/one_wire/bitbang/bitbang_master.hpp.in +++ b/src/modm/platform/one_wire/bitbang/bitbang_master.hpp.in @@ -40,7 +40,7 @@ namespace platform * 1-Wire Search Algorithm based on AppNote 187 at * http://www.maxim-ic.com/appnotes.cfm/appnote_number/187 * - * \ingroup 1-wire + * \ingroup modm_platform_1_wire_bitbang */ template class BitBangOneWireMaster @@ -159,14 +159,6 @@ public: searchSkipCurrentFamily(); protected: - /** - * \internal - * Universal base class for the SAB interface - * - * \see - * Understanding and Using Cyclic Redundancy Checks with Maxim iButton Products - * \ingroup sab - */ static uint8_t crcUpdate(uint8_t crc, uint8_t data); diff --git a/src/modm/platform/one_wire/bitbang/module.lb b/src/modm/platform/one_wire/bitbang/module.lb index 6588ba0241..aa35abb955 100644 --- a/src/modm/platform/one_wire/bitbang/module.lb +++ b/src/modm/platform/one_wire/bitbang/module.lb @@ -13,6 +13,7 @@ def init(module): module.name = "1-wire.bitbang" module.parent = "platform" + module.description = "Software 1-Wire" def prepare(module, options): if not options[":target"].has_driver("gpio"): diff --git a/src/modm/platform/random/stm32/module.lb b/src/modm/platform/random/stm32/module.lb index a0159deb19..95b84eaf7d 100644 --- a/src/modm/platform/random/stm32/module.lb +++ b/src/modm/platform/random/stm32/module.lb @@ -13,6 +13,7 @@ def init(module): module.name = "random" module.parent = "platform" + module.description = "Random Number Generator (RNG)" def prepare(module, options): if not options[":target"].has_driver("rng:stm32"): diff --git a/src/modm/platform/random/stm32/random_number_generator.hpp.in b/src/modm/platform/random/stm32/random_number_generator.hpp.in index c3aafa394f..b9a4e6e2aa 100644 --- a/src/modm/platform/random/stm32/random_number_generator.hpp.in +++ b/src/modm/platform/random/stm32/random_number_generator.hpp.in @@ -16,10 +16,6 @@ #include #include "../device.hpp" -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_random Random - */ namespace modm { @@ -33,7 +29,7 @@ namespace platform * @todo check error status * * @author Fabian Greif - * @ingroup {{partname}}_random + * @ingroup modm_platform_random */ class RandomNumberGenerator { diff --git a/src/modm/platform/spi/at90_tiny_mega/module.lb b/src/modm/platform/spi/at90_tiny_mega/module.lb index 1e70c2510c..5a460d2508 100644 --- a/src/modm/platform/spi/at90_tiny_mega/module.lb +++ b/src/modm/platform/spi/at90_tiny_mega/module.lb @@ -34,7 +34,7 @@ class Instance(Module): def init(self, module): module.name = str(self.instance) - module.description = "SPI {} instance".format(self.instance) + module.description = "Instance {}".format(self.instance) def prepare(self, module, options): module.depends(":platform:spi") @@ -55,6 +55,7 @@ class Instance(Module): def init(module): module.name = "spi" module.parent = "platform" + module.description = "Serial Peripheral Interface (SPI)" def prepare(module, options): device = options[":target"] diff --git a/src/modm/platform/spi/at90_tiny_mega/spi.hpp.in b/src/modm/platform/spi/at90_tiny_mega/spi.hpp.in index f41682b9ba..4eec7ada92 100644 --- a/src/modm/platform/spi/at90_tiny_mega/spi.hpp.in +++ b/src/modm/platform/spi/at90_tiny_mega/spi.hpp.in @@ -15,6 +15,7 @@ #include +/// @cond %% if partname in ["attiny40"] // The avr-libc Header files for the ATtiny40 is missing the following // defines although they are meantioned in the datasheet. @@ -48,11 +49,7 @@ #define SPIF SPIF0 #define SPDR SPDR0 %% endif - -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_spi SPI - */ +/// @endcond namespace modm { @@ -60,7 +57,7 @@ namespace modm namespace platform { -/// @ingroup {{partname}}_spi +/// @ingroup modm_platform_spi struct Spi { enum class diff --git a/src/modm/platform/spi/at90_tiny_mega/spi_master.hpp.in b/src/modm/platform/spi/at90_tiny_mega/spi_master.hpp.in index 72ebc586e6..f7f87e013e 100644 --- a/src/modm/platform/spi/at90_tiny_mega/spi_master.hpp.in +++ b/src/modm/platform/spi/at90_tiny_mega/spi_master.hpp.in @@ -46,7 +46,7 @@ namespace platform * hardware will switch into SPI slave mode. It is therefore necessary * to configure the pin either in output mode or to pull it high. * - * @ingroup {{partname}}_spi + * @ingroup modm_platform_spi modm_platform_spi_{{id}} * @author Niklas Hauser */ class SpiMaster{{ id }} : public ::modm::SpiMaster, private Spi diff --git a/src/modm/platform/spi/at90_tiny_mega_uart/module.lb b/src/modm/platform/spi/at90_tiny_mega_uart/module.lb index 580fe8860e..98ef1fd485 100644 --- a/src/modm/platform/spi/at90_tiny_mega_uart/module.lb +++ b/src/modm/platform/spi/at90_tiny_mega_uart/module.lb @@ -26,7 +26,7 @@ class Instance(Module): def init(self, module): module.name = str(self.instance) - module.description = "SPI (UART) {} instance".format(self.instance) + module.description = "Instance {}".format(self.instance) def prepare(self, module, options): module.depends(":platform:spi_uart") @@ -83,6 +83,7 @@ class Instance(Module): def init(module): module.name = "uart.spi" module.parent = "platform" + module.description = "USART in SPI Mode" def prepare(module, options): device = options[":target"] diff --git a/src/modm/platform/spi/at90_tiny_mega_uart/uart_spi_master.hpp.in b/src/modm/platform/spi/at90_tiny_mega_uart/uart_spi_master.hpp.in index 3ad0e0ff9c..31ca376eeb 100644 --- a/src/modm/platform/spi/at90_tiny_mega_uart/uart_spi_master.hpp.in +++ b/src/modm/platform/spi/at90_tiny_mega_uart/uart_spi_master.hpp.in @@ -29,7 +29,7 @@ namespace platform /** * Implementation of the SimpleSpi of the Uart in Spi Master mode. * - * @ingroup {{partname}}_spi + * @ingroup modm_platform_uart_spi modm_platform_uart_spi_{{id}} * @author Niklas Hauser */ class UartSpiMaster{{ id }} : public ::modm::SpiMaster diff --git a/src/modm/platform/spi/bitbang/bitbang_spi_master.hpp b/src/modm/platform/spi/bitbang/bitbang_spi_master.hpp index 2292a332ed..cd4630cfaf 100644 --- a/src/modm/platform/spi/bitbang/bitbang_spi_master.hpp +++ b/src/modm/platform/spi/bitbang/bitbang_spi_master.hpp @@ -34,7 +34,7 @@ namespace platform * @tparam Mosi master out slave in pin [output] * @tparam Miso master in slave out pin [input] * - * @ingroup spi + * @ingroup modm_platform_spi_bitbang * @author Niklas Hauser * @see gpio */ diff --git a/src/modm/platform/spi/bitbang/module.lb b/src/modm/platform/spi/bitbang/module.lb index 7ce31b92da..9cc611290b 100644 --- a/src/modm/platform/spi/bitbang/module.lb +++ b/src/modm/platform/spi/bitbang/module.lb @@ -13,6 +13,7 @@ def init(module): module.name = "spi.bitbang" module.parent = "platform" + module.description = "Software Serial Peripheral Interface (SPI)" def prepare(module, options): if not options[":target"].has_driver("gpio"): diff --git a/src/modm/platform/spi/stm32/module.lb b/src/modm/platform/spi/stm32/module.lb index 9c67d99dc9..f903e16658 100644 --- a/src/modm/platform/spi/stm32/module.lb +++ b/src/modm/platform/spi/stm32/module.lb @@ -27,7 +27,7 @@ class Instance(Module): def init(self, module): module.name = str(self.instance) - module.description = "SPI {} instance".format(self.instance) + module.description = "Instance {}".format(self.instance) def prepare(self, module, options): module.depends(":platform:spi") @@ -51,6 +51,7 @@ class Instance(Module): def init(module): module.name = "spi" module.parent = "platform" + module.description = "Serial Peripheral Interface (SPI)" def prepare(module, options): device = options[":target"] diff --git a/src/modm/platform/spi/stm32/spi_base.hpp.in b/src/modm/platform/spi/stm32/spi_base.hpp.in index fea8538567..d8fad02aab 100644 --- a/src/modm/platform/spi/stm32/spi_base.hpp.in +++ b/src/modm/platform/spi/stm32/spi_base.hpp.in @@ -18,11 +18,6 @@ #include "../device.hpp" #include -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_spi SPI - */ - namespace modm { @@ -35,8 +30,7 @@ namespace platform * Provides some common enum that do not depend on the specific SPI. * * @author Kevin Laeufer - * @internal - * @ingroup {{partname}}_spi + * @ingroup modm_platform_spi */ class SpiBase { diff --git a/src/modm/platform/spi/stm32/spi_hal.hpp.in b/src/modm/platform/spi/stm32/spi_hal.hpp.in index f316129db2..2342300a39 100644 --- a/src/modm/platform/spi/stm32/spi_hal.hpp.in +++ b/src/modm/platform/spi/stm32/spi_hal.hpp.in @@ -29,7 +29,7 @@ namespace platform * the regular Spi classes. * * @author Kevin Laeufer - * @ingroup {{partname}}_spi + * @ingroup modm_platform_spi modm_platform_spi_{{id}} */ class SpiHal{{ id }} : public SpiBase { diff --git a/src/modm/platform/spi/stm32/spi_master.hpp.in b/src/modm/platform/spi/stm32/spi_master.hpp.in index 7328877921..125e39f6f9 100644 --- a/src/modm/platform/spi/stm32/spi_master.hpp.in +++ b/src/modm/platform/spi/stm32/spi_master.hpp.in @@ -33,7 +33,7 @@ namespace platform * Simple unbuffered implementation. * * @author Niklas Hauser - * @ingroup {{partname}}_spi + * @ingroup modm_platform_spi modm_platform_spi_{{id}} */ class SpiMaster{{ id }} : public modm::SpiMaster { diff --git a/src/modm/platform/spi/stm32_uart/module.lb b/src/modm/platform/spi/stm32_uart/module.lb index 6a5162d6fb..e33d5472bd 100644 --- a/src/modm/platform/spi/stm32_uart/module.lb +++ b/src/modm/platform/spi/stm32_uart/module.lb @@ -24,7 +24,7 @@ class Instance(Module): def init(self, module): module.name = str(self.instance) - module.description = "SPI in UART mode {} instance".format(self.instance) + module.description = "Instance {}".format(self.instance) def prepare(self, module, options): module.depends(":platform:uart:{}".format(self.instance)) @@ -43,6 +43,7 @@ class Instance(Module): def init(module): module.name = "uart.spi" module.parent = "platform" + module.description = "USART in SPI Mode" def prepare(module, options): device = options[":target"] diff --git a/src/modm/platform/spi/stm32_uart/uart_spi_master.hpp.in b/src/modm/platform/spi/stm32_uart/uart_spi_master.hpp.in index 20d4e3662e..6f68efd516 100644 --- a/src/modm/platform/spi/stm32_uart/uart_spi_master.hpp.in +++ b/src/modm/platform/spi/stm32_uart/uart_spi_master.hpp.in @@ -31,7 +31,7 @@ namespace platform * Therefore the data is bit reversed in software for DataOrder::MsbFirst. * * @author Niklas Hauser - * @ingroup {{partname}}_spi + * @ingroup modm_platform_uart_spi modm_platform_uart_spi_{{id}} */ class UartSpiMaster{{ id }} : public modm::SpiMaster, public UartBase { diff --git a/src/modm/platform/timer/stm32/advanced.hpp.in b/src/modm/platform/timer/stm32/advanced.hpp.in index bad2b5504b..54571963c2 100644 --- a/src/modm/platform/timer/stm32/advanced.hpp.in +++ b/src/modm/platform/timer/stm32/advanced.hpp.in @@ -71,7 +71,7 @@ namespace platform * * @author Fabian Greif * @author Kevin Laeufer - * @ingroup {{partname}}_timer + * @ingroup modm_platform_timer */ class Timer{{ id }} : public AdvancedControlTimer { diff --git a/src/modm/platform/timer/stm32/advanced_base.hpp.in b/src/modm/platform/timer/stm32/advanced_base.hpp.in index a7edfad6f7..48ff52bc3b 100644 --- a/src/modm/platform/timer/stm32/advanced_base.hpp.in +++ b/src/modm/platform/timer/stm32/advanced_base.hpp.in @@ -22,7 +22,7 @@ namespace modm namespace platform { -/// @ingroup {{partname}}_timer +/// @ingroup modm_platform_timer class AdvancedControlTimer : public GeneralPurposeTimer { public: diff --git a/src/modm/platform/timer/stm32/basic.hpp.in b/src/modm/platform/timer/stm32/basic.hpp.in index 6710b57bcf..3298e8b1f4 100644 --- a/src/modm/platform/timer/stm32/basic.hpp.in +++ b/src/modm/platform/timer/stm32/basic.hpp.in @@ -51,7 +51,7 @@ namespace platform {%- endif %} * * @author Fabian Greif - * @ingroup {{partname}}_timer + * @ingroup modm_platform_timer */ class Timer{{ id }} : public BasicTimer { diff --git a/src/modm/platform/timer/stm32/basic_base.hpp.in b/src/modm/platform/timer/stm32/basic_base.hpp.in index 1762593689..c082991381 100644 --- a/src/modm/platform/timer/stm32/basic_base.hpp.in +++ b/src/modm/platform/timer/stm32/basic_base.hpp.in @@ -17,18 +17,13 @@ #include "../device.hpp" #include -/** - * @ingroup {{partname}} - * @defgroup {{partname}}_timer Timer - */ - namespace modm { namespace platform { -/// @ingroup {{partname}}_timer +/// @ingroup modm_platform_timer class BasicTimer { public: diff --git a/src/modm/platform/timer/stm32/general_purpose.hpp.in b/src/modm/platform/timer/stm32/general_purpose.hpp.in index 0b34f2e7a9..8f9ba82651 100644 --- a/src/modm/platform/timer/stm32/general_purpose.hpp.in +++ b/src/modm/platform/timer/stm32/general_purpose.hpp.in @@ -42,7 +42,7 @@ namespace platform * It might be expanded in the future. * * @author Fabian Greif - * @ingroup {{partname}}_timer + * @ingroup modm_platform_timer */ class Timer{{ id }} : public GeneralPurposeTimer { diff --git a/src/modm/platform/timer/stm32/general_purpose_base.hpp.in b/src/modm/platform/timer/stm32/general_purpose_base.hpp.in index 539a552eec..f275bda4fc 100644 --- a/src/modm/platform/timer/stm32/general_purpose_base.hpp.in +++ b/src/modm/platform/timer/stm32/general_purpose_base.hpp.in @@ -22,7 +22,7 @@ namespace modm namespace platform { -/// @ingroup {{partname}}_timer +/// @ingroup modm_platform_timer class GeneralPurposeTimer : public BasicTimer { public: diff --git a/src/modm/platform/timer/stm32/module.lb b/src/modm/platform/timer/stm32/module.lb index 500d7310b3..3f665946fc 100644 --- a/src/modm/platform/timer/stm32/module.lb +++ b/src/modm/platform/timer/stm32/module.lb @@ -41,7 +41,7 @@ class Instance(Module): def init(self, module): module.name = str(self.instance) - module.description = "Timer {} instance".format(self.instance) + module.description = "Instance {}".format(self.instance) def prepare(self, module, options): module.depends(":platform:timer") @@ -70,6 +70,7 @@ class Instance(Module): def init(module): module.name = "timer" module.parent = "platform" + module.description = "Timers (TIM)" def prepare(module, options): device = options[":target"] diff --git a/src/modm/platform/uart/at90_tiny_mega/module.lb b/src/modm/platform/uart/at90_tiny_mega/module.lb index 7d310ac2f8..34eec7265b 100644 --- a/src/modm/platform/uart/at90_tiny_mega/module.lb +++ b/src/modm/platform/uart/at90_tiny_mega/module.lb @@ -44,7 +44,7 @@ class Instance(Module): def init(self, module): module.name = str(self.instance) - module.description = "UART {} instance".format(self.instance) + module.description = "Instance {}".format(self.instance) def prepare(self, module, options): module.depends(":platform:uart") @@ -72,6 +72,7 @@ class Instance(Module): def init(module): module.name = "uart" module.parent = "platform" + module.description = "Universal Asynchronous Receiver Transmitter (UART)" def prepare(module, options): device = options[":target"] diff --git a/src/modm/platform/uart/at90_tiny_mega/uart.hpp.in b/src/modm/platform/uart/at90_tiny_mega/uart.hpp.in index b06e46108c..59ebd02dcb 100644 --- a/src/modm/platform/uart/at90_tiny_mega/uart.hpp.in +++ b/src/modm/platform/uart/at90_tiny_mega/uart.hpp.in @@ -11,11 +11,6 @@ */ // ---------------------------------------------------------------------------- -/** - * @ingroup avr - * @defgroup avr_uart UART - */ - #ifndef MODM_AVR_UART{{ id }}_HPP #define MODM_AVR_UART{{ id }}_HPP @@ -34,22 +29,11 @@ namespace platform * (Non-)Buffered Uart{{ id }} * * This implementation uses a ringbuffer. The size of the ringbuffer - * can be changed in the `project.cfg` file. - * - * Just add add a value for `tx_buffer` and/or `rx_buffer` in the - * `parameters` section. The size can be any value between 1 and 254 - * for buffered and 0 for non-buffered operation. - * - * Example: - * @code - * [parameters] - * uart.at90_tiny_mega.{{ id }}.tx_buffer = 20 - * uart.at90_tiny_mega.{{ id }}.rx_buffer = 30 - * @endcode + * can be changed in the options. * * @author Fabian Greif * @author Niklas Hauser - * @ingroup {{partname}}_uart + * @ingroup modm_platform_uart modm_platform_uart_{{id}} */ class Uart{{ id }} : public ::modm::Uart { diff --git a/src/modm/platform/uart/at90_tiny_mega/uart_defines.h b/src/modm/platform/uart/at90_tiny_mega/uart_defines.h index 9003245281..ef1b028efe 100644 --- a/src/modm/platform/uart/at90_tiny_mega/uart_defines.h +++ b/src/modm/platform/uart/at90_tiny_mega/uart_defines.h @@ -13,6 +13,7 @@ #ifndef MODM_AT90_ATTINY_ATMEGA_UART_DEFINES_H #define MODM_AT90_ATTINY_ATMEGA_UART_DEFINES_H +/// @cond // Atmel made a mess with the register names for UART0 between the "old" devices. // To avoid to much conditional compiling we try to mimic the new names for @@ -118,5 +119,6 @@ # define USART0_TX_vect USART_TXC_vect #endif +/// @endcond #endif // MODM_AT90_ATTINY_ATMEGA_UART_DEFINES_H diff --git a/src/modm/platform/uart/hosted/module.lb b/src/modm/platform/uart/hosted/module.lb index 0a2b63acaf..c28256f410 100644 --- a/src/modm/platform/uart/hosted/module.lb +++ b/src/modm/platform/uart/hosted/module.lb @@ -15,6 +15,7 @@ def init(module): module.name = "uart" module.parent = "platform" + module.description = "UART and Serial" def prepare(module, options): diff --git a/src/modm/platform/uart/hosted/serial_interface.hpp b/src/modm/platform/uart/hosted/serial_interface.hpp index 24be8cf698..9e617786b8 100644 --- a/src/modm/platform/uart/hosted/serial_interface.hpp +++ b/src/modm/platform/uart/hosted/serial_interface.hpp @@ -37,7 +37,7 @@ namespace modm * - close() * * @author Philipp & Metty - * @ingroup linux + * @ingroup modm_platform_uart */ class SerialInterface : public IODevice { diff --git a/src/modm/platform/uart/hosted/serial_port.hpp b/src/modm/platform/uart/hosted/serial_port.hpp index 6973cc8083..9ead0a2b38 100644 --- a/src/modm/platform/uart/hosted/serial_port.hpp +++ b/src/modm/platform/uart/hosted/serial_port.hpp @@ -33,7 +33,7 @@ namespace modm * * Port is closed right after construction. * - * \ingroup linux + * \ingroup modm_platform_uart */ class SerialPort : IODevice { diff --git a/src/modm/platform/uart/hosted/static_serial_interface.hpp b/src/modm/platform/uart/hosted/static_serial_interface.hpp index a5b6ca777e..aae320faf4 100644 --- a/src/modm/platform/uart/hosted/static_serial_interface.hpp +++ b/src/modm/platform/uart/hosted/static_serial_interface.hpp @@ -30,7 +30,7 @@ namespace modm * specialization number) will generate a shared object! * * @author Fabian Greif - * @ingroup linux + * @ingroup modm_platform_uart */ template class StaticSerialInterface : public modm::Uart diff --git a/src/modm/platform/uart/hosted/terminal.hpp b/src/modm/platform/uart/hosted/terminal.hpp index dfd6fbfa7f..fddd58bfa7 100644 --- a/src/modm/platform/uart/hosted/terminal.hpp +++ b/src/modm/platform/uart/hosted/terminal.hpp @@ -25,7 +25,7 @@ namespace modm * * Uses the STL IOStream for in- and output. * - * \ingroup hosted + * \ingroup modm_platform_uart */ class Terminal : public IODevice { diff --git a/src/modm/platform/uart/stm32/module.lb b/src/modm/platform/uart/stm32/module.lb index 37ba5bb5cd..cc0ed81d47 100644 --- a/src/modm/platform/uart/stm32/module.lb +++ b/src/modm/platform/uart/stm32/module.lb @@ -30,7 +30,7 @@ class Instance(Module): def init(self, module): module.name = str(self.instance) - module.description = "UART {} instance".format(self.instance) + module.description = "Instance {}".format(self.instance) def prepare(self, module, options): module.depends(":platform:uart") @@ -87,6 +87,7 @@ class Instance(Module): def init(module): module.name = "uart" module.parent = "platform" + module.description = "Universal Asynchronous Receiver Transmitter (UART)" def prepare(module, options): device = options[":target"] diff --git a/src/modm/platform/uart/stm32/uart.hpp.in b/src/modm/platform/uart/stm32/uart.hpp.in index d5cba8dcf3..b8e246a234 100644 --- a/src/modm/platform/uart/stm32/uart.hpp.in +++ b/src/modm/platform/uart/stm32/uart.hpp.in @@ -37,7 +37,7 @@ namespace platform * * @author Kevin Laeufer * @author Niklas Hauser - * @ingroup {{partname}}_uart + * @ingroup modm_platform_uart modm_platform_uart_{{id}} */ class {{ name }} : public UartBase, public ::modm::Uart { diff --git a/src/modm/platform/uart/stm32/uart_base.hpp.in b/src/modm/platform/uart/stm32/uart_base.hpp.in index 31d9d18c84..c801a087c3 100644 --- a/src/modm/platform/uart/stm32/uart_base.hpp.in +++ b/src/modm/platform/uart/stm32/uart_base.hpp.in @@ -19,6 +19,7 @@ #include #include +/// @cond %% if not extended_driver // STM has some weird ideas about continuity #define USART_BRR_DIV_MANTISSA USART_BRR_DIV_Mantissa @@ -30,11 +31,8 @@ #define USART_ISR_RXNE USART_ISR_RXNE_RXFNE #define USART_ISR_TXE USART_ISR_TXE_TXFNF %% endif +/// @endcond -/** -* @ingroup {{partname}} -* @defgroup {{partname}}_uart UART -*/ namespace modm { @@ -46,8 +44,7 @@ namespace platform * Provides some common enum that do not depend on the specific UART. * * @author Kevin Laeufer - * @internal - * @ingroup {{partname}}_uart + * @ingroup modm_platform_uart */ class UartBase { diff --git a/src/modm/platform/uart/stm32/uart_baudrate.hpp.in b/src/modm/platform/uart/stm32/uart_baudrate.hpp.in index 5a5e6d97c5..077069cf77 100644 --- a/src/modm/platform/uart/stm32/uart_baudrate.hpp.in +++ b/src/modm/platform/uart/stm32/uart_baudrate.hpp.in @@ -35,7 +35,7 @@ namespace platform * * @author Kevin Laeufer * @author Niklas Hauser - * @ingroup {{partname}}_uart + * @ingroup modm_platform_uart */ class UartBaudrate : /** @cond */protected modm::PeripheralDriver /** @endcond */ { diff --git a/src/modm/platform/uart/stm32/uart_hal.hpp.in b/src/modm/platform/uart/stm32/uart_hal.hpp.in index 7aad9b0b2e..9438a2852b 100644 --- a/src/modm/platform/uart/stm32/uart_hal.hpp.in +++ b/src/modm/platform/uart/stm32/uart_hal.hpp.in @@ -34,7 +34,7 @@ namespace platform * the regular Usart classes. * * @author Kevin Laeufer - * @ingroup {{partname}}_uart + * @ingroup modm_platform_uart */ class {{ uart_name ~ "Hal" ~ id }} : public UartBase { diff --git a/src/modm/processing/module.lb b/src/modm/processing/module.lb index ca8535ba1f..ba474144a1 100644 --- a/src/modm/processing/module.lb +++ b/src/modm/processing/module.lb @@ -11,10 +11,14 @@ # file, You can obtain one at http://mozilla.org/MPL/2.0/. # ----------------------------------------------------------------------------- -import re - def init(module): module.name = "processing" + module.description = """\ +# Processing + +Constructs to influence program flow execution, timing, synchronization +and delegation. +""" def prepare(module, options): return True diff --git a/src/modm/processing/processing.hpp.in b/src/modm/processing/processing.hpp.in index 91ed471d13..bdc5983f3b 100644 --- a/src/modm/processing/processing.hpp.in +++ b/src/modm/processing/processing.hpp.in @@ -11,12 +11,6 @@ */ // ---------------------------------------------------------------------------- -/** - * @defgroup processing Processing - * @brief Constructs to influence program flow execution, timing, - * synchronisation and delegation. - */ - #ifndef MODM_PROCESSING_HPP #define MODM_PROCESSING_HPP diff --git a/src/modm/processing/protothread.hpp b/src/modm/processing/protothread.hpp index 9fb8c8caa0..11265a271d 100644 --- a/src/modm/processing/protothread.hpp +++ b/src/modm/processing/protothread.hpp @@ -10,41 +10,13 @@ */ // ---------------------------------------------------------------------------- -/** - * \ingroup processing - * \defgroup protothread Protothreads - * \brief Lightweight, stackless threads - * - * Protothreads are extremely lightweight stackless threads designed for - * severely memory constrained systems, such as small embedded systems or - * wireless sensor network nodes. Protothreads provide linear code execution - * for event-driven systems implemented in C. Protothreads can be used with or - * without an underlying operating system to provide blocking event-handlers. - * - * Protothreads provide sequential flow of control without complex state - * machines or full multi-threading. - * - * As they implement some kind of cooperative multithreading - * Protothreads are non-preemptable. Therefore, a context switch can only take - * place on blocking operations. Therefore you don't need complex - * synchronisation. Protothreads are also stackless, which means - * member variables of the modm::Protothread subclasses are needed for - * preserving variables across context switches. - * - * A protothread runs within a single function (modm::Protothread::run()) and - * cannot span over other functions. A protothread may call normal functions, - * but cannot block inside a called function. Blocking inside nested function - * calls is instead made by spawning a separate protothread for each - * potentially blocking function. - * - * The protothread concept was developed by Adam Dunkels and Oliver Schmidt. - * - * Originally ported to C++ for use by Hamilton Jet (www.hamiltonjet.co.nz) by - * Ben Hoyt, but stripped down for public release. See his blog entry about - * it for more information: http://blog.micropledge.com/2008/07/protothreads/ - * - * \see http://www.sics.se/~adam/pt/ - */ +namespace modm +{ + /// @ingroup modm_processing_protothread + namespace pt + { + } +} #include "protothread/protothread.hpp" #include "protothread/semaphore.hpp" diff --git a/src/modm/processing/protothread/macros.hpp b/src/modm/processing/protothread/macros.hpp index 5a98aa1ca1..08afbc842d 100644 --- a/src/modm/processing/protothread/macros.hpp +++ b/src/modm/processing/protothread/macros.hpp @@ -16,11 +16,13 @@ #include +/// @ingroup modm_processing_protothread +/// @{ + /** * Declare start of protothread * * \warning Use at start of the run() implementation! - * \ingroup protothread * \hideinitializer */ #define PT_BEGIN() \ @@ -31,7 +33,6 @@ * Stop protothread and end it * * \warning Use at end of the run() implementation! - * \ingroup protothread * \hideinitializer */ #define PT_END() \ @@ -40,12 +41,8 @@ this->stop(); \ return false; -/** - * Yield protothread till next call to its run(). - * - * \ingroup protothread - * \hideinitializer - */ +/// Yield protothread till next call to its run(). +/// \hideinitializer #define PT_YIELD() \ do { \ this->ptState = __LINE__; \ @@ -53,12 +50,8 @@ case __LINE__: ; \ } while (0) -/** - * Cause protothread to wait **while** given condition is true. - * - * \ingroup protothread - * \hideinitializer - */ +/// Cause protothread to wait **while** given condition is true. +/// \hideinitializer #define PT_WAIT_WHILE(condition) \ do { \ this->ptState = __LINE__; \ @@ -68,29 +61,17 @@ return true; \ } while (0) -/** - * Cause protothread to wait **until** given condition is true. - * - * \ingroup protothread - * \hideinitializer - */ +/// Cause protothread to wait **until** given condition is true. +/// \hideinitializer #define PT_WAIT_UNTIL(condition) \ PT_WAIT_WHILE(!(condition)) -/** - * Cause protothread to wait until given child protothread completes. - * - * \ingroup protothread - * \hideinitializer - */ +/// Cause protothread to wait until given child protothread completes. +/// \hideinitializer #define PT_WAIT_THREAD(child) PT_WAIT_UNTIL(!(child).run()) -/** - * Restart and spawn given child protothread and wait until it completes. - * - * \ingroup protothread - * \hideinitializer - */ +/// Restart and spawn given child protothread and wait until it completes. +/// \hideinitializer #define PT_SPAWN(child) \ do { \ (child).restart(); \ @@ -101,8 +82,6 @@ /** * Calls a given resumable function and returns * whether it completed successfully or not. - * - * \ingroup protothread * \hideinitializer */ #define PT_CALL(resumable) \ @@ -122,8 +101,6 @@ * * In the next executing cycle the protothread will restart its execution at * its PT_BEGIN. - * - * \ingroup protothread * \hideinitializer */ #define PT_RESTART() \ @@ -132,16 +109,14 @@ return true; \ } while (0) -/** - * Stop and exit from protothread. - * - * \ingroup protothread - * \hideinitializer - */ +/// Stop and exit from protothread. +/// \hideinitializer #define PT_EXIT() \ do { \ this->stop(); \ return false; \ } while (0) +/// @} + #endif // MODM_PT_MACROS_HPP diff --git a/src/modm/processing/protothread/module.lb b/src/modm/processing/protothread/module.lb index 5d9fe9e7e6..e6a931255a 100644 --- a/src/modm/processing/protothread/module.lb +++ b/src/modm/processing/protothread/module.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "processing" module.name = "protothread" + module.description = FileReader("module.md") def prepare(module, options): module.depends(":architecture") diff --git a/src/modm/processing/protothread/module.md b/src/modm/processing/protothread/module.md new file mode 100644 index 0000000000..cc7d2698db --- /dev/null +++ b/src/modm/processing/protothread/module.md @@ -0,0 +1,76 @@ +# Protothreads + +Protothreads are extremely lightweight stackless threads designed for +severely memory constrained systems, such as small embedded systems or +wireless sensor network nodes. Protothreads provide linear code execution +for event-driven systems implemented in C. Protothreads can be used with or +without an underlying operating system to provide blocking event-handlers. + +Protothreads provide sequential flow of control without complex state +machines or full multi-threading. + +Since they implement some kind of cooperative multi-threading, Protothreads +are non-preemptable. Therefore, a context switch can only take place on +blocking operations, which means you don't need complex synchronization. + +Protothreads are also stackless, so local variables are not preserved across +context switches, and must instead become member variables of the +`modm::Protothread` subclass + +A protothread runs within a single function (`modm::Protothread::run()`) and +cannot span over other functions. A protothread may call normal functions, +but cannot block inside a called function. Blocking inside nested function +calls is instead made by spawning a separate protothread for each +potentially blocking function. + +The protothread concept was developed by Adam Dunkels and Oliver Schmidt: +http://dunkels.com/adam/pt + +Originally ported to C++ for use by Hamilton Jet (www.hamiltonjet.co.nz) by +Ben Hoyt, but stripped down for public release. + + +## Example + +```cpp +#include + +using Led = GpioB0; + +class BlinkingLight : public modm::pt::Protothread +{ +public: + bool + run() + { + PT_BEGIN(); + + // set everything up + Led::setOutput(); + Led::set(); + + while (true) + { + timeout.restart(100); + Led::set(); + PT_WAIT_UNTIL(timeout.isExpired()); + + timeout.restart(200); + Led::reset(); + PT_WAIT_UNTIL(timeout.isExpired()); + } + + PT_END(); + } + +private: + modm::ShortTimeout timeout; +}; +// ... + +BlinkingLight light; + +while (1) { + light.run(); +} +``` diff --git a/src/modm/processing/protothread/protothread.hpp b/src/modm/processing/protothread/protothread.hpp index f671df81a9..b4ab675011 100644 --- a/src/modm/processing/protothread/protothread.hpp +++ b/src/modm/processing/protothread/protothread.hpp @@ -34,60 +34,13 @@ namespace modm * protothread will run until it blocks or exits. Thus the scheduling of * protothreads is done by the application that uses protothreads. * - * Example: - * \code - * #include - * #include - * #include - * - * typedef GpioOutputB0 Led; - * - * class BlinkingLight : public modm::pt::Protothread - * { - * public: - * bool - * run() - * { - * PT_BEGIN(); - * - * // set everything up - * Led::setOutput(); - * Led::set(); - * - * while (true) - * { - * timeout.restart(100); - * Led::set(); - * PT_WAIT_UNTIL(timeout.isExpired()); - * - * timeout.restart(200); - * Led::reset(); - * PT_WAIT_UNTIL(timeout.isExpired()); - * } - * - * PT_END(); - * } - * - * private: - * modm::ShortTimeout timeout; - * }; - * - * - * ... - * BlinkingLight light; - * - * while (...) { - * light.run(); - * } - * \endcode - * * For other examples take a look in the \c examples folder in the MODM * root folder. * * \warning The names \c ptState and \c ptYield are reserved and may not * be used as variables or function names! * - * \ingroup protothread + * \ingroup modm_processing_protothread */ class Protothread { @@ -135,8 +88,8 @@ namespace modm return (this->ptState != Invalid); } -#ifdef __DOXYGEN__ /// @cond +#ifdef __DOXYGEN__ /** * \brief Run the protothread * diff --git a/src/modm/processing/protothread/semaphore.hpp b/src/modm/processing/protothread/semaphore.hpp index 1157d349e6..43d92f948f 100644 --- a/src/modm/processing/protothread/semaphore.hpp +++ b/src/modm/processing/protothread/semaphore.hpp @@ -55,7 +55,7 @@ namespace modm * * Therefore there's no Mutex implementation, it isn't needed. * - * \ingroup protothread + * \ingroup modm_processing_protothread */ class Semaphore { diff --git a/src/modm/processing/resumable.hpp b/src/modm/processing/resumable.hpp index 4de0322879..6bad01aa2d 100644 --- a/src/modm/processing/resumable.hpp +++ b/src/modm/processing/resumable.hpp @@ -13,10 +13,5 @@ */ // ---------------------------------------------------------------------------- -/** - * @ingroup processing - * @defgroup resumable Resumables - */ - #include "resumable/resumable.hpp" #include "resumable/nested_resumable.hpp" diff --git a/src/modm/processing/resumable/macros.hpp b/src/modm/processing/resumable/macros.hpp index 9aac64d534..3de767d467 100644 --- a/src/modm/processing/resumable/macros.hpp +++ b/src/modm/processing/resumable/macros.hpp @@ -18,21 +18,19 @@ #include #include +/// @ingroup modm_processing_resumable +/// @{ + #ifdef __DOXYGEN__ -/** - * Declare start of resumable function with index. - * - * @warning Use at start of the `resumable()` implementation! - * @ingroup resumable - */ +/// Declare start of resumable function with index. +/// @warning Use at start of the `resumable()` implementation! #define RF_BEGIN(index) /** * Declare start of a nested resumable function. - * This will immidiately return if the nesting is too deep. + * This will immediately return if the nesting is too deep. * - * @warning Use at start of the `resumable()` implementation! - * @ingroup resumable + * @warning Use at start of the `resumable()` implementation! */ #define RF_BEGIN() #endif @@ -41,7 +39,6 @@ * End the resumable function and return a result. * * @warning Use at end of the `resumable()` implementation only! - * @ingroup resumable * @hideinitializer */ #define RF_END_RETURN(result) \ @@ -57,7 +54,6 @@ * End the resumable function. You can use this to return `void`, or if the result does not matter. * * @warning Use at end of the `resumable()` implementation only! - * @ingroup resumable * @hideinitializer */ #define RF_END() \ @@ -74,7 +70,6 @@ * End the resumable function by calling another resumable function and returning its result. * * @warning Use at end of the `resumable()` implementation only! - * @ingroup resumable * @hideinitializer */ #define RF_END_RETURN_CALL(resumable) \ @@ -86,29 +81,17 @@ } \ static_assert(uint16_t(__COUNTER__) - rfCounter < 256, "You have too many states in this resumable function!") -/** - * Yield resumable function until next invocation. - * - * @ingroup resumable - * @hideinitializer - */ +/// Yield resumable function until next invocation. +/// @hideinitializer #define RF_YIELD() \ RF_INTERNAL_SET_CASE_YIELD(__COUNTER__) -/** - * Cause resumable function to wait until given child protothread completes. - * - * @ingroup resumable - * @hideinitializer - */ +/// Cause resumable function to wait until given child protothread completes. +/// @hideinitializer #define RF_WAIT_THREAD(child) RF_WAIT_UNTIL(!(child).run()) -/** - * Cause resumable function to wait **while** given `condition` is true. - * - * @ingroup resumable - * @hideinitializer - */ +/// Cause resumable function to wait **while** given `condition` is true. +/// @hideinitializer #define RF_WAIT_WHILE(condition) \ do { \ RF_INTERNAL_SET_CASE(__COUNTER__); \ @@ -118,21 +101,13 @@ } \ } while(0) -/** - * Cause resumable function to wait **until** given `condition` is true. - * - * @ingroup resumable - * @hideinitializer - */ +/// Cause resumable function to wait **until** given `condition` is true. +/// @hideinitializer #define RF_WAIT_UNTIL(condition) \ RF_WAIT_WHILE(!(condition)) -/** - * Calls a resumable function and returns its result. - * - * @ingroup resumable - * @hideinitializer - */ +/// Calls a resumable function and returns its result. +/// @hideinitializer #define RF_CALL(resumable) \ ({ \ RF_INTERNAL_SET_CASE(__COUNTER__); \ @@ -148,7 +123,6 @@ * Calls a resumable function, busy-waits and returns its result. * * @warning Use this with extreme caution, this can cause deadlocks! - * @ingroup resumable * @hideinitializer */ #define RF_CALL_BLOCKING(resumable) \ @@ -159,12 +133,8 @@ rfResult.getResult(); \ }) -/** -* Exits a resumable function and returns another resumable function's result. -* -* @ingroup resumable -* @hideinitializer -*/ +/// Exits a resumable function and returns another resumable function's result. +/// @hideinitializer #define RF_RETURN_CALL(resumable) \ do { \ RF_INTERNAL_SET_CASE(__COUNTER__); \ @@ -179,33 +149,25 @@ } while(0) #ifdef __DOXYGEN__ -/** - * Stop and exit from resumable function with a result. - * - * @ingroup resumable - * @hideinitializer - */ +/// Stop and exit from resumable function with a result. +/// @hideinitializer #define RF_RETURN(result) -/** - * Stop and exit from resumable function of `void` return type. - * - * @ingroup resumable - * @hideinitializer - */ +/// Stop and exit from resumable function of `void` return type. +/// @hideinitializer #define RF_RETURN() - #endif +/// @} #ifndef __DOXYGEN__ -/// Required macro to set the same unique number twice +// Required macro to set the same unique number twice #define RF_INTERNAL_SET_CASE(counter) \ this->setRf((counter % 255) + 1, rfIndex); \ MODM_FALLTHROUGH; \ case ((counter % 255) + 1): ; -/// Internal macro for yield +// Internal macro for yield #define RF_INTERNAL_SET_CASE_YIELD(counter) \ this->setRf((counter % 255) + 1, rfIndex); \ this->popRf(); \ @@ -226,7 +188,7 @@ return {modm::rf::Stop, (result)}; \ } while(0) -/// Beginner structure for nested resumable functions +// Beginner structure for nested resumable functions #define RF_BEGIN_1() \ constexpr uint16_t rfCounter = __COUNTER__; \ this->template checkRfType(); \ @@ -239,7 +201,7 @@ case (::modm::rf::Stopped): \ RF_INTERNAL_SET_CASE(__COUNTER__); -/// Beginner structure for conventional resumable functions +// Beginner structure for conventional resumable functions #define RF_BEGIN_0(index) \ constexpr uint16_t rfCounter = __COUNTER__; \ this->template checkRfFunctions(); \ diff --git a/src/modm/processing/resumable/nested_resumable.hpp.in b/src/modm/processing/resumable/nested_resumable.hpp.in index 4baa5364fa..e3d77d1b48 100644 --- a/src/modm/processing/resumable/nested_resumable.hpp.in +++ b/src/modm/processing/resumable/nested_resumable.hpp.in @@ -21,7 +21,7 @@ namespace modm { /** - * @ingroup resumable + * @ingroup modm_processing_resumable * @author Niklas Hauser * @tparam Levels maximum number of nesting levels (should be <128): * max(number of resumable functions that are called within resumable functions) + 1 @@ -69,7 +69,6 @@ public: } #ifdef __DOXYGEN__ - /// @cond /** * Run the resumable function. * @@ -79,7 +78,6 @@ public: */ modm::ResumableResult< ReturnType > resumable function(...); - /// @endcond #endif protected: diff --git a/src/modm/processing/resumable/resumable.hpp b/src/modm/processing/resumable/resumable.hpp index fca45d6d43..292e68f859 100644 --- a/src/modm/processing/resumable/resumable.hpp +++ b/src/modm/processing/resumable/resumable.hpp @@ -18,7 +18,6 @@ #include #include -/// @ingroup resumable #define MODM_RESUMABLE_MODULE_NAME "resumable" namespace modm @@ -54,7 +53,7 @@ static constexpr State Stopped = State(0); /// All resumable functions return an encapsulated result type. /// @warning The result type **must** have a default constructor! -/// @ingroup resumable +/// @ingroup modm_processing_resumable template < typename T > struct ResumableResult { @@ -102,7 +101,7 @@ struct ResumableResult /// @endcond /** - * @ingroup resumable + * @ingroup modm_processing_resumable * @author Niklas Hauser * @tparam Functions the number of resumable functions that are available in this class. Must be non-zero! */ diff --git a/src/modm/processing/rtos.hpp b/src/modm/processing/rtos.hpp index 2f34ba68fa..a6e13a01d8 100644 --- a/src/modm/processing/rtos.hpp +++ b/src/modm/processing/rtos.hpp @@ -11,6 +11,14 @@ */ // ---------------------------------------------------------------------------- +namespace modm +{ + /// @ingroup modm_processing_rtos + namespace rtos + { + } +} + #include "rtos/scheduler.hpp" #include "rtos/thread.hpp" #include "rtos/mutex.hpp" diff --git a/src/modm/processing/rtos/freertos/freertos.hpp b/src/modm/processing/rtos/freertos/freertos.hpp index e61732fbcf..cc4db522ec 100644 --- a/src/modm/processing/rtos/freertos/freertos.hpp +++ b/src/modm/processing/rtos/freertos/freertos.hpp @@ -12,9 +12,8 @@ // ---------------------------------------------------------------------------- /** - * \ingroup processing - * \defgroup freertos FreeRTOS - * + * \ingroup modm_processing_rtos + * * FreeRTOS is a real-time operating system for embedded devices, being ported * to several microcontrollers. It is distributed under the GPL with an * optional exception. @@ -30,11 +29,3 @@ * * \see http://www.freertos.org/ */ - -namespace modm -{ - /// \ingroup freertos - namespace freertos - { - } -} diff --git a/src/modm/processing/rtos/freertos/mutex.hpp b/src/modm/processing/rtos/freertos/mutex.hpp index 623afde7cb..4e53b37876 100644 --- a/src/modm/processing/rtos/freertos/mutex.hpp +++ b/src/modm/processing/rtos/freertos/mutex.hpp @@ -32,7 +32,7 @@ namespace modm * synchronisation (between threads or between threads and an interrupt), * and mutexes the better choice for implementing simple mutual exclusion. * - * \ingroup freertos + * \ingroup modm_processing_rtos */ class Mutex { @@ -62,6 +62,8 @@ namespace modm * Implements a RAII-style locking. * * Locks the Mutex when created and unlocks it on destruction. + * + * \ingroup modm_processing_rtos */ class MutexGuard { diff --git a/src/modm/processing/rtos/freertos/queue.hpp b/src/modm/processing/rtos/freertos/queue.hpp index 891a0b1319..ab075e0c3f 100644 --- a/src/modm/processing/rtos/freertos/queue.hpp +++ b/src/modm/processing/rtos/freertos/queue.hpp @@ -24,8 +24,6 @@ namespace modm { /** * \brief Queue base class - * - * \ingroup freertos */ class QueueBase { @@ -94,7 +92,7 @@ namespace modm * * This is a type-safe wrapper around QueueBase * - * \ingroup freertos + * \ingroup modm_processing_rtos */ template class Queue : private QueueBase diff --git a/src/modm/processing/rtos/freertos/scheduler.hpp b/src/modm/processing/rtos/freertos/scheduler.hpp index 44bccd9803..3baf097a86 100644 --- a/src/modm/processing/rtos/freertos/scheduler.hpp +++ b/src/modm/processing/rtos/freertos/scheduler.hpp @@ -49,7 +49,7 @@ namespace modm * FreeRTOS therefore no stop() method is implemented here. * See the README file in ext/freertos/port for more details. * - * \ingroup freertos + * \ingroup modm_processing_rtos */ class Scheduler { diff --git a/src/modm/processing/rtos/freertos/semaphore.hpp b/src/modm/processing/rtos/freertos/semaphore.hpp index 2131bc68c8..091d158ec0 100644 --- a/src/modm/processing/rtos/freertos/semaphore.hpp +++ b/src/modm/processing/rtos/freertos/semaphore.hpp @@ -99,7 +99,7 @@ namespace modm * equal to the maximum count value, indicating that all resources * are free. * - * \ingroup freertos + * \ingroup modm_processing_rtos */ class Semaphore : public SemaphoreBase { @@ -128,7 +128,7 @@ namespace modm * * The semaphore is released by default. * - * \ingroup rtos + * \ingroup modm_processing_rtos */ class BinarySemaphore : public SemaphoreBase { diff --git a/src/modm/processing/rtos/freertos/thread.hpp b/src/modm/processing/rtos/freertos/thread.hpp index d9cc6eb67d..412bd2e0cd 100644 --- a/src/modm/processing/rtos/freertos/thread.hpp +++ b/src/modm/processing/rtos/freertos/thread.hpp @@ -39,7 +39,7 @@ * \see vTaskDelayUntil() from FreeRTOS * * \hideinitializer - * \ingroup freertos + * \ingroup modm_processing_rtos */ #define TIME_LOOP(frequency) \ for(portTickType lastTime = xTaskGetTickCount() ; \ @@ -67,7 +67,7 @@ * first which will lead to wrong results. * * \hideinitializer - * \ingroup freertos + * \ingroup modm_processing_rtos */ #define MILLISECONDS (configTICK_RATE_HZ / 1000.0) @@ -103,7 +103,7 @@ namespace modm * Sideeffects: * Thread constructor disables the SysTickTimer until the Scheduler is called. * - * \ingroup freertos + * \ingroup modm_processing_rtos */ class Thread { diff --git a/src/modm/processing/rtos/module.lb b/src/modm/processing/rtos/module.lb index 9b582da688..db677a4e08 100644 --- a/src/modm/processing/rtos/module.lb +++ b/src/modm/processing/rtos/module.lb @@ -14,6 +14,12 @@ def init(module): module.parent = "processing" module.name = "rtos" + module.description = """\ +# RTOS Abstractions + +Basic building blocks of an RTOS abstracted as C++ classes and implemented +either with FreeRTOS or stdlibc++. +""" def prepare(module, options): if options[":target"].identifier["platform"] not in ["hosted", "stm32"]: diff --git a/src/modm/processing/rtos/stdlib/mutex.hpp b/src/modm/processing/rtos/stdlib/mutex.hpp index 3ab1f2dae9..bac863d032 100644 --- a/src/modm/processing/rtos/stdlib/mutex.hpp +++ b/src/modm/processing/rtos/stdlib/mutex.hpp @@ -26,7 +26,7 @@ namespace modm /** * \brief Mutex * - * \ingroup stdlib_rtos + * \ingroup modm_processing_rtos */ class Mutex { @@ -70,6 +70,7 @@ namespace modm * Implements a RAII-style locking. * * Locks the Mutex when created and unlocks it on destruction. + * \ingroup modm_processing_rtos */ class MutexGuard : std::lock_guard { diff --git a/src/modm/processing/rtos/stdlib/queue.hpp b/src/modm/processing/rtos/stdlib/queue.hpp index e44a7fc58c..9ef1565877 100644 --- a/src/modm/processing/rtos/stdlib/queue.hpp +++ b/src/modm/processing/rtos/stdlib/queue.hpp @@ -25,7 +25,7 @@ namespace modm /** * Thread-safe Queue. * - * \ingroup rtos_boost + * \ingroup modm_processing_rtos */ template class Queue diff --git a/src/modm/processing/rtos/stdlib/scheduler.hpp b/src/modm/processing/rtos/stdlib/scheduler.hpp index d1ce5b0c63..ba2ddee441 100644 --- a/src/modm/processing/rtos/stdlib/scheduler.hpp +++ b/src/modm/processing/rtos/stdlib/scheduler.hpp @@ -21,6 +21,7 @@ namespace modm { namespace rtos { + /// @ingroup modm_processing_rtos class Scheduler { public: diff --git a/src/modm/processing/rtos/stdlib/semaphore.hpp b/src/modm/processing/rtos/stdlib/semaphore.hpp index 8eed81ad8f..15e65e16b4 100644 --- a/src/modm/processing/rtos/stdlib/semaphore.hpp +++ b/src/modm/processing/rtos/stdlib/semaphore.hpp @@ -46,7 +46,7 @@ namespace modm * equal to the maximum count value, indicating that all resources * are free. * - * \ingroup rtos_boost + * \ingroup modm_processing_rtos */ class Semaphore { @@ -115,7 +115,7 @@ namespace modm * * The semaphore is released by default. * - * \ingroup rtos_boost + * \ingroup modm_processing_rtos */ class BinarySemaphore : public Semaphore { diff --git a/src/modm/processing/rtos/stdlib/thread.hpp b/src/modm/processing/rtos/stdlib/thread.hpp index d78c17bc55..a6444b2bd2 100644 --- a/src/modm/processing/rtos/stdlib/thread.hpp +++ b/src/modm/processing/rtos/stdlib/thread.hpp @@ -38,7 +38,7 @@ * \see MILLISECONDS * * \hideinitializer - * \ingroup stdlib_rtos + * \ingroup modm_processing_rtos */ /*#define TIME_LOOP(frequency) \ for(portTickType lastTime = xTaskGetTickCount() ; \ @@ -55,7 +55,7 @@ * \endcode * * \hideinitializer - * \ingroup stdlib_rtos + * \ingroup modm_processing_rtos */ #define MILLISECONDS 1 @@ -69,7 +69,7 @@ namespace modm /** * \brief Thread * - * \ingroup stdlib_rtos + * \ingroup modm_processing_rtos */ class Thread { diff --git a/src/modm/processing/scheduler/module.lb b/src/modm/processing/scheduler/module.lb index 240e2f5857..f7f6a3360d 100644 --- a/src/modm/processing/scheduler/module.lb +++ b/src/modm/processing/scheduler/module.lb @@ -14,6 +14,11 @@ def init(module): module.parent = "processing" module.name = "scheduler" + module.description = """\ +# Generic Scheduler + +Priority task scheduling +""" def prepare(module, options): module.depends( diff --git a/src/modm/processing/scheduler/scheduler.hpp b/src/modm/processing/scheduler/scheduler.hpp index 2c25afb18d..ceffec0df3 100644 --- a/src/modm/processing/scheduler/scheduler.hpp +++ b/src/modm/processing/scheduler/scheduler.hpp @@ -24,16 +24,14 @@ namespace modm { /** - * \ingroup processing - * \brief %Scheduler + * \ingroup modm_processing_scheduler + * \brief Scheduler * * If the schedule() method is call from a timer interrupt, this scheduler * is a priority based preemptive scheduler, meaning that always the task * with the highest priority is executed. It will only change tasks if a * task with a higher priority becomes ready or the current task ends. * - * \image html scheduler.png - * * \warning Works for ATmega, but currently not for the ATxmega! * * \author Fabian Greif @@ -45,7 +43,7 @@ namespace modm typedef uint8_t Priority; /** - * \brief %Scheduler task + * \brief Scheduler task */ class Task { diff --git a/src/modm/processing/task.hpp b/src/modm/processing/task.hpp index 740cb94c53..dae23ba554 100644 --- a/src/modm/processing/task.hpp +++ b/src/modm/processing/task.hpp @@ -26,7 +26,7 @@ namespace modm * and starts execution. It is not declared here because the task may need * some specific information which should be passed as a parameter. * - * @ingroup processing + * @ingroup modm_processing * @author Fabian Greif */ class Task diff --git a/src/modm/processing/timer.hpp b/src/modm/processing/timer.hpp index 159d1d4422..62f4f4914d 100644 --- a/src/modm/processing/timer.hpp +++ b/src/modm/processing/timer.hpp @@ -11,13 +11,6 @@ */ // ---------------------------------------------------------------------------- -/** - * @ingroup processing - * @defgroup software_timer Software Timers - * - * An implementation of lightweight software timeouts and periodic timers. - */ - #include "timer/timestamp.hpp" #include "timer/timeout.hpp" #include "timer/periodic_timer.hpp" diff --git a/src/modm/processing/timer/module.lb b/src/modm/processing/timer/module.lb index cebe6714f4..680c474363 100644 --- a/src/modm/processing/timer/module.lb +++ b/src/modm/processing/timer/module.lb @@ -14,6 +14,7 @@ def init(module): module.parent = "processing" module.name = "timer" + module.description = FileReader("module.md") def prepare(module, options): module.depends( diff --git a/src/modm/processing/timer/module.md b/src/modm/processing/timer/module.md new file mode 100644 index 0000000000..6025f117df --- /dev/null +++ b/src/modm/processing/timer/module.md @@ -0,0 +1,138 @@ +# Software Timers + +An implementation of lightweight software timeouts and periodic timers. + +- `modm::Timestamp` containing a time in millisecond resolution up to 49 days. +- `modm::Timeout` for timeouts up to 24 days. +- `modm::PeriodicTimer` for periodic timeouts up to 24 days periods. + +There are also 16-bit versions of these, in case you need to preserve memory: + +- `modm::ShortTimestamp` containing a time in millisecond resolution up to 65 seconds. +- `modm::ShortTimeout` for timeouts up to 32 seconds. +- `modm::ShortPeriodicTimer` for periodic timeouts up to 32 second periods. + +These classes default to using `modm::Clock`, which must be implemented on your +system to return a time with millisecond resolution. + +You may also create your own timers with custom time bases and resolutions +using these classes: + +- `modm::GenericTimestamp`. +- `modm::GenericTimeout`. +- `modm::GenericPeriodicTimer`. + +!!! warning + Never use these classes when a precise timebase is needed! + +## Timeouts + +The `modm::GenericTimeout` classes allow for a signal to be generated after a +period of time, which can also be used to execute code once after timeout +expiration. + +Its behavior can be described by the following annotated waveform: + +- C: Default Constructor +- S: (Re-)Start timeout +- E: Timeout Expired +- H: Code handler (`execute()` returned `true`) +- P: Stop timeout + +``` +Event: C S E H P S E H + _____________ ______________ +Expired: ______________/ \_______________________/ ... + ______ __________ +Armed: _______/ \__________________________/ \______________... + _______ ____________ +Stopped: \____________________/ \_________________________... + + _ _ +Handle: ___________________/ \_______________________________/ \___________... + +Remaining: 0 | + | - | 0 | + | - +``` + +The default constructor initializes the timeout in the `Stopped` state, +in which `isExpired()` and `execute()` never return `true`. +If you need a timeout to expire immidiately after construction, you need +to explicitly initialize the constructor with time `0`, which has the +same behavior as `restart(0)`. + +If you want to execute code once after the timeout expired, poll the +`execute()` method, which returns `true` exactly once after expiration. + +```cpp +if (timeout.execute()) +{ + // called once after timeout + Led::toggle(); +} +``` + +Be aware, however, that since this method is polled, it cannot execute +exactly at the time of expiration, but some time after expiration, as +indicated in the above waveform graph. + +The `remaining()` time until expiration is signed positive before, and +negative after expiration. This means `Clock::now() + Timeout::remaining()` +will yield the timestamp of the expiration. +If the timeout is stopped, `remaining()` returns zero. + +## Periodic Timers + +The `modm::GenericPeriodicTimer` class allows for periodic code execution. + +Its behavior can be described by the following annotated waveform: + +- C: Constructor +- S: (Re-)Start timer +- I: Period interval +- H: Code handler (`execute()` returned `true`) +- P: Stop timer + +``` +Event: C IH I I H I S IH I IH P + _ _____________ __ _ ______ +Expired: __________/ \_______/ \_____/ \____/ \__/ \____... + __________ _______ _____ ____ __ _ +Armed: \_/ \_____________/ \__/ \_/ \______/ \__... + __ +Stopped: ______________________________________________________________/ ... + + _ _ _ _ +Handle: __________/ \___________________/ \_____________/ \_______/ \____... + +Remaining: + |0| + | - |0| + | -| + |0| +| - |0|+| 0 +``` + * + * If you want to execute code once per period interval, poll the + * `execute()` method, which returns `true` exactly once after expiration. + * + * @code + * if (timer.execute()) + * { + * // periodically called once + * Led::toggle(); + * } + * @endcode + * + * Be aware, however, that since this method is polled, it cannot execute + * exactly at the time of expiration, but some time after expiration, as + * indicated in the above waveform graph. + * If one or several periods are missed when polling `execute()`, these + * code executions are discarded and will not be caught up. + * Instead, `execute()` returns `true` once and then reschedules itself + * for the next period, without any period skewing. + * + * @warning Never use this class when a precise timebase is needed! + * + * Notice, that the `PeriodicTimerState::Expired` is reset to + * `PeriodicTimerState::Armed` only after `execute()` has returned `true`. + * This is different to the behavior of GenericTimeout, where calls to + * `GenericTimeout::execute()` have no impact on class state. + * + * The `remaining()` time until period expiration is signed positive before, + * and negative after period expiration until `execute()` is called. + * If the timer is stopped, `remaining()` returns zero. \ No newline at end of file diff --git a/src/modm/processing/timer/periodic_timer.hpp b/src/modm/processing/timer/periodic_timer.hpp index 0b40fbfd3c..5b687c6012 100644 --- a/src/modm/processing/timer/periodic_timer.hpp +++ b/src/modm/processing/timer/periodic_timer.hpp @@ -22,7 +22,7 @@ namespace modm { /// Possible states of a timer -/// @ingroup software_timer +/// @ingroup modm_processing_timer enum class PeriodicTimerState : uint8_t { @@ -32,62 +32,7 @@ PeriodicTimerState : uint8_t }; /** - * Generic software timeout class for variable timebase and timestamp width. - * - * This class allows for periodic code execution - * - * Its logic can be described by the following annotated waveform: - * - * - C: Constructor - * - S: (Re-)Start timer - * - I: Period interval - * - H: Code handler (`execute()` returned `true`) - * - P: Stop timer - * -@verbatim -Event: C IH I I H I S IH I IH P - _ _____________ __ _ ______ -Expired: __________/ \_______/ \_____/ \____/ \__/ \____... - __________ _______ _____ ____ __ _ -Armed: \_/ \_____________/ \__/ \_/ \______/ \__... - __ -Stopped: ______________________________________________________________/ ... - - _ _ _ _ -Handle: __________/ \___________________/ \_____________/ \_______/ \____... - -Remaining: + |0| + | - |0| + | -| + |0| +| - |0|+| 0 -@endverbatim - * - * If you want to execute code once per period interval, poll the - * `execute()` method, which returns `true` exactly once after expiration. - * - * @code - * if (timer.execute()) - * { - * // periodically called once - * Led::toggle(); - * } - * @endcode - * - * Be aware, however, that since this method is polled, it cannot execute - * exactly at the time of expiration, but some time after expiration, as - * indicated in the above waveform graph. - * If one or several periods are missed when polling `execute()`, these - * code executions are discarded and will not be caught up. - * Instead, `execute()` returns `true` once and then reschedules itself - * for the next period, without any period skewing. - * - * @warning Never use this class when a precise timebase is needed! - * - * Notice, that the `PeriodicTimerState::Expired` is reset to - * `PeriodicTimerState::Armed` only after `execute()` has returned `true`. - * This is different to the behavior of GenericTimeout, where calls to - * `GenericTimeout::execute()` have no impact on class state. - * - * The `remaining()` time until period expiration is signed positive before, - * and negative after period expiration until `execute()` is called. - * If the timer is stopped, `remaining()` returns zero. + * Generic periodic software timeout class for variable timebase and timestamp width. * * @see GenericTimeout * @@ -98,7 +43,7 @@ Remaining: + |0| + | - |0| + | -| + |0| +| - |0|+| 0 * * @author Fabian Greif * @author Niklas Hauser - * @ingroup software_timer + * @ingroup modm_processing_timer */ template< class Clock, typename TimestampType = modm::Timestamp > class GenericPeriodicTimer @@ -155,12 +100,12 @@ class GenericPeriodicTimer * * If you need a longer time period, use PeriodicTimer. * - * @ingroup software_timer + * @ingroup modm_processing_timer */ using ShortPeriodicTimer = GenericPeriodicTimer< ::modm::Clock, ShortTimestamp>; /// Periodic software timer for up to 24 days with millisecond resolution. -/// @ingroup software_timer +/// @ingroup modm_processing_timer using PeriodicTimer = GenericPeriodicTimer< ::modm::Clock, Timestamp>; } // namespace diff --git a/src/modm/processing/timer/timeout.hpp b/src/modm/processing/timer/timeout.hpp index 3fef615c65..9653b7baee 100644 --- a/src/modm/processing/timer/timeout.hpp +++ b/src/modm/processing/timer/timeout.hpp @@ -24,7 +24,7 @@ namespace modm { /// Possible states of a timeout -/// @ingroup software_timer +/// @ingroup modm_processing_timer enum class TimeoutState : uint8_t { @@ -40,61 +40,6 @@ class GenericPeriodicTimer; /** * Generic software timeout class for variable timebase and timestamp width. * - * This class allows for a signal to be generated after a period of time, - * which can also be used to execute code once after timeout expiration. - * - * Its logic can be described by the following annotated waveform: - * - * - C: Default Constructor - * - S: (Re-)Start timeout - * - E: Timeout Expired - * - H: Code handler (`execute()` returned `true`) - * - P: Stop timeout - * -@verbatim -Event: C S E H P S E H - _____________ ______________ -Expired: ______________/ \_______________________/ ... - ______ __________ -Armed: _______/ \__________________________/ \______________... - _______ ____________ -Stopped: \____________________/ \_________________________... - - _ _ -Handle: ___________________/ \_______________________________/ \___________... - -Remaining: 0 | + | - | 0 | + | - -@endverbatim - * - * The default constructor initializes the timeout in the `Stopped` state, - * in which `isExpired()` and `execute()` never return `true`. - * If you need a timeout to expire immidiately after construction, you need - * to explicitly initialize the constructor with time `0`, which has the - * same behavior as `restart(0)`. - * - * If you want to execute code once after the timeout expired, poll the - * `execute()` method, which returns `true` exactly once after expiration. - * - * @code - * if (timeout.execute()) - * { - * // called once after timeout - * Led::toggle(); - * } - * @endcode - * - * Be aware, however, that since this method is polled, it cannot execute - * exactly at the time of expiration, but some time after expiration, as - * indicated in the above waveform graph. - * - * @warning Never use this class when a precise timebase is needed! - * - * The `remaining()` time until expiration is signed positive before, and - * negative after expiration. This means `Clock::now() + Timeout::remaining()` - * will yield the timestamp of the expiration. - * If the timeout is stopped, `remaining()` returns zero. - * - * * @see GenericPeriodicTimer * * @tparam Clock @@ -104,7 +49,7 @@ Remaining: 0 | + | - | 0 | + | - * * @author Fabian Greif * @author Niklas Hauser - * @ingroup software_timer + * @ingroup modm_processing_timer */ template< class Clock, class TimestampType = modm::Timestamp > class GenericTimeout @@ -184,12 +129,12 @@ class GenericTimeout * * If you need a longer time period, use Timeout. * - * @ingroup software_timer + * @ingroup modm_processing_timer */ using ShortTimeout = GenericTimeout< ::modm::Clock, ShortTimestamp>; /// Software timeout for up to 24 days with millisecond resolution. -/// @ingroup software_timer +/// @ingroup modm_processing_timer using Timeout = GenericTimeout< ::modm::Clock, Timestamp>; } // namespace modm diff --git a/src/modm/processing/timer/timestamp.hpp b/src/modm/processing/timer/timestamp.hpp index 29f09ee686..7c655513f3 100644 --- a/src/modm/processing/timer/timestamp.hpp +++ b/src/modm/processing/timer/timestamp.hpp @@ -30,7 +30,7 @@ namespace modm * * @author Fabian Greif * @author Niklas Hauser - * @ingroup software_timer + * @ingroup modm_processing_timer */ template< typename T > class GenericTimestamp @@ -110,11 +110,11 @@ class GenericTimestamp }; /// 16bit timestamp, which can hold up to 65 seconds at millisecond resolution. -/// @ingroup software_timer +/// @ingroup modm_processing_timer using ShortTimestamp = GenericTimestamp; /// 32bit timestamp, which can hold up to 49 days at millisecond resolution. -/// @ingroup software_timer +/// @ingroup modm_processing_timer using Timestamp = GenericTimestamp; // ------------------------------------------------------------------------ diff --git a/src/modm/ui/animation.hpp b/src/modm/ui/animation.hpp index bf60821e27..e25b0a6c62 100644 --- a/src/modm/ui/animation.hpp +++ b/src/modm/ui/animation.hpp @@ -10,13 +10,6 @@ */ // ---------------------------------------------------------------------------- -/** - * @defgroup animation Animators - * @brief Various classes for animating values. - * - * @ingroup ui - */ - #include "animation/base.hpp" #include "animation/key_frame.hpp" #include "animation/indicator.hpp" diff --git a/src/modm/ui/animation/base.hpp b/src/modm/ui/animation/base.hpp index 490ca1186d..5da9df3035 100644 --- a/src/modm/ui/animation/base.hpp +++ b/src/modm/ui/animation/base.hpp @@ -26,16 +26,16 @@ namespace ui /** * This class allows the linear animation of one value over time. * - * Be aware that the algortihm for 8bit types is optimized for low computational costs, - * developed for fast LED fading (@see modm::ui::Led). - * Therefore the animation length is limited to `128ms * value_difference`, which is - * about 32s over the full 8bit range. + * Be aware that the algorithm for 8-bit types is optimized for low computational + * costs, developed for fast LED fading (@see `modm::ui::Led`). + * Therefore the animation length is limited to `128ms * value_difference`, + * which is about 32s over the full 8-bit range. * If you specify a longer time in this case, the animation simply finishes before. - * If this is a problem, consider using a 16bit type, which does not have + * If this is a problem, consider using a 16-bit type, which does not have * this limitation. * * @author Niklas Hauser - * @ingroup animation + * @ingroup modm_ui_animation */ template< typename T = uint8_t > class Animation diff --git a/src/modm/ui/animation/indicator.hpp b/src/modm/ui/animation/indicator.hpp index e96c5198e8..0cf9fbcb69 100644 --- a/src/modm/ui/animation/indicator.hpp +++ b/src/modm/ui/animation/indicator.hpp @@ -35,7 +35,7 @@ namespace ui * @endcode * * @author Niklas Hauser - * @ingroup animation + * @ingroup modm_ui_animation */ template< typename T = uint8_t > class Indicator diff --git a/src/modm/ui/animation/interpolation.hpp b/src/modm/ui/animation/interpolation.hpp index 276eb0f99c..c9dacab17c 100644 --- a/src/modm/ui/animation/interpolation.hpp +++ b/src/modm/ui/animation/interpolation.hpp @@ -41,7 +41,7 @@ namespace ui * must be prevented externally. * * @author Niklas Hauser - * @ingroup animation + * @ingroup modm_ui_animation */ template< typename T = uint8_t > class FastRamp diff --git a/src/modm/ui/animation/key_frame.hpp b/src/modm/ui/animation/key_frame.hpp index d13156cc1c..4c9cdf5566 100644 --- a/src/modm/ui/animation/key_frame.hpp +++ b/src/modm/ui/animation/key_frame.hpp @@ -21,6 +21,7 @@ namespace modm namespace ui { +/// @ingroup modm_ui_animation enum class KeyFrameAnimationMode { @@ -67,7 +68,7 @@ using KeyFrame = typename KeyFrameHelper::type; * @tparam N the number of values in this frame * * @author Niklas Hauser - * @ingroup animation + * @ingroup modm_ui_animation */ template struct KeyFrame @@ -164,7 +165,7 @@ using KeyFrameAnimation = typename KeyFrameAnimationHelper::type; * This class takes an array of keyframes and applies them to an animation. * * @author Niklas Hauser - * @ingroup animation + * @ingroup modm_ui_animation */ template class KeyFrameAnimation diff --git a/src/modm/ui/animation/module.lb b/src/modm/ui/animation/module.lb index 6d4aaa1a12..ac6c12230a 100644 --- a/src/modm/ui/animation/module.lb +++ b/src/modm/ui/animation/module.lb @@ -13,6 +13,11 @@ def init(module): module.parent = "ui" module.name = "animation" + module.description = """\ +# Animators + +Various classes for animating values. +""" def prepare(module, options): module.depends(":architecture:clock", ":utils") diff --git a/src/modm/ui/animation/pulse.hpp b/src/modm/ui/animation/pulse.hpp index a819166721..db9028b05c 100644 --- a/src/modm/ui/animation/pulse.hpp +++ b/src/modm/ui/animation/pulse.hpp @@ -35,7 +35,7 @@ namespace ui * @endcode * * @author Niklas Hauser - * @ingroup animation + * @ingroup modm_ui_animation */ template< typename T = uint8_t > class Pulse diff --git a/src/modm/ui/animation/strobe.hpp b/src/modm/ui/animation/strobe.hpp index 43ecc96677..da9b2940d7 100644 --- a/src/modm/ui/animation/strobe.hpp +++ b/src/modm/ui/animation/strobe.hpp @@ -34,7 +34,7 @@ namespace ui * @endcode * * @author Niklas Hauser - * @ingroup animation + * @ingroup modm_ui_animation */ template< typename T = uint8_t > class Strobe diff --git a/src/modm/ui/button.hpp b/src/modm/ui/button.hpp index 9a5f1656b8..646af4a365 100644 --- a/src/modm/ui/button.hpp +++ b/src/modm/ui/button.hpp @@ -23,7 +23,7 @@ namespace modm * * \todo Implementation is incomplete * - * \ingroup ui + * \ingroup modm_ui_button * \author Fabian Greif */ template diff --git a/src/modm/ui/button.lb b/src/modm/ui/button.lb index aa28f84070..44b409452a 100644 --- a/src/modm/ui/button.lb +++ b/src/modm/ui/button.lb @@ -13,6 +13,48 @@ def init(module): module.parent = "ui" module.name = "button" + module.description = """\ +# Debouncing Buttons + +The `modm::ButtonGroup` class is able to debounce eight buttons at the same time. +The buttons have to be low-active. If this isn't the case invert their signal +before passing it to the `update()` method. + +The `update()` method needs to be called periodically for example +every 10ms. Preferred in a timer interrupt function. + +The detection for long or repeated presses works only correctly for +one key at a time. This constraint only applies to buttons listed in the +`mask` variable."""r""" + +Mode 1: + +``` + Timeline ----> + __ _________________ __ +getState() ____/ \____/ \____/ \____ +isPressed() ----X-------X----------------------X------- +isRepeated() --------------------X--X--X--X------------- +isReleased() -------X----------------------X-------X---- + | |__|__| + |_______| \ / + \ interval + timeout +``` + +Mode 2: + +``` + __ _________________ __ +getState() ____/ \____/ \____/ \____ +isPressedShort() -------X------------------------------X---- +isPressedLong() --------------------X---------------------- +isReleased() -------X----------------------X-------X---- +``` + +This implementation is based on the C functions written +by Peter Dannegger (see http://www.mikrocontroller.net/topic/48465). +""" def prepare(module, options): module.depends(":architecture:atomic") diff --git a/src/modm/ui/button_group.hpp b/src/modm/ui/button_group.hpp index b68eeee78f..4532caeb3b 100644 --- a/src/modm/ui/button_group.hpp +++ b/src/modm/ui/button_group.hpp @@ -24,53 +24,11 @@ namespace modm { /** - * Debouncing signals - * - * This class is able to debounce eight buttons at the same time. The - * buttons have to be low-active. If this isn't the case invert their signal - * before passing it to the `update()` method. - * - * The `update()` method needs to be called periodically for example - * every 10ms. Preferred in a timer interrupt function. - * - * Example: - * @include gpio/button_group/main.cpp - * - * The detection for long or repeated presses works only correctly for - * one key at a time. This constraint only applies to buttons listed in the - * `mask` variable. - * - * Mode 1: -@verbatim - Timeline ----> - __ _________________ __ -getState() ____/ \____/ \____/ \____ -isPressed() ----X-------X----------------------X------- -isRepeated() --------------------X--X--X--X------------- -isReleased() -------X----------------------X-------X---- - | |__|__| - |_______| \ / - \ interval - timeout -@endverbatim - * - * Mode 2: -@verbatim - __ _________________ __ -getState() ____/ \____/ \____/ \____ -isPressedShort() -------X------------------------------X---- -isPressedLong() --------------------X---------------------- -isReleased() -------X----------------------X-------X---- -@endverbatim - * - * This implementation is based on the C functions written - * by Peter Dannegger (see http://www.mikrocontroller.net/topic/48465). - * * @tparam T * Container type: `uint8_t` for eight buttons or `uint16_t` for * up to 16 buttons * - * @ingroup ui + * @ingroup modm_ui_button */ template class ButtonGroup diff --git a/src/modm/ui/color.hpp b/src/modm/ui/color.hpp index 130842b138..7418b3bcc5 100644 --- a/src/modm/ui/color.hpp +++ b/src/modm/ui/color.hpp @@ -22,6 +22,7 @@ namespace modm { +/// @ingroup modm_ui_color namespace color { @@ -31,6 +32,7 @@ class HsvT; template class RgbT; +/// @ingroup modm_ui_color template class RgbT { @@ -95,8 +97,10 @@ class RgbT operator << ( IOStream& os, const RgbT&); }; +/// @ingroup modm_ui_color typedef RgbT<> Rgb; +/// @ingroup modm_ui_color template class HsvT { @@ -120,6 +124,7 @@ class HsvT toRgb(RgbT* color) const; }; +/// @ingroup modm_ui_color typedef HsvT<> Hsv; template diff --git a/src/modm/ui/color.lb b/src/modm/ui/color.lb index ffd1ae02be..118aa6a590 100644 --- a/src/modm/ui/color.lb +++ b/src/modm/ui/color.lb @@ -13,6 +13,11 @@ def init(module): module.parent = "ui" module.name = "color" + module.description = """\ +# Color + +RGB and HSV containers and converters. +""" def prepare(module, options): module.depends( diff --git a/src/modm/ui/display.hpp b/src/modm/ui/display.hpp index be368388aa..4ce3be2fd4 100644 --- a/src/modm/ui/display.hpp +++ b/src/modm/ui/display.hpp @@ -12,13 +12,6 @@ */ // ---------------------------------------------------------------------------- -/** - * \defgroup graphics Graphics - * \brief Code for writing and drawing on displays. - * - * \ingroup ui - */ - #include "display/font.hpp" #include "display/image.hpp" diff --git a/src/modm/ui/display/buffered_graphic_display.hpp b/src/modm/ui/display/buffered_graphic_display.hpp index 132746ecfd..b3cf269b23 100644 --- a/src/modm/ui/display/buffered_graphic_display.hpp +++ b/src/modm/ui/display/buffered_graphic_display.hpp @@ -31,7 +31,7 @@ namespace modm * \tparam Height Height of the display. Must be a multiple of 8! * * \author Fabian Greif - * \ingroup graphics + * \ingroup modm_ui_display */ template class BufferedGraphicDisplay : public GraphicDisplay diff --git a/src/modm/ui/display/character_display.hpp b/src/modm/ui/display/character_display.hpp index d75250eac6..0fbf2e7f62 100644 --- a/src/modm/ui/display/character_display.hpp +++ b/src/modm/ui/display/character_display.hpp @@ -25,15 +25,15 @@ namespace modm * About this implementation: * * In contrast to other drivers which use static methods, - * this class is directly derived from IODevice with all the virtual + * this class is directly derived from `modm::IODevice` with all the virtual * methods because it will be most likely used to create a IOStream * which then handles the output to the display. * * Therefore creating this class with static methods and using a wrapper - * class to create a IODevice seems unnecessary complicated. + * class to create a `modm::IODevice` seems unnecessary complicated. * * @author Fabian Greif - * @ingroup graphics + * @ingroup modm_ui_display */ class CharacterDisplay : public IOStream { diff --git a/src/modm/ui/display/font.hpp b/src/modm/ui/display/font.hpp index 04b6921dff..bdc5a08377 100644 --- a/src/modm/ui/display/font.hpp +++ b/src/modm/ui/display/font.hpp @@ -14,8 +14,8 @@ // ---------------------------------------------------------------------------- /** - * \ingroup graphics - * \defgroup font Fonts + * \ingroup modm_ui_display + * \defgroup modm_ui_display_font Fonts * * Various fonts for graphical displays. * The fonts are created with the "FontCreator 3.0", see \c tools/font_creator. diff --git a/src/modm/ui/display/font/all_caps_3x5.hpp b/src/modm/ui/display/font/all_caps_3x5.hpp index 588ed2dac9..982eb938f8 100644 --- a/src/modm/ui/display/font/all_caps_3x5.hpp +++ b/src/modm/ui/display/font/all_caps_3x5.hpp @@ -35,7 +35,7 @@ namespace modm * - number of chars : 96 * - size in bytes : 370 * - * \ingroup font + * \ingroup modm_ui_display_font */ EXTERN_FLASH_STORAGE(uint8_t AllCaps3x5[]); } diff --git a/src/modm/ui/display/font/arcade_classic.hpp b/src/modm/ui/display/font/arcade_classic.hpp index 2bee0968b0..b65ef58a50 100644 --- a/src/modm/ui/display/font/arcade_classic.hpp +++ b/src/modm/ui/display/font/arcade_classic.hpp @@ -35,7 +35,7 @@ namespace modm * - number of chars : 96 * - size in bytes : 776 * - * \ingroup font + * \ingroup modm_ui_display_font */ EXTERN_FLASH_STORAGE(uint8_t ArcadeClassic[]); } diff --git a/src/modm/ui/display/font/assertion.hpp b/src/modm/ui/display/font/assertion.hpp index 97b34d8651..d26f4a3f92 100644 --- a/src/modm/ui/display/font/assertion.hpp +++ b/src/modm/ui/display/font/assertion.hpp @@ -35,7 +35,7 @@ namespace modm * - number of chars : 96 * - size in bytes : 1304 * - * \ingroup font + * \ingroup modm_ui_display_font */ EXTERN_FLASH_STORAGE(uint8_t Assertion[]); } diff --git a/src/modm/ui/display/font/fixed_width_5x8.hpp b/src/modm/ui/display/font/fixed_width_5x8.hpp index 23f26b7fe4..ea391e1410 100644 --- a/src/modm/ui/display/font/fixed_width_5x8.hpp +++ b/src/modm/ui/display/font/fixed_width_5x8.hpp @@ -35,7 +35,7 @@ namespace modm * - number of chars : 96 * - size in bytes : 584 * - * \ingroup font + * \ingroup modm_ui_display_font */ EXTERN_FLASH_STORAGE(uint8_t FixedWidth5x8[]); } diff --git a/src/modm/ui/display/font/matrix_8x8.hpp b/src/modm/ui/display/font/matrix_8x8.hpp index 05469d9136..c2666fb356 100644 --- a/src/modm/ui/display/font/matrix_8x8.hpp +++ b/src/modm/ui/display/font/matrix_8x8.hpp @@ -35,7 +35,7 @@ namespace modm * - number of chars : 10 * - size in bytes : 98 * - * \ingroup font + * \ingroup modm_ui_display_font */ EXTERN_FLASH_STORAGE(uint8_t Matrix8x8[]); } diff --git a/src/modm/ui/display/font/numbers_14x32.hpp b/src/modm/ui/display/font/numbers_14x32.hpp index 37ad063782..8a4a1071a2 100644 --- a/src/modm/ui/display/font/numbers_14x32.hpp +++ b/src/modm/ui/display/font/numbers_14x32.hpp @@ -35,7 +35,7 @@ namespace modm * - number of chars : 10 * - size in bytes : 578 * - * \ingroup font + * \ingroup modm_ui_display_font */ EXTERN_FLASH_STORAGE(uint8_t Numbers14x32[]); } diff --git a/src/modm/ui/display/font/numbers_40x56.hpp b/src/modm/ui/display/font/numbers_40x56.hpp index 9212769ff2..31ae54b7b4 100644 --- a/src/modm/ui/display/font/numbers_40x56.hpp +++ b/src/modm/ui/display/font/numbers_40x56.hpp @@ -35,7 +35,7 @@ namespace modm * - number of chars : 10 * - size in bytes : 2818 * - * \ingroup font + * \ingroup modm_ui_display_font */ EXTERN_FLASH_STORAGE(uint8_t Numbers40x57[]); } diff --git a/src/modm/ui/display/font/numbers_46x64.hpp b/src/modm/ui/display/font/numbers_46x64.hpp index f2437e6b52..9881a83ff7 100644 --- a/src/modm/ui/display/font/numbers_46x64.hpp +++ b/src/modm/ui/display/font/numbers_46x64.hpp @@ -35,7 +35,7 @@ namespace modm * - number of chars : 10 * - size in bytes : 3698 * - * \ingroup font + * \ingroup modm_ui_display_font */ EXTERN_FLASH_STORAGE(uint8_t Numbers46x64[]); } diff --git a/src/modm/ui/display/font/scripto_narrow.hpp b/src/modm/ui/display/font/scripto_narrow.hpp index 95c4b2d71e..05d815c8bb 100644 --- a/src/modm/ui/display/font/scripto_narrow.hpp +++ b/src/modm/ui/display/font/scripto_narrow.hpp @@ -35,7 +35,7 @@ namespace modm * - number of chars : 95 * - size in bytes : 382 * - * \ingroup font + * \ingroup modm_ui_display_font */ EXTERN_FLASH_STORAGE(uint8_t ScriptoNarrow[]); } diff --git a/src/modm/ui/display/font/ubuntu_36.hpp b/src/modm/ui/display/font/ubuntu_36.hpp index eb6bd41efb..b05ba82133 100644 --- a/src/modm/ui/display/font/ubuntu_36.hpp +++ b/src/modm/ui/display/font/ubuntu_36.hpp @@ -35,7 +35,7 @@ namespace modm * - number of chars : 96 * - size in bytes : 7389 * - * \ingroup font + * \ingroup modm_ui_display_font */ EXTERN_FLASH_STORAGE(uint8_t Ubuntu_36[]); } diff --git a/src/modm/ui/display/graphic_display.hpp b/src/modm/ui/display/graphic_display.hpp index da95601423..11b98f8139 100644 --- a/src/modm/ui/display/graphic_display.hpp +++ b/src/modm/ui/display/graphic_display.hpp @@ -28,12 +28,14 @@ namespace modm { - /// @ingroup graphics + /// @ingroup modm_ui_display namespace glcd { + /// @ingroup modm_ui_display typedef Vector Point; // RGB16 (565) Format + /// @ingroup modm_ui_display class Color { public: @@ -105,27 +107,7 @@ namespace modm /** * Base class for graphical displays. * - * Coordinate System: - * \code - * (0, 0) - * +---------------------+ - * | ----> X | - * | | | - * | | | - * | V Y | - * | | - * | | - * | | - * +---------------------+ - * e.g. (127, 63) - * \endcode - * - * The size (width and height) of a graphics primitive always correspond - * to its mathematical model, ignoring the rendered with. As everything - * is drawn one pixel wide, the pixels will be rendered to the right and - * below the mathematically defined points. - * - * \ingroup graphics + * \ingroup modm_ui_display */ /* * TODO diff --git a/src/modm/ui/display/image.hpp b/src/modm/ui/display/image.hpp index 99953988bf..c84dc9a631 100644 --- a/src/modm/ui/display/image.hpp +++ b/src/modm/ui/display/image.hpp @@ -12,13 +12,12 @@ // ---------------------------------------------------------------------------- /** - * \ingroup graphics - * \defgroup image Images + * \ingroup modm_ui_display + * \defgroup modm_ui_display_image Images * * Images are generated out of PBM format, see \c tools/bitmap. */ -#include "image/logo_xpcc_90x64.hpp" #include "image/logo_rca_90x64.hpp" #include "image/logo_eurobot_90x64.hpp" #include "image/skull_64x64.hpp" diff --git a/src/modm/ui/display/image/home_16x16.hpp b/src/modm/ui/display/image/home_16x16.hpp index 4ce43d4f24..9a06623c2d 100644 --- a/src/modm/ui/display/image/home_16x16.hpp +++ b/src/modm/ui/display/image/home_16x16.hpp @@ -26,7 +26,7 @@ namespace bitmap * - Width : 16 * - Height : 16 * - * \ingroup image + * \ingroup modm_ui_display_image */ EXTERN_FLASH_STORAGE(uint8_t home_16x16[]); } diff --git a/src/modm/ui/display/image/logo_eurobot_90x64.hpp b/src/modm/ui/display/image/logo_eurobot_90x64.hpp index aa4643dbb5..75cea765eb 100644 --- a/src/modm/ui/display/image/logo_eurobot_90x64.hpp +++ b/src/modm/ui/display/image/logo_eurobot_90x64.hpp @@ -26,7 +26,7 @@ namespace bitmap * - Width : 90 * - Height : 64 * - * \ingroup image + * \ingroup modm_ui_display_image */ EXTERN_FLASH_STORAGE(uint8_t logo_eurobot_90x64[]); } diff --git a/src/modm/ui/display/image/logo_rca_90x64.hpp b/src/modm/ui/display/image/logo_rca_90x64.hpp index faa374230d..fca47b10bb 100644 --- a/src/modm/ui/display/image/logo_rca_90x64.hpp +++ b/src/modm/ui/display/image/logo_rca_90x64.hpp @@ -26,7 +26,7 @@ namespace bitmap * - Width : 90 * - Height : 64 * - * \ingroup image + * \ingroup modm_ui_display_image */ EXTERN_FLASH_STORAGE(uint8_t logo_rca_90x64[]); } diff --git a/src/modm/ui/display/image/logo_xpcc_90x64.cpp b/src/modm/ui/display/image/logo_xpcc_90x64.cpp deleted file mode 100644 index 0da7968083..0000000000 --- a/src/modm/ui/display/image/logo_xpcc_90x64.cpp +++ /dev/null @@ -1,30 +0,0 @@ -/* - * Copyright (c) 2011, Fabian Greif - * Copyright (c) 2013, Niklas Hauser - * - * This file is part of the modm project. - * - * This Source Code Form is subject to the terms of the Mozilla Public - * License, v. 2.0. If a copy of the MPL was not distributed with this - * file, You can obtain one at http://mozilla.org/MPL/2.0/. - */ -// ---------------------------------------------------------------------------- - -#include - -namespace bitmap -{ - FLASH_STORAGE(uint8_t logo_modm_90x64[]) = - { - 90, 64, - 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x80, 0x80, 0x80, 0xc0, 0xc0, 0xc0, 0xc0, 0xe0, 0xe0, 0xe0, 0xe0, 0xe0, 0xe0, 0xe0, 0xe0, 0xe0, 0xc0, 0xc0, 0x60, 0x20, 0x30, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x30, 0x20, 0x60, 0xc0, 0x00, 0x80, 0x80, 0xc0, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, - 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x06, 0x1a, 0x22, 0xc2, 0x02, 0x02, 0x0c, 0x10, 0x20, 0x40, 0x20, 0x10, 0x0c, 0x02, 0x82, 0xc2, 0xf2, 0xfa, 0xfe, 0x1e, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x1f, 0x1f, 0x3f, 0xff, 0xff, 0x07, 0x01, 0x00, 0x00, 0xe0, 0xf8, 0xfc, 0xfe, 0xfe, 0xfe, 0xfe, 0xfc, 0xfc, 0xfc, 0x3e, 0x07, 0x03, 0x01, 0x80, 0xe0, 0x30, 0x18, 0x08, 0x08, 0x18, 0x10, 0x10, 0x10, 0x0f, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, - 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xc0, 0x21, 0x12, 0x0c, 0x00, 0x80, 0xc0, 0x80, 0x00, 0x04, 0x0e, 0x3f, 0x7f, 0xff, 0xff, 0xff, 0x00, 0x00, 0x00, 0x00, 0xfe, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xfe, 0xfc, 0x00, 0x00, 0x00, 0x00, 0xff, 0xe0, 0x80, 0x00, 0x00, 0x07, 0x1f, 0x3f, 0x3f, 0x7f, 0x7f, 0x7f, 0x7f, 0x3f, 0x3f, 0xc0, 0x00, 0x00, 0x00, 0x1f, 0x3c, 0x78, 0xe0, 0xc0, 0x80, 0x80, 0xc0, 0x40, 0x40, 0x40, 0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, - 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x38, 0x26, 0x21, 0x20, 0x20, 0x38, 0xfc, 0xff, 0xff, 0xff, 0xff, 0xff, 0xfc, 0xf0, 0xe0, 0xe0, 0xe1, 0xe7, 0xff, 0x00, 0x00, 0x00, 0x00, 0x07, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x07, 0x83, 0x80, 0xc0, 0xe0, 0xf8, 0xff, 0xff, 0xff, 0xff, 0xfe, 0xfe, 0xfc, 0xfc, 0xf8, 0xf8, 0xf8, 0xf8, 0xf8, 0xfc, 0xfc, 0xfe, 0xff, 0xfe, 0xfc, 0xf8, 0xf8, 0xf0, 0xf0, 0xf0, 0xf0, 0x10, 0x10, 0x10, 0x18, 0x08, 0x07, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, - 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x80, 0x80, 0x80, 0x80, 0xff, 0xdf, 0xff, 0xdf, 0xff, 0xe7, 0xd3, 0xf7, 0xff, 0xc7, 0xfb, 0xc7, 0xff, 0xcb, 0xc3, 0xff, 0xc1, 0xdb, 0xe7, 0xff, 0xe1, 0xdf, 0xff, 0xc5, 0xff, 0xc7, 0xfb, 0xc7, 0xff, 0x67, 0x5b, 0x83, 0xff, 0xff, 0xff, 0xc3, 0xfb, 0x3f, 0x18, 0x24, 0x18, 0x00, 0x3e, 0x24, 0x18, 0x00, 0x18, 0x24, 0x18, 0x00, 0x1e, 0x24, 0x00, 0x28, 0x24, 0x14, - 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x0f, 0x3f, 0x7f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x7f, 0x3f, 0x0f, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, - 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x03, 0x07, 0x0f, 0x1f, 0x3f, 0x7f, 0x7f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x7f, 0x7f, 0x3f, 0x1f, 0x0f, 0x07, 0x03, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, - 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x01, 0x03, 0x03, 0x03, 0x07, 0x07, 0x07, 0x07, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x07, 0x07, 0x07, 0x07, 0x03, 0x03, 0x03, 0x01, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, - }; -} - diff --git a/src/modm/ui/display/image/logo_xpcc_90x64.hpp b/src/modm/ui/display/image/logo_xpcc_90x64.hpp deleted file mode 100644 index 245da58536..0000000000 --- a/src/modm/ui/display/image/logo_xpcc_90x64.hpp +++ /dev/null @@ -1,35 +0,0 @@ -/* - * Copyright (c) 2011, Fabian Greif - * Copyright (c) 2013-2014, Niklas Hauser - * Copyright (c) 2015, Sascha Schade - * - * This file is part of the modm project. - * - * This Source Code Form is subject to the terms of the Mozilla Public - * License, v. 2.0. If a copy of the MPL was not distributed with this - * file, You can obtain one at http://mozilla.org/MPL/2.0/. - */ -// ---------------------------------------------------------------------------- - -#ifndef BITMAP_LOGO_MODM_90X64_HPP -#define BITMAP_LOGO_MODM_90X64_HPP - -#include - -namespace bitmap -{ - /** - * \brief Generated bitmap - * - * Generated from file "src/modm/ui/display/image/logo_modm_90x64.pbm". - * - * - Width : 90 - * - Height : 64 - * - * \ingroup image - */ - EXTERN_FLASH_STORAGE(uint8_t logo_modm_90x64[]); -} - -#endif // BITMAP_LOGO_MODM_90X64_HPP - diff --git a/src/modm/ui/display/image/logo_xpcc_90x64.pbm b/src/modm/ui/display/image/logo_xpcc_90x64.pbm deleted file mode 100644 index 926f5ec5b1..0000000000 --- a/src/modm/ui/display/image/logo_xpcc_90x64.pbm +++ /dev/null @@ -1,86 +0,0 @@ -P1 -# CREATOR: GIMP PNM Filter Version 1.1 -90 64 -0000000000000000000000000000000000000000000000000000000000000000000000 -0000000000000000000000000000000000000000000000000000000000000000000000 -0000000000000000000000000000000000000000000000000000000000000000000000 -0000000000000000000000000000000000000000000000000000000000000000000000 -0000000000000000000000000000000000000000000000000000000000000000000000 -0000000000000000000000000000000000000000000000000000000000000001111111 -1000000000000000000000000000000000000000000000000000000000000000000000 -1111111110011100000011100000000000000000000000000000000000000000000000 -0000000000000000111111111111111100000000001100011111111000000000000000 -0000000000000000000000000000000001111111111111111110000000000001011100 -0000010000000000000000000000000000000000000000000001111111111111111111 -0000000000000111000000000010000000000000000000000001111110000000111111 -1111111111111111111000000111100011100000000000100000000000000000000000 -0100000100000100000111111111111111111110000011111111110000000000001000 -0000000000000000000000100001000001000011111111111111111111000001111111 -1110000001111000100000000000000000000000001000001000100001111000000000 -0001111100000111111111100000110011110000000000000000000000000001000001 -0100000111000000000000000111000011111111111000011000000000000000000000 -0000000000000010000010000011110000000000000000110000111111111100000100 -0000000000000000000000000000000000100000000001111100000000000000001100 -0011111111110000110000000000000000000000000000000000000100000000011111 -0000011111100000010000111111111100001000000000000000000000000000000000 -0000001000000011111100001111111100000100001111111111000010000000000000 -0000000000000000000000000001000001111111000011111111100001000011111111 -1100001100000000000000000000000000000000000000010000001111110000111111 -1110000100000111111111000011100000000000000000000000000000000000001000 -0000011111000011111111100001000001111111110000111000000000000000000000 -0000000000000001000000000111110000111111111000011000001111111100000111 -0000000000000000000000000000000000100000100000111100001111111110000110 -0000001111001000001110011110000000000000000000000000001000011100000111 -0000111111111000011100000000000010000001111100010000000000000000000000 -0001000011111000011100001111111110000111100000000000010000000000000100 -0000000000000000000000100000111110000011000011111111100001111110000000 -0011100000000000010000000000000000000000001000011111110000110000111111 -1100000111111110000011111100000000000100000000000000000000000100001111 -1111000001000001111110000011111111111111111111110000000110000000000000 -0000000000010000111111111000010000000000000000111111111111111111111111 -1111110000000000000000000000000111111111111111111100000000000000011111 -1111111111111111111111000000000000000000000000000000000001111111111111 -0000000000000011111111111111111111111111110000000000000000000000000000 -0000000111111111111100000000000011111111111111111111111111111100000000 -0000000000000000000000000001111111111111000011111111111111111111111111 -1111111111110000000000000000000000000000000000011111111111110000111111 -1111111111011101101111111111111100001000000010000000000000000000000111 -1111111111000011111101110110010011011111011100111001010011000100110011 -0000000000000000011111111111110000111110001010110101010110101010101110 -1110101010101010010000000000000000000111111111111100001111101110101001 -0101011010101010111011101010101010100001000000000000000000111111111111 -0000101011011010100100111010101011001110110100110001000101100000000000 -0000000011111111111100001111111111111111111111111111111011111000000000 -0000000000000000000000000000111111111111111111111111111111111111111111 -1110011111100000000000000000000000000000000000001111111111111111111111 -1111111111111111111111111111111000000000000000000000000000000000000001 -1111111111111111111111111111111111111111111111111100000000000000000000 -0000000000000000000111111111111111111111111111111111111111111111111111 -0000000000000000000000000000000000000001111111111111111111111111111111 -1111111111111111111100000000000000000000000000000000000000001111111111 -1111111111111111111111111111111111111110000000000000000000000000000000 -0000000000111111111111111111111111111111111111111111111111100000000000 -0000000000000000000000000000000111111111111111111111111111111111111111 -1111111100000000000000000000000000000000000000000000111111111111111111 -1111111111111111111111111110000000000000000000000000000000000000000000 -0011111111111111111111111111111111111111111111100000000000000000000000 -0000000000000000000000011111111111111111111111111111111111111111110000 -0000000000000000000000000000000000000000000011111111111111111111111111 -1111111111111110000000000000000000000000000000000000000000000000011111 -1111111111111111111111111111111111000000000000000000000000000000000000 -0000000000000000111111111111111111111111111111111111100000000000000000 -0000000000000000000000000000000000000111111111111111111111111111111111 -1100000000000000000000000000000000000000000000000000000000111111111111 -1111111111111111111110000000000000000000000000000000000000000000000000 -0000000000111111111111111111111111111110000000000000000000000000000000 -0000000000000000000000000000000111111111111111111111111111000000000000 -0000000000000000000000000000000000000000000000000000011111111111111111 -1111110000000000000000000000000000000000000000000000000000000000000000 -0000001111111111111111100000000000000000000000000000000000000000000000 -0000000000000000000000000000001111111110000000000000000000000000000000 -0000000000000000000000000000000000000000000000000000000000000000000000 -0000000000000000000000000000000000000000000000000000000000000000000000 -0000000000000000000000000000000000000000000000000000000000000000000000 -0000000000000000000000000000000000000000000000000000000000000000000000 -0000000000000000000000000000000000000000000000000000000000000000000000 -00000000000000000000 \ No newline at end of file diff --git a/src/modm/ui/display/image/skull_64x64.hpp b/src/modm/ui/display/image/skull_64x64.hpp index c9d6c3a9f6..75338bff7e 100644 --- a/src/modm/ui/display/image/skull_64x64.hpp +++ b/src/modm/ui/display/image/skull_64x64.hpp @@ -26,7 +26,7 @@ namespace bitmap * - Width : 64 * - Height : 64 * - * \ingroup image + * \ingroup modm_ui_display_image */ EXTERN_FLASH_STORAGE(uint8_t skull_64x64[]); } diff --git a/src/modm/ui/display/module.lb b/src/modm/ui/display/module.lb index b183ebc751..81deef0e9e 100644 --- a/src/modm/ui/display/module.lb +++ b/src/modm/ui/display/module.lb @@ -13,6 +13,32 @@ def init(module): module.parent = "ui" module.name = "display" + module.description = """\ +# Display Graphics + +Code for writing and drawing on character and graphical displays. + +## Coordinate System + +``` +(0, 0) + +---------------------+ + | ----> X | + | | | + | | | + | V Y | + | | + | | + | | + +---------------------+ + e.g. (127, 63) +``` + +The size (width and height) of a graphics primitive always correspond +to its mathematical model, ignoring the rendered with. As everything +is drawn one pixel wide, the pixels will be rendered to the right and +below the mathematically defined points. +""" def prepare(module, options): module.depends( diff --git a/src/modm/ui/display/virtual_graphic_display.hpp b/src/modm/ui/display/virtual_graphic_display.hpp index 1e9d7706d6..b73363a1fe 100644 --- a/src/modm/ui/display/virtual_graphic_display.hpp +++ b/src/modm/ui/display/virtual_graphic_display.hpp @@ -20,7 +20,7 @@ namespace modm { - /// @ingroup graphics + /// @ingroup modm_ui_display class VirtualGraphicDisplay: public modm::GraphicDisplay { diff --git a/src/modm/ui/gui.hpp b/src/modm/ui/gui.hpp index b73527f33b..10da89d433 100644 --- a/src/modm/ui/gui.hpp +++ b/src/modm/ui/gui.hpp @@ -11,13 +11,6 @@ */ // ---------------------------------------------------------------------------- -/** - * @defgroup gui Graphical User Interface - * @brief Various classes for creating GUI applications. - * - * @ingroup ui - */ - #include "gui/types.hpp" #include "gui/colorpalette.hpp" #include "gui/view_stack.hpp" diff --git a/src/modm/ui/gui/colorpalette.hpp b/src/modm/ui/gui/colorpalette.hpp index db2c28ee79..759cda205f 100644 --- a/src/modm/ui/gui/colorpalette.hpp +++ b/src/modm/ui/gui/colorpalette.hpp @@ -25,11 +25,13 @@ namespace gui { class ColorPalette; +/// @ingroup modm_ui_gui extern ColorPalette DefaultColorPalette; /* * TODO: find a way so that color options can be defined in user program */ +/// @ingroup modm_ui_gui enum Color { BLACK, @@ -50,7 +52,7 @@ Color { }; /// @author Niklas Hauser -/// @ingroup gui +/// @ingroup modm_ui_gui class ColorPalette { public: diff --git a/src/modm/ui/gui/module.lb b/src/modm/ui/gui/module.lb index 13ae0d72a1..6a977cd7b1 100644 --- a/src/modm/ui/gui/module.lb +++ b/src/modm/ui/gui/module.lb @@ -13,6 +13,11 @@ def init(module): module.parent = "ui" module.name = "gui" + module.description = """\ +# Graphical User Interface + +Various classes for creating GUI applications. +""" def prepare(module, options): module.depends( diff --git a/src/modm/ui/gui/types.hpp b/src/modm/ui/gui/types.hpp index 65a12d2d88..04280d0341 100644 --- a/src/modm/ui/gui/types.hpp +++ b/src/modm/ui/gui/types.hpp @@ -34,6 +34,9 @@ namespace modm namespace gui { +/// @ingroup modm_ui_gui +/// @{ + // forward declare so that everything compiles. can this be done better? class View; class Widget; @@ -47,7 +50,6 @@ typedef void (*genericCallback)(void*); /** * Input event that is collected when some input happens. Will be processed by View * - * @ingroup gui * @author Daniel Krebs */ class InputEvent @@ -89,7 +91,6 @@ class InputEvent * is_expired() must be called repeatedly for the callback to get called. It is * garantueed that the callback will only be called once. * - * @ingroup gui * @author Daniel Krebs */ class AsyncEvent @@ -150,6 +151,8 @@ typedef struct Dimension typedef modm::glcd::Point Point; +/// @} + } // namespace gui } // namespace modm diff --git a/src/modm/ui/gui/view.hpp b/src/modm/ui/gui/view.hpp index a188dbb384..a161a47002 100644 --- a/src/modm/ui/gui/view.hpp +++ b/src/modm/ui/gui/view.hpp @@ -38,7 +38,7 @@ class GuiViewStack; /** * The View class is the base class for all screens handled by the ViewStack class * - * @ingroup gui + * @ingroup modm_ui_gui * @author Thorsten Lajewski */ class View : public modm::AbstractView diff --git a/src/modm/ui/gui/view_stack.hpp b/src/modm/ui/gui/view_stack.hpp index 323578d086..48b5e88390 100644 --- a/src/modm/ui/gui/view_stack.hpp +++ b/src/modm/ui/gui/view_stack.hpp @@ -38,7 +38,7 @@ namespace gui * This class also deallocates the views passed * to the stack. * - * @ingroup gui + * @ingroup modm_ui_gui * @author Thorsten Lajewski */ class GuiViewStack : public modm::ViewStack diff --git a/src/modm/ui/gui/widgets/button.hpp b/src/modm/ui/gui/widgets/button.hpp index 3dd9244a94..71e280242a 100644 --- a/src/modm/ui/gui/widgets/button.hpp +++ b/src/modm/ui/gui/widgets/button.hpp @@ -24,7 +24,7 @@ namespace gui { /** - * @ingroup gui + * @ingroup modm_ui_gui * @author Daniel Krebs */ class ButtonWidget : public Widget @@ -50,7 +50,7 @@ class ButtonWidget : public Widget }; /** - * @ingroup gui + * @ingroup modm_ui_gui * @author Daniel Krebs */ class ArrowButton : public Widget @@ -71,7 +71,7 @@ class ArrowButton : public Widget }; /** - * @ingroup gui + * @ingroup modm_ui_gui * @author Daniel Krebs */ class FilledAreaButton : public Widget diff --git a/src/modm/ui/gui/widgets/checkbox.hpp b/src/modm/ui/gui/widgets/checkbox.hpp index f97e12dcfa..6a02180c28 100644 --- a/src/modm/ui/gui/widgets/checkbox.hpp +++ b/src/modm/ui/gui/widgets/checkbox.hpp @@ -23,7 +23,7 @@ namespace gui { /** - * @ingroup gui + * @ingroup modm_ui_gui * @author Daniel Krebs */ class CheckboxWidget : public Widget diff --git a/src/modm/ui/gui/widgets/composed_widgets/stringrocker.hpp b/src/modm/ui/gui/widgets/composed_widgets/stringrocker.hpp index 6b4f282582..82e5047ac7 100644 --- a/src/modm/ui/gui/widgets/composed_widgets/stringrocker.hpp +++ b/src/modm/ui/gui/widgets/composed_widgets/stringrocker.hpp @@ -24,7 +24,7 @@ namespace gui { /** - * @ingroup gui + * @ingroup modm_ui_gui * @author Daniel Krebs */ class StringRocker : public WidgetGroup diff --git a/src/modm/ui/gui/widgets/composed_widgets/tab_panel.hpp b/src/modm/ui/gui/widgets/composed_widgets/tab_panel.hpp index e2c968504a..e02c5a87a3 100644 --- a/src/modm/ui/gui/widgets/composed_widgets/tab_panel.hpp +++ b/src/modm/ui/gui/widgets/composed_widgets/tab_panel.hpp @@ -24,7 +24,7 @@ namespace gui { /** - * @ingroup gui + * @ingroup modm_ui_gui * @author Daniel Krebs */ class TabPanel : public WidgetGroup diff --git a/src/modm/ui/gui/widgets/label.hpp b/src/modm/ui/gui/widgets/label.hpp index 7820bbc365..2329fb32f9 100644 --- a/src/modm/ui/gui/widgets/label.hpp +++ b/src/modm/ui/gui/widgets/label.hpp @@ -23,7 +23,7 @@ namespace gui { /** - * @ingroup gui + * @ingroup modm_ui_gui * @author Daniel Krebs */ class Label : public Widget diff --git a/src/modm/ui/gui/widgets/numberfield.hpp b/src/modm/ui/gui/widgets/numberfield.hpp index ef34575977..57a6d04535 100644 --- a/src/modm/ui/gui/widgets/numberfield.hpp +++ b/src/modm/ui/gui/widgets/numberfield.hpp @@ -23,7 +23,7 @@ namespace gui { /** - * @ingroup gui + * @ingroup modm_ui_gui * @author Daniel Krebs */ template @@ -58,9 +58,10 @@ class NumberField : public Widget T value; }; +/// @ingroup modm_ui_gui typedef NumberField IntegerField; - +/// @ingroup modm_ui_gui class FloatField : public NumberField { public: diff --git a/src/modm/ui/gui/widgets/numberrocker.hpp b/src/modm/ui/gui/widgets/numberrocker.hpp index ab26b20c02..0aaacd2acb 100644 --- a/src/modm/ui/gui/widgets/numberrocker.hpp +++ b/src/modm/ui/gui/widgets/numberrocker.hpp @@ -24,7 +24,7 @@ namespace gui { /** - * @ingroup gui + * @ingroup modm_ui_gui * @author Daniel Krebs */ template @@ -79,7 +79,9 @@ class NumberRocker : public WidgetGroup NumberField num_field; }; +/// @ingroup modm_ui_gui typedef NumberRocker IntegerRocker; +/// @ingroup modm_ui_gui typedef NumberRocker FloatRocker; diff --git a/src/modm/ui/gui/widgets/stringfield.hpp b/src/modm/ui/gui/widgets/stringfield.hpp index e8d98a4ea7..4b5f8baad8 100644 --- a/src/modm/ui/gui/widgets/stringfield.hpp +++ b/src/modm/ui/gui/widgets/stringfield.hpp @@ -24,7 +24,7 @@ namespace gui { /** - * @ingroup gui + * @ingroup modm_ui_gui * @author Daniel Krebs */ class StringField : public Widget diff --git a/src/modm/ui/gui/widgets/widget.hpp b/src/modm/ui/gui/widgets/widget.hpp index a5798b23b5..6dd68c4c56 100644 --- a/src/modm/ui/gui/widgets/widget.hpp +++ b/src/modm/ui/gui/widgets/widget.hpp @@ -35,7 +35,7 @@ static int16_t uid_global = 0; class View; /** - * @ingroup gui + * @ingroup modm_ui_gui * @author Daniel Krebs */ class Widget @@ -332,7 +332,7 @@ class Widget }; /** - * @ingroup gui + * @ingroup modm_ui_gui * @author Daniel Krebs */ class WidgetGroup : public Widget diff --git a/src/modm/ui/led.hpp b/src/modm/ui/led.hpp index 13d4885de2..699d2c4d11 100644 --- a/src/modm/ui/led.hpp +++ b/src/modm/ui/led.hpp @@ -12,13 +12,6 @@ */ // ---------------------------------------------------------------------------- -/** - * @defgroup led LED Indicators - * @brief Various classes for controlling the brightness of LEDs. - * - * @ingroup ui - */ - #include "led/tables.hpp" #include "led/led.hpp" #include "led/rgb.hpp" diff --git a/src/modm/ui/led/led.hpp b/src/modm/ui/led/led.hpp index b992c464dd..3982ced7bc 100644 --- a/src/modm/ui/led/led.hpp +++ b/src/modm/ui/led/led.hpp @@ -46,9 +46,9 @@ namespace ui * This is just a very, very thin wrapper around modm::ui::Animation. * If you need more advanced features, have a look there. * - * @see Animation + * @see modm_ui_animation * @author Niklas Hauser - * @ingroup led + * @ingroup modm_ui_led */ class Led { diff --git a/src/modm/ui/led/rgb.hpp b/src/modm/ui/led/rgb.hpp index 37d14e71ed..894c88c50b 100644 --- a/src/modm/ui/led/rgb.hpp +++ b/src/modm/ui/led/rgb.hpp @@ -31,7 +31,7 @@ namespace ui * @todo add RGB specific functions to this class. * * @author Niklas Hauser - * @ingroup led + * @ingroup modm_ui_led */ class RgbLed { diff --git a/src/modm/ui/led/tables.hpp.in b/src/modm/ui/led/tables.hpp.in index f4d614361f..fcac5af56f 100644 --- a/src/modm/ui/led/tables.hpp.in +++ b/src/modm/ui/led/tables.hpp.in @@ -24,6 +24,7 @@ namespace ui { %% for t in tables /// {{t.gamma / 10}} gamma correction with {{t.bit}}-bit resolution (0 to {{t.bit_range - 1}}) in {{t.range}} steps at {{t.size}} bytes. + /// @ingroup modm_ui_led extern modm::accessor::Flash<{{t.type}}> table{{t.gamma}}_{{t.bit}}_{{t.range}}; %% endfor diff --git a/src/modm/ui/menu.hpp b/src/modm/ui/menu.hpp index 6d060e4134..f3ff8e3b8d 100644 --- a/src/modm/ui/menu.hpp +++ b/src/modm/ui/menu.hpp @@ -11,28 +11,6 @@ */ // ---------------------------------------------------------------------------- -/** - * \defgroup display_menu Display Menu - * \ingroup ui - * - * \brief Simple to use classes for implementing menu structures - * on graphic displays. - * - * Some convenience classes for implementing menus. The menus are - * using a stack to allow stepping forward and backwards through the - * screens. - * The menus are based on the usage of five buttons. Inside most of the - * screens these buttons have the following functions: - * Left: Go back one screen. - * Right: Go to next screen. - * Up: Go to previous selected entry on screen - * Down: Go to next entry on screen - * OK: Edit selected entry - * - *\warning Some classes currently only work with the font - * modm::font::FixedWidth5x8 - */ - #ifndef MODM_MENU_HPP #define MODM_MENU_HPP diff --git a/src/modm/ui/menu/abstract_menu.hpp b/src/modm/ui/menu/abstract_menu.hpp index 977e25cfb3..e36c5741a2 100644 --- a/src/modm/ui/menu/abstract_menu.hpp +++ b/src/modm/ui/menu/abstract_menu.hpp @@ -28,7 +28,7 @@ namespace modm{ * of button presses. * * \author Thorsten Lajewski - * \ingroup display_menu + * \ingroup modm_ui_menu */ class AbstractMenu: public AbstractView { diff --git a/src/modm/ui/menu/abstract_view.hpp b/src/modm/ui/menu/abstract_view.hpp index 50158dc18e..d13cd81761 100644 --- a/src/modm/ui/menu/abstract_view.hpp +++ b/src/modm/ui/menu/abstract_view.hpp @@ -31,7 +31,7 @@ namespace modm * handled by the ViewStack class * *\author Thorsten Lajewski - *\ingroup display_menu + *\ingroup modm_ui_menu */ class AbstractView diff --git a/src/modm/ui/menu/choice_menu.hpp b/src/modm/ui/menu/choice_menu.hpp index b23978f55c..f63b8e4401 100644 --- a/src/modm/ui/menu/choice_menu.hpp +++ b/src/modm/ui/menu/choice_menu.hpp @@ -34,7 +34,7 @@ namespace modm{ * RIGHT - put next screen on stack * * \author Thorsten Lajewski - * \ingroup display_menu + * \ingroup modm_ui_menu * */ class ChoiceMenu: public AbstractMenu diff --git a/src/modm/ui/menu/choice_menu_entry.hpp b/src/modm/ui/menu/choice_menu_entry.hpp index 787b5cd9f0..3afe216885 100644 --- a/src/modm/ui/menu/choice_menu_entry.hpp +++ b/src/modm/ui/menu/choice_menu_entry.hpp @@ -22,6 +22,7 @@ namespace modm { + /// @ingroup modm_ui_menu class ChoiceMenuEntry { public: diff --git a/src/modm/ui/menu/communicating_view.hpp b/src/modm/ui/menu/communicating_view.hpp index 5cafb8257c..d41727b742 100644 --- a/src/modm/ui/menu/communicating_view.hpp +++ b/src/modm/ui/menu/communicating_view.hpp @@ -23,6 +23,7 @@ namespace modm { + /// @ingroup modm_ui_menu class CommunicatingView : public xpcc::Communicatable { public: diff --git a/src/modm/ui/menu/communicating_view_stack.hpp b/src/modm/ui/menu/communicating_view_stack.hpp index 445f3ccab5..a5ce74f93f 100644 --- a/src/modm/ui/menu/communicating_view_stack.hpp +++ b/src/modm/ui/menu/communicating_view_stack.hpp @@ -25,6 +25,7 @@ namespace modm { + /// @ingroup modm_ui_menu class CommunicatingViewStack : public ViewStack { public: diff --git a/src/modm/ui/menu/menu_buttons.hpp b/src/modm/ui/menu/menu_buttons.hpp index 706ff0e148..991dece01f 100644 --- a/src/modm/ui/menu/menu_buttons.hpp +++ b/src/modm/ui/menu/menu_buttons.hpp @@ -26,7 +26,7 @@ namespace modm * * \author Thorsten Lajewski * - * \ingroup display_menu + * \ingroup modm_ui_menu */ enum Button { diff --git a/src/modm/ui/menu/menu_entry_callback.hpp b/src/modm/ui/menu/menu_entry_callback.hpp index e8a0490a4b..e5592aa961 100644 --- a/src/modm/ui/menu/menu_entry_callback.hpp +++ b/src/modm/ui/menu/menu_entry_callback.hpp @@ -21,6 +21,7 @@ namespace modm { + /// @ingroup modm_ui_menu class MenuEntryCallback { public: diff --git a/src/modm/ui/menu/module.lb b/src/modm/ui/menu/module.lb index 2da612d8bc..8687c318ca 100644 --- a/src/modm/ui/menu/module.lb +++ b/src/modm/ui/menu/module.lb @@ -13,6 +13,27 @@ def init(module): module.parent = "ui" module.name = "menu" + module.description = """\ +# Display Menu + +Simple to use classes for implementing menu structures on graphic displays. + +Some convenience classes for implementing menus. The menus are +using a stack to allow stepping forward and backwards through the +screens. + +The menus are based on the usage of five buttons. Inside most of the +screens these buttons have the following functions: + +- Left: Go back one screen. +- Right: Go to next screen. +- Up: Go to previous selected entry on screen +- Down: Go to next entry on screen +- OK: Edit selected entry + +!!! warning + Some classes currently only work with the font `modm::font::FixedWidth5x8`! +""" def prepare(module, options): module.depends( diff --git a/src/modm/ui/menu/scrollable_text.hpp b/src/modm/ui/menu/scrollable_text.hpp index 02b2fd1762..e333ddfa55 100644 --- a/src/modm/ui/menu/scrollable_text.hpp +++ b/src/modm/ui/menu/scrollable_text.hpp @@ -26,7 +26,7 @@ namespace modm * available. * *\author Thorsten Lajewski - *\ingroup display_menu + *\ingroup modm_ui_menu *\warning This class only works in combination with modm::font::FixedWidth5x8 *\todo A better implementation is needed. */ diff --git a/src/modm/ui/menu/standard_menu.hpp b/src/modm/ui/menu/standard_menu.hpp index 7a5271bed0..8e22df0f68 100644 --- a/src/modm/ui/menu/standard_menu.hpp +++ b/src/modm/ui/menu/standard_menu.hpp @@ -31,7 +31,7 @@ namespace modm /** * \brief Menu Entry of Standard Menu * - * \ingroup display_menu + * \ingroup modm_ui_menu * \author Thorsten Lajewski */ struct MenuEntry @@ -57,7 +57,7 @@ namespace modm * Left - remove Standard Menu from stack * Right - select chosen entry. * - * \ingroup display_menu + * \ingroup modm_ui_menu * \author Thorsten Lajewski */ diff --git a/src/modm/ui/menu/view_stack.hpp b/src/modm/ui/menu/view_stack.hpp index f00ecb6570..0fda5776cd 100644 --- a/src/modm/ui/menu/view_stack.hpp +++ b/src/modm/ui/menu/view_stack.hpp @@ -32,7 +32,7 @@ namespace modm * This class also deallocates the views passed * to the stack. * - * \ingroup display_menu + * \ingroup modm_ui_menu * \author Thorsten Lajewski */ diff --git a/src/modm/ui/time/module.lb b/src/modm/ui/time/module.lb index 7764d64a44..888f59d4f2 100644 --- a/src/modm/ui/time/module.lb +++ b/src/modm/ui/time/module.lb @@ -13,6 +13,7 @@ def init(module): module.parent = "ui" module.name = "time" + module.description = "Date and Time" def prepare(module, options): module.depends(":architecture:accessor") diff --git a/src/modm/ui/time/time.hpp b/src/modm/ui/time/time.hpp index 05bfd07bb0..d29e52cfab 100644 --- a/src/modm/ui/time/time.hpp +++ b/src/modm/ui/time/time.hpp @@ -25,7 +25,7 @@ namespace modm * Number of Seconds since 00:00, Jan 1 1970 UTC * * @author Fabian Greif - * @ingroup ui + * @ingroup modm_ui_time */ class UnixTime { @@ -55,7 +55,7 @@ namespace modm * @brief Calender Date and Time * * @author Fabian Greif - * @ingroup ui + * @ingroup modm_ui_time */ class Date { diff --git a/src/modm/ui/ui.dox b/src/modm/ui/ui.dox deleted file mode 100644 index fd87f6f455..0000000000 --- a/src/modm/ui/ui.dox +++ /dev/null @@ -1,9 +0,0 @@ -// coding: utf-8 -// - -/** - * \defgroup ui User interface - * - * Interfacing with human users. - * Contains code for Graphics, Buttons, LEDs, Animations, Menu Structures. - */ diff --git a/src/modm/ui/ui.lb b/src/modm/ui/ui.lb index 8ba45dc4ac..da941f2302 100644 --- a/src/modm/ui/ui.lb +++ b/src/modm/ui/ui.lb @@ -13,10 +13,15 @@ def init(module): module.name = "ui" + module.description = """\ +# User interface + +Interfacing with human users. +Contains code for Graphics, Buttons, LEDs, Animations, Menu Structures. +""" def prepare(module, options): return True def build(env): - env.outbasepath = "modm/src/modm/ui" pass \ No newline at end of file diff --git a/src/modm/utils/algorithm.hpp b/src/modm/utils/algorithm.hpp index a51fe7b72b..571eefb92c 100644 --- a/src/modm/utils/algorithm.hpp +++ b/src/modm/utils/algorithm.hpp @@ -17,6 +17,7 @@ namespace modm { + /// @ingroup modm_utils template InputIterator find (InputIterator first, InputIterator last, const T& value) diff --git a/src/modm/utils/allocator.hpp b/src/modm/utils/allocator.hpp index d8eff90c5d..257a63eef9 100644 --- a/src/modm/utils/allocator.hpp +++ b/src/modm/utils/allocator.hpp @@ -21,11 +21,9 @@ namespace modm { /** - * \ingroup utils - * \defgroup allocator - * - * \brief Memory allocators - * + * \ingroup modm_utils + * \defgroup modm_utils_allocator Memory allocators + * * \author Fabian Greif */ namespace allocator diff --git a/src/modm/utils/allocator/allocator_base.hpp b/src/modm/utils/allocator/allocator_base.hpp index f7b43f1c96..4545038564 100644 --- a/src/modm/utils/allocator/allocator_base.hpp +++ b/src/modm/utils/allocator/allocator_base.hpp @@ -26,7 +26,7 @@ namespace modm * * \internal * - * \ingroup allocator + * \ingroup modm_utils_allocator * \author Fabian Greif */ template diff --git a/src/modm/utils/allocator/block.hpp b/src/modm/utils/allocator/block.hpp index 4437ce35b2..e9eee10f25 100644 --- a/src/modm/utils/allocator/block.hpp +++ b/src/modm/utils/allocator/block.hpp @@ -30,7 +30,7 @@ namespace modm * * This technique is known as "memory pool". * - * \ingroup allocator + * \ingroup modm_utils_allocator * \author Fabian Greif */ template diff --git a/src/modm/utils/allocator/static.hpp b/src/modm/utils/allocator/static.hpp index b2988abd02..3b805cc206 100644 --- a/src/modm/utils/allocator/static.hpp +++ b/src/modm/utils/allocator/static.hpp @@ -26,7 +26,7 @@ namespace modm * Allocates a big static block and distributes pieces of it during * run-time. No reallocation is done when no more pieces are available. * - * \ingroup allocator + * \ingroup modm_utils_allocator * \author Fabian Greif */ template * @author Fabian Greif * @author Niklas Hauser + * + * @{ */ // ------------------------------------------------------------------------ -/*\{*/ template struct ArithmeticTraits { @@ -294,7 +295,7 @@ struct ArithmeticTraits static constexpr double epsilon = __DBL_EPSILON__; }; -//// @} +/// @} } // namespace modm #endif // MODM_ARITHMETIC_TRAITS_HPP diff --git a/src/modm/utils/bit_constants.hpp b/src/modm/utils/bit_constants.hpp index 208458c830..dd6853d5a4 100644 --- a/src/modm/utils/bit_constants.hpp +++ b/src/modm/utils/bit_constants.hpp @@ -18,6 +18,9 @@ namespace modm { +/// @ingroup modm_utils +/// @{ + constexpr uint8_t Bit0 = (1ul << 0); constexpr uint8_t Bit1 = (1ul << 1); constexpr uint8_t Bit2 = (1ul << 2); @@ -51,6 +54,8 @@ constexpr uint32_t Bit29 = (1ul << 29); constexpr uint32_t Bit30 = (1ul << 30); constexpr uint32_t Bit31 = (1ul << 31); +/// @} + }; // namespace modm #endif // MODM_BIT_CONSTANTS_HPP diff --git a/src/modm/utils/dummy.hpp b/src/modm/utils/dummy.hpp index 745e6f5ca6..50828d99f8 100644 --- a/src/modm/utils/dummy.hpp +++ b/src/modm/utils/dummy.hpp @@ -18,8 +18,8 @@ namespace modm { /** - * \ingroup utils - * + * \ingroup modm_utils + * * Dummy function for default function pointers. */ void diff --git a/src/modm/utils/module.lb b/src/modm/utils/module.lb index 91baa0ab77..a7ed6726b4 100644 --- a/src/modm/utils/module.lb +++ b/src/modm/utils/module.lb @@ -13,6 +13,7 @@ def init(module): module.name = "utils" + module.description = "Utilities" def prepare(module, options): module.depends(":architecture") diff --git a/src/modm/utils/template_metaprogramming.hpp b/src/modm/utils/template_metaprogramming.hpp index 260f7d617d..af67d63d24 100644 --- a/src/modm/utils/template_metaprogramming.hpp +++ b/src/modm/utils/template_metaprogramming.hpp @@ -19,9 +19,9 @@ #include /** - * \ingroup utils - * \defgroup tmp Template Metaprogramming - * + * \ingroup modm_utils + * \defgroup modm_utils_tmp Template Metaprogramming + * * Helper classes for some basic template metaprogramming. Template * metaprogramming is a programming technique in which templates are used by a * compiler to generate temporary source code, which is merged by the compiler @@ -34,13 +34,13 @@ namespace modm { /** * \brief Template Metaprogramming - * \ingroup tmp + * \ingroup modm_utils_tmp */ namespace tmp { /** * \brief An empty type useful as a placeholder. - * \ingroup tmp + * \ingroup modm_utils_tmp */ class NullType { @@ -49,7 +49,7 @@ namespace modm // -------------------------------------------------------------------- /** * \brief Selects type Result = (flag == true) ? T : U - * \ingroup tmp + * \ingroup modm_utils_tmp */ template struct Select @@ -66,7 +66,7 @@ namespace modm // -------------------------------------------------------------------- /** * \brief SameType::value is true when T=U - * \ingroup tmp + * \ingroup modm_utils_tmp */ template struct SameType @@ -92,7 +92,7 @@ namespace modm * - \c Conversion::existsBothWays is \c true if \c U is also convertible to \c T * - \c Conversion::isSameType is \c true if \c U is \c T * - * \ingroup tmp + * \ingroup modm_utils_tmp */ template class Conversion @@ -170,7 +170,7 @@ namespace modm * \c SuperSubclass::value is \c true when \c U is derived * from \c T, or when \c U is \c T. * - * \ingroup tmp + * \ingroup modm_utils_tmp */ template struct SuperSubclass @@ -221,7 +221,7 @@ namespace modm * * \c SuperSubclassStrict::value is \c true when \c U is derived from \c T * - * \ingroup tmp + * \ingroup modm_utils_tmp */ template struct SuperSubclassStrict @@ -263,7 +263,7 @@ namespace modm * FloatingPointTraits::max(); * \endcode * - * \ingroup tmp + * \ingroup modm_utils_tmp */ template struct EnableIfCondition @@ -280,7 +280,7 @@ namespace modm }; /** - * \ingroup tmp + * \ingroup modm_utils_tmp */ template struct EnableIf : public EnableIfCondition< Conditional::value, T > @@ -311,7 +311,7 @@ namespace modm * Inspired by the BOOST_STATIC_ASSERT macro. * * \see http://www.boost.org/doc/libs/1_43_0/doc/html/boost_staticassert.html - * \ingroup tmp + * \ingroup modm_utils_tmp * \deprecated Use static_assert(bool_constexpr, string) (since C++11) instead. */ #ifdef __DOXYGEN__ diff --git a/src/modm/utils/utils.hpp b/src/modm/utils/utils.hpp index 649f3ae00e..b8e0139af4 100644 --- a/src/modm/utils/utils.hpp +++ b/src/modm/utils/utils.hpp @@ -12,12 +12,6 @@ */ // ---------------------------------------------------------------------------- -/** - * \defgroup utils Utilities - * \brief Some Utilities - * - */ - #include #include "utils/algorithm.hpp" diff --git a/src/unittest/controller.hpp b/src/unittest/controller.hpp index 5f2ea7f6cc..827bb197ad 100644 --- a/src/unittest/controller.hpp +++ b/src/unittest/controller.hpp @@ -22,14 +22,14 @@ namespace unittest { /** - * \brief %Controller singleton + * \brief Controller singleton * * Used to forward information from the test suites to the reporters. * All macros form 'harness.hpp' use this class to determine the * active reporter. * * \author Fabian Greif - * \ingroup unittest + * \ingroup modm_unittest */ class Controller { diff --git a/src/unittest/harness.cpp b/src/unittest/harness.cpp index 834dbd5b2a..f8a1f0064f 100644 --- a/src/unittest/harness.cpp +++ b/src/unittest/harness.cpp @@ -14,6 +14,8 @@ #include "harness.hpp" +#define TEST_FLOAT_EPSILON 0.00001f + namespace unittest { FLASH_STORAGE_STRING(stringEqual) = " == "; @@ -38,7 +40,7 @@ unittest::checkExpression(bool expr, unsigned int line) bool unittest::checkEqual(const float& a, const float& b, unsigned int line) { - if (((a + TEST_FLOAT_EPISLON) >= b) and ((a - TEST_FLOAT_EPISLON) <= b)) + if (((a + TEST_FLOAT_EPSILON) >= b) and ((a - TEST_FLOAT_EPSILON) <= b)) { TEST_REPORTER_.reportPass(); return true; diff --git a/src/unittest/harness.hpp b/src/unittest/harness.hpp index b6e7f8a11a..dd1eae9675 100644 --- a/src/unittest/harness.hpp +++ b/src/unittest/harness.hpp @@ -18,71 +18,10 @@ #include "controller.hpp" -#define TEST_FLOAT_EPISLON 0.00001f - -#ifdef __DOXYGEN__ - -/** - * \brief Verify (expr) is true - * - * \ingroup unittest - */ -#define TEST_ASSERT_TRUE(expr) - -/** - * \brief Verify (expr) is false - * - * \ingroup unittest - */ -#define TEST_ASSERT_FALSE(expr) - -/** - * \brief Verify (x==y) - * - * Shortcut with extended output message for `TEST_ASSERT_TRUE(x == y);` - * - * \ingroup unittest - */ -#define TEST_ASSERT_EQUALS(x, y) - -/** - * \brief Verify (x==y) for floating point values - * \ingroup unittest - */ -#define TEST_ASSERT_EQUALS_FLOAT(x, y) - -/** - * \brief Verify (x==y) up to d - * - * This macro verifies two values are equal up to a delta - * - * \ingroup unittest - */ -#define TEST_ASSERT_EQUALS_DELTA(x, y, d) - -/** - * \brief Verify (lower <= value <= upper) - * \ingroup unittest - */ -#define TEST_ASSERT_EQUALS_RANGE(value, lower, upper) - -/** - * \brief Check if the arrays contains the same data - * - * start is optional (default = 0). - * - * \ingroup unittest - */ -#define TEST_ASSERT_EQUALS_ARRAY(array1, array2, count, start) - -/** - * \brief Fail unconditionally - * \ingroup unittest - */ -#define TEST_FAIL(msg) - -#else // !__DOXYGEN__ +/// @ingroup modm_unittest +/// @{ +/// @cond #include namespace unittest @@ -245,40 +184,56 @@ namespace unittest return true; } } +/// @endcond +/// Verify (expr) is true #define TEST_ASSERT_TRUE(expr) \ TEST_RETURN_(::unittest::checkExpression((expr), __LINE__)) +/// Verify (expr) is false #define TEST_ASSERT_FALSE(expr) \ TEST_RETURN_(::unittest::checkExpression(!static_cast(expr), __LINE__)) +/// Verify (x == y) #define TEST_ASSERT_EQUALS(x, y) \ TEST_RETURN_(::unittest::checkEqual((x), (y), __LINE__)) +/// Verify (x != y) #define TEST_ASSERT_DIFFERS(x, y) \ TEST_RETURN_(::unittest::checkDiffer((x), (y), __LINE__)) +/// Verify (x == y) for floating point values #define TEST_ASSERT_EQUALS_FLOAT(x, y) \ TEST_RETURN_(::unittest::checkEqual(static_cast(x), static_cast(y), __LINE__)) +/// Verify (x == y) up to delta d #define TEST_ASSERT_EQUALS_DELTA(x, y, d) \ TEST_RETURN_(::unittest::checkEqualDelta((x), (y), (d), __LINE__)) +/// Verify (lower <= value <= upper) #define TEST_ASSERT_EQUALS_RANGE(value, lower, upper) \ TEST_RETURN_(::unittest::checkRange((value), (lower), (upper), __LINE__)) +/// Verify two strings as equal #define TEST_ASSERT_EQUALS_STRING(x, y) \ TEST_RETURN_(::unittest::checkString((x), (y), __LINE__)) +#ifdef __DOXYGEN__ +/// Verify two arrays as equal +/// start is optional (default = 0). +#define TEST_ASSERT_EQUALS_ARRAY(x, y, count, start=0) +#else #define TEST_ASSERT_EQUALS_ARRAY(x, y, ...) \ TEST_RETURN_(::unittest::checkArray((x), (y), __LINE__, __VA_ARGS__)) +#endif +/// Fail unconditionally #define TEST_FAIL(msg) \ do { TEST_REPORTER_.reportFailure(__LINE__) \ << msg << '\n'; \ } while (0); \ TEST_RETURN_((void) false) -#endif // __DOXYGEN__ +/// @} #endif // UNITTEST_HARNESS_HPP diff --git a/src/unittest/module.lb b/src/unittest/module.lb index 22fa4f1c18..6cde0336e4 100644 --- a/src/unittest/module.lb +++ b/src/unittest/module.lb @@ -14,6 +14,11 @@ def init(module): module.name = "unittest" + module.description = """\ +# Unit Tests + +Lightweight library for on-device unit testing. +""" def prepare(module, options): diff --git a/src/unittest/reporter.hpp b/src/unittest/reporter.hpp index fed55c85cc..7c1d628f31 100644 --- a/src/unittest/reporter.hpp +++ b/src/unittest/reporter.hpp @@ -24,12 +24,12 @@ namespace unittest { /** - * \brief %Reporter + * \brief Reporter * * Used to generate the visible output. * * \author Fabian Greif - * \ingroup unittest + * \ingroup modm_unittest */ class Reporter { diff --git a/src/unittest/testsuite.hpp b/src/unittest/testsuite.hpp index abb465e2a2..c99a21c7ce 100644 --- a/src/unittest/testsuite.hpp +++ b/src/unittest/testsuite.hpp @@ -22,7 +22,7 @@ namespace unittest * \brief Base class for every test suite * * \author Fabian Greif - * \ingroup unittest + * \ingroup modm_unittest */ class TestSuite { diff --git a/src/unittest/type/count_type.hpp b/src/unittest/type/count_type.hpp index 81bc5e2532..3205370293 100644 --- a/src/unittest/type/count_type.hpp +++ b/src/unittest/type/count_type.hpp @@ -23,7 +23,7 @@ namespace unittest /** * \brief Data type to count the number of constructor etc. calls * - * \ingroup unittest + * \ingroup modm_unittest */ class CountType { diff --git a/src/unittest/unittest.hpp b/src/unittest/unittest.hpp index 8fd1aef19b..e3f4ab25ec 100644 --- a/src/unittest/unittest.hpp +++ b/src/unittest/unittest.hpp @@ -11,12 +11,6 @@ */ // ---------------------------------------------------------------------------- -/** - * \defgroup unittest Unit tests - * \brief Perform a unit test - * - */ - #include "unittest/testsuite.hpp" #include "unittest/harness.hpp" #include "unittest/controller.hpp" diff --git a/test/module.lb b/test/module.lb index b13bdaa2fa..a5515b8e69 100644 --- a/test/module.lb +++ b/test/module.lb @@ -13,6 +13,7 @@ def init(module): module.name = "test" + module.description = "Tests for modm" def prepare(module, options): diff --git a/tools/build_script_generator/scons/site_tools/bitmap.py b/tools/build_script_generator/scons/site_tools/bitmap.py index b07a9b99c8..e4264470e3 100644 --- a/tools/build_script_generator/scons/site_tools/bitmap.py +++ b/tools/build_script_generator/scons/site_tools/bitmap.py @@ -52,7 +52,7 @@ * - Width : ${width} * - Height : ${height} * - * \\ingroup image + * \\ingroup modm_ui_display_image */ EXTERN_FLASH_STORAGE(uint8_t ${name}[]); } diff --git a/tools/doc_generator/doxyfile.cfg b/tools/doc_generator/doxyfile.cfg.in similarity index 51% rename from tools/doc_generator/doxyfile.cfg rename to tools/doc_generator/doxyfile.cfg.in index 2d6d188f7d..1d847090d8 100644 --- a/tools/doc_generator/doxyfile.cfg +++ b/tools/doc_generator/doxyfile.cfg.in @@ -1,23 +1,32 @@ PROJECT_NAME = modm -INPUT = ../src/ +INPUT = dox/ \ + ../src/ STRIP_FROM_INC_PATH = ../src/ RECURSIVE = YES FILE_PATTERNS = *.hpp \ *.h \ *.dox -QUIET = YES +EXCLUDE_PATTERNS = *_impl.hpp +INPUT += README.md +USE_MDFILE_AS_MAINPAGE = README.md + + +QUIET = {{ "YES" if xml else "NO" }} WARN_LOGFILE = doxygen_warnings.txt -GENERATE_HTML = NO +GENERATE_HTML = YES GENERATE_LATEX = NO GENERATE_MAN = NO GENERATE_RTF = NO CASE_SENSE_NAMES = NO -GENERATE_XML = YES +GENERATE_XML = {{ "YES" if xml else "NO" }} XML_PROGRAMLISTING = NO +INLINE_SIMPLE_STRUCTS = YES BRIEF_MEMBER_DESC = NO -EXTRACT_ALL = NO +EXTRACT_ALL = YES +SHOW_FILES = YES +SHOW_USED_FILES = NO MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = YES @@ -25,10 +34,11 @@ PREDEFINED = __DOXYGEN__ \ __cplusplus \ "EXTERN_FLASH_STORAGE(x):=const x" \ modm_always_inline=inline \ - "MODM_FLAGS8(x):=typedef modm::Flags8< x > x ## _t" \ - "MODM_FLAGS16(x):=typedef modm::Flags16< x > x ## _t" \ - "MODM_FLAGS32(x):=typedef modm::Flags32< x > x ## _t" \ + "MODM_FLAGS8(x):=using x ## _t = modm::Flags8< x >" \ + "MODM_FLAGS16(x):=using x ## _t = modm::Flags16< x >" \ + "MODM_FLAGS32(x):=using x ## _t = modm::Flags32< x >" \ MODM_TYPE_FLAGS(x)= \ MODM_INT_TYPE_FLAGS(x)= \ __attribute__(x)= \ - modm_packed= + modm_packed= \ + modm_extern_c="extern \"C\"" diff --git a/tools/doc_generator/group.dox.in b/tools/doc_generator/group.dox.in new file mode 100644 index 0000000000..097ccd5a91 --- /dev/null +++ b/tools/doc_generator/group.dox.in @@ -0,0 +1,10 @@ +/** + +%% if module.pref != "modm" +@ingroup {{ module.pref }} +%% endif +@defgroup {{ module.ref }} {{ module.title if module.title else module.name }} + +{{ module.description | doxify }} + + */ \ No newline at end of file diff --git a/tools/doc_generator/module.lb b/tools/doc_generator/module.lb index 270deff4f6..ff882192e2 100644 --- a/tools/doc_generator/module.lb +++ b/tools/doc_generator/module.lb @@ -18,10 +18,6 @@ import json import fnmatch import traceback import subprocess -try: - import graphviz as gv -except: - pass from lxml import etree from pathlib import Path @@ -101,32 +97,35 @@ class RObject: return self.signature +def _name(name, replace): + new_name = "" + for c in name: + if c.isalpha() or c.isnumeric(): + new_name += c + else: + new_name += replace + return new_name + def url_name(name): - return name.replace(":", "-").replace(".", "-") + return _name(name, "-") def ref_name(name): - return name.replace(":", "_").replace(".", "_") + return _name(name, "_") def node_name(name): return name.replace(":", ":\n") +def doxify(content): + content = re.sub(r"```(.+)\n", r"~~~{.\1}\n", content) + content = re.sub(r"```", "~~~", content) + content = re.sub(r"!!! *", "@", content) + return content + def split_description(descr): - try: - descr = descr.read() - except: - pass - description = [] - title = None - for line in descr.splitlines(): - if title is None and line.startswith("#"): - title = line.replace("#", "").strip() - continue - description.append(line) - if len(description) == 1: - title = description[0] - description = [] - return title, "\n".join(description) + lines = str(descr).strip(" \n").splitlines() + [""] + title = lines[0].replace("#", "").strip() + return title, "\n".join(lines[1:]).strip(" \n") def extract(text, key): return re.search(r"# {0}\n(.*?)\n# /{0}".format(key), text, flags=re.DOTALL | re.MULTILINE).group(1) @@ -137,6 +136,7 @@ def replace(text, key, content): # ----------------------------------------------------------------------------- def init(module): module.name = "docs" + module.description = FileReader("module.md") def prepare(module, options): module.add_option(BooleanOption(name="generate_module_docs", @@ -146,25 +146,26 @@ def prepare(module, options): def build(env): env.outbasepath = "modm/docs" - env.copy("doxyfile.cfg") + env.substitutions = {"xml": env["generate_module_docs"]} + env.template("doxyfile.cfg.in") + env.copy(repopath("README.md"), "README.md") def post_build(env, buildlog): - if not env["generate_module_docs"]: - return - lbuild_plain = lbuild.format.plain lbuild.format.plain = True + # FIXME: Get me a proper API for this omodules = list(env._env.modules._node.root.all_modules()) omodules.sort(key=lambda m: m.fullname) modules = [] - env.log.info("Build dependency graph") + env.log.debug("Parsing module documentation...") for m in omodules: title, descr = split_description(m._description) mprops = {"name": m.fullname, "title": title, "description": descr, - "ref": url_name(m.fullname), + "pref": ref_name(m.parent.fullname), + "ref": ref_name(m.fullname), "dependencies": sorted([d.fullname for d in m.dependencies]), "options": []} for o in m.options: @@ -184,6 +185,24 @@ def post_build(env, buildlog): m["dependents"].append(d["name"]) m["dependents"].sort() + env.log.debug("Generating doxygen group documentation...") + env.outbasepath = "modm/docs/dox" + for m in modules: + env.substitutions = {"module": m} + env.template("group.dox.in", "{}.dox".format(url_name(m["name"])), filters={"doxify": doxify}) + + + + + + + # INTERNAL DOCUMENTATION GENERATOR + if not env["generate_module_docs"]: + return + + env.log.debug("Building module dependency graph...") + import graphviz as gv + for m in modules: graph = gv.Digraph(name=m["name"], format="svg", graph_attr={"rankdir": "BT"}, @@ -199,9 +218,8 @@ def post_build(env, buildlog): m["graph"] = graph.pipe().decode("utf-8") - # Run doxygen - env.log.info("Build doxygen") - build_dir = Path(os.path.abspath(buildlog.get_operations_per_module("modm:docs")[0].filename_out)).parent + build_dir = Path(env.outpath("modm/docs", basepath=".")) + env.log.info("Running doxygen may take a minute or two...") subprocess.check_call("doxygen doxyfile.cfg", cwd=build_dir, shell=True) env.log.info("Parse doxygen") @@ -226,6 +244,7 @@ def post_build(env, buildlog): doxobjs[location].append(member) + env.outbasepath = "modm/docs" modtable = [] for m in modules: env.log.info("Render {}".format(m["name"])) diff --git a/tools/doc_generator/module.md b/tools/doc_generator/module.md new file mode 100644 index 0000000000..f48ad1a3ac --- /dev/null +++ b/tools/doc_generator/module.md @@ -0,0 +1,2 @@ +# Documentation Generator + diff --git a/tools/font_creator/font_export.py b/tools/font_creator/font_export.py index 64f367876b..eae072dc32 100755 --- a/tools/font_creator/font_export.py +++ b/tools/font_creator/font_export.py @@ -88,7 +88,7 @@ * - number of chars : ${count} * - size in bytes : ${size} * - * \\ingroup font + * \\ingroup modm_ui_display_font */ EXTERN_FLASH_STORAGE(uint8_t ${array_name}[]); } diff --git a/tools/xpcc_generator/module.lb b/tools/xpcc_generator/module.lb index 2141dd706f..11d5a7fef1 100644 --- a/tools/xpcc_generator/module.lb +++ b/tools/xpcc_generator/module.lb @@ -13,6 +13,7 @@ def init(module): module.parent = "communication:xpcc" module.name = "generator" + module.description = "XPCC Generator" def prepare(module, options): module.add_option(