Revision 9:b6218dc218ad, committed 2014-08-11

Comitter:

dan_ackme

Date:

Mon Aug 11 21:25:37 2014 -0700

Parent:

8:1fad4ca6c6a4

Child:

10:735194df0097

Commit message:

started adding docs

Changed in this revision

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.h	Mon Aug 11 21:25:37 2014 -0700
@@ -0,0 +1,181 @@
+/**
+ * @mainpage WiConnect Library Overview
+ *
+ * @section Overview
+ * The WiConnect Library runs on a host MCU and controls a
+ * WiConnect enabled WiFi module. This library is essentially a
+ * programming API for the WiConnect serial command set. More infomation
+ * about the serial command set may be found here:
+ * <a href="http://wiconnect.ack.me" target="_blank">WiConnect Reference Guide</a>
+ *
+ * @section notes Important Notes
+ * - This class is implemented as a 'singleton'. This means it only needs to be
+ *   instantiated once.
+ * - The WiConnect library does NOT call the global 'new' or 'malloc' functions.
+ *   All memory allocation (if required) comes from a user supplied malloc function pointer or buffer
+ *
+ *
+ * @section features Library Settings
+ * The WiConnect Library has multiple settings so as to allow
+ * for the most flexibility within a user's application.
+ *
+ * Some of these configurations are as follows:
+ * - Blocking / Non-blocking
+ * - Dynamic / Static allocation
+ * - Asynchronous Processing
+ *
+ *
+ * @subsection setting_blocking_modes Blocking / Non-blocking Modes
+ * The WiConnect Library may be configured for either 'blocking' or
+ * 'non-blocking' operation:
+ * - blocking - API calls do not return until they complete successfully or timeout.
+ * - non-blocking - API calls return immediately. The caller should check the return code to see
+ *                  if the command is still processing, completed, or an error occurred. The caller
+ *                  should continue to call the API function (as often as possible) until it returns
+ *                  either a success or error code.
+ *
+ * @subsubsection setting_blocking_mode Blocking Mode
+ * In blocking mode, an API function will block until it completes.
+ * TODO: more details here
+ *
+ * @subsubsection setting_nonblocking_mode Non-Blocking Mode
+ * In non-blocking mode, an API function returns immediately.
+ * TODO: more details here
+ *
+ *
+ *
+ * @subsection setting_alloc Dynamic / Static Allocation
+ * There are two cases when memory allocation is required:
+ * - Buffer allocation
+ * - Class instantiation
+ *
+ * In both cases, either static or dynamic memory allocation may be used.
+ *
+ * In cases when memory allocation is needed, the API call requires a buffer pointer
+ * and length parameters. If both are supplied, the library uses the supplied external buffer.
+ * This is considered static allocation (however the buffer could have been dynamically allocated).
+ * The caller is responsible for maintaining the supplied buffer.
+ *
+ * If, however, only the buffer length is supplied and the buffer pointer is NULL
+ * the Wiconnect Library will call the user supplied malloc() function. This is considered
+ * dynamic allocation. In this case, the library will maintain the buffer and release it
+ * when necessary using the user supplied free() function.
+ *
+ * @note To use dynamic allocation the WiConnect Library must be compiled with
+ * @ref WICONNECT_ENABLE_MALLOC defined, and the Wiconnect() constructor must be
+ * supplied with pointers to malloc() and free() functions.
+ *
+ * @note The Wiconnect Library does NOT call the global 'new' operator. Classes that are
+ *       internally instantiated overload the 'new' operator and either call the user
+ *       supplied malloc() function or use the supplied static buffer.
+ *
+ *
+ * @subsection setting_async_processing Asynchronous Processing
+ * When applicable, the WiConnect Library will asynchronously process
+ * commands in the background. When the background processing completes, the
+ * supplied callback is called.
+ *
+ * User commands may also be executed in the background using the enqueueCommand()
+ * API function.
+ *
+ * @note The WiConnect Library must be compiled with @ref WICONNECT_ASYNC_TIMER_ENABLED
+ *       defined for background processing to be enabled.
+ *
+ *
+ *
+ * @section send_command_desc Sending Commands To WiFi Module
+ * TODO: add detailed description here
+ *
+ *
+ */
+
+
+/**
+ * @defgroup api_core Core API
+ * @brief   This contains all core API Library methods
+ *
+ * @{
+ */
+
+/**
+ * @defgroup api_core_settings Settings
+ * @brief    API getters/setters for core library settings
+ */
+
+/**
+ * @defgroup api_core_send_command Send Command
+ * @brief    API methods for sending commands to WiConnect WiFi module
+ */
+
+/**
+ * @defgroup api_core_misc Miscellaneous
+ * @brief    Other core API methods
+ */
+
+// @}
+
+
+
+/**
+ * @defgroup api_network Network API
+ * @brief   This contains all network API Library methods
+ *
+ * @{
+ */
+
+/**
+ * @defgroup api_network_settings Settings
+ * @brief    API getters/setters for module network settings
+ */
+
+/**
+ * @defgroup api_network_wlan WLAN
+ * @brief    API methods for joining/leaving a WLAN
+ */
+
+/**
+ * @defgroup api_network_setup Web Setup
+ * @brief    API methods for enabled/disabling module web setup
+ */
+
+/**
+ * @defgroup api_network_util Utilities
+ * @brief    Network utility API methods
+ */
+
+// @}
+
+
+/**
+ * @defgroup api_socket Socket API
+ * @brief   This contains all socket API Library methods
+ *
+ * @{
+ */
+
+/**
+ * @defgroup api_socket_tcp TCP
+ * @brief    TCP API methods
+ */
+
+/**
+ * @defgroup api_socket_udp UDP
+ * @brief    UDP API methods
+ */
+
+/**
+ * @defgroup api_socket_tls TLS
+ * @brief    TLS API methods
+ */
+
+/**
+ * @defgroup api_socket_http HTTP
+ * @brief    HTTP API methods
+ */
+
+/**
+ * @defgroup api_socket_misc Miscellaneous
+ * @brief    Miscellaneous socket API methods
+ */
+
+// @}

