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:
- 9:b6218dc218ad
- Parent:
- 6:8a87a59d0d21
- Child:
- 11:ea484e1b7fc4
--- 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