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 GhmInterface.h Source File

GhmInterface.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 "Wiconnect.h"
00032 
00033 #include "api/types/WiconnectSocket.h"
00034 #include "api/types/GhmMessageList.h"
00035 
00036 /**
00037  * @namespace wiconnect
00038  */
00039 namespace wiconnect {
00040 
00041 /**
00042  * @ingroup api_ghm_macro
00043  * @brief Helper macro for adding an integer value to a @ref GhmElementArray
00044  */
00045 #define GHM_ADD_INT(array, name, integerVal)            \
00046 {                                                       \
00047     array.elementName = name;                           \
00048     array.type = GHM_VALUE_INT;                         \
00049     array.u.intValue = (uint32_t)integerVal;            \
00050 }
00051 
00052 
00053 /**
00054  * @ingroup api_ghm_macro
00055  * @brief Helper macro for adding a string value to a @ref GhmElementArray
00056  */
00057 #define GHM_ADD_STR(array, name, stringVal)             \
00058 {                                                       \
00059     array.elementName = name;                           \
00060     array.type = GHM_VALUE_STR;                         \
00061     array.u.strValue = (const char*)stringVal;          \
00062 }
00063 
00064 
00065 
00066 
00067 /**
00068  * @ingroup api_ghm_types
00069  *
00070  * @brief The provides an interface for http://goHACK.me
00071  *
00072  * The goHACK.me API provided by WiConnect enables monitoring and control of your ACKme device.
00073  * You can set up a goHACK.me account, then using goHACK.me commands and goHACK.me variables,
00074  * you can activate your device and synchronize data, control and messages with the goHACK.me cloud service.
00075  *
00076  * More information here: http://wiconnect.ack.me/2.0/gohackme
00077  *
00078  * @note This class is an interface to the Wiconnect class. It should never be
00079  *       independently instantiated or the parent of another class.
00080  */
00081 class GhmInterface
00082 {
00083 public:
00084 
00085     /**
00086      * @ingroup api_ghm_activate
00087      *
00088      * @brief Download a device capabilities file to WiFi module's internal
00089      *        file system.
00090      *
00091      * @param[in] capsNameOrCustomUrl Optional, specify the caps file name or URL to caps file
00092      * @param[in] version Optional, version to set downloaded caps file as
00093      * @return Result of method. See @ref WiconnectResult
00094      */
00095     WiconnectResult ghmDownloadCapabilities(const char *capsNameOrCustomUrl = NULL, uint32_t version = 0);
00096 
00097     /**
00098      * @ingroup api_ghm_activate
00099      *
00100      * @brief Activate WiFi module with http://goHACK.me
00101      *
00102      * @note You must first sign-up with http://goHACK.me before you can
00103      *       activate the device. Go to http://goHACK.me to sign-up.
00104      *
00105      * @param[in] userName Your username
00106      * @param[in] password Your password
00107      * @param[in] capsFilename Optional, filename of existing capabilities file on module's internal file system.
00108      * @return Result of method. See @ref WiconnectResult
00109      */
00110     WiconnectResult ghmActivate(const char *userName, const char *password, const char *capsFilename = NULL);
00111 
00112     /**
00113      * @ingroup api_ghm_activate
00114      *
00115      * @brief Deactivate WiFi module with http://goHACK.me
00116      *
00117      * @note You must first sign-up with http://goHACK.me before you can
00118      *       deactivate the device. Go to http://goHACK.me to sign-up.
00119      *
00120      * @param[in] userName Your username
00121      * @param[in] password Your password
00122      * @return Result of method. See @ref WiconnectResult
00123      */
00124     WiconnectResult ghmDeactivate(const char *userName, const char *password);
00125 
00126     /**
00127      * @ingroup api_ghm_activate
00128      *
00129      * @brief Return if WiFi module is activated with http://goHACK.me
00130      *
00131      * @param[out] statusPtr Pointer to hold activation status.
00132      * @return Result of method. See @ref WiconnectResult
00133      */
00134     WiconnectResult ghmIsActivated(bool *statusPtr);
00135 
00136 
00137     // ------------------------------------------------------------------------
00138 
00139 
00140     /**
00141      * @ingroup api_ghm_com
00142      *
00143      * @brief Read control data from http://goHACK.me
00144      *
00145      * @note The WiFi module must first be activated. See @ref ghmActivate()
00146      *
00147      * @param[in] controlName The name of the control in the activated capabilities file.
00148      * @param[in] valueStrPtr Pointer to pointer to hold control's string value
00149      * @return Result of method. See @ref WiconnectResult
00150      */
00151     WiconnectResult ghmRead(const char *controlName, const char **valueStrPtr);
00152 
00153     /**
00154      * @ingroup api_ghm_com
00155      *
00156      * @brief Read control data from http://goHACK.me
00157      *
00158      * @note The WiFi module must first be activated. See @ref ghmActivate()
00159      *
00160      * @param[in] controlName The name of the control in the activated capabilities file.
00161      * @param[in] valueIntPtr Pointer hold control's integer value
00162      * @return Result of method. See @ref WiconnectResult
00163      */
00164     WiconnectResult ghmRead(const char *controlName, uint32_t *valueIntPtr);
00165 
00166     /**
00167      * @ingroup api_ghm_com
00168      *
00169      * @brief Read control data from http://goHACK.me
00170      *
00171      * @note The WiFi module must first be activated. See @ref ghmActivate()
00172      *
00173      * @param[in] controlName The name of the control in the activated capabilities file.
00174      * @param[in] valueBuffer Buffer to hold control's string value
00175      * @param[in] valueBufferLen Length of valueBuffer
00176      * @return Result of method. See @ref WiconnectResult
00177      */
00178     WiconnectResult ghmRead(const char *controlName, char *valueBuffer, uint16_t valueBufferLen);
00179 
00180     /**
00181      * @ingroup api_ghm_com
00182      *
00183      * @brief Write stream or control data to http://goHACK.me
00184      *
00185      * @note The WiFi module must first be activated. See @ref ghmActivate()
00186      *
00187      * @param[in] elementName The name of the control or stream in the activated capabilities file.
00188      * @param[in] strValue String value of control or stream
00189      * @return Result of method. See @ref WiconnectResult
00190      */
00191     WiconnectResult ghmWrite(const char *elementName, const char *strValue);
00192 
00193     /**
00194      * @ingroup api_ghm_com
00195      *
00196      * @brief Write stream or control data to http://goHACK.me
00197      *
00198      * @note The WiFi module must first be activated. See @ref ghmActivate()
00199      *
00200      * @param[in] elementName The name of the control or stream in the activated capabilities file.
00201      * @param[in] uintValue Unsigned integer value of control or stream
00202      * @return Result of method. See @ref WiconnectResult
00203      */
00204     WiconnectResult ghmWrite(const char *elementName, uint32_t uintValue);
00205 
00206     /**
00207      * @ingroup api_ghm_com
00208      *
00209      * @brief Write stream or control data to http://goHACK.me
00210      *
00211      * @note The WiFi module must first be activated. See @ref ghmActivate()
00212      *
00213      * @param[in] elementName The name of the control or stream in the activated capabilities file.
00214      * @param[in] intValue signed integer value of control or stream
00215      * @return Result of method. See @ref WiconnectResult
00216      */
00217     WiconnectResult ghmWrite(const char *elementName, int32_t intValue);
00218 
00219     /**
00220      * @ingroup api_ghm_com
00221      *
00222      * @brief Write stream or control data to http://goHACK.me
00223      *
00224      * @note The WiFi module must first be activated. See @ref ghmActivate()
00225      *
00226      * @param[in] elementArray Array of stream and/or control values to send to http://goHACK.me
00227      * @return Result of method. See @ref WiconnectResult
00228      */
00229     WiconnectResult ghmWrite(const GhmElementArray *elementArray);
00230 
00231     /**
00232      * @ingroup api_ghm_com
00233      *
00234      * @brief Synchronize WiFi module with http://goHACK.me
00235      *
00236      * @note The WiFi module must first be activated. See @ref ghmActivate()
00237      *
00238      * @param[in] type Type of synchronization. See @ref GhmSyncType
00239      * @return Result of method. See @ref WiconnectResult
00240      */
00241     WiconnectResult ghmSynchronize(GhmSyncType type = GHM_SYNC_ALL);
00242 
00243 
00244     // ------------------------------------------------------------------------
00245 
00246 
00247     /**
00248      * @ingroup api_ghm_msg
00249      *
00250      * @brief POST message to http://goHACK.me
00251      *
00252      * @note The WiFi module must first be activated. See @ref ghmActivate()
00253      *
00254      * @param[out] socket @ref WiconnectSocket used to send message data to http://goHACK.me
00255      * @param[in] jsonFormatted If true, the input message data should be JSON formatted, else the message data should be ASCII formatted.
00256      * @return Result of method. See @ref WiconnectResult
00257      */
00258     WiconnectResult ghmPostMessage(WiconnectSocket &socket, bool jsonFormatted=false);
00259 
00260     /**
00261      * @ingroup api_ghm_msg
00262      *
00263      * @brief GET message from http://goHACK.me
00264      *
00265      * @note The WiFi module must first be activated. See @ref ghmActivate()
00266      *
00267      * @param[out] socket @ref WiconnectSocket used to receive message data from http://goHACK.me
00268      * @param[in] getType The additional message data to receive. See @ref GhmMessageGetType
00269      * @return Result of method. See @ref WiconnectResult
00270      */
00271     WiconnectResult ghmGetMessage(WiconnectSocket &socket, GhmMessageGetType getType = GHM_MSG_GET_DATA_ONLY);
00272 
00273     /**
00274      * @ingroup api_ghm_msg
00275      *
00276      * @brief GET message from http://goHACK.me
00277      *
00278      * @note @ref ghmListMessages() must be called first before using this method.
00279      *
00280      * @note The WiFi module must first be activated. See @ref ghmActivate()
00281      *
00282      * @param[out] socket @ref WiconnectSocket used to receive message data from http://goHACK.me
00283      * @param[in] listIndex The index of the message returned from ghmListMessages()
00284      * @param[in] getType The additional message data to receive. See @ref GhmMessageGetType
00285      * @return Result of method. See @ref WiconnectResult
00286      */
00287     WiconnectResult ghmGetMessage(WiconnectSocket &socket, uint8_t listIndex, GhmMessageGetType getType = GHM_MSG_GET_DATA_ONLY);
00288 
00289     /**
00290      * @ingroup api_ghm_msg
00291      *
00292      * @brief GET message from http://goHACK.me
00293      *
00294      * @note The WiFi module must first be activated. See @ref ghmActivate()
00295      *
00296      * @param[out] socket @ref WiconnectSocket used to receive message data from http://goHACK.me
00297      * @param[in] msgId The http://goHACK.me message ID.
00298      * @param[in] getType The additional message data to receive. See @ref GhmMessageGetType
00299      * @return Result of method. See @ref WiconnectResult
00300      */
00301     WiconnectResult ghmGetMessage(WiconnectSocket &socket, const char *msgId, GhmMessageGetType getType = GHM_MSG_GET_DATA_ONLY);
00302 
00303     /**
00304      * @ingroup api_ghm_msg
00305      *
00306      * @brief Delete message from http://goHACK.me
00307      *
00308      * @note @ref ghmListMessages() must be called first before using this method.
00309      *
00310      * @note The WiFi module must first be activated. See @ref ghmActivate()
00311      *
00312      * @param[in] listIndex The index of the message returned from ghmListMessages()
00313      * @return Result of method. See @ref WiconnectResult
00314      */
00315     WiconnectResult ghmDeleteMessage(uint8_t listIndex);
00316 
00317     /**
00318      * @ingroup api_ghm_msg
00319      *
00320      * @brief Delete message from http://goHACK.me
00321      *
00322      * @note The WiFi module must first be activated. See @ref ghmActivate()
00323      *
00324      * @param[in] msgId The http://goHACK.me message ID.
00325      * @return Result of method. See @ref WiconnectResult
00326      */
00327     WiconnectResult ghmDeleteMessage(const char *msgId);
00328 
00329     /**
00330      * @ingroup api_ghm_msg
00331      *
00332      * @brief List available messages for device on http://goHACK.me
00333      *
00334      * @note The WiFi module must first be activated. See @ref ghmActivate()
00335      *
00336      * @param[out] msgList @ref GhmMessageList to hold received messages.
00337      * @param[in] maxCount Optional, the maximum number of messages to receive. If 0,
00338      *            receive all messages (max of 25).
00339      * @return Result of method. See @ref WiconnectResult
00340      */
00341     WiconnectResult ghmListMessages(GhmMessageList &msgList, uint8_t maxCount = 0);
00342 
00343 
00344 protected:
00345     GhmInterface(Wiconnect *wiconnect);
00346 
00347     WiconnectResult ghmGetMessage(WiconnectSocket &socket, uint8_t listIndex, const char *msgId, GhmMessageGetType getType);
00348     WiconnectResult processMessageList(char *resultStr, GhmMessageList &resultList);
00349 
00350 private:
00351     Wiconnect *wiconnect;
00352 
00353 };
00354 
00355 
00356 }