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/BlynkHandlers.h>
00018 #include <Blynk/BlynkProtocolDefs.h>
00019 
00020 /**
00021  * Represents high-level functions of Blynk
00022  */
00023 template <class Proto>
00024 class BlynkApi
00025 {
00026 public:
00027     BlynkApi() {
00028         Init();
00029     }
00030 
00031 #ifdef DOXYGEN // These API here are only for the documentation
00032 
00033     /**
00034      * Connects to the server.
00035      * Blocks until connected or timeout happens.
00036      * May take less or more then timeout value.
00037      *
00038      * @param timeout    Connection timeout
00039      * @returns          True if connected to the server
00040      */
00041     bool connect(unsigned long timeout = BLYNK_TIMEOUT_MS*3);
00042 
00043     /**
00044      * Disconnects from the server.
00045      * It will not try to reconnect, until connect() is called
00046      */
00047     void disconnect();
00048 
00049     /**
00050      * @returns          True if connected to the server
00051      */
00052     bool connected ();
00053 
00054     /**
00055      * Performs Blynk-related housekeeping
00056      * and processes incoming commands
00057      *
00058      * @param available  True if there is incoming data to process
00059      *                   Only used when user manages connection manually.
00060      */
00061     bool run(bool available = false);
00062 
00063 #endif // DOXYGEN
00064 
00065     /**
00066      * Sends value to a Virtual Pin
00067      *
00068      * @param pin  Virtual Pin number
00069      * @param data Value to be sent
00070      */
00071     template <typename T>
00072     void virtualWrite(int pin, const T& data) {
00073         //pc.printf("Enter virtualWrite,pin:%d, data=%f\r\n", pin, data);
00074         char mem[BLYNK_MAX_SENDBYTES];
00075         BlynkParam cmd(mem, 0, sizeof(mem));
00076         cmd.add("vw");
00077         cmd.add(pin);
00078         cmd.add(data);
00079         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_HARDWARE, 0, cmd.getBuffer(), cmd.getLength()-1);
00080     }
00081 
00082     template <typename T1, typename T2>
00083     void virtualWrite(int pin, const T1& data1, const T2& data2) {
00084         char mem[BLYNK_MAX_SENDBYTES];
00085         BlynkParam cmd(mem, 0, sizeof(mem));
00086         cmd.add("vw");
00087         cmd.add(pin);
00088         cmd.add(data1);
00089         cmd.add(data2);
00090         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_HARDWARE, 0, cmd.getBuffer(), cmd.getLength()-1);
00091     }
00092 
00093     template <typename T1, typename T2, typename T3>
00094     void virtualWrite(int pin, const T1& data1, const T2& data2, const T3& data3) {
00095         char mem[BLYNK_MAX_SENDBYTES];
00096         BlynkParam cmd(mem, 0, sizeof(mem));
00097         cmd.add("vw");
00098         cmd.add(pin);
00099         cmd.add(data1);
00100         cmd.add(data2);
00101         cmd.add(data3);
00102         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_HARDWARE, 0, cmd.getBuffer(), cmd.getLength()-1);
00103     }
00104 
00105     template <typename T1, typename T2, typename T3, typename T4>
00106     void virtualWrite(int pin, const T1& data1, const T2& data2, const T3& data3, const T4& data4) {
00107         char mem[BLYNK_MAX_SENDBYTES];
00108         BlynkParam cmd(mem, 0, sizeof(mem));
00109         cmd.add("vw");
00110         cmd.add(pin);
00111         cmd.add(data1);
00112         cmd.add(data2);
00113         cmd.add(data3);
00114         cmd.add(data4);
00115         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_HARDWARE, 0, cmd.getBuffer(), cmd.getLength()-1);
00116     }
00117 
00118     /**
00119      * Sends buffer to a Virtual Pin
00120      *
00121      * @param pin  Virtual Pin number
00122      * @param buff Data buffer
00123      * @param len  Length of data
00124      */
00125     void virtualWriteBinary(int pin, const void* buff, size_t len) {
00126         char mem[8];
00127         BlynkParam cmd(mem, 0, sizeof(mem));
00128         cmd.add("vw");
00129         cmd.add(pin);
00130         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_HARDWARE, 0, cmd.getBuffer(), cmd.getLength(), buff, len);
00131     }
00132 
00133     /**
00134      * Sends BlynkParam to a Virtual Pin
00135      *
00136      * @param pin  Virtual Pin number
00137      * @param param
00138      */
00139     void virtualWrite(int pin, const BlynkParam& param) {
00140         virtualWriteBinary(pin, param.getBuffer(), param.getLength());
00141     }
00142 
00143     /**
00144      * Requests Server to re-send current values for all widgets.
00145      */
00146     void syncAll() {
00147         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_HARDWARE_SYNC);
00148     }
00149 
00150     /**
00151      * Requests App or Server to re-send current value of a Virtual Pin.
00152      * This will probably cause user-defined BLYNK_WRITE handler to be called.
00153      *
00154      * @param pin Virtual Pin number
00155      */
00156     void syncVirtual(int pin) {
00157         char mem[8];
00158         BlynkParam cmd(mem, 0, sizeof(mem));
00159         cmd.add("vr");
00160         cmd.add(pin);
00161         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_HARDWARE_SYNC, 0, cmd.getBuffer(), cmd.getLength()-1);
00162     }
00163 
00164     /**
00165      * Tweets a message
00166      *
00167      * @param msg Text of the message
00168      */
00169     template<typename T>
00170     void tweet(const T& msg) {
00171         char mem[BLYNK_MAX_SENDBYTES];
00172         BlynkParam cmd(mem, 0, sizeof(mem));
00173         cmd.add(msg);
00174         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_TWEET, 0, cmd.getBuffer(), cmd.getLength()-1);
00175     }
00176 
00177     /**
00178      * Sends a push notification to the App
00179      *
00180      * @param msg Text of the message
00181      */
00182     template<typename T>
00183     void notify(const T& msg) {
00184         char mem[BLYNK_MAX_SENDBYTES];
00185         BlynkParam cmd(mem, 0, sizeof(mem));
00186         cmd.add(msg);
00187         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_NOTIFY, 0, cmd.getBuffer(), cmd.getLength()-1);
00188     }
00189 
00190     /**
00191      * Sends an SMS
00192      *
00193      * @param msg Text of the message
00194      */
00195     template<typename T>
00196     void sms(const T& msg) {
00197         char mem[BLYNK_MAX_SENDBYTES];
00198         BlynkParam cmd(mem, 0, sizeof(mem));
00199         cmd.add(msg);
00200         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_SMS, 0, cmd.getBuffer(), cmd.getLength()-1);
00201     }
00202 
00203     /**
00204      * Sends an email message
00205      *
00206      * @param email   Email to send to
00207      * @param subject Subject of message
00208      * @param msg     Text of the message
00209      */
00210     template <typename T1, typename T2>
00211     void email(const char* email, const T1& subject, const T2& msg) {
00212         char mem[BLYNK_MAX_SENDBYTES];
00213         BlynkParam cmd(mem, 0, sizeof(mem));
00214         cmd.add(email);
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      * Sends an email message
00222      *
00223      * @param subject Subject of message
00224      * @param msg     Text of the message
00225      */
00226     template <typename T1, typename T2>
00227     void email(const T1& subject, const T2& msg) {
00228         char mem[BLYNK_MAX_SENDBYTES];
00229         BlynkParam cmd(mem, 0, sizeof(mem));
00230         cmd.add(subject);
00231         cmd.add(msg);
00232         static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_EMAIL, 0, cmd.getBuffer(), cmd.getLength()-1);
00233     }
00234 
00235 #if defined(BLYNK_EXPERIMENTAL)
00236     // Attention!
00237     // Every function in this section may be changed, removed or renamed.
00238 
00239     /**
00240      * Refreshes value of a widget by running
00241      * user-defined BLYNK_READ handler of a pin.
00242      *
00243      * @experimental
00244      *
00245      * @param pin Virtual Pin number
00246      */
00247     void refresh(int pin) {
00248         if (WidgetReadHandler handler = GetReadHandler(pin)) {
00249             BlynkReq req = { 0, BLYNK_SUCCESS, (uint8_t)pin };
00250             handler(req);
00251         }
00252     }
00253 
00254     /**
00255      * Delays for N milliseconds, handling server communication in background.
00256      *
00257      * @experimental
00258      * @warning Should be used very carefully, especially on platforms with small RAM.
00259      *
00260      * @param ms Milliseconds to wait
00261      */
00262     void delay(unsigned long ms) {
00263         uint16_t start = (uint16_t)micros();
00264         while (ms > 0) {
00265             static_cast<Proto*>(this)->run();
00266 #if !defined(BLYNK_NO_YIELD)
00267             yield();
00268 #endif
00269             if (((uint16_t)micros() - start) >= 1000) {
00270                 ms--;
00271                 start += 1000;
00272             }
00273         }
00274     }
00275 
00276 #endif
00277 
00278 protected:
00279     void Init();
00280     static millis_time_t getMillis();
00281     void processCmd(const void* buff, size_t len);
00282     void sendInfo();
00283 
00284 };
00285 
00286 
00287 #endif
00288