From 5b191ab6cdf92106f6190955cc2d279c39e1992c Mon Sep 17 00:00:00 2001 From: Brendan Le Foll Date: Fri, 30 May 2014 17:10:52 +0100 Subject: [PATCH] api: add proper doxygen comments to C++ headers and normalise doc Signed-off-by: Brendan Le Foll --- api/aio.h | 36 +++++------ api/aio.hpp | 32 +++++++--- api/gpio.h | 136 ++++++++++++++++++++--------------------- api/gpio.hpp | 103 +++++++++++++++++++++++++------ api/i2c.h | 88 ++++++++++++++------------- api/i2c.hpp | 66 ++++++++++++++++++-- api/maa.h | 17 ++++-- api/pwm.h | 141 ++++++++++++++++++++++--------------------- api/pwm.hpp | 85 ++++++++++++++++++++++++-- api/spi.h | 68 ++++++++++----------- api/spi.hpp | 70 ++++++++++++++++++--- examples/c++/AioA0.cpp | 2 + examples/c++/Blink-IO.cpp | 9 +-- examples/c++/I2c-compass.cpp | 3 +- examples/c++/Pwm3-cycle.cpp | 5 +- examples/c++/Spi-pot.cpp | 6 +- 16 files changed, 569 insertions(+), 298 deletions(-) diff --git a/api/aio.h b/api/aio.h index 4513e24..9cd55f6 100644 --- a/api/aio.h +++ b/api/aio.h @@ -23,8 +23,8 @@ */ #pragma once -/** @file - * +/** + * @file * @brief Analog input/output * * AIO is the anlog input & output interface to libmaa. It is used to read or @@ -53,33 +53,27 @@ extern "C" { */ typedef struct _aio* maa_aio_context; -/** Initialise an Analog input device, connected to the specified pin - * - * @param aio_channel channel number to read ADC inputs +/** + * Initialise an Analog input device, connected to the specified pin * - * @returns pointer to maa_aio_context structure after initialisation of Analog - * input pin successfully, else returns null. + * @param pin Channel number to read ADC inputs + * @returns aio context or NULL */ -maa_aio_context maa_aio_init(unsigned int aio_channel); +maa_aio_context maa_aio_init(unsigned int pin); -/** Read the input voltage, represented as an unsigned short in the range [0x0, - * 0xFFFF] - * - * @param dev - pointer to maa_aio_context structure initialised by - * maa_aio_init() +/** + * Read the input voltage * - * @returns 16-bit unsigned integer representing the current input voltage, - * normalised to a 16-bit value + * @param dev The AIO context + * @returns The current input voltage, normalised to a 16-bit value */ uint16_t maa_aio_read(maa_aio_context dev); -/** Close the analog input context - * - Will free the memory for the context. - * - * @param dev - pointer to maa_aio_context structure initialised by - * maa_aio_init() +/** + * Close the analog input context, this will free the memory for the context * - * @return maa_result_t - result type. + * @param dev The AIO context + * @return Result of operation */ maa_result_t maa_aio_close(maa_aio_context dev); diff --git a/api/aio.hpp b/api/aio.hpp index f882b6c..dd145d7 100644 --- a/api/aio.hpp +++ b/api/aio.hpp @@ -24,27 +24,43 @@ #pragma once -/** @file - * - * This file defines the aio C++ interface for libmaa - * - */ - #include "aio.h" namespace maa { +/** + * @brief C++ API to Analog IO + * + * This file defines the aio C++ interface for libmaa + * + * @snippet examples/c++/AioA0.cpp Interesting + */ class Aio { public: + /** + * Aio Constructor, takes a pin number which will map directly to the + * board number + * + * @param pin channel number to read ADC inputs + */ Aio(unsigned int pin) { m_aio = maa_aio_init(pin); } + /** + * Aio destructor + */ ~Aio() { maa_aio_close(m_aio); } + /** + * Read a value from the AIO pin. Note this value can never be outside + * of the bounds of an unsigned short + * + * @returns The current input voltage, normalised to a 16-bit value + */ int read() { - // Use basic types to make swig code generation simpler - return (int) maa_aio_read(m_aio); + // Use basic types to make swig code generation simpler + return (int) maa_aio_read(m_aio); } private: maa_aio_context m_aio; diff --git a/api/gpio.h b/api/gpio.h index d3ced85..bc99981 100644 --- a/api/gpio.h +++ b/api/gpio.h @@ -24,15 +24,15 @@ #pragma once -/** @file - * +/** + * @file * @brief General Purpose IO * - * GPIO is the General Purpose IO interface to libmaa. It's features depends on + * Gpio is the General Purpose IO interface to libmaa. It's features depends on * the board type used, it can use gpiolibs (exported via a kernel module * through sysfs), or memory mapped IO via a /dev/uio device or /dev/mem * depending again on the board configuratio, or memory mapped IO via a - * /dev/uio device or /dev/mem depending again on the board configuration. + * /dev/uio device or /dev/mem depending again on the board configuration * * @snippet gpio_read6.c Interesting */ @@ -49,9 +49,6 @@ extern "C" { #include #include "maa.h" -/** - * A strucutre representing a gpio pin. - */ /** * Opaque pointer definition to the internal struct _gpio @@ -59,7 +56,7 @@ extern "C" { typedef struct _gpio* maa_gpio_context; /** - * GPIO Output modes + * Gpio Output modes */ typedef enum { MAA_GPIO_STRONG = 0, /**< Default. Strong high and low */ @@ -69,124 +66,127 @@ typedef enum { } gpio_mode_t; /** - * GPIO Direction options. + * Gpio Direction options */ typedef enum { MAA_GPIO_OUT = 0, /**< Output. A Mode can also be set */ - MAA_GPIO_IN = 1 /**< Input. */ + MAA_GPIO_IN = 1 /**< Input */ } gpio_dir_t; +/** + * Gpio Edge types for interupts + */ typedef enum { - MAA_GPIO_EDGE_NONE = 0, /**< No interrupt on GPIO */ + MAA_GPIO_EDGE_NONE = 0, /**< No interrupt on Gpio */ MAA_GPIO_EDGE_BOTH = 1, /**< Interupt on rising & falling */ MAA_GPIO_EDGE_RISING = 2, /**< Interupt on rising only */ MAA_GPIO_EDGE_FALLING = 3 /**< Interupt on falling only */ } gpio_edge_t; -/** Initialise gpio_context, based on board number - * - * @param pin pin number read from the board, i.e IO3 is 3. +/** + * Initialise gpio_context, based on board number * - * @returns maa_gpio_context based on the IO pin + * @param pin Pin number read from the board, i.e IO3 is 3 + * @returns gpio context or NULL */ maa_gpio_context maa_gpio_init(int pin); -/** Initialise gpio context without any mapping to a pin. - * - For more expert users +/** + * Initialise gpio context without any mapping to a pin * * @param gpiopin gpio pin as listed in SYSFS - * - * @return gpio context + * @return gpio context or NULL */ maa_gpio_context maa_gpio_init_raw(int gpiopin); -/** Set the edge mode on the gpio +/** + * Set the edge mode on the gpio * - * @param dev The GPIO context + * @param dev The Gpio context * @param mode The edge mode to set the gpio into - * - * @return maa result type. + * @return Result of operation */ maa_result_t maa_gpio_edge_mode(maa_gpio_context dev, gpio_edge_t mode); -/** Set an interupt on pin +/** + * Set an interupt on pin * - * @param dev The GPIO context - * @param mode The edge mode to set the gpio into + * @param dev The Gpio context + * @param edge The edge mode to set the gpio into * @param fptr Function pointer to function to be called when interupt is * triggered - * - * @return maa result type. + * @return Result of operation */ -maa_result_t -maa_gpio_isr(maa_gpio_context dev, gpio_edge_t edge, void (*fptr)(void)); +maa_result_t maa_gpio_isr(maa_gpio_context dev, gpio_edge_t edge, void (*fptr)(void)); -/** Stop the current interupt watcher on this GPIO, and set the GPIO edge mode - * to MAA_GPIO_EDGE_NONE. - * - * @param dev The GPIO context. +/** + * Stop the current interupt watcher on this Gpio, and set the Gpio edge mode + * to MAA_GPIO_EDGE_NONE * - * @return maa result type. + * @param dev The Gpio context + * @return Result of operation */ -maa_result_t -maa_gpio_isr_exit(maa_gpio_context dev); +maa_result_t maa_gpio_isr_exit(maa_gpio_context dev); -/** Set GPIO Output Mode, - * - * @param dev The GPIO context - * @param mode The GPIO Output Mode. +/** + * Set Gpio Output Mode, * - * @return maa result type. + * @param dev The Gpio context + * @param mode The Gpio Output Mode + * @return Result of operation */ maa_result_t maa_gpio_mode(maa_gpio_context dev, gpio_mode_t mode); -/** Set GPIO direction - * - * @param dev The GPIO context. - * @param dir The direction of the GPIO. +/** + * Set Gpio direction * - * @return maa result type. + * @param dev The Gpio context + * @param dir The direction of the Gpio + * @return Result of operation */ maa_result_t maa_gpio_dir(maa_gpio_context dev, gpio_dir_t dir); -/** Close the GPIO context - * - Will free the memory for the context and unexport the GPIO - * - * @param dev the GPIO context +/** + * Close the Gpio context + * - Will free the memory for the context and unexport the Gpio * - * @return maa result type. + * @param dev The Gpio context + * @return Result of operation */ maa_result_t maa_gpio_close(maa_gpio_context dev); -/** Read the GPIO value. - * - * @param dev The GPIO context. +/** + * Read the Gpio value. * - * @return the integer value of the GPIO + * @param dev The Gpio context + * @return Result of operation */ int maa_gpio_read(maa_gpio_context dev); -/** Write to the GPIO Value. - * - * @param dev The GPIO context. - * @param value Integer value to write. +/** + * Write to the Gpio Value. * - * @return maa result type + * @param dev The Gpio context + * @param value Integer value to write + * @return Result of operation */ maa_result_t maa_gpio_write(maa_gpio_context dev, int value); -/** Change ownership of the context. +/** + * Change ownership of the context. * - * @param dev gpio context - * @param owner does this context own the pin. + * @param dev The Gpio context + * @param owner Does this context own the pin + * @return Result of operation */ maa_result_t maa_gpio_owner(maa_gpio_context dev, maa_boolean_t owner); -/** Enable using memory mapped io instead of sysfs +/** + * Enable using memory mapped io instead of sysfs * - * @param dev gpio context - * @param mmap use mmap instead of sysfs - * @return maa_result type + * @param dev The Gpio context + * @param mmap Use mmap instead of sysfs + * @return Result of operation */ maa_result_t maa_gpio_use_mmaped(maa_gpio_context dev, maa_boolean_t mmap); diff --git a/api/gpio.hpp b/api/gpio.hpp index 8d156b8..1ba84c5 100644 --- a/api/gpio.hpp +++ b/api/gpio.hpp @@ -24,38 +24,61 @@ #pragma once -/** @file - * - * This file defines the gpio C++ interface for libmaa - * - */ - #include "gpio.h" namespace maa { // These enums must match the enums in gpio.h + +/** + * Gpio Output modes + */ typedef enum { - MODE_STRONG = 0, - MODE_PULLUP = 1, - MODE_PULLDOWN = 2, - MODE_HIZ = 3 + MODE_STRONG = 0, /**< No interrupt on Gpio */ + MODE_PULLUP = 1, /**< Interupt on rising & falling */ + MODE_PULLDOWN = 2, /**< Interupt on rising only */ + MODE_HIZ = 3 /**< Interupt on falling only */ } Mode; +/** + * Gpio Direction options + */ typedef enum { - DIR_OUT = 0, - DIR_IN = 1 + DIR_OUT = 0, /**< Output. A Mode can also be set */ + DIR_IN = 1 /**< Input */ } Dir; +/** + * Gpio Edge types for interupts + */ typedef enum { - EDGE_NONE = 0, - EDGE_BOTH = 1, - EDGE_RISING = 2, - EDGE_FALLING = 3 + EDGE_NONE = 0, /**< No interrupt on Gpio */ + EDGE_BOTH = 1, /**< Interupt on rising & falling */ + EDGE_RISING = 2, /**< Interupt on rising only */ + EDGE_FALLING = 3 /**< Interupt on falling only */ } Edge; +/** + * @brief C++ API to General Purpose IO + * + * This file defines the gpio C++ interface for libmaa + * + * @snippet Blink-IO.cpp Interesting + */ class Gpio { public: + /** + * Instanciates a Gpio object + * + * @param pin pin number to use + * @param owner (optional) Set pin owner, default behaviour is to 'own' + * the pin if we exported it. This means we will close it on destruct. + * Otherwise it will get left open. This is only valid in sysfs use + * cases + * @param raw (optional) Raw pins will use gpiolibs pin numbering from + * the kernel module. Note that you will not get any muxers set up for + * you so this may not always work as expected. + */ Gpio(int pin, bool owner=true, bool raw=false) { if (raw) m_gpio = maa_gpio_init_raw(pin); @@ -64,9 +87,19 @@ class Gpio { if (!owner) maa_gpio_owner(m_gpio, 0); } + /** + * Gpio object destructor, this will only unexport the gpio if we where + * the owner + */ ~Gpio() { - maa_result_t x = maa_gpio_close(m_gpio); + maa_gpio_close(m_gpio); } + /** + * Set the edge mode for ISR + * + * @param mode The edge mode to set + * @return Result of operation + */ maa_result_t edge(Edge mode) { return maa_gpio_edge_mode(m_gpio, (gpio_edge_t) mode); } @@ -75,23 +108,57 @@ class Gpio { return maa_gpio_isr(m_gpio, (gpio_edge_t) mode, (void (*) ()) pyfunc); } #else + /** + * Sets a callback to be called when pin value changes + * + * @return Result of operation + */ maa_result_t isr(Edge mode, void (*fptr)(void)) { return maa_gpio_isr(m_gpio, (gpio_edge_t) mode, fptr); } #endif + /** + * Exits callback - this call will not kill the isr thread imediatlu + * but only when it is out of it's critical section + * + * @return Result of operation + */ maa_result_t isr_exit() { return maa_gpio_isr_exit(m_gpio); } + /** + * Change Gpio mode + * + * @param mode The mode to change the gpio into + * @return Result of operation + */ maa_result_t mode(Mode mode) { return maa_gpio_mode(m_gpio, (gpio_mode_t) mode); } + /** + * Change Gpio direction + * + * @param dir The direction to change the gpio into + * @return Result of operation + */ maa_result_t dir(Dir dir) { return maa_gpio_dir(m_gpio, (gpio_dir_t) dir); } + /** + * Read value from Gpio + * + * @return Gpio value + */ int read() { return maa_gpio_read(m_gpio); } - int write(int value) { + /** + * Write value to Gpio + * + * @param value Value to write to Gpio + * @return Result of operation + */ + maa_result_t write(int value) { return maa_gpio_write(m_gpio, value); } private: diff --git a/api/i2c.h b/api/i2c.h index 86c9f2f..214737f 100644 --- a/api/i2c.h +++ b/api/i2c.h @@ -24,8 +24,8 @@ #pragma once -/** @file - * +/** + * @file * @brief Inter-Integrated Circuit * * This file defines the i2c/Iic interface for libmaa. A context represents a @@ -54,82 +54,84 @@ extern "C" { */ typedef struct _i2c* maa_i2c_context; -/** Initialise i2c context, using board defintions +/** + * Initialise i2c context, using board defintions * * @param bus i2c bus to use - * @return maa_i2c_context i2c context ready for other calls. + * @return i2c context or NULL */ maa_i2c_context maa_i2c_init(int bus); -/** Initialise i2c context, passing in spi bus to use. +/** + * Initialise i2c context, passing in spi bus to use. * * @param bus The i2c bus to use i.e. /dev/i2c-2 would be "2" - * @return maa_i2c_context i2c context ready for other calls. + * @return i2c context or NULL */ maa_i2c_context maa_i2c_init_raw(unsigned int bus); -/** Sets the frequency of the i2c context - * - * @param dev the i2c context - * @param hz The bus frequency in hertz +/** + * Sets the frequency of the i2c context * - * @return maa_result_t the maa result. + * @param dev The i2c context + * @param hz The bus frequency in hertz + * @return Result of operation */ maa_result_t maa_i2c_frequency(maa_i2c_context dev, int hz); -/** Read from an i2c context - * - * @param dev the i2c context - * @param data pointer to the byte array to read data in to - * @param length max number of bytes to read +/** + * Read from an i2c context * - * @return maa_result_t the maa result. + * @param dev The i2c context + * @param data pointer to the byte array to read data in to + * @param length max number of bytes to read + * @return Result of operation */ maa_result_t maa_i2c_read(maa_i2c_context dev, uint8_t *data, int length); -/** Read a single byte from the i2c context - * - * @param dev the i2c context +/** + * Read a single byte from the i2c context * - * @return byte the result of the read or -1 if failed. + * @param dev The i2c context + * @return The result of the read or -1 if failed */ uint8_t maa_i2c_read_byte(maa_i2c_context dev); -/** Write to an i2c context - * - * @param dev the i2c context - * @param data pointer to the byte array to be written - * @param length the number of bytes to transmit +/** + * Write to an i2c context * - * @return maa_result_t the maa result. + * @param dev The i2c context + * @param data pointer to the byte array to be written + * @param length the number of bytes to transmit + * @return Result of operation */ maa_result_t maa_i2c_write(maa_i2c_context dev, const uint8_t *data, int length); -/** Write a single byte to an i2c context - * - * @param dev the i2c context - * @data the byte to write +/** + * Write a single byte to an i2c context * - * @return maa_result_t the maa result. + * @param dev The i2c context + * @param data The byte to write + * @return Result of operation */ maa_result_t maa_i2c_write_byte(maa_i2c_context dev, const uint8_t data); -/** Sets the i2c context address. - * - * @param dev the i2c context - * @param address The address to set for the slave (ignoring the least - * signifcant bit). If set to 0, the slave will only respond to the - * general call address. +/** + * Sets the i2c context address. * - * @return maa_result_t the maa result. + * @param dev The i2c context + * @param address The address to set for the slave (ignoring the least + * signifcant bit). If set to 0, the slave will only respond to the + * general call address. + * @return Result of operation */ maa_result_t maa_i2c_address(maa_i2c_context dev, int address); -/** De-inits an maa_i2c_context device - * - * @param dev the i2c context +/** + * De-inits an maa_i2c_context device * - * @return maa_result_t the maa result. + * @param dev The i2c context + * @return Result of operation */ maa_result_t maa_i2c_stop(maa_i2c_context dev); diff --git a/api/i2c.hpp b/api/i2c.hpp index 4d5f794..eb480aa 100644 --- a/api/i2c.hpp +++ b/api/i2c.hpp @@ -24,42 +24,96 @@ #pragma once -/** @file - * - * This file defines the i2c C++ interface for libmaa - * - */ - #include "i2c.h" namespace maa { +/** + * @brief C++ API to Inter-Integrated Circuit + * + * This file defines the I2c C++ interface for libmaa + * + * @snippet I2c-compass.cpp Interesting + */ class I2c { public: + /** + * Instantiates an i2c bus. Multiple instances of the same bus can + * exist and the bus is not guarranteed to be on the correct address + * before read/write. + * + * @param bus The i2c bus to use + * @param raw Whether to disable pinmapper for your board + */ I2c(int bus, bool raw=false) { if (raw) m_i2c = maa_i2c_init_raw(bus); else m_i2c = maa_i2c_init(bus); } + /** + * Closes the I2c Bus used. This does not guarrantee the bus will not + * be usable by anyone else or communicates this disconnect to any + * slaves. + */ ~I2c() { maa_i2c_stop(m_i2c); } + /** + * Sets the i2c Frequency for communication. Your board may not support + * the set frequency. Anyone can change this at any time and this will + * affect every slave on the bus + * + * @param hz Frequency to set the bus to in hz + * @return Result of operation + */ maa_result_t frequency(int hz) { return maa_i2c_frequency(m_i2c, hz); } + /** + * Set the slave to talk to, typically called before every read/write + * operation + * + * @param address Communicate to the i2c slave on this address + * @return Result of operation + */ maa_result_t address(int address) { return maa_i2c_address(m_i2c, address); } + /** + * Read exactly one byte from the bus + * + * @return Char read from the bus + */ unsigned char read_byte() { return (unsigned char) maa_i2c_read_byte(m_i2c); } + /** + * Read mutliple bytes from the bus + * + * @param data Buffer to write into + * @param length Size of read + * @return Result of operation + */ maa_result_t read(unsigned char * data, int length) { return maa_i2c_read(m_i2c, data, length); } + /** + * Write one byte to the bus + * + * @param data Buffer to send on the bus + * @param length Size of buffer to send + * @return Result of operation + */ maa_result_t write(const unsigned char* data, int length) { return maa_i2c_write(m_i2c, data, length); } + /** + * Write multiple bytes to the bus + * + * @param data The byte to send on the bus + * @return Result of operation + */ maa_result_t write_byte(const unsigned char data) { return maa_i2c_write_byte(m_i2c, data); } diff --git a/api/maa.h b/api/maa.h index 0c83c3b..63f7b53 100644 --- a/api/maa.h +++ b/api/maa.h @@ -27,7 +27,6 @@ /** @file * * This file defines the basic shared values for libmaa - * */ #ifdef __cplusplus @@ -96,6 +95,7 @@ typedef struct { /*@{*/ unsigned int pin; /**< Raw GPIO pin id */ unsigned int value; /**< Raw GPIO value */ + /*@}*/ } maa_mux_t; /** @@ -179,10 +179,12 @@ typedef struct { /*@}*/ } maa_board_t; -/** Initialise MAA +/** + * Initialise MAA * * Detects running platform and attempts to use included pinmap - * @return maa_result_t maa result + * + * @return Result of operation */ #ifndef SWIG // this sets a compiler attribute (supported by GCC & clang) to have maa_init() @@ -197,17 +199,20 @@ maa_result_t maa_init(); * * The version returned may not be what is expected however it is a reliable * number associated with the git tag closest to that version at build time + * * @return version string from version.h */ const char* maa_get_version(); -/** Print a textual representation of the maa_result_t +/** + * Print a textual representation of the maa_result_t * - * @param result the result to print, + * @param result the result to print */ void maa_result_print(maa_result_t result); -/** Checks if a pin is able to use the passed in mode. +/** + * Checks if a pin is able to use the passed in mode. * * @param pin Physical Pin to be checked. * @param mode the mode to be tested. diff --git a/api/pwm.h b/api/pwm.h index fce45c8..c4f0a2f 100644 --- a/api/pwm.h +++ b/api/pwm.h @@ -24,8 +24,8 @@ #pragma once -/** @file - * +/** + * @file * @brief Pulse Width Modulation module * * PWM is the Pulse Width Modulation interface to libmaa. It allows the @@ -47,121 +47,124 @@ extern "C" { typedef struct _pwm* maa_pwm_context; -/** Initialise pwm_context, uses board mapping. - * - * @param pin The PWM PIN. +/** + * Initialise pwm_context, uses board mapping * - * @return maa_pwm_context The returned initialised pwm context + * @param pin The PWM PIN + * @return pwm context or NULL */ maa_pwm_context maa_pwm_init(int pin); -/** Initialise pwm_context, raw mode. +/** + * Initialise pwm_context, raw mode * * @param chipid The chip inwhich the PWM is under in SYSFS * @param pin The PWM PIN. - * - * @return maa_pwm_context The returned initialised pwm context + * @return pwm context or NULL */ maa_pwm_context maa_pwm_init_raw(int chipid, int pin); -/** Set the ouput duty-cycle percentage, as a float +/** + * Set the ouput duty-cycle percentage, as a float * - * @param pwm The PWM context to use. + * @param dev The Pwm context to use * @param percentage A floating-point value representing percentage of output. * The value should lie between 0.0f (representing on 0%) and 1.0f - * Values above or below this range will be set at either 0.0f or 1.0f. - * - * @return maa_result_t the maa result. + * Values above or below this range will be set at either 0.0f or 1.0f + * @return Result of operation */ -maa_result_t maa_pwm_write(maa_pwm_context pwm, float percentage); +maa_result_t maa_pwm_write(maa_pwm_context dev, float percentage); -/** Read the ouput duty-cycle percentage, as a float +/** + * Read the ouput duty-cycle percentage, as a float * - * @param pwm The PWM context to use. + * @param dev The Pwm context to use * @return percentage A floating-point value representing percentage of output. * The value should lie between 0.0f (representing on 0%) and 1.0f - * Values above or below this range will be set at either 0.0f or 1.0f. + * Values above or below this range will be set at either 0.0f or 1.0f */ -float maa_pwm_read(maa_pwm_context pwm); +float maa_pwm_read(maa_pwm_context dev); -/** Set the PWM period as seconds represented in a float - * - * @param pwm The PWM context to use. - * @param seconds Peroid represented as a float in seconds. +/** + * Set the PWM period as seconds represented in a float * - * @return maa_result_t the maa result. + * @param dev The Pwm context to use + * @param seconds Period represented as a float in seconds + * @return Result of operation */ -maa_result_t maa_pwm_period(maa_pwm_context pwm, float seconds); +maa_result_t maa_pwm_period(maa_pwm_context dev, float seconds); -/** Set period, milli-oseconds. - * - * @param pwm The PWM context to use. - * @param ms milli-seconds for period. +/** + * Set period, milliseconds. * - * @return maa_result_t the maa result. + * @param dev The Pwm context to use + * @param ms Milliseconds for period + * @return Result of operation */ -maa_result_t maa_pwm_period_ms(maa_pwm_context pwm, int ms); +maa_result_t maa_pwm_period_ms(maa_pwm_context dev, int ms); -/** Set period, microseconds +/** + * Set period, microseconds * - * @param pwm The PWM context to use. - * @param ns microseconds as period. - * - * @return maa_result_t the maa result. + * @param dev The Pwm context to use + * @param us Microseconds as period + * @return Result of operation */ -maa_result_t maa_pwm_period_us(maa_pwm_context pwm, int us); +maa_result_t maa_pwm_period_us(maa_pwm_context dev, int us); -/** Set pulsewidth, As represnted by seconds in a (float). +/** + * Set pulsewidth, As represnted by seconds in a (float) * - * @param pwm The PWM context to use. + * @param dev The Pwm context to use * @param seconds The duration of a pulse - * - * @return maa_result_t the maa result. + * @return Result of operation */ -maa_result_t maa_pwm_pulsewidth(maa_pwm_context pwm, float seconds); +maa_result_t maa_pwm_pulsewidth(maa_pwm_context dev, float seconds); -/** Set pulsewidth, milliseconds - * - * @param pwm The PWM context to use. - * @param ms milliseconds for pulsewidth. +/** + * Set pulsewidth, milliseconds * - * @return maa_result_t the maa result. + * @param dev The Pwm context to use + * @param ms Milliseconds for pulsewidth + * @return Result of operation */ -maa_result_t maa_pwm_pulsewidth_ms(maa_pwm_context pwm, int ms); +maa_result_t maa_pwm_pulsewidth_ms(maa_pwm_context dev, int ms); -/** Set pulsewidth, microseconds. +/** + * Set pulsewidth, microseconds * - * @param pwm The PWM context to use. - * @param us microseconds for pulsewidth. - * - * @return maa_result_t the maa result. + * @param dev The Pwm context to use + * @param us Microseconds for pulsewidth + * @return Result of operation */ -maa_result_t maa_pwm_pulsewidth_us(maa_pwm_context pwm, int us); +maa_result_t maa_pwm_pulsewidth_us(maa_pwm_context dev, int us); -/** Set the enable status of the PWM pin. None zero will assume on with output being driven. +/** + * Set the enable status of the PWM pin. None zero will assume on with output being driven. * and 0 will disable the output. * - * @param pwm The PWM context to use. - * @param enable enable status of pin - * - * @return maa_result_t the maa result. + * @param dev The pwm context to use + * @param enable Toggle status of pin + * @return Result of operation. */ -maa_result_t maa_pwm_enable(maa_pwm_context pwm, int enable); +maa_result_t maa_pwm_enable(maa_pwm_context dev, int enable); -/** Change ownership of context +/** + * Change ownership of context * - * @param pwm the context - * @param owner ownership , 1 to own + * @param dev the context + * @param owner Ownership boolean + * @return Result of operation */ -maa_result_t maa_pwm_owner(maa_pwm_context pwm, maa_boolean_t owner); +maa_result_t maa_pwm_owner(maa_pwm_context dev, maa_boolean_t owner); -/** Close and unexport the PWM pin. - * - * @param pwm The PWM context to use. +/** + * Close and unexport the PWM pin * - * @return maa_result_t the maa result. + * @param dev The pwm context to use + * @return Result of operation */ -maa_result_t maa_pwm_close(maa_pwm_context pwm); +maa_result_t maa_pwm_close(maa_pwm_context dev); #ifdef __cplusplus } diff --git a/api/pwm.hpp b/api/pwm.hpp index 2481b63..a897841 100644 --- a/api/pwm.hpp +++ b/api/pwm.hpp @@ -24,18 +24,28 @@ #pragma once -/** @file - * - * This file defines the pwm C++ interface for libmaa - * - */ - #include "pwm.h" namespace maa { +/** + * @brief C++ API to Pulse Width Modulation + * + * This file defines the PWM C++ interface for libmaa + * + * @snippet Pwm3-cycle.cpp Interesting + */ class Pwm { public: + /** + * instanciates a PWM object on a pin + * + * @param pin the pin number used on your board + * @param chipid the pwmchip to use, use only in raw mode + * @param owner if you are the owner of the pin the destructor will + * unexport the pin from sysfs, default behaviour is you are the owner + * if the pinmapper exported it + */ Pwm(int pin, int chipid=-1, bool owner = true) { if (chipid == -1) m_pwm = maa_pwm_init(pin); @@ -44,33 +54,96 @@ class Pwm { if (!owner) maa_pwm_owner(m_pwm, 0); } + /** + * Pwm destructor + */ ~Pwm() { maa_pwm_close(m_pwm); } + /** + * Set the output duty-cycle percentage, as a float + * + * @param percentage A floating-point value representing percentage of + * output. The value should lie between 0.0f (representing on 0%) and + * 1.0f Values above or below this range will be set at either 0.0f or + * 1.0f + * @return Result of operation + */ maa_result_t write(float percentage) { return maa_pwm_write(m_pwm, percentage); } + /** + * Read the ouput duty-cycle percentage, as a float + * + * @return A floating-point value representing percentage of + * output. The value should lie between 0.0f (representing on 0%) and + * 1.0f Values above or below this range will be set at either 0.0f or + * 1.0f + */ float read() { return maa_pwm_read(m_pwm); } + /** + * Set the PWM period as seconds represented in a float + * + * @param period Period represented as a float in seconds + * @return Result of operation + */ maa_result_t period(float period) { return maa_pwm_period(m_pwm, period); } + /** + * Set period, milliseconds + * + * @param ms milliseconds for period + * @return Result of operation + */ maa_result_t period_ms(int ms) { return maa_pwm_period_ms(m_pwm, ms); } + /** + * Set period, microseconds + * + * @param us microseconds as period + * @return Result of operation + */ maa_result_t period_us(int us) { return maa_pwm_period_us(m_pwm, us); } + /** + * Set pulsewidth, As represnted by seconds in a (float) + * + * @param seconds The duration of a pulse + * @return Result of operation + */ maa_result_t pulsewidth(float seconds) { return maa_pwm_pulsewidth(m_pwm, seconds); } + /** + * Set pulsewidth, milliseconds + * + * @param ms milliseconds for pulsewidth + * @return Result of operation + */ maa_result_t pulsewidth_ms(int ms) { return maa_pwm_pulsewidth_ms(m_pwm, ms); } + /** + * The pulsewidth, microseconds + * + * @param us microseconds for pulsewidth + * @return Result of operation + */ maa_result_t pulsewidth_us(int us) { return maa_pwm_pulsewidth_us(m_pwm, us); } + /** + * Set the enable status of the PWM pin. None zero will assume on with + * output being driven and 0 will disable the output + * + * @param enable enable status of pin + * @return Result of operation + */ maa_result_t enable(bool enable) { if (enable) return maa_pwm_enable(m_pwm, 1); diff --git a/api/spi.h b/api/spi.h index a1d7bea..84a3c80 100644 --- a/api/spi.h +++ b/api/spi.h @@ -24,8 +24,8 @@ #pragma once -/** @file - * +/** + * @file * @brief System Packet Interface * * This file defines the spi interface for libmaa @@ -43,78 +43,76 @@ extern "C" { #include "maa.h" +/** + * Opaque pointer definition to the internal struct _spi + */ typedef struct _spi* maa_spi_context; -/** Initialise SPI_context, uses board mapping. Sets the muxes +/** + * Initialise SPI_context, uses board mapping. Sets the muxes * - * @param bus to use, as listed in platform definition. Normally 0 - * @return maa_spi_context The returned initialised SPI context + * @param bus Bus to use, as listed in platform definition, normally 0 + * @return Spi context or NULL */ maa_spi_context maa_spi_init(int bus); -/** Set the SPI device mode. see spidev - * 0-3. - * @param spi the spi device context - * @param mode the mode. See Linux spidev +/** + * Set the SPI device mode. see spidev 0-3. * - * @return maa_spi_context The returned initialised SPI context + * @param dev The Spi context + * @param mode The SPI mode, See Linux spidev + * @return Spi context or NULL */ maa_result_t maa_spi_mode(maa_spi_context dev,unsigned short mode); /** Set the SPI device operating clock frequency. * - * @param spi the spid device clock frequency + * @param dev the Spi context * @param hz the frequency in hz - * * @return maa_spi_context The returned initialised SPI context */ maa_result_t maa_spi_frequency(maa_spi_context dev, int hz); /** Write Single Byte to the SPI device. * - * @param spi the spid device clock frequency - * @param data to send - * - * @return data received on the miso line. + * @param dev The Spi context + * @param data Data to send + * @return Data received on the miso line */ uint8_t maa_spi_write(maa_spi_context dev, uint8_t data); /** Write Buffer of bytes to the SPI device. * - * @param spi the spid device clock frequency + * @param dev The Spi context * @param data to send * @param length elements within buffer, Max 4096 - * - * @return data received on the miso line. Same length as passed in. + * @return Data received on the miso line, same length as passed in */ uint8_t* maa_spi_write_buf(maa_spi_context dev, uint8_t* data, int length); /** + * Change the SPI lsb mode * - * @param dev spi context - * @param lsb. Use least significant bit transmission. 0 for msbi - * - * @return maa result of operation + * @param dev The Spi context + * @param lsb Use least significant bit transmission. 0 for msbi + * @return Result of operation */ -maa_result_t -maa_spi_lsbmode(maa_spi_context dev, maa_boolean_t lsb); +maa_result_t maa_spi_lsbmode(maa_spi_context dev, maa_boolean_t lsb); -/** Set bits per mode on transaction - * Defaults at 8. +/** + * Set bits per mode on transaction, defaults at 8 * - * @param dev spi context + * @param dev The Spi context * @param bits bits per word - * * @return Result of operation */ -maa_result_t -maa_spi_bit_per_word(maa_spi_context dev, unsigned int bits); +maa_result_t maa_spi_bit_per_word(maa_spi_context dev, unsigned int bits); -/** De-inits an maa_spi_context device - * - * @param dev the spi context +/** + * De-inits an maa_spi_context device * - * @return maa_result_t the maa result. + * @param dev The Spi context + * @return Result of operation */ maa_result_t maa_spi_stop(maa_spi_context dev); diff --git a/api/spi.hpp b/api/spi.hpp index b5e01b3..a2cc9e9 100644 --- a/api/spi.hpp +++ b/api/spi.hpp @@ -24,37 +24,89 @@ #pragma once -/** @file - * - * This file defines the spi C++ interface for libmaa - */ - #include "spi.h" namespace maa { +/** + * @brief C++ API to System Packet Interface + * + * This file defines the SPI C++ interface for libmaa + * + * @snippet Spi-pot.cpp Interesting + */ class Spi { public: + /** + * Initialise SPI object using the board mapping to set muxes + * + * @param bus to use, as listed in the platform definition, normally 0 + */ Spi(int bus) { m_spi = maa_spi_init(bus); } + /** + * Closes spi bus + */ ~Spi() { maa_spi_stop(m_spi); } + /** + * Set the SPI device mode. see spidev0-3 + * + * @param mode the mode. See Linux spidev doc + * @return Result of operation + */ maa_result_t mode(unsigned short mode) { return maa_spi_mode(m_spi, mode); } + /** + * Set the SPI device operating clock frequency + * + * @param hz the frequency to set in hz + * @return Result of operation + */ maa_result_t frequency(int hz) { return maa_spi_frequency(m_spi, hz); } + /** + * Write single byte to the SPI device + * + * @param data the byte to send + * @return data received on the miso line + */ unsigned char write(uint8_t data) { return (unsigned char) maa_spi_write(m_spi, data); } + /** + * Write buffer of bytes to SPI device + * + * @param data buffer to send + * @param length size of buffer to send + * @return char* data received on the miso line. Same length as passed in + */ unsigned char* write_buf(uint8_t* data, int length) { return (unsigned char*) maa_spi_write_buf(m_spi, data, length); } - private: - maa_spi_context m_spi; -}; - + /** + * Change the SPI lsb mode + * + * @param lsb Use least significant bit transmission - 0 for msbi + * @return Result of operation + */ + maa_result_t lsbmode(bool lsb) { + return maa_spi_lsbmode(m_spi, (maa_boolean_t) lsb); + } + /** + * Set bits per mode on transaction, default is 8 + * + * @param bits bits per word + * @return Result of operation + */ + maa_result_t bit_per_word(unsigned int bits) { + return maa_spi_bit_per_word(m_spi, bits); + } + private: + maa_spi_context m_spi; + }; } diff --git a/examples/c++/AioA0.cpp b/examples/c++/AioA0.cpp index 2a809d3..cfa3af6 100644 --- a/examples/c++/AioA0.cpp +++ b/examples/c++/AioA0.cpp @@ -22,6 +22,7 @@ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +//! [Interesting] #include "aio.hpp" int main () @@ -41,3 +42,4 @@ int main () return MAA_SUCCESS; } +//! [Interesting] diff --git a/examples/c++/Blink-IO.cpp b/examples/c++/Blink-IO.cpp index c06ea6d..c39af75 100644 --- a/examples/c++/Blink-IO.cpp +++ b/examples/c++/Blink-IO.cpp @@ -30,7 +30,6 @@ #include #include "gpio.hpp" - #define DEFAULT_IOPIN 8 static int iopin; @@ -44,7 +43,6 @@ sig_handler(int signo) running = -1; } } - int main (int argc, char **argv) { if (argc < 2) { @@ -53,6 +51,10 @@ int main (int argc, char **argv) } else { iopin = strtol(argv[1], NULL, 10); } + + signal(SIGINT, sig_handler); + +//! [Interesting] maa::Gpio* gpio = new maa::Gpio(iopin); if (gpio == NULL) { return MAA_ERROR_UNSPECIFIED; @@ -61,8 +63,6 @@ int main (int argc, char **argv) if (response != MAA_SUCCESS) maa_result_print((maa_result_t) MAA_SUCCESS); - signal(SIGINT, sig_handler); - while (running == 0) { response = gpio->write(1); sleep(1); @@ -71,4 +71,5 @@ int main (int argc, char **argv) } delete gpio; return response; +//! [Interesting] } diff --git a/examples/c++/I2c-compass.cpp b/examples/c++/I2c-compass.cpp index 4dcb587..d30c518 100644 --- a/examples/c++/I2c-compass.cpp +++ b/examples/c++/I2c-compass.cpp @@ -93,6 +93,7 @@ sig_handler(int signo) int main () { +//! [Interesting] maa::I2c* i2c; i2c = new maa::I2c(0); float direction = 0; @@ -103,7 +104,7 @@ int main () rx_tx_buf[0] = HMC5883L_CONF_REG_B; rx_tx_buf[1] = GA_1_3_REG; i2c->write(rx_tx_buf, 2); - +//! [Interesting] signal(SIGINT, sig_handler); while (running == 0) { diff --git a/examples/c++/Pwm3-cycle.cpp b/examples/c++/Pwm3-cycle.cpp index ea2bfa2..af8f497 100644 --- a/examples/c++/Pwm3-cycle.cpp +++ b/examples/c++/Pwm3-cycle.cpp @@ -40,6 +40,8 @@ sig_handler(int signo) int main () { + signal(SIGINT, sig_handler); +//! [Interesting] maa::Pwm* pwm; pwm = new maa::Pwm(3); @@ -48,8 +50,6 @@ int main () } fprintf(stdout, "Cycling PWM on IO3 (pwm3) \n"); - signal(SIGINT, sig_handler); - float value = 0.0f; while (running == 0) { value = value + 0.01f; @@ -60,6 +60,7 @@ int main () } } delete pwm; +//! [Interesting] return MAA_SUCCESS; } diff --git a/examples/c++/Spi-pot.cpp b/examples/c++/Spi-pot.cpp index 52084ee..57a1264 100644 --- a/examples/c++/Spi-pot.cpp +++ b/examples/c++/Spi-pot.cpp @@ -41,12 +41,13 @@ sig_handler(int signo) int main () { + signal(SIGINT, sig_handler); + +//! [Interesting] maa::Spi* spi; spi = new maa::Spi(0); - signal(SIGINT, sig_handler); - uint8_t data[] = {0x00, 100}; uint8_t *recv; while (running == 0) { @@ -68,6 +69,7 @@ int main () } delete spi; +//! [Interesting] return MAA_SUCCESS; } -- 2.7.4