BlynkApi.h

00001 /**
00002  * @file       BlynkApi.h
00003  * @author     Volodymyr Shymanskyy
00004  * @license    This project is released under the MIT License (MIT)
00005  * @copyright  Copyright (c) 2015 Volodymyr Shymanskyy
00006  * @date       Jan 2015
00007  * @brief      High-level functions
00008  *
00009  */
00010 
00011 #ifndef BlynkApi_h
00012 #define BlynkApi_h
00013 
00014 #include <Blynk/BlynkConfig.h>
00015 #include <Blynk/BlynkDebug.h>
00016 #include <Blynk/BlynkParam.h>
00017 #include <Blynk/BlynkTimer.h>
00018 #include <Blynk/BlynkHandlers.h>
00019 #include <Blynk/BlynkProtocolDefs.h>
00020 
00021 #if defined(BLYNK_EXPERIMENTAL)
00022     #include <Blynk/BlynkEveryN.h>
00023 #endif
00024 
00025 /**
00026  * Represents high-level functions of Blynk
00027  */
00028  
00029 template <class Proto>
00030 class BlynkApi
00031 {
00032 public:
00033     BlynkApi() {
00034         BlynkSystemInit();
00035     }
00036 
00037 #ifdef DOXYGEN // These API here are only for the documentation
00038 
00039     /**
00040      * Connects to the server.
00041      * Blocks until connected or timeout happens.
00042      * May take less or more then timeout value.
00043      *
00044      * @param timeout    Connection timeout
00045      * @returns          True if connected to the server
00046      */
00047     bool connect(unsigned long timeout = BLYNK_TIMEOUT_MS*3);
00048 
00049     /**
00050      * Disconnects from the server.
00051      * It will not try to reconnect, until connect() is called
00052      */
00053     void disconnect();
00054 
00055     /**
00056      * @returns          True if connected to the server
00057      */
00058     bool connected ();
00059 
00060     /**
00061      * Performs Blynk-related housekeeping
00062      * and processes incoming commands
00063      *
00064      * @param available  True if there is incoming data to process
00065      *                   Only used when user manages connection manually.
00066      */
00067     bool run(bool available = false);
00068 
00069 #endif // DOXYGEN
00070 
00071     /**
00072      * Sends value to a Virtual Pin
00073      *
00074      * @param pin  Virtual Pin number
00075      * @param data Value to be sent
00076      */
00077     template <typename... Args>
00078     void virtualWrite(int pin, Args... values) {
00079         char mem[BLYNK_MAX_SENDBYTES];
00080         BlynkParam cmd(mem, 0, sizeof(mem));
00081         cmd.add("vw");
00082         cmd.add(pin);
00083         cmd.add_multi(values...);
00084         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_HARDWARE, 0, cmd.getBuffer(), cmd.getLength()-1);
00085     }
00086 
00087     /**
00088      * Sends buffer to a Virtual Pin
00089      *
00090      * @param pin  Virtual Pin number
00091      * @param buff Data buffer
00092      * @param len  Length of data
00093      */
00094     void virtualWriteBinary(int pin, const void* buff, size_t len) {
00095         char mem[8];
00096         BlynkParam cmd(mem, 0, sizeof(mem));
00097         cmd.add("vw");
00098         cmd.add(pin);
00099         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_HARDWARE, 0, cmd.getBuffer(), cmd.getLength(), buff, len);
00100     }
00101 
00102     /**
00103      * Sends BlynkParam to a Virtual Pin
00104      *
00105      * @param pin  Virtual Pin number
00106      * @param param
00107      */
00108     void virtualWrite(int pin, const BlynkParam& param) {
00109         virtualWriteBinary(pin, param.getBuffer(), param.getLength());
00110     }
00111 
00112     void virtualWrite(int pin, const BlynkParamAllocated& param) {
00113         virtualWriteBinary(pin, param.getBuffer(), param.getLength());
00114     }
00115 
00116     /**
00117      * Requests Server to re-send current values for all widgets.
00118      */
00119     void syncAll() {
00120         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_HARDWARE_SYNC);
00121     }
00122 
00123     /**
00124      * Sends internal command
00125      */
00126     template <typename... Args>
00127     void sendInternal(Args... params) {
00128         char mem[BLYNK_MAX_SENDBYTES];
00129         BlynkParam cmd(mem, 0, sizeof(mem));
00130         cmd.add_multi(params...);
00131         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_INTERNAL, 0, cmd.getBuffer(), cmd.getLength()-1);
00132     }
00133 
00134     /**
00135      * Requests App or Server to re-send current value of a Virtual Pin.
00136      * This will probably cause user-defined BLYNK_WRITE handler to be called.
00137      *
00138      * @param pin Virtual Pin number
00139      */
00140     template <typename... Args>
00141     void syncVirtual(Args... pins) {
00142         char mem[BLYNK_MAX_SENDBYTES];
00143         BlynkParam cmd(mem, 0, sizeof(mem));
00144         cmd.add("vr");
00145         cmd.add_multi(pins...);
00146         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_HARDWARE_SYNC, 0, cmd.getBuffer(), cmd.getLength()-1);
00147     }
00148 
00149     /**
00150      * Tweets a message
00151      *
00152      * @param msg Text of the message
00153      */
00154     template<typename T>
00155     void tweet(const T& msg) {
00156         char mem[BLYNK_MAX_SENDBYTES];
00157         BlynkParam cmd(mem, 0, sizeof(mem));
00158         cmd.add(msg);
00159         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_TWEET, 0, cmd.getBuffer(), cmd.getLength()-1);
00160     }
00161 
00162     /**
00163      * Sends a push notification to the App
00164      *
00165      * @param msg Text of the message
00166      */
00167     template<typename T>
00168     void notify(const T& msg) {
00169         char mem[BLYNK_MAX_SENDBYTES];
00170         BlynkParam cmd(mem, 0, sizeof(mem));
00171         cmd.add(msg);
00172         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_NOTIFY, 0, cmd.getBuffer(), cmd.getLength()-1);
00173     }
00174 
00175     /**
00176      * Sends an SMS
00177      *
00178      * @param msg Text of the message
00179      */
00180     template<typename T>
00181     void sms(const T& msg) {
00182         char mem[BLYNK_MAX_SENDBYTES];
00183         BlynkParam cmd(mem, 0, sizeof(mem));
00184         cmd.add(msg);
00185         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_SMS, 0, cmd.getBuffer(), cmd.getLength()-1);
00186     }
00187 
00188     /**
00189      * Sends an email message
00190      *
00191      * @param email   Email to send to
00192      * @param subject Subject of message
00193      * @param msg     Text of the message
00194      */
00195     template <typename T1, typename T2>
00196     void email(const char* email, const T1& subject, const T2& msg) {
00197         char mem[BLYNK_MAX_SENDBYTES];
00198         BlynkParam cmd(mem, 0, sizeof(mem));
00199         cmd.add(email);
00200         cmd.add(subject);
00201         cmd.add(msg);
00202         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_EMAIL, 0, cmd.getBuffer(), cmd.getLength()-1);
00203     }
00204 
00205     /**
00206      * Sends an email message
00207      *
00208      * @param subject Subject of message
00209      * @param msg     Text of the message
00210      */
00211     template <typename T1, typename T2>
00212     void email(const T1& subject, const T2& msg) {
00213         char mem[BLYNK_MAX_SENDBYTES];
00214         BlynkParam cmd(mem, 0, sizeof(mem));
00215         cmd.add(subject);
00216         cmd.add(msg);
00217         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_EMAIL, 0, cmd.getBuffer(), cmd.getLength()-1);
00218     }
00219 
00220     /**
00221      * Sets property of a Widget
00222      *
00223      * @experimental
00224      *
00225      * @param pin      Virtual Pin number
00226      * @param property Property name ("label", "labels", "color", ...)
00227      * @param value    Property value
00228      */
00229     template <typename T, typename... Args>
00230     void setProperty(int pin, const T& property, Args... values) {
00231         char mem[BLYNK_MAX_SENDBYTES];
00232         BlynkParam cmd(mem, 0, sizeof(mem));
00233         cmd.add(pin);
00234         cmd.add(property);
00235         cmd.add_multi(values...);
00236         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_PROPERTY, 0, cmd.getBuffer(), cmd.getLength()-1);
00237     }
00238 
00239     template <typename T>
00240     void setProperty(int pin, const T& property, const BlynkParam& param) {
00241         char mem[32];
00242         BlynkParam cmd(mem, 0, sizeof(mem));
00243         cmd.add(pin);
00244         cmd.add(property);
00245         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_PROPERTY, 0, cmd.getBuffer(), cmd.getLength(), param.getBuffer(), param.getLength());
00246     }
00247 
00248     template <typename T>
00249     void setProperty(int pin, const T& property, const BlynkParamAllocated& param) {
00250         char mem[32];
00251         BlynkParam cmd(mem, 0, sizeof(mem));
00252         cmd.add(pin);
00253         cmd.add(property);
00254         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_PROPERTY, 0, cmd.getBuffer(), cmd.getLength(), param.getBuffer(), param.getLength());
00255     }
00256 
00257     template <typename NAME>
00258     void logEvent(const NAME& event_name) {
00259         char mem[BLYNK_MAX_SENDBYTES];
00260         BlynkParam cmd(mem, 0, sizeof(mem));
00261         cmd.add(event_name);
00262         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_EVENT_LOG, 0, cmd.getBuffer(), cmd.getLength());
00263     }
00264 
00265     template <typename NAME, typename DESCR>
00266     void logEvent(const NAME& event_name, const DESCR& description) {
00267         char mem[BLYNK_MAX_SENDBYTES];
00268         BlynkParam cmd(mem, 0, sizeof(mem));
00269         cmd.add(event_name);
00270         cmd.add(description);
00271         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_EVENT_LOG, 0, cmd.getBuffer(), cmd.getLength());
00272     }
00273 
00274 #if defined(BLYNK_EXPERIMENTAL)
00275     // Attention!
00276     // Every function in this section may be changed, removed or renamed.
00277 
00278     /**
00279      * Refreshes value of a widget by running
00280      * user-defined BLYNK_READ handler of a pin.
00281      *
00282      * @experimental
00283      *
00284      * @param pin Virtual Pin number
00285      */
00286     void refresh(int pin) {
00287         if (WidgetReadHandler handler = GetReadHandler(pin)) {
00288             BlynkReq req = { 0, BLYNK_SUCCESS, (uint8_t)pin };
00289             handler(req);
00290         }
00291     }
00292 
00293     /**
00294      * Delays for N milliseconds, handling server communication in background.
00295      *
00296      * @experimental
00297      * @warning Should be used very carefully, especially on platforms with small RAM.
00298      *
00299      * @param ms Milliseconds to wait
00300      */
00301     void delay(unsigned long ms) {
00302         uint16_t start = (uint16_t)micros();
00303         while (ms > 0) {
00304             static_cast<Proto*>(this)->run();
00305 #if !defined(BLYNK_NO_YIELD)
00306             yield();
00307 #endif
00308             if (((uint16_t)micros() - start) >= 1000) {
00309                 ms--;
00310                 start += 1000;
00311             }
00312         }
00313     }
00314 
00315 #endif
00316 
00317 protected:
00318     void processCmd(const void* buff, size_t len);
00319     void sendInfo();
00320 };
00321 
00322 
00323 #endif