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@21:17bb3eddcbae, 2014-08-26 (annotated)

Committer:
dan_ackme
Date:
Tue Aug 26 16:38:19 2014 -0700
Revision:
21:17bb3eddcbae
Parent:
13:2b51f5267c92
Child:
26:8067e3d463d3
Add TCP server API

Who changed what in which revision?

UserRevisionLine numberNew contents of line
dan_ackme 9:b6218dc218ad 1 /**
dan_ackme 13:2b51f5267c92 2 * @mainpage 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 13:2b51f5267c92 39 * More details to come...
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 13:2b51f5267c92 43 * More details to come...
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 13:2b51f5267c92 87 * More details to come...
dan_ackme 9:b6218dc218ad 88 *
dan_ackme 9:b6218dc218ad 89 *
dan_ackme 9:b6218dc218ad 90 */
dan_ackme 9:b6218dc218ad 91
dan_ackme 11:ea484e1b7fc4 92 // ----------------------------------------------------------------------------
dan_ackme 9:b6218dc218ad 93
dan_ackme 9:b6218dc218ad 94 /**
dan_ackme 13:2b51f5267c92 95 * @defgroup api_core Core
dan_ackme 13:2b51f5267c92 96 * @brief This contains all core methods
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 /**
dan_ackme 13:2b51f5267c92 102 * @defgroup api_core_settings Settings Methods
dan_ackme 9:b6218dc218ad 103 * @brief API getters/setters for core library settings
dan_ackme 9:b6218dc218ad 104 */
dan_ackme 9:b6218dc218ad 105
dan_ackme 9:b6218dc218ad 106 /**
dan_ackme 13:2b51f5267c92 107 * @defgroup api_core_send_command Send Command Methods
dan_ackme 9:b6218dc218ad 108 * @brief API methods for sending commands to WiConnect WiFi module
dan_ackme 9:b6218dc218ad 109 */
dan_ackme 9:b6218dc218ad 110
dan_ackme 9:b6218dc218ad 111 /**
dan_ackme 13:2b51f5267c92 112 * @defgroup api_core_misc Miscellaneous Methods
dan_ackme 13:2b51f5267c92 113 * @brief Other core methods
dan_ackme 9:b6218dc218ad 114 */
dan_ackme 9:b6218dc218ad 115
dan_ackme 11:ea484e1b7fc4 116 /**
dan_ackme 13:2b51f5267c92 117 * @defgroup api_core_types Types
dan_ackme 13:2b51f5267c92 118 * @brief Core Types
dan_ackme 13:2b51f5267c92 119 */
dan_ackme 13:2b51f5267c92 120
dan_ackme 13:2b51f5267c92 121
dan_ackme 13:2b51f5267c92 122 /**
dan_ackme 11:ea484e1b7fc4 123 * @defgroup api_core_macro Macros
dan_ackme 13:2b51f5267c92 124 * @brief Core macros
dan_ackme 13:2b51f5267c92 125 */
dan_ackme 13:2b51f5267c92 126
dan_ackme 13:2b51f5267c92 127 /**
dan_ackme 13:2b51f5267c92 128 * @defgroup api_core_examples Examples
dan_ackme 13:2b51f5267c92 129 * @brief Core examples
dan_ackme 11:ea484e1b7fc4 130 */
dan_ackme 11:ea484e1b7fc4 131
dan_ackme 9:b6218dc218ad 132 // @}
dan_ackme 9:b6218dc218ad 133
dan_ackme 9:b6218dc218ad 134
dan_ackme 11:ea484e1b7fc4 135 // ----------------------------------------------------------------------------
dan_ackme 9:b6218dc218ad 136
dan_ackme 9:b6218dc218ad 137 /**
dan_ackme 13:2b51f5267c92 138 * @defgroup api_network Network
dan_ackme 13:2b51f5267c92 139 * @brief This contains all network methods
dan_ackme 9:b6218dc218ad 140 *
dan_ackme 9:b6218dc218ad 141 * @{
dan_ackme 9:b6218dc218ad 142 */
dan_ackme 9:b6218dc218ad 143
dan_ackme 9:b6218dc218ad 144 /**
dan_ackme 13:2b51f5267c92 145 * @defgroup api_network_settings Settings Methods
dan_ackme 9:b6218dc218ad 146 * @brief API getters/setters for module network settings
dan_ackme 9:b6218dc218ad 147 */
dan_ackme 9:b6218dc218ad 148
dan_ackme 9:b6218dc218ad 149 /**
dan_ackme 13:2b51f5267c92 150 * @defgroup api_network_wlan WLAN Methods
dan_ackme 13:2b51f5267c92 151 * @brief Methods for joining/leaving a WLAN
dan_ackme 9:b6218dc218ad 152 */
dan_ackme 9:b6218dc218ad 153
dan_ackme 9:b6218dc218ad 154 /**
dan_ackme 13:2b51f5267c92 155 * @defgroup api_network_setup Web Setup Methods
dan_ackme 13:2b51f5267c92 156 * @brief Methods for enabled/disabling module web setup
dan_ackme 9:b6218dc218ad 157 */
dan_ackme 9:b6218dc218ad 158
dan_ackme 9:b6218dc218ad 159 /**
dan_ackme 13:2b51f5267c92 160 * @defgroup api_network_util Utility Methods
dan_ackme 13:2b51f5267c92 161 * @brief Network utility methods
dan_ackme 13:2b51f5267c92 162 */
dan_ackme 13:2b51f5267c92 163
dan_ackme 13:2b51f5267c92 164 /**
dan_ackme 13:2b51f5267c92 165 * @defgroup api_network_types Types
dan_ackme 13:2b51f5267c92 166 * @brief Network Types
dan_ackme 9:b6218dc218ad 167 */
dan_ackme 9:b6218dc218ad 168
dan_ackme 11:ea484e1b7fc4 169 /**
dan_ackme 11:ea484e1b7fc4 170 * @defgroup api_network_macros Macros
dan_ackme 13:2b51f5267c92 171 * @brief Network specific macros
dan_ackme 9:b6218dc218ad 172 */
dan_ackme 9:b6218dc218ad 173
dan_ackme 9:b6218dc218ad 174 /**
dan_ackme 13:2b51f5267c92 175 * @defgroup api_network_examples Examples
dan_ackme 13:2b51f5267c92 176 * @brief Network examples
dan_ackme 13:2b51f5267c92 177 * * @ref web_setup/example.cpp
dan_ackme 13:2b51f5267c92 178 * * @ref join/example.cpp
dan_ackme 11:ea484e1b7fc4 179 */
dan_ackme 11:ea484e1b7fc4 180
dan_ackme 9:b6218dc218ad 181 // @}
dan_ackme 11:ea484e1b7fc4 182
dan_ackme 11:ea484e1b7fc4 183
dan_ackme 11:ea484e1b7fc4 184 // ----------------------------------------------------------------------------
dan_ackme 11:ea484e1b7fc4 185
dan_ackme 11:ea484e1b7fc4 186 /**
dan_ackme 13:2b51f5267c92 187 * @defgroup api_socket Socket
dan_ackme 13:2b51f5267c92 188 * @brief This contains all socket methods
dan_ackme 11:ea484e1b7fc4 189 *
dan_ackme 11:ea484e1b7fc4 190 * @{
dan_ackme 11:ea484e1b7fc4 191 */
dan_ackme 11:ea484e1b7fc4 192
dan_ackme 11:ea484e1b7fc4 193 /**
dan_ackme 13:2b51f5267c92 194 * @defgroup api_socket_tcp TCP Methods
dan_ackme 13:2b51f5267c92 195 * @brief TCP methods
dan_ackme 13:2b51f5267c92 196 */
dan_ackme 13:2b51f5267c92 197
dan_ackme 13:2b51f5267c92 198 /**
dan_ackme 13:2b51f5267c92 199 * @defgroup api_socket_udp UDP Methods
dan_ackme 13:2b51f5267c92 200 * @brief UDP methods
dan_ackme 13:2b51f5267c92 201 */
dan_ackme 13:2b51f5267c92 202
dan_ackme 13:2b51f5267c92 203 /**
dan_ackme 13:2b51f5267c92 204 * @defgroup api_socket_tls TLS Methods
dan_ackme 13:2b51f5267c92 205 * @brief TLS methods
dan_ackme 13:2b51f5267c92 206 */
dan_ackme 13:2b51f5267c92 207
dan_ackme 13:2b51f5267c92 208 /**
dan_ackme 13:2b51f5267c92 209 * @defgroup api_socket_http HTTP Methods
dan_ackme 13:2b51f5267c92 210 * @brief HTTP methods
dan_ackme 13:2b51f5267c92 211 */
dan_ackme 13:2b51f5267c92 212
dan_ackme 13:2b51f5267c92 213 /**
dan_ackme 13:2b51f5267c92 214 * @defgroup api_socket_misc Miscellaneous Methods
dan_ackme 13:2b51f5267c92 215 * @brief Miscellaneous socket methods
dan_ackme 13:2b51f5267c92 216 */
dan_ackme 13:2b51f5267c92 217
dan_ackme 13:2b51f5267c92 218 /**
dan_ackme 13:2b51f5267c92 219 * @defgroup api_socket_types Types
dan_ackme 13:2b51f5267c92 220 * @brief Socket Types
dan_ackme 13:2b51f5267c92 221 */
dan_ackme 13:2b51f5267c92 222
dan_ackme 13:2b51f5267c92 223 /**
dan_ackme 13:2b51f5267c92 224 * @defgroup api_socket_macro Macros
dan_ackme 13:2b51f5267c92 225 * @brief Socket specific macros
dan_ackme 13:2b51f5267c92 226 */
dan_ackme 13:2b51f5267c92 227
dan_ackme 13:2b51f5267c92 228 /**
dan_ackme 13:2b51f5267c92 229 * @defgroup api_socket_examples Examples
dan_ackme 13:2b51f5267c92 230 * @brief Socket examples
dan_ackme 13:2b51f5267c92 231 * * @ref http_get/example.cpp
dan_ackme 21:17bb3eddcbae 232 * * @ref tcp_server/example.cpp
dan_ackme 13:2b51f5267c92 233 *
dan_ackme 13:2b51f5267c92 234 */
dan_ackme 13:2b51f5267c92 235
dan_ackme 13:2b51f5267c92 236 // @}
dan_ackme 13:2b51f5267c92 237
dan_ackme 13:2b51f5267c92 238
dan_ackme 13:2b51f5267c92 239 // ----------------------------------------------------------------------------
dan_ackme 13:2b51f5267c92 240
dan_ackme 13:2b51f5267c92 241 /**
dan_ackme 13:2b51f5267c92 242 * @defgroup api_file File
dan_ackme 13:2b51f5267c92 243 * @brief This contains all file methods
dan_ackme 13:2b51f5267c92 244 *
dan_ackme 13:2b51f5267c92 245 * @{
dan_ackme 13:2b51f5267c92 246 */
dan_ackme 13:2b51f5267c92 247
dan_ackme 13:2b51f5267c92 248 /**
dan_ackme 13:2b51f5267c92 249 * @defgroup api_file_methods Methods
dan_ackme 13:2b51f5267c92 250 * @brief File Types
dan_ackme 13:2b51f5267c92 251 */
dan_ackme 13:2b51f5267c92 252
dan_ackme 13:2b51f5267c92 253 /**
dan_ackme 13:2b51f5267c92 254 * @defgroup api_file_types Types
dan_ackme 13:2b51f5267c92 255 * @brief File Types
dan_ackme 13:2b51f5267c92 256 */
dan_ackme 13:2b51f5267c92 257
dan_ackme 13:2b51f5267c92 258 /**
dan_ackme 11:ea484e1b7fc4 259 * @defgroup api_file_macro Macros
dan_ackme 11:ea484e1b7fc4 260 * @brief API specific macros
dan_ackme 11:ea484e1b7fc4 261 */
dan_ackme 11:ea484e1b7fc4 262
dan_ackme 11:ea484e1b7fc4 263 /**
dan_ackme 13:2b51f5267c92 264 * @defgroup api_file_examples Examples
dan_ackme 13:2b51f5267c92 265 * @brief File examples
dan_ackme 11:ea484e1b7fc4 266 */
dan_ackme 11:ea484e1b7fc4 267
dan_ackme 11:ea484e1b7fc4 268 // @}
dan_ackme 11:ea484e1b7fc4 269
dan_ackme 13:2b51f5267c92 270
dan_ackme 11:ea484e1b7fc4 271 // ----------------------------------------------------------------------------
dan_ackme 11:ea484e1b7fc4 272
dan_ackme 11:ea484e1b7fc4 273 /**
dan_ackme 11:ea484e1b7fc4 274 * @defgroup conversion_util Conversion Utilities
dan_ackme 11:ea484e1b7fc4 275 * @brief This contains all the conversion utility static functions.
dan_ackme 11:ea484e1b7fc4 276 *
dan_ackme 11:ea484e1b7fc4 277 */
dan_ackme 11:ea484e1b7fc4 278
dan_ackme 11:ea484e1b7fc4 279