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

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers WiconnectTypes.h Source File

WiconnectTypes.h

00001 /**
00002  * ACKme WiConnect Host Library is licensed under the BSD licence: 
00003  * 
00004  * Copyright (c)2014 ACKme Networks.
00005  * All rights reserved. 
00006  * 
00007  * Redistribution and use in source and binary forms, with or without modification, 
00008  * are permitted provided that the following conditions are met: 
00009  * 
00010  * 1. Redistributions of source code must retain the above copyright notice, 
00011  * this list of conditions and the following disclaimer. 
00012  * 2. Redistributions in binary form must reproduce the above copyright notice, 
00013  * this list of conditions and the following disclaimer in the documentation 
00014  * and/or other materials provided with the distribution. 
00015  * 3. The name of the author may not be used to endorse or promote products 
00016  * derived from this software without specific prior written permission. 
00017  * 
00018  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS AND ANY EXPRESS OR IMPLIED 
00019  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 
00020  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 
00021  * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
00022  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 
00023  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
00024  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
00025  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 
00026  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 
00027  * OF SUCH DAMAGE.
00028  */
00029 #pragma once
00030 
00031 #include <stdint.h>
00032 #include <stdarg.h>
00033 #include <stddef.h>
00034 
00035 #include "sdk.h"
00036 
00037 /**
00038  * @namespace wiconnect
00039  *
00040  * @brief The entire Wiconnect Library is contained within the 'wiconnect' namespace
00041  */
00042 namespace wiconnect {
00043 
00044 
00045 #ifndef MIN
00046 /**
00047  * @ingroup api_core_macro
00048  * @def MIN(x,y)
00049  * @brief Computes the minimum of \a x and \a y.
00050  */
00051 #define MIN(x,y) ((x) < (y) ? (x) : (y))
00052 #endif
00053 #ifndef MAX
00054 /**
00055  * @ingroup api_core_macro
00056  * @def MAX(x,y)
00057  * @brief Computes the maximum of \a x and \a y.
00058  */
00059 #define MAX(x,y)  ((x) > (y) ? (x) : (y))
00060 #endif
00061 /**
00062  * @ingroup api_core_macro
00063  * @def ALIGN_n(x, n)
00064  * @brief Align \a x to \a n bytes (\a n must be power of 2)
00065  */
00066 #define ALIGN_n(x, n) ((((uint32_t)x) + ((n)-1)) & ~((n)-1))
00067 /**
00068  * @ingroup api_core_macro
00069  * @def ALIGN_8(x)
00070  * @brief Align \a x to 8 bytes
00071  */
00072 #define ALIGN_8(x) ALIGN_n(x, 8)
00073 /**
00074  * @ingroup api_core_macro
00075  * @def ALIGN_4(x)
00076  * @brief Align \a x to 4 bytes
00077  */
00078 #define ALIGN_4(x) ALIGN_n(x, 4)
00079 /**
00080  * @ingroup api_core_macro
00081  * @def ARRAY_COUNT(x)
00082  * @brief Return number of elements in static array \a x
00083  */
00084 #define ARRAY_COUNT(x) (sizeof (x) / sizeof *(x))
00085 
00086 
00087 
00088 /**
00089  * @ingroup api_core_macro
00090  * @def WICONNECT_FAILED(result, func)
00091  * @brief Populates \a result with return value from \a func, returns TRUE if return value contains error.
00092  */
00093 #define WICONNECT_FAILED(result, func) ((int)(result = (func)) < (int)wiconnect::WICONNECT_SUCCESS)
00094 
00095 /**
00096  * @ingroup api_core_macro
00097  * @def WICONNECT_SUCCEEDED(result, func)
00098  * @brief Populates \a result with return value from \a func, returns TRUE if return value is WICONNECT_SUCCESS.
00099  */
00100 #define WICONNECT_SUCCEEDED(result, func) ((result = (func)) == wiconnect::WICONNECT_SUCCESS)
00101 
00102 /**
00103  * @ingroup api_core_macro
00104  * @def WICONNECT_IS_PROCESSING(result, func)
00105  * @brief Populates \a result with return value from \a func, returns TRUE if return value is WICONNECT_PROCESSING.
00106  */
00107 #define WICONNECT_IS_PROCESSING(result, func) ((result = (func)) == wiconnect::WICONNECT_PROCESSING)
00108 
00109 /**
00110  * @ingroup api_core_macro
00111  * @brief The maximum command size that may be sent to the WiConnect WiFi module
00112  */
00113 #define WICONNECT_MAX_CMD_SIZE 128
00114 /**
00115  * @ingroup api_core_macro
00116  * @brief The maximum WiConnect WiFi module version string size
00117  */
00118 #define WICONNECT_MAX_VERSION_SIZE 96
00119 /**
00120  * @ingroup api_core_macro
00121  * @brief The maximum number of simulanteous opened sockets
00122  */
00123 #define WICONNECT_MAX_SOCKETS 8
00124 /**
00125  * @ingroup api_core_macro
00126  * @brief The maximum server string length
00127  */
00128 #define WICONNECT_MAX_HOST_SIZE 64
00129 /**
00130  * @ingroup api_core_macro
00131  * @brief The maximum Wiconnect Module flash filesystem filename length
00132  */
00133 #define WICONNECT_MAX_FILENAME_SIZE 96
00134 /**
00135  * @ingroup api_core_macro
00136  * @brief Never timeout
00137  */
00138 #define WICONNECT_WAIT_FOREVER 0xFFFFFFFFUL
00139 /**
00140  * @ingroup api_core_macro
00141  * @brief Timeout immediately
00142  */
00143 #define WICONNECT_NO_WAIT 0
00144 /**
00145  * @ingroup api_core_macro
00146  * @brief Default firmware update timeout in ms
00147  */
00148 #define WICONNECT_FIRMWARE_UPDATE_TIMEOUT 300000UL
00149 
00150 /**
00151  * @ingroup api_socket_macro
00152  * @brief Default which indicates to use the most optimal port
00153  */
00154 #define SOCKET_ANY_PORT (uint16_t)0
00155 /**
00156  * @ingroup api_socket_macro
00157  * @brief Default which indicates to use the most optimal port
00158  */
00159 #define SOCKET_INVALID_HANDLE ((uint8_t)0xFF)
00160 
00161 
00162 /**
00163  * @ingroup api_core_types
00164  * @brief API Result code
00165  */
00166 typedef enum
00167 {
00168     // Status Codes
00169     WICONNECT_ABORTED               = 3,    ///< Command was aborted
00170     WICONNECT_IDLE                  = 2,    ///< Library not processing any commands
00171     WICONNECT_PROCESSING            = 1,    ///< Library processing current command
00172     WICONNECT_SUCCESS               = 0,    ///< Command successfully completed
00173 
00174     // Error codes
00175     WICONNECT_ERROR                 = -1,   ///< Generic error
00176     WICONNECT_CMD_RESPONSE_ERROR    = -2,   ///< Module returned error code
00177     WICONNECT_NULL_BUFFER           = -3,   ///< Null buffer supplied
00178     WICONNECT_NOT_INITIALIZED       = -4,   ///< Library not initialed
00179     WICONNECT_OVERFLOW              = -5,   ///< Buffer overflowed
00180     WICONNECT_TIMEOUT               = -6,   ///< Command timed out
00181 //    WICONNECT_RESPONSE_HANDLER_NULL = -7,   ///<
00182     WICONNECT_RESPONSE_PARSE_ERROR  = -8,   ///< Failed to parse module response
00183     WICONNECT_ANOTHER_CMD_EXECUTING = -9,   ///< Currently executing another command
00184     WICONNECT_BAD_ARG               = -10,  ///< Bad argument supplied
00185     WICONNECT_UNSUPPORTED           = -11,  ///< Command / parameter not supported
00186     WICONNECT_PINNAME_TO_GPIO_MAPPER_NULL = -12,    ///< The pinToGpioMapper hasn't been set
00187     WICONNECT_DUPLICATE             = -13,  ///< Duplicate value
00188     WICONNECT_NOT_FOUND             = -14,  ///< Not found
00189     WICONNECT_PINNAME_TO_GPIO_NO_MAPPING = -15, ///< No mapping found for given pin
00190     WICONNECT_NOT_CONNECTED         = -16,  ///< Not connected
00191     WICONNECT_UNDERFLOW             = -17,  ///< Data underflow
00192     WICONNECT_MONITOR_NOT_AVAILABLE = -18,  ///< Background processing monitor is not available (i.e in use)
00193     WICONNECT_NOT_OPENED_FOR_READING = -19, ///< The file is not open for reading
00194     WICONNECT_FIRMWARE_OUTDATED     = -20,  ///< The WiFi module's firmware is out-dated. See updateFirmware() to update the firmware.
00195 } WiconnectResult;
00196 
00197 
00198 
00199 /**
00200  * @ingroup types_core
00201  * @brief Function pointer for mapping from a host pin to a WiConnect Module GPIO.
00202  *
00203  * @param[in] pin A host pin
00204  * @return The corresponding WiConnect Module GPIO (which the given pin is physically connected).
00205  *         Return -1 if no mapping is available.
00206  */
00207 typedef int8_t (*PinToGpioMapper)(Pin pin);
00208 
00209 /**
00210  * @ingroup types_core
00211  * @brief Timeout type
00212  */
00213 typedef unsigned long TimerTimeout;
00214 
00215 
00216 /**
00217  * @brief Generic buffer type
00218  *
00219  * @note Internal use only
00220  */
00221 typedef struct
00222 {
00223     int size;
00224     uint8_t *buffer;
00225     uint8_t *ptr;
00226     int bytesPending;
00227     bool allocated;
00228 } Buffer;
00229 
00230 
00231 // ----------------------------------------------------------------------------
00232 
00233 
00234 
00235 /**
00236  * @ingroup api_network_types
00237  * @brief Network connection status
00238  */
00239 typedef enum
00240 {
00241     NETWORK_STATUS_DOWN,            ///< Not connected to network
00242     NETWORK_STATUS_WIFI_ONLY,       ///< Connected to network but don't have IP address
00243     NETWORK_STATUS_UP,              ///< Conntected to network and have IP address
00244     NETWORK_STATUS_JOINING          ///< Joining a network
00245 } NetworkStatus;
00246 
00247 /**
00248  * @ingroup api_network_types
00249  * @brief Network connection status
00250  */
00251 typedef enum
00252 {
00253     NETWORK_JOIN_RESULT_NONE,           ///< Haven't attempted to join
00254     NETWORK_JOIN_RESULT_SUCCESS,        ///< Successfully joined the network
00255     NETWORK_JOIN_RESULT_JOINING,        ///< Currently attempting to join
00256     NETWORK_JOIN_RESULT_NO_SSID,        ///< The SSID has not be configured
00257     NETWORK_JOIN_RESULT_NO_PASSWORD,    ///< The network requires a password and none has been set
00258     NETWORK_JOIN_RESULT_BAD_SECURITY,   ///< The specified security type is not supported by the network
00259     NETWORK_JOIN_RESULT_NOT_FOUND,      ///< The network with the configured SSID was not found
00260     NETWORK_JOIN_RESULT_FAILED,         ///< Failed to join the network
00261     NETWORK_JOIN_RESULT_ABORTED,        ///< Joining was aborted (via command)
00262 } NetworkJoinResult;
00263 
00264 /**
00265  * @ingroup api_network_types
00266  * @brief Network RSSI signal level
00267  */
00268 typedef enum
00269 {
00270     NETWORK_RSSI_EXCELLENT              = 0,    ///< > -20 dBm
00271     NETWORK_RSSI_VERY_GOOD              = 1,    ///< > -35 dBm
00272     NETWORK_RSSI_GOOD                   = 2,    ///< > -50 dBm
00273     NETWORK_RSSI_POOR                   = 3,    ///< > -70 dBm
00274     NETWORK_RSSI_VERY_POOR              = 4,    ///< < -71 dBm
00275     NETWORK_RSSI_UNKNOWN                = 5     ///< Not available
00276 } NetworkSignalStrength;
00277 
00278 /**
00279  * @ingroup api_network_types
00280  * @brief Network security type
00281  */
00282 typedef enum
00283 {
00284     NETWORK_SECURITY_OPEN,
00285     NETWORK_SECURITY_WEP_PSK,
00286     NETWORK_SECURITY_WPA_AES_PSK,
00287     NETWORK_SECURITY_WPA_TKIP_PSK,
00288     NETWORK_SECURITY_WPA2_AES_PSK,
00289     NETWORK_SECURITY_WPA2_MIXED_PSK,
00290     NETWORK_SECURITY_WPA2_TKIP_PSK,
00291     NETWORK_SECURITY_UNKNOWN
00292 } NetworkSecurity;
00293 
00294 /**
00295  * @ingroup api_network_types
00296  * @brief Network SSID type
00297  */
00298 typedef struct
00299 {
00300     uint8_t val[32];        ///< The raw data of the SSID (not necessarily a string)
00301     uint8_t len;            ///< The length in bytes of the SSID raw data
00302 } Ssid;
00303 
00304 /**
00305  * @ingroup api_network_types
00306  * @brief Network MAC Address type
00307  */
00308 typedef struct
00309 {
00310     uint8_t octet[6];
00311 } MacAddress;
00312 
00313 /**
00314  * @ingroup api_network_types
00315  * @brief Buffer to hold a MAC address string
00316  */
00317 typedef char MacAddressStrBuffer[18];
00318 
00319 /**
00320  * @ingroup api_network_types
00321  * @brief Buffer to hold a SSID string
00322  */
00323 typedef char SsidStrBuffer[129];
00324 
00325 /**
00326  * @ingroup api_network_types
00327  * @brief Buffer to hold an IP address string
00328  */
00329 typedef char IpStrBuffer[18];
00330 
00331 
00332 // ----------------------------------------------------------------------------
00333 
00334 
00335 /**
00336  * @ingroup api_socket_types
00337  * @brief Socket type
00338  */
00339 typedef enum
00340 {
00341     SOCKET_TYPE_UNKNOWN,    ///< Socket type not known
00342     SOCKET_TYPE_TCP,        ///< TCP Socket type
00343     SOCKET_TYPE_TLS,        ///< TLS Socket type
00344     SOCKET_TYPE_UDP,        ///< UDP Socket type
00345     SOCKET_TYPE_HTTP,       ///< HTTP Socket type,
00346     SOCKET_TYPE_UDPS,       ///< UDP Server Socket type
00347     SOCKET_TYPE_GHM,        ///< goHACK.me message type
00348 } SocketType;
00349 
00350 /**
00351  * @ingroup api_socket_types
00352  * @brief HTTP Socket sub-type
00353  */
00354 typedef enum
00355 {
00356     SOCKET_HTTP_GET,        ///< HTTP GET Request socket type
00357     SOCKET_HTTP_POST,       ///< HTTP POST Request socket type
00358     SOCKET_HTTP_HEAD,       ///< HTTP HEAD Request socket type
00359 } HttpSocketType;
00360 
00361 /**
00362  * @ingroup api_socket_types
00363  * @brief Struct for hold HTTP socket configuration
00364  */
00365 typedef struct
00366 {
00367     const char *contextType;    ///< A POST Request 'context-type' value
00368     const char *certName;       ///< TLS certificate filename on module flash file system
00369     bool openOnly;              ///< Only open the connection, don't issue the request yet
00370     HttpSocketType type;        ///< The type of HTTP connection
00371 } HttpSocketArgs;
00372 
00373 
00374 // ----------------------------------------------------------------------------
00375 
00376 
00377 /**
00378  * @ingroup api_file_types
00379  * @brief File flags type
00380  */
00381 typedef enum
00382 {
00383     FILE_FLAG_NONE          = 0,            ///< No flags
00384 
00385     FILE_FLAG_VALID         = (1 << 0),     ///< File valid
00386     FILE_FLAG_EXECUTABLE    = (1 << 1),     ///< File executable
00387     FILE_FLAG_ENCRYPTED     = (1 << 2),     ///< File encrypted
00388     FILE_FLAG_INTERNAL      = (1 << 3),     ///< File on internal module flash
00389     FILE_FLAG_BOOTABLE      = (1 << 4),     ///< File bootable
00390     FILE_FLAG_USER          = (1 << 5),     ///< File created by user
00391     FILE_FLAG_ESSENTIAL     = (1 << 6),     ///< File is essential
00392 
00393     FILE_FLAG_INVALID       = 0xFFFF        ///< File flags invalid
00394 } FileFlags;
00395 
00396 /**
00397  * @ingroup api_file_types
00398  * @brief File type type
00399  */
00400 typedef enum
00401 {
00402     FILE_TYPE_UPGRADE_APP   = 0x00,         ///< Internal upgrade application
00403     FILE_TYPE_WIFI_FW       = 0x01,         ///< Wifi firmware binary
00404 
00405     FILE_TYPE_REGULAR_APP   = 0x81,         ///< Regular application
00406 
00407     FILE_TYPE_USER_RANGE_START = 150,       ///< User type start index
00408     FILE_TYPE_USER_RANGE_END = 199,         ///< User type end index
00409 
00410     FILE_TYPE_TEMPORY       = 0xF9,         ///< Temporary file
00411     FILE_TYPE_GPIO_CONFIG   = 0xFA,         ///< GPIO configuration file
00412     FILE_TYPE_COMMAND_HELP  = 0xFB,         ///< WiConnect command help file
00413     FILE_TYPE_SDC_CAPS      = 0xFC,         ///< SDC / goHACK.me file
00414     FILE_TYPE_SETUP_SCRIPT  = 0xFD,         ///< Setup script file
00415     FILE_TYPE_MISC_FIX_LEN  = 0xFE,         ///< Miscellaneous fixed length file
00416     FILE_TYPE_UNKNOWN       = 0xFF,         ///< Unknown file type
00417     FILE_TYPE_ANY           = FILE_TYPE_UNKNOWN
00418 } FileType;
00419 
00420 
00421 // ----------------------------------------------------------------------------
00422 
00423 /**
00424  * @ingroup api_ghm_types
00425  * @brief goHACK.me stream or control value type
00426  */
00427 typedef enum
00428 {
00429     GHM_VALUE_INT,
00430     GHM_VALUE_STR
00431 } GhmElementValueType;
00432 
00433 /**
00434  * @ingroup api_ghm_types
00435  * @brief goHACK.me stream or control value
00436  */
00437 typedef struct
00438 {
00439     const char *elementName;
00440     GhmElementValueType type;
00441     union
00442     {
00443        const char *strValue;
00444        uint32_t intValue;
00445     } u;
00446 } GhmElement;
00447 
00448 /**
00449  * @ingroup api_ghm_types
00450  * @brief Array of goHACK.me stream or control values
00451  */
00452 typedef struct
00453 {
00454     uint16_t count;
00455     GhmElement elements[1];
00456 } GhmElementArray;
00457 
00458 /**
00459  * @ingroup api_ghm_types
00460  * @brief goHACK.me sychronization type
00461  */
00462 typedef enum
00463 {
00464     GHM_SYNC_ALL,           ///< Push and pull all streams and controls
00465     GHM_SYNC_PUSH_ONLY,     ///< Only push streams and controls to remote server
00466     GHM_SYNC_PULL_ONLY      ///< Only pull controls from remote server
00467 } GhmSyncType;
00468 
00469 /**
00470  * @ingroup api_ghm_types
00471  * @brief goHACK.me message GET type
00472  */
00473 typedef enum
00474 {
00475     GHM_MSG_GET_DATA_ONLY,  ///< Only GET the message data
00476     GHM_MSG_GET_BODY,       ///< Get the message body. This is JSON formatted.
00477     GHM_MSG_GET_ALL         ///< Get entire message. This includes headers. Is JSON formatted.
00478 } GhmMessageGetType;
00479 
00480 
00481 
00482 // ----------------------------------------------------------------------------
00483 
00484 
00485 // Forward declarations
00486 
00487 class Wiconnect;
00488 class TimeoutTimer;
00489 class PeriodicTimer;
00490 class QueuedCommand;
00491 class CommandQueue;
00492 class LogFunc;
00493 class ReaderFunc;
00494 class ReaderFuncCallback;
00495 class Callback;
00496 class ScanResult;
00497 class ScanResultList;
00498 class WiconnectSocket;
00499 class WiconnectSerial;
00500 class WiconnectFile;
00501 class FileList;
00502 class Gpio;
00503 class SocketIrqHandlerMap;
00504 class WiconnectUdpServer;
00505 class GhmMessageList;
00506 class GhmMessage;
00507 
00508 }