Host library for controlling a WiConnect enabled Wi-Fi module.
Dependents: wiconnect-ota_example wiconnect-web_setup_example wiconnect-test-console wiconnect-tcp_server_example ... more
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