--- a/Wiconnect.h	Mon Aug 11 16:30:38 2014 -0700
+++ b/Wiconnect.h	Mon Aug 11 21:25:37 2014 -0700
@@ -10,8 +10,6 @@
 
 #pragma once
 
-
-
 #include "WiconnectInterface.h"
 
 

--- a/WiconnectInterface.h	Mon Aug 11 16:30:38 2014 -0700
+++ b/WiconnectInterface.h	Mon Aug 11 21:25:37 2014 -0700
@@ -29,6 +29,7 @@
 
 
 #ifdef WICONNECT_ENABLE_MALLOC
+/// These are optional arguments for host specific malloc/free
 #define WICONNECT_MALLOC_ARGS , void* (*malloc_)(size_t) = WICONNECT_DEFAULT_MALLOC, void (*free_)(void*) = WICONNECT_DEFAULT_FREE
 #else
 #define WICONNECT_MALLOC_ARGS
@@ -38,65 +39,401 @@
 namespace wiconnect {
 
 
+/**
+ *
+ *
+ * The root WiConnect library class. This class
+ * inheriets all WiConnect functionality.
+ *
+ * This class is implemented as a 'singleton'. This means it
+ * only needs to be instantiated once. Subsequent class may either
+ * use the class instance or the static function: @ref Wiconnect::getInstance()
+ *
+ */
 class Wiconnect : public NetworkInterface,
                   public SocketInterface,
                   public FileInterface
 {
 public:
+
+    /**
+     *
+     *
+     * WiConnect class constructor
+     *
+     * @note This should only be called once within a program as the WiConnect
+     *       library is implemented as a singleton.
+     *
+     * @note If this constructor is used, then all commands must be supplied with an external response buffer.
+     *       This means most the API functions will not work as they use the internal buffer.
+     *       It's recommended to use the other constructor that supplies an internal buffer. See @ref setting_alloc
+     *
+     * @param[in] serialConfig The serial (i.e. UART) configuration connected to a WiConnect module.
+     * @param[in] reset Optional, The pin connected to the WiConnect module reset signal. Default: No connection
+     * @param[in] wake Optional, The pin connected to the WiConnect module wake signal. Default: No connection
+     * @param[in] nonBlocking Optional, indicates if the API blocking mode. See @ref setting_blocking_modes
+     */
     Wiconnect(const SerialConfig &serialConfig, Pin reset = PIN_NC, Pin wake = PIN_NC, bool nonBlocking = WICONNECT_DEFAULT_NONBLOCKING WICONNECT_MALLOC_ARGS);
+
+    /**
+     *
+     *
+     * WiConnect class constructor
+     *
+     * @note This should only be called once within a program as the WiConnect
+     *       library is implemented as a singleton.
+     *
+     * @note This is the recommended construstor as it supplies the WiConnect library with an
+     *       internal buffer. Most API calls require the internal buffer.
+     *
+     * @param[in] serialConfig The serial (i.e. UART) configuration connected to a WiConnect module.
+     * @param[in] internalBuffer Optional, a user allocated buffer. See @ref setting_alloc
+     * @param[in] internalBufferSize The size of the internal buffer. If internalBuffer is NULL, then this size will be dynamically allocated. See @ref setting_alloc
+     * @param[in] reset Optional, The pin connected to the WiConnect module reset signal. Default: No connection
+     * @param[in] wake Optional, The pin connected to the WiConnect module wake signal. Default: No connection
+     * @param[in] nonBlocking Optional, indicates if the API blocking mode. See @ref setting_blocking_modes
+     */
     Wiconnect(const SerialConfig &serialConfig, void *internalBuffer, int internalBufferSize, Pin reset = PIN_NC, Pin wake = PIN_NC, bool nonBlocking = WICONNECT_DEFAULT_NONBLOCKING WICONNECT_MALLOC_ARGS);
     ~Wiconnect();
 
+    /**
+     * @ingroup  api_core_misc
+     *
+     * Get instance of previously instantiated Wiconnect Library
+     *
+     * @return Pointer to instance of @ref Wiconnect Library.
+     */
     static Wiconnect* getInstance();
 
+    /**
+     * @ingroup  api_core_misc
+     *
+     * Initialize library and communication link with WiConnect WiFi module.
+     *
+     * @note This function is always blocking regardless of configured mode.
+     *
+     * @param[in] bringNetworkUp Flag indicating if the module should try to bring the network up upon initialization.
+     * @return Result of initialization. See @ref WiconnectResult
+     */
     WiconnectResult init(bool bringNetworkUp);
+
+    /**
+     * @ingroup  api_core_misc
+     *
+     * De-initialize library.
+     */
     void deinit();
+
+    /**
+     * @ingroup api_core_misc
+     *
+     * Return TRUE if library is able to communicated with WiConnect WiFi module.
+     * FALSE else.
+     *
+     * @return TRUE if library can communicate with WiFi module, FALSE else.
+     */
     bool isInitialized();
+
+    /**
+     * @ingroup api_core_misc
+     *
+     * Toggle the WiConnect WiFi module reset signal.
+     *
+     * @note This only resets the module if the library was instantiated with the 'reset' pin
+     *       parameter in the Wiconnect::Wiconnect constructor.
+     * @note This method is always blocking. A small (1s) delay is added to ensure the module
+     *       has returned from reset and ready.
+     *
+     * @return Result of method. See @ref WiconnectResult
+     */
     WiconnectResult reset();
+
+    /**
+     * @ingroup api_core_misc
+     *
+     * Toggle the WiConnect WiFi moduel wakeup signal.
+     *
+     * @note This only wakes the module if the library was instantiated with the 'wake' pin
+     *       parameter in the Wiconnect::Wiconnect constructor.
+     * @note This method is always blocking.
+     *
+     * @return Result of method. See @ref WiconnectResult
+     */
     WiconnectResult wakeup();
+
+    /**
+     * @ingroup api_core_misc
+     *
+     * Flush any received data in serial RX buffer and terminate any commands on WiConnect WiFi module.
+     */
     void flush(int delayMs = 500);
 
+    /**
+     * @ingroup api_core_misc
+     *
+     * Return current version of WiConnect WiFi module.
+     */
     WiconnectResult getVersion(char *versionBuffer = NULL, int versionBufferSize = 0, const Callback &completeCallback = Callback());
 
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     */
     WiconnectResult sendCommand(const Callback &completeCallback, char *responseBuffer, int responseBufferLen,
                                 int timeoutMs, const ReaderFunc &reader, void *user, const char *cmd, va_list vaList);
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     */
     WiconnectResult sendCommand(char *responseBuffer, int responseBufferLen, int timeoutMs, const ReaderFunc &reader,
                                 void *user, const char *cmd, va_list vaList);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     * @note This method supports variable arguments
+     *
+     */
     WiconnectResult sendCommand(char *responseBuffer, int responseBufferLen, int timeoutMs, const ReaderFunc &reader,
                                 void *user, const char *cmd, ...);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     * @note This method supports variable arguments
+     *
+     */
     WiconnectResult sendCommand( int timeoutMs, const ReaderFunc &reader, void *user, const char *cmd, ...);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     * @note This method supports variable arguments
+     *
+     */
     WiconnectResult sendCommand(const ReaderFunc &reader, void *user, const char *cmd, ...);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     * @note This method supports variable arguments
+     *
+     */
     WiconnectResult sendCommand(char *responseBuffer, int responseBufferLen,  int timeoutMs, const char *cmd, ...);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     * @note This method supports variable arguments
+     *
+     */
     WiconnectResult sendCommand(const Callback &completeCallback, char *responseBuffer, int responseBufferLen, const char *cmd, ...);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     * @note This method supports variable arguments
+     *
+     */
     WiconnectResult sendCommand(char *responseBuffer, int responseBufferLen, const char *cmd, ...);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     * @note This method supports variable arguments
+     *
+     */
     WiconnectResult sendCommand(const Callback &completeCallback, const char *cmd, ...);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     * @note This method supports variable arguments
+     *
+     */
     WiconnectResult sendCommand(const char *cmd, ...);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     * @note This method supports variable arguments
+     *
+     */
     WiconnectResult sendCommand(const Callback &completeCallback, int timeoutMs, const char *cmd, ...);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     * @note This method supports variable arguments
+     *
+     */
     WiconnectResult sendCommand(int timeoutMs, const char *cmd, ...);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     */
     WiconnectResult sendCommand(const char *cmd, va_list vaList);
 
+    /**
+     * @ingroup api_core_misc
+     *
+     * When the WiConnect WiFi module returns a response, it contains a
+     * response code in the header. This function converts the previous response code
+     * to a readable string.
+     */
     const char* getLastCommandResponseCodeStr();
+
+    /**
+     * @ingroup api_core_misc
+     *
+     * Return the length in bytes of the previous response.
+     */
     uint16_t getLastCommandResponseLength();
+
+    /**
+     * @ingroup api_core_misc
+     *
+     * Return pointer to internal response buffer.
+     */
     char* getResponseBuffer();
+
+    /**
+     * @ingroup api_core_misc
+     *
+     * Helper method to convert previous response to uint32
+     */
     WiconnectResult responseToUint32(uint32_t *uint32Ptr);
+
+    /**
+     * @ingroup api_core_misc
+     *
+     * Helper method to convert previous response to int32
+     */
     WiconnectResult responseToInt32(int32_t *int32Ptr);
 
+    /**
+     * @ingroup api_core_send_command
+     *
+     * Check the status of the currently executing command.
+     *
+     * Refer to @ref WiconnectResult for more information about the return code.
+     *
+     * @note This command is only applicable for non-blocking mode. Refer to @ref setting_blocking_modes.
+     */
     WiconnectResult checkCurrentCommand();
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * Stop the currently executing command.
+     *
+     * @note This command is only applicable for non-blocking mode. Refer to @ref setting_blocking_modes.
+     */
     void stopCurrentCommand();
+
+    /**
+     * @ingroup api_core_settings
+     *
+     * Sets the default maximum time an API method may execute before
+     * terminating and return a timeout error code.
+     *
+     * @note All API method (execpt some sendCommand()) use this default value.
+     */
     void setCommandDefaultTimeout(int timeoutMs);
+
+    /**
+     * @ingroup api_core_settings
+     *
+     * Returns the current default maximum API execution time.
+     */
     int getCommandDefaultTimeout();
 
+    /**
+     * @ingroup api_core_settings
+     *
+     * Sets a mapping function used to convert from a host Pin to WiConnect WiFi module GPIO.
+     */
     void setPinToGpioMapper(PinToGpioMapper mapper);
 
-    static const char* getWiconnectResultStr(WiconnectResult wiconnectResult);
+    /**
+     * @ingroup api_core_settings
+     *
+     * Sets callback function used to debug WiConnect WiFi module RX/TX serial data.
+     */
     void setDebugLogger(LogFunc logFunc);
+
+    /**
+     * @ingroup api_core_settings
+     *
+     * Sets callback used when Wiconnect Library hits and internal assertion.
+     *
+     * @note This is mainly for debugging. There's nothing the callback can do to fix the assertion.
+     */
     void setAssertLogger(LogFunc assertLogFunc);
 
 #ifdef WICONNECT_ASYNC_TIMER_ENABLED
+    /**
+     * @ingroup api_core_send_command
+     *
+     * Add user command to be executed asynchronously.
+     *
+     */
     WiconnectResult enqueueCommand(QueuedCommand *command, const Callback &commandCompleteHandler = Callback());
+
+    /**
+     * @ingroup api_core_settings
+     *
+     * Set the period at which an asynchronous command should be processed.
+     */
     void setCommandProcessingPeriod(uint32_t periodMs);
 #endif
 
+
+    /**
+     * @ingroup conversion_util
+     *
+     * Converts a @ref WiconnectResult to string representation.
+     */
+    static const char* getWiconnectResultStr(WiconnectResult wiconnectResult);
+
 protected:
 
 #ifdef WICONNECT_ENABLE_MALLOC