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@26:8067e3d463d3, 2014-10-23 (annotated)

Committer:
dan_ackme
Date:
Thu Oct 23 15:16:06 2014 -0700
Revision:
26:8067e3d463d3
Parent:
21:17bb3eddcbae 
Added 'updateFirmware' and 'networkGetJoinResult' api methods

Various bug fixes

Updated documentation

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 26:8067e3d463d3 130 * * @ref ota/example.cpp
dan_ackme 11:ea484e1b7fc4 131 */
dan_ackme 11:ea484e1b7fc4 132
dan_ackme 9:b6218dc218ad 133 // @}
dan_ackme 9:b6218dc218ad 134
dan_ackme 9:b6218dc218ad 135
dan_ackme 11:ea484e1b7fc4 136 // ----------------------------------------------------------------------------
dan_ackme 9:b6218dc218ad 137
dan_ackme 9:b6218dc218ad 138 /**
dan_ackme 13:2b51f5267c92 139 * @defgroup api_network Network
dan_ackme 13:2b51f5267c92 140 * @brief This contains all network methods
dan_ackme 9:b6218dc218ad 141 *
dan_ackme 9:b6218dc218ad 142 * @{
dan_ackme 9:b6218dc218ad 143 */
dan_ackme 9:b6218dc218ad 144
dan_ackme 9:b6218dc218ad 145 /**
dan_ackme 13:2b51f5267c92 146 * @defgroup api_network_settings Settings Methods
dan_ackme 9:b6218dc218ad 147 * @brief API getters/setters for module network settings
dan_ackme 9:b6218dc218ad 148 */
dan_ackme 9:b6218dc218ad 149
dan_ackme 9:b6218dc218ad 150 /**
dan_ackme 13:2b51f5267c92 151 * @defgroup api_network_wlan WLAN Methods
dan_ackme 13:2b51f5267c92 152 * @brief Methods for joining/leaving a WLAN
dan_ackme 9:b6218dc218ad 153 */
dan_ackme 9:b6218dc218ad 154
dan_ackme 9:b6218dc218ad 155 /**
dan_ackme 13:2b51f5267c92 156 * @defgroup api_network_setup Web Setup Methods
dan_ackme 13:2b51f5267c92 157 * @brief Methods for enabled/disabling module web setup
dan_ackme 9:b6218dc218ad 158 */
dan_ackme 9:b6218dc218ad 159
dan_ackme 9:b6218dc218ad 160 /**
dan_ackme 13:2b51f5267c92 161 * @defgroup api_network_util Utility Methods
dan_ackme 13:2b51f5267c92 162 * @brief Network utility methods
dan_ackme 13:2b51f5267c92 163 */
dan_ackme 13:2b51f5267c92 164
dan_ackme 13:2b51f5267c92 165 /**
dan_ackme 13:2b51f5267c92 166 * @defgroup api_network_types Types
dan_ackme 13:2b51f5267c92 167 * @brief Network Types
dan_ackme 9:b6218dc218ad 168 */
dan_ackme 9:b6218dc218ad 169
dan_ackme 11:ea484e1b7fc4 170 /**
dan_ackme 11:ea484e1b7fc4 171 * @defgroup api_network_macros Macros
dan_ackme 13:2b51f5267c92 172 * @brief Network specific macros
dan_ackme 9:b6218dc218ad 173 */
dan_ackme 9:b6218dc218ad 174
dan_ackme 9:b6218dc218ad 175 /**
dan_ackme 13:2b51f5267c92 176 * @defgroup api_network_examples Examples
dan_ackme 13:2b51f5267c92 177 * @brief Network examples
dan_ackme 13:2b51f5267c92 178 * * @ref web_setup/example.cpp
dan_ackme 13:2b51f5267c92 179 * * @ref join/example.cpp
dan_ackme 11:ea484e1b7fc4 180 */
dan_ackme 11:ea484e1b7fc4 181
dan_ackme 9:b6218dc218ad 182 // @}
dan_ackme 11:ea484e1b7fc4 183
dan_ackme 11:ea484e1b7fc4 184
dan_ackme 11:ea484e1b7fc4 185 // ----------------------------------------------------------------------------
dan_ackme 11:ea484e1b7fc4 186
dan_ackme 11:ea484e1b7fc4 187 /**
dan_ackme 13:2b51f5267c92 188 * @defgroup api_socket Socket
dan_ackme 13:2b51f5267c92 189 * @brief This contains all socket methods
dan_ackme 11:ea484e1b7fc4 190 *
dan_ackme 11:ea484e1b7fc4 191 * @{
dan_ackme 11:ea484e1b7fc4 192 */
dan_ackme 11:ea484e1b7fc4 193
dan_ackme 11:ea484e1b7fc4 194 /**
dan_ackme 13:2b51f5267c92 195 * @defgroup api_socket_tcp TCP Methods
dan_ackme 13:2b51f5267c92 196 * @brief TCP methods
dan_ackme 13:2b51f5267c92 197 */
dan_ackme 13:2b51f5267c92 198
dan_ackme 13:2b51f5267c92 199 /**
dan_ackme 13:2b51f5267c92 200 * @defgroup api_socket_udp UDP Methods
dan_ackme 13:2b51f5267c92 201 * @brief UDP methods
dan_ackme 13:2b51f5267c92 202 */
dan_ackme 13:2b51f5267c92 203
dan_ackme 13:2b51f5267c92 204 /**
dan_ackme 13:2b51f5267c92 205 * @defgroup api_socket_tls TLS Methods
dan_ackme 13:2b51f5267c92 206 * @brief TLS methods
dan_ackme 13:2b51f5267c92 207 */
dan_ackme 13:2b51f5267c92 208
dan_ackme 13:2b51f5267c92 209 /**
dan_ackme 13:2b51f5267c92 210 * @defgroup api_socket_http HTTP Methods
dan_ackme 13:2b51f5267c92 211 * @brief HTTP methods
dan_ackme 13:2b51f5267c92 212 */
dan_ackme 13:2b51f5267c92 213
dan_ackme 13:2b51f5267c92 214 /**
dan_ackme 13:2b51f5267c92 215 * @defgroup api_socket_misc Miscellaneous Methods
dan_ackme 13:2b51f5267c92 216 * @brief Miscellaneous socket methods
dan_ackme 13:2b51f5267c92 217 */
dan_ackme 13:2b51f5267c92 218
dan_ackme 13:2b51f5267c92 219 /**
dan_ackme 13:2b51f5267c92 220 * @defgroup api_socket_types Types
dan_ackme 13:2b51f5267c92 221 * @brief Socket Types
dan_ackme 13:2b51f5267c92 222 */
dan_ackme 13:2b51f5267c92 223
dan_ackme 13:2b51f5267c92 224 /**
dan_ackme 13:2b51f5267c92 225 * @defgroup api_socket_macro Macros
dan_ackme 13:2b51f5267c92 226 * @brief Socket specific macros
dan_ackme 13:2b51f5267c92 227 */
dan_ackme 13:2b51f5267c92 228
dan_ackme 13:2b51f5267c92 229 /**
dan_ackme 13:2b51f5267c92 230 * @defgroup api_socket_examples Examples
dan_ackme 13:2b51f5267c92 231 * @brief Socket examples
dan_ackme 13:2b51f5267c92 232 * * @ref http_get/example.cpp
dan_ackme 21:17bb3eddcbae 233 * * @ref tcp_server/example.cpp
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 /**
dan_ackme 13:2b51f5267c92 243 * @defgroup api_file File
dan_ackme 13:2b51f5267c92 244 * @brief This contains all file methods
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 /**
dan_ackme 13:2b51f5267c92 250 * @defgroup api_file_methods Methods
dan_ackme 13:2b51f5267c92 251 * @brief File Types
dan_ackme 13:2b51f5267c92 252 */
dan_ackme 13:2b51f5267c92 253
dan_ackme 13:2b51f5267c92 254 /**
dan_ackme 13:2b51f5267c92 255 * @defgroup api_file_types Types
dan_ackme 13:2b51f5267c92 256 * @brief File Types
dan_ackme 13:2b51f5267c92 257 */
dan_ackme 13:2b51f5267c92 258
dan_ackme 13:2b51f5267c92 259 /**
dan_ackme 11:ea484e1b7fc4 260 * @defgroup api_file_macro Macros
dan_ackme 11:ea484e1b7fc4 261 * @brief API specific macros
dan_ackme 11:ea484e1b7fc4 262 */
dan_ackme 11:ea484e1b7fc4 263
dan_ackme 11:ea484e1b7fc4 264 /**
dan_ackme 13:2b51f5267c92 265 * @defgroup api_file_examples Examples
dan_ackme 13:2b51f5267c92 266 * @brief File examples
dan_ackme 11:ea484e1b7fc4 267 */
dan_ackme 11:ea484e1b7fc4 268
dan_ackme 11:ea484e1b7fc4 269 // @}
dan_ackme 11:ea484e1b7fc4 270
dan_ackme 13:2b51f5267c92 271
dan_ackme 11:ea484e1b7fc4 272 // ----------------------------------------------------------------------------
dan_ackme 11:ea484e1b7fc4 273
dan_ackme 11:ea484e1b7fc4 274 /**
dan_ackme 11:ea484e1b7fc4 275 * @defgroup conversion_util Conversion Utilities
dan_ackme 11:ea484e1b7fc4 276 * @brief This contains all the conversion utility static functions.
dan_ackme 11:ea484e1b7fc4 277 *
dan_ackme 11:ea484e1b7fc4 278 */
dan_ackme 11:ea484e1b7fc4 279
dan_ackme 11:ea484e1b7fc4 280