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
Diff: WiconnectInterface.h
- Revision:
- 13:2b51f5267c92
- Parent:
- 11:ea484e1b7fc4
- Child:
- 16:7f1d6d359787
--- a/WiconnectInterface.h Tue Aug 12 02:44:34 2014 -0700 +++ b/WiconnectInterface.h Wed Aug 13 03:14:30 2014 -0700 @@ -43,7 +43,7 @@ /** - * @ingroup types_core + * @ingroup api_core_types * * @brief The root WiConnect library class. This class * inheriets all WiConnect functionality. @@ -60,8 +60,6 @@ public: /** - * @ingroup types_core - * * @brief WiConnect class constructor * * @note This should only be called once within a program as the WiConnect @@ -79,8 +77,6 @@ Wiconnect(const SerialConfig &serialConfig, Pin reset = PIN_NC, Pin wake = PIN_NC, bool nonBlocking = WICONNECT_DEFAULT_NONBLOCKING WICONNECT_MALLOC_ARGS); /** - * @ingroup types_core - * * @brief WiConnect class constructor * * @note This should only be called once within a program as the WiConnect @@ -90,13 +86,13 @@ * 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] internalBufferSize The size of the internal buffer. If internalBuffer is NULL, then this size will be dynamically allocated. See @ref setting_alloc * @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(const SerialConfig &serialConfig, int internalBufferSize, void *internalBuffer = NULL, Pin reset = PIN_NC, Pin wake = PIN_NC, bool nonBlocking = WICONNECT_DEFAULT_NONBLOCKING WICONNECT_MALLOC_ARGS); ~Wiconnect(); @@ -172,6 +168,12 @@ * @ingroup api_core_misc * * @brief Flush any received data in serial RX buffer and terminate any commands on WiConnect WiFi module. + * + * The delayMs parameter is used as the delay between terminating commands on the module and flushing + * the serial RX buffer. This is needed because after terminating commands on the module, the module will + * returns a response. These responses are invalid at this point and should be flushed from the serial RX buffer. + * + * @param[in] delayMs Optional, if not specificed this only flushes the serial RX buffer. */ void flush(int delayMs = 500); @@ -179,6 +181,11 @@ * @ingroup api_core_misc * * @brief Return current version of WiConnect WiFi module. + * @param[in] versionBuffer Optional, Buffer to hold received version string + * @param[in] versionBufferSize Optional, required if versionBuffer specified. + * @param[in] completeCallback Optional, callback when version is received. arg1 of callback contains version buffer pointer. + * + * @return Result of method. See @ref WiconnectResult */ WiconnectResult getVersion(char *versionBuffer = NULL, int versionBufferSize = 0, const Callback &completeCallback = Callback()); @@ -190,7 +197,18 @@ * @ingroup api_core_send_command * * @brief Send command to WiConnect WiFi module - * Refer to @ref send_command_desc for more info + * + * @note Refer to @ref send_command_desc for more info + * + * @param[in] completeCallback Callback when command completes. arg1 of callback contains responseBuffer pointer, arg2 contains the response length + * @param[in] responseBuffer Buffer to hold command response + * @param[in] responseBufferLen Length of responseBuffer + * @param[in] timeoutMs Maximum time in milliseconds this command should execute + * @param[in] reader Callback for reading data to be read from host and send to module during command + * @param[in] user User data struct used during read Callback. Library doesn't use this. Set NULL if not used. + * @param[in] cmd WiConnect command to send to module + * @param[in] vaList Varaible list of arguments + * @return Result of method. See @ref WiconnectResult */ WiconnectResult sendCommand(const Callback &completeCallback, char *responseBuffer, int responseBufferLen, int timeoutMs, const ReaderFunc &reader, void *user, const char *cmd, va_list vaList); @@ -198,7 +216,17 @@ * @ingroup api_core_send_command * * @brief Send command to WiConnect WiFi module - * Refer to @ref send_command_desc for more info + * + * @note Refer to @ref send_command_desc for more info + * + * @param[in] responseBuffer Buffer to hold command response + * @param[in] responseBufferLen Length of responseBuffer + * @param[in] timeoutMs Maximum time in milliseconds this command should execute + * @param[in] reader Callback for reading data to be read from host and send to module during command + * @param[in] user User data struct used during read Callback. Library doesn't use this. Set NULL if not used. + * @param[in] cmd WiConnect command to send to module + * @param[in] vaList Varaible list of arguments + * @return Result of method. See @ref WiconnectResult */ WiconnectResult sendCommand(char *responseBuffer, int responseBufferLen, int timeoutMs, const ReaderFunc &reader, void *user, const char *cmd, va_list vaList); @@ -207,10 +235,17 @@ * @ingroup api_core_send_command * * @brief Send command to WiConnect WiFi module - * Refer to @ref send_command_desc for more info * + * @note Refer to @ref send_command_desc for more info * @note This method supports variable arguments * + * @param[in] responseBuffer Buffer to hold command response + * @param[in] responseBufferLen Length of responseBuffer + * @param[in] timeoutMs Maximum time in milliseconds this command should execute + * @param[in] reader Callback for reading data to be read from host and send to module during command + * @param[in] user User data struct used during read Callback. Library doesn't use this. Set NULL if not used. + * @param[in] cmd WiConnect command to send to module + * @return Result of method. See @ref WiconnectResult */ WiconnectResult sendCommand(char *responseBuffer, int responseBufferLen, int timeoutMs, const ReaderFunc &reader, void *user, const char *cmd, ...); @@ -219,10 +254,17 @@ * @ingroup api_core_send_command * * @brief Send command to WiConnect WiFi module - * Refer to @ref send_command_desc for more info * + * This method uses the library internal buffer. + * + * @note Refer to @ref send_command_desc for more info * @note This method supports variable arguments * + * @param[in] timeoutMs Maximum time in milliseconds this command should execute + * @param[in] reader Callback for reading data to be read from host and send to module during command + * @param[in] user User data struct used during read Callback. Library doesn't use this. Set NULL if not used. + * @param[in] cmd WiConnect command to send to module + * @return Result of method. See @ref WiconnectResult */ WiconnectResult sendCommand( int timeoutMs, const ReaderFunc &reader, void *user, const char *cmd, ...); @@ -230,10 +272,17 @@ * @ingroup api_core_send_command * * @brief Send command to WiConnect WiFi module - * Refer to @ref send_command_desc for more info * + * - This method uses the library internal buffer and + * - default timeout. See setCommandDefaultTimeout() + * + * @note Refer to @ref send_command_desc for more info * @note This method supports variable arguments * + * @param[in] reader Callback for reading data to be read from host and send to module during command + * @param[in] user User data struct used during read Callback. Library doesn't use this. Set NULL if not used. + * @param[in] cmd WiConnect command to send to module + * @return Result of method. See @ref WiconnectResult */ WiconnectResult sendCommand(const ReaderFunc &reader, void *user, const char *cmd, ...); @@ -241,10 +290,15 @@ * @ingroup api_core_send_command * * @brief Send command to WiConnect WiFi module - * Refer to @ref send_command_desc for more info * + * @note Refer to @ref send_command_desc for more info * @note This method supports variable arguments * + * @param[in] responseBuffer Buffer to hold command response + * @param[in] responseBufferLen Length of responseBuffer + * @param[in] timeoutMs Maximum time in milliseconds this command should execute + * @param[in] cmd WiConnect command to send to module + * @return Result of method. See @ref WiconnectResult */ WiconnectResult sendCommand(char *responseBuffer, int responseBufferLen, int timeoutMs, const char *cmd, ...); @@ -252,10 +306,15 @@ * @ingroup api_core_send_command * * @brief Send command to WiConnect WiFi module - * Refer to @ref send_command_desc for more info * + * @note Refer to @ref send_command_desc for more info * @note This method supports variable arguments * + * @param[in] completeCallback Callback when command completes. arg1 of callback contains responseBuffer pointer, arg2 contains the response length + * @param[in] responseBuffer Buffer to hold command response + * @param[in] responseBufferLen Length of responseBuffer + * @param[in] cmd WiConnect command to send to module + * @return Result of method. See @ref WiconnectResult */ WiconnectResult sendCommand(const Callback &completeCallback, char *responseBuffer, int responseBufferLen, const char *cmd, ...); @@ -263,10 +322,14 @@ * @ingroup api_core_send_command * * @brief Send command to WiConnect WiFi module - * Refer to @ref send_command_desc for more info * + * @note Refer to @ref send_command_desc for more info * @note This method supports variable arguments * + * @param[in] responseBuffer Buffer to hold command response + * @param[in] responseBufferLen Length of responseBuffer + * @param[in] cmd WiConnect command to send to module + * @return Result of method. See @ref WiconnectResult */ WiconnectResult sendCommand(char *responseBuffer, int responseBufferLen, const char *cmd, ...); @@ -274,10 +337,16 @@ * @ingroup api_core_send_command * * @brief Send command to WiConnect WiFi module - * Refer to @ref send_command_desc for more info * + * - This method uses the library internal buffer and + * - default timeout. See setCommandDefaultTimeout() + * + * @note Refer to @ref send_command_desc for more info * @note This method supports variable arguments * + * @param[in] completeCallback Callback when command completes. arg1 of callback contains responseBuffer pointer, arg2 contains the response length + * @param[in] cmd WiConnect command to send to module + * @return Result of method. See @ref WiconnectResult */ WiconnectResult sendCommand(const Callback &completeCallback, const char *cmd, ...); @@ -285,21 +354,30 @@ * @ingroup api_core_send_command * * @brief Send command to WiConnect WiFi module - * Refer to @ref send_command_desc for more info * + * - This method uses the library internal buffer and + * - default timeout. See setCommandDefaultTimeout() + * + * @note Refer to @ref send_command_desc for more info * @note This method supports variable arguments * + * @param[in] cmd WiConnect command to send to module + * @return Result of method. See @ref WiconnectResult */ 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 + * This method uses the library internal buffer * + * @note Refer to @ref send_command_desc for more info * @note This method supports variable arguments * + * @param[in] completeCallback Callback when command completes. arg1 of callback contains responseBuffer pointer, arg2 contains the response length + * @param[in] timeoutMs Maximum time in milliseconds this command should execute + * @param[in] cmd WiConnect command to send to module + * @return Result of method. See @ref WiconnectResult */ WiconnectResult sendCommand(const Callback &completeCallback, int timeoutMs, const char *cmd, ...); @@ -307,19 +385,29 @@ * @ingroup api_core_send_command * * @brief Send command to WiConnect WiFi module - * Refer to @ref send_command_desc for more info * + * This method uses the library internal buffer + * + * @note Refer to @ref send_command_desc for more info * @note This method supports variable arguments * + * @param[in] timeoutMs Maximum time in milliseconds this command should execute + * @param[in] cmd WiConnect command to send to module + * @return Result of method. See @ref WiconnectResult */ 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 + * - This method uses the library internal buffer and + * - default timeout. See setCommandDefaultTimeout() * + * @note Refer to @ref send_command_desc for more info + * + * @param[in] cmd WiConnect command to send to module + * @param[in] vaList Varaible list of arguments + * @return Result of method. See @ref WiconnectResult */ WiconnectResult sendCommand(const char *cmd, va_list vaList); @@ -331,6 +419,8 @@ * 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. + * + * @return Result of method. See @ref WiconnectResult */ WiconnectResult checkCurrentCommand(); @@ -354,6 +444,8 @@ * @brief 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. + * + * @return string representation of module response code */ const char* getLastCommandResponseCodeStr(); @@ -361,6 +453,8 @@ * @ingroup api_core_misc * * @brief Return the length in bytes of the previous response. + * + * @return length of previous response */ uint16_t getLastCommandResponseLength(); @@ -368,6 +462,8 @@ * @ingroup api_core_misc * * @brief Return pointer to internal response buffer. + * + * @return pointer to internal response buffer */ char* getResponseBuffer(); @@ -375,6 +471,11 @@ * @ingroup api_core_misc * * @brief Helper method to convert previous response to uint32 + * + * @note This uses the internal response buffer. + * + * @param[out] uint32Ptr Pointer to hold result of conversion. + * @return Result of conversion. See @ref WiconnectResult */ WiconnectResult responseToUint32(uint32_t *uint32Ptr); @@ -382,6 +483,11 @@ * @ingroup api_core_misc * * @brief Helper method to convert previous response to int32 + * + * @note This uses the internal response buffer. + * + * @param[out] int32Ptr Pointer to hold result of conversion. + * @return Result of conversion. See @ref WiconnectResult */ WiconnectResult responseToInt32(int32_t *int32Ptr); @@ -395,7 +501,9 @@ * @brief 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. + * @note All API methods (execpt some sendCommand()) use this default value. + * + * @param[in] timeoutMs Default command timeout in milliseconds */ void setCommandDefaultTimeout(int timeoutMs); @@ -403,6 +511,8 @@ * @ingroup api_core_settings * * @brief Returns the current default maximum API execution time. + * + * @return Default command timeout in milliseconds */ int getCommandDefaultTimeout(); @@ -410,6 +520,8 @@ * @ingroup api_core_settings * * @brief Sets a mapping function used to convert from a host Pin to WiConnect WiFi module GPIO. + * + * @param[in] mapper Pin to GPIO mapper function pointer */ void setPinToGpioMapper(PinToGpioMapper mapper); @@ -417,6 +529,8 @@ * @ingroup api_core_settings * * @brief Sets callback function used to debug WiConnect WiFi module RX/TX serial data. + * + * @param[in] logFunc Logging function pointer */ void setDebugLogger(LogFunc logFunc); @@ -426,6 +540,8 @@ * @brief 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. + * + * @param[in] assertLogFunc Logging function pointer */ void setAssertLogger(LogFunc assertLogFunc); @@ -439,6 +555,11 @@ * * @brief Add user command to be executed asynchronously. * + * Refer to @ref setting_async_processing for more info. + * + * @param[in] command Pointer to QueuedCommand to be executed asynchronously + * @param[in] commandCompleteHandler Callback to be executed when processing is complete. + * @return Result of method. See @ref WiconnectResult */ WiconnectResult enqueueCommand(QueuedCommand *command, const Callback &commandCompleteHandler = Callback()); @@ -446,6 +567,10 @@ * @ingroup api_core_settings * * @brief Set the period at which an asynchronous command should be processed. + * + * Refer to @ref setting_async_processing for more info. + * + * @param[in] periodMs Processing period in milliseconds */ void setCommandProcessingPeriod(uint32_t periodMs); #endif @@ -455,6 +580,9 @@ * @ingroup conversion_util * * @brief Converts a @ref WiconnectResult to string representation. + * + * @param[in] wiconnectResult Result code + * @return String representaion of result code */ static const char* getWiconnectResultStr(WiconnectResult wiconnectResult);