ACKme / WiConnect

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

README.h@9:b6218dc218ad, 2014-08-11 (annotated)

Committer:
dan_ackme
Date:
Mon Aug 11 21:25:37 2014 -0700
Revision:
9:b6218dc218ad
Child:
11:ea484e1b7fc4
started adding docs

Who changed what in which revision?

UserRevisionLine numberNew contents of line
dan_ackme 9:b6218dc218ad 1 /**
dan_ackme 9:b6218dc218ad 2 * @mainpage WiConnect Library Overview
dan_ackme 9:b6218dc218ad 3 *
dan_ackme 9:b6218dc218ad 4 * @section Overview
dan_ackme 9:b6218dc218ad 5 * The WiConnect Library runs on a host MCU and controls a
dan_ackme 9:b6218dc218ad 6 * WiConnect enabled WiFi module. This library is essentially a
dan_ackme 9:b6218dc218ad 7 * programming API for the WiConnect serial command set. More infomation
dan_ackme 9:b6218dc218ad 8 * about the serial command set may be found here:
dan_ackme 9:b6218dc218ad 9 * <a href="http://wiconnect.ack.me" target="_blank">WiConnect Reference Guide</a>
dan_ackme 9:b6218dc218ad 10 *
dan_ackme 9:b6218dc218ad 11 * @section notes Important Notes
dan_ackme 9:b6218dc218ad 12 * - This class is implemented as a 'singleton'. This means it only needs to be
dan_ackme 9:b6218dc218ad 13 * instantiated once.
dan_ackme 9:b6218dc218ad 14 * - The WiConnect library does NOT call the global 'new' or 'malloc' functions.
dan_ackme 9:b6218dc218ad 15 * All memory allocation (if required) comes from a user supplied malloc function pointer or buffer
dan_ackme 9:b6218dc218ad 16 *
dan_ackme 9:b6218dc218ad 17 *
dan_ackme 9:b6218dc218ad 18 * @section features Library Settings
dan_ackme 9:b6218dc218ad 19 * The WiConnect Library has multiple settings so as to allow
dan_ackme 9:b6218dc218ad 20 * for the most flexibility within a user's application.
dan_ackme 9:b6218dc218ad 21 *
dan_ackme 9:b6218dc218ad 22 * Some of these configurations are as follows:
dan_ackme 9:b6218dc218ad 23 * - Blocking / Non-blocking
dan_ackme 9:b6218dc218ad 24 * - Dynamic / Static allocation
dan_ackme 9:b6218dc218ad 25 * - Asynchronous Processing
dan_ackme 9:b6218dc218ad 26 *
dan_ackme 9:b6218dc218ad 27 *
dan_ackme 9:b6218dc218ad 28 * @subsection setting_blocking_modes Blocking / Non-blocking Modes
dan_ackme 9:b6218dc218ad 29 * The WiConnect Library may be configured for either 'blocking' or
dan_ackme 9:b6218dc218ad 30 * 'non-blocking' operation:
dan_ackme 9:b6218dc218ad 31 * - blocking - API calls do not return until they complete successfully or timeout.
dan_ackme 9:b6218dc218ad 32 * - non-blocking - API calls return immediately. The caller should check the return code to see
dan_ackme 9:b6218dc218ad 33 * if the command is still processing, completed, or an error occurred. The caller
dan_ackme 9:b6218dc218ad 34 * should continue to call the API function (as often as possible) until it returns
dan_ackme 9:b6218dc218ad 35 * either a success or error code.
dan_ackme 9:b6218dc218ad 36 *
dan_ackme 9:b6218dc218ad 37 * @subsubsection setting_blocking_mode Blocking Mode
dan_ackme 9:b6218dc218ad 38 * In blocking mode, an API function will block until it completes.
dan_ackme 9:b6218dc218ad 39 * TODO: more details here
dan_ackme 9:b6218dc218ad 40 *
dan_ackme 9:b6218dc218ad 41 * @subsubsection setting_nonblocking_mode Non-Blocking Mode
dan_ackme 9:b6218dc218ad 42 * In non-blocking mode, an API function returns immediately.
dan_ackme 9:b6218dc218ad 43 * TODO: more details here
dan_ackme 9:b6218dc218ad 44 *
dan_ackme 9:b6218dc218ad 45 *
dan_ackme 9:b6218dc218ad 46 *
dan_ackme 9:b6218dc218ad 47 * @subsection setting_alloc Dynamic / Static Allocation
dan_ackme 9:b6218dc218ad 48 * There are two cases when memory allocation is required:
dan_ackme 9:b6218dc218ad 49 * - Buffer allocation
dan_ackme 9:b6218dc218ad 50 * - Class instantiation
dan_ackme 9:b6218dc218ad 51 *
dan_ackme 9:b6218dc218ad 52 * In both cases, either static or dynamic memory allocation may be used.
dan_ackme 9:b6218dc218ad 53 *
dan_ackme 9:b6218dc218ad 54 * In cases when memory allocation is needed, the API call requires a buffer pointer
dan_ackme 9:b6218dc218ad 55 * and length parameters. If both are supplied, the library uses the supplied external buffer.
dan_ackme 9:b6218dc218ad 56 * This is considered static allocation (however the buffer could have been dynamically allocated).
dan_ackme 9:b6218dc218ad 57 * The caller is responsible for maintaining the supplied buffer.
dan_ackme 9:b6218dc218ad 58 *
dan_ackme 9:b6218dc218ad 59 * If, however, only the buffer length is supplied and the buffer pointer is NULL
dan_ackme 9:b6218dc218ad 60 * the Wiconnect Library will call the user supplied malloc() function. This is considered
dan_ackme 9:b6218dc218ad 61 * dynamic allocation. In this case, the library will maintain the buffer and release it
dan_ackme 9:b6218dc218ad 62 * when necessary using the user supplied free() function.
dan_ackme 9:b6218dc218ad 63 *
dan_ackme 9:b6218dc218ad 64 * @note To use dynamic allocation the WiConnect Library must be compiled with
dan_ackme 9:b6218dc218ad 65 * @ref WICONNECT_ENABLE_MALLOC defined, and the Wiconnect() constructor must be
dan_ackme 9:b6218dc218ad 66 * supplied with pointers to malloc() and free() functions.
dan_ackme 9:b6218dc218ad 67 *
dan_ackme 9:b6218dc218ad 68 * @note The Wiconnect Library does NOT call the global 'new' operator. Classes that are
dan_ackme 9:b6218dc218ad 69 * internally instantiated overload the 'new' operator and either call the user
dan_ackme 9:b6218dc218ad 70 * supplied malloc() function or use the supplied static buffer.
dan_ackme 9:b6218dc218ad 71 *
dan_ackme 9:b6218dc218ad 72 *
dan_ackme 9:b6218dc218ad 73 * @subsection setting_async_processing Asynchronous Processing
dan_ackme 9:b6218dc218ad 74 * When applicable, the WiConnect Library will asynchronously process
dan_ackme 9:b6218dc218ad 75 * commands in the background. When the background processing completes, the
dan_ackme 9:b6218dc218ad 76 * supplied callback is called.
dan_ackme 9:b6218dc218ad 77 *
dan_ackme 9:b6218dc218ad 78 * User commands may also be executed in the background using the enqueueCommand()
dan_ackme 9:b6218dc218ad 79 * API function.
dan_ackme 9:b6218dc218ad 80 *
dan_ackme 9:b6218dc218ad 81 * @note The WiConnect Library must be compiled with @ref WICONNECT_ASYNC_TIMER_ENABLED
dan_ackme 9:b6218dc218ad 82 * defined for background processing to be enabled.
dan_ackme 9:b6218dc218ad 83 *
dan_ackme 9:b6218dc218ad 84 *
dan_ackme 9:b6218dc218ad 85 *
dan_ackme 9:b6218dc218ad 86 * @section send_command_desc Sending Commands To WiFi Module
dan_ackme 9:b6218dc218ad 87 * TODO: add detailed description here
dan_ackme 9:b6218dc218ad 88 *
dan_ackme 9:b6218dc218ad 89 *
dan_ackme 9:b6218dc218ad 90 */
dan_ackme 9:b6218dc218ad 91
dan_ackme 9:b6218dc218ad 92
dan_ackme 9:b6218dc218ad 93 /**
dan_ackme 9:b6218dc218ad 94 * @defgroup api_core Core API
dan_ackme 9:b6218dc218ad 95 * @brief This contains all core API Library methods
dan_ackme 9:b6218dc218ad 96 *
dan_ackme 9:b6218dc218ad 97 * @{
dan_ackme 9:b6218dc218ad 98 */
dan_ackme 9:b6218dc218ad 99
dan_ackme 9:b6218dc218ad 100 /**
dan_ackme 9:b6218dc218ad 101 * @defgroup api_core_settings Settings
dan_ackme 9:b6218dc218ad 102 * @brief API getters/setters for core library settings
dan_ackme 9:b6218dc218ad 103 */
dan_ackme 9:b6218dc218ad 104
dan_ackme 9:b6218dc218ad 105 /**
dan_ackme 9:b6218dc218ad 106 * @defgroup api_core_send_command Send Command
dan_ackme 9:b6218dc218ad 107 * @brief API methods for sending commands to WiConnect WiFi module
dan_ackme 9:b6218dc218ad 108 */
dan_ackme 9:b6218dc218ad 109
dan_ackme 9:b6218dc218ad 110 /**
dan_ackme 9:b6218dc218ad 111 * @defgroup api_core_misc Miscellaneous
dan_ackme 9:b6218dc218ad 112 * @brief Other core API methods
dan_ackme 9:b6218dc218ad 113 */
dan_ackme 9:b6218dc218ad 114
dan_ackme 9:b6218dc218ad 115 // @}
dan_ackme 9:b6218dc218ad 116
dan_ackme 9:b6218dc218ad 117
dan_ackme 9:b6218dc218ad 118
dan_ackme 9:b6218dc218ad 119 /**
dan_ackme 9:b6218dc218ad 120 * @defgroup api_network Network API
dan_ackme 9:b6218dc218ad 121 * @brief This contains all network API Library methods
dan_ackme 9:b6218dc218ad 122 *
dan_ackme 9:b6218dc218ad 123 * @{
dan_ackme 9:b6218dc218ad 124 */
dan_ackme 9:b6218dc218ad 125
dan_ackme 9:b6218dc218ad 126 /**
dan_ackme 9:b6218dc218ad 127 * @defgroup api_network_settings Settings
dan_ackme 9:b6218dc218ad 128 * @brief API getters/setters for module network settings
dan_ackme 9:b6218dc218ad 129 */
dan_ackme 9:b6218dc218ad 130
dan_ackme 9:b6218dc218ad 131 /**
dan_ackme 9:b6218dc218ad 132 * @defgroup api_network_wlan WLAN
dan_ackme 9:b6218dc218ad 133 * @brief API methods for joining/leaving a WLAN
dan_ackme 9:b6218dc218ad 134 */
dan_ackme 9:b6218dc218ad 135
dan_ackme 9:b6218dc218ad 136 /**
dan_ackme 9:b6218dc218ad 137 * @defgroup api_network_setup Web Setup
dan_ackme 9:b6218dc218ad 138 * @brief API methods for enabled/disabling module web setup
dan_ackme 9:b6218dc218ad 139 */
dan_ackme 9:b6218dc218ad 140
dan_ackme 9:b6218dc218ad 141 /**
dan_ackme 9:b6218dc218ad 142 * @defgroup api_network_util Utilities
dan_ackme 9:b6218dc218ad 143 * @brief Network utility API methods
dan_ackme 9:b6218dc218ad 144 */
dan_ackme 9:b6218dc218ad 145
dan_ackme 9:b6218dc218ad 146 // @}
dan_ackme 9:b6218dc218ad 147
dan_ackme 9:b6218dc218ad 148
dan_ackme 9:b6218dc218ad 149 /**
dan_ackme 9:b6218dc218ad 150 * @defgroup api_socket Socket API
dan_ackme 9:b6218dc218ad 151 * @brief This contains all socket API Library methods
dan_ackme 9:b6218dc218ad 152 *
dan_ackme 9:b6218dc218ad 153 * @{
dan_ackme 9:b6218dc218ad 154 */
dan_ackme 9:b6218dc218ad 155
dan_ackme 9:b6218dc218ad 156 /**
dan_ackme 9:b6218dc218ad 157 * @defgroup api_socket_tcp TCP
dan_ackme 9:b6218dc218ad 158 * @brief TCP API methods
dan_ackme 9:b6218dc218ad 159 */
dan_ackme 9:b6218dc218ad 160
dan_ackme 9:b6218dc218ad 161 /**
dan_ackme 9:b6218dc218ad 162 * @defgroup api_socket_udp UDP
dan_ackme 9:b6218dc218ad 163 * @brief UDP API methods
dan_ackme 9:b6218dc218ad 164 */
dan_ackme 9:b6218dc218ad 165
dan_ackme 9:b6218dc218ad 166 /**
dan_ackme 9:b6218dc218ad 167 * @defgroup api_socket_tls TLS
dan_ackme 9:b6218dc218ad 168 * @brief TLS API methods
dan_ackme 9:b6218dc218ad 169 */
dan_ackme 9:b6218dc218ad 170
dan_ackme 9:b6218dc218ad 171 /**
dan_ackme 9:b6218dc218ad 172 * @defgroup api_socket_http HTTP
dan_ackme 9:b6218dc218ad 173 * @brief HTTP API methods
dan_ackme 9:b6218dc218ad 174 */
dan_ackme 9:b6218dc218ad 175
dan_ackme 9:b6218dc218ad 176 /**
dan_ackme 9:b6218dc218ad 177 * @defgroup api_socket_misc Miscellaneous
dan_ackme 9:b6218dc218ad 178 * @brief Miscellaneous socket API methods
dan_ackme 9:b6218dc218ad 179 */
dan_ackme 9:b6218dc218ad 180
dan_ackme 9:b6218dc218ad 181 // @}