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