Blynk library for embedded hardware. Works with Arduino, ESP8266, Raspberry Pi, Intel Edison/Galileo, LinkIt ONE, Particle Core/Photon, Energia, ARM mbed, etc. http://www.blynk.cc/

Dependents:   Blynk_RBL_BLE_Nano Blynk_MicroBit Blynk_Serial Blynk_RBL_BLE_Nano

Committer:
Volodymyr Shymanskyy
Date:
Thu Jan 12 02:10:58 2017 +0200
Revision:
10:c241e4227173
Parent:
9:7369ec77a3ea
Child:
13:ed6276c0afb7
Update

Who changed what in which revision?

UserRevisionLine numberNew contents of line
vshymanskyy 0:58b20b438383 1 /**
vshymanskyy 0:58b20b438383 2 * @file BlynkApi.h
vshymanskyy 0:58b20b438383 3 * @author Volodymyr Shymanskyy
vshymanskyy 0:58b20b438383 4 * @license This project is released under the MIT License (MIT)
vshymanskyy 0:58b20b438383 5 * @copyright Copyright (c) 2015 Volodymyr Shymanskyy
vshymanskyy 0:58b20b438383 6 * @date Jan 2015
vshymanskyy 0:58b20b438383 7 * @brief High-level functions
vshymanskyy 0:58b20b438383 8 *
vshymanskyy 0:58b20b438383 9 */
vshymanskyy 0:58b20b438383 10
vshymanskyy 0:58b20b438383 11 #ifndef BlynkApi_h
vshymanskyy 0:58b20b438383 12 #define BlynkApi_h
vshymanskyy 0:58b20b438383 13
vshymanskyy 0:58b20b438383 14 #include <Blynk/BlynkConfig.h>
vshymanskyy 0:58b20b438383 15 #include <Blynk/BlynkDebug.h>
vshymanskyy 0:58b20b438383 16 #include <Blynk/BlynkParam.h>
vshymanskyy 0:58b20b438383 17 #include <Blynk/BlynkHandlers.h>
vshymanskyy 0:58b20b438383 18 #include <Blynk/BlynkProtocolDefs.h>
vshymanskyy 0:58b20b438383 19
vshymanskyy 0:58b20b438383 20 /**
vshymanskyy 0:58b20b438383 21 * Represents high-level functions of Blynk
vshymanskyy 0:58b20b438383 22 */
vshymanskyy 0:58b20b438383 23 template <class Proto>
vshymanskyy 0:58b20b438383 24 class BlynkApi
vshymanskyy 0:58b20b438383 25 {
vshymanskyy 0:58b20b438383 26 public:
vshymanskyy 0:58b20b438383 27 BlynkApi() {
vshymanskyy 0:58b20b438383 28 Init();
vshymanskyy 0:58b20b438383 29 }
vshymanskyy 0:58b20b438383 30
vshymanskyy 0:58b20b438383 31 #ifdef DOXYGEN // These API here are only for the documentation
vshymanskyy 0:58b20b438383 32
vshymanskyy 0:58b20b438383 33 /**
vshymanskyy 0:58b20b438383 34 * Connects to the server.
vshymanskyy 0:58b20b438383 35 * Blocks until connected or timeout happens.
vshymanskyy 0:58b20b438383 36 * May take less or more then timeout value.
vshymanskyy 0:58b20b438383 37 *
vshymanskyy 0:58b20b438383 38 * @param timeout Connection timeout
vshymanskyy 0:58b20b438383 39 * @returns True if connected to the server
vshymanskyy 0:58b20b438383 40 */
vshymanskyy 0:58b20b438383 41 bool connect(unsigned long timeout = BLYNK_TIMEOUT_MS*3);
vshymanskyy 0:58b20b438383 42
vshymanskyy 0:58b20b438383 43 /**
vshymanskyy 0:58b20b438383 44 * Disconnects from the server.
vshymanskyy 0:58b20b438383 45 * It will not try to reconnect, until connect() is called
vshymanskyy 0:58b20b438383 46 */
vshymanskyy 0:58b20b438383 47 void disconnect();
vshymanskyy 0:58b20b438383 48
vshymanskyy 0:58b20b438383 49 /**
vshymanskyy 0:58b20b438383 50 * @returns True if connected to the server
vshymanskyy 0:58b20b438383 51 */
vshymanskyy 0:58b20b438383 52 bool connected();
vshymanskyy 0:58b20b438383 53
vshymanskyy 0:58b20b438383 54 /**
vshymanskyy 0:58b20b438383 55 * Performs Blynk-related housekeeping
vshymanskyy 0:58b20b438383 56 * and processes incoming commands
vshymanskyy 0:58b20b438383 57 *
vshymanskyy 0:58b20b438383 58 * @param available True if there is incoming data to process
vshymanskyy 0:58b20b438383 59 * Only used when user manages connection manually.
vshymanskyy 0:58b20b438383 60 */
vshymanskyy 0:58b20b438383 61 bool run(bool available = false);
vshymanskyy 0:58b20b438383 62
vshymanskyy 0:58b20b438383 63 #endif // DOXYGEN
vshymanskyy 0:58b20b438383 64
vshymanskyy 0:58b20b438383 65 /**
vshymanskyy 0:58b20b438383 66 * Sends value to a Virtual Pin
vshymanskyy 0:58b20b438383 67 *
vshymanskyy 0:58b20b438383 68 * @param pin Virtual Pin number
vshymanskyy 0:58b20b438383 69 * @param data Value to be sent
vshymanskyy 0:58b20b438383 70 */
Volodymyr Shymanskyy 9:7369ec77a3ea 71 template <typename... Args>
Volodymyr Shymanskyy 9:7369ec77a3ea 72 void virtualWrite(int pin, Args... values) {
vshymanskyy 0:58b20b438383 73 char mem[BLYNK_MAX_SENDBYTES];
vshymanskyy 0:58b20b438383 74 BlynkParam cmd(mem, 0, sizeof(mem));
vshymanskyy 0:58b20b438383 75 cmd.add("vw");
vshymanskyy 0:58b20b438383 76 cmd.add(pin);
Volodymyr Shymanskyy 9:7369ec77a3ea 77 cmd.add_multi(values...);
vshymanskyy 0:58b20b438383 78 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_HARDWARE, 0, cmd.getBuffer(), cmd.getLength()-1);
vshymanskyy 0:58b20b438383 79 }
vshymanskyy 0:58b20b438383 80
vshymanskyy 0:58b20b438383 81 /**
vshymanskyy 0:58b20b438383 82 * Sends buffer to a Virtual Pin
vshymanskyy 0:58b20b438383 83 *
vshymanskyy 0:58b20b438383 84 * @param pin Virtual Pin number
vshymanskyy 0:58b20b438383 85 * @param buff Data buffer
vshymanskyy 0:58b20b438383 86 * @param len Length of data
vshymanskyy 0:58b20b438383 87 */
vshymanskyy 0:58b20b438383 88 void virtualWriteBinary(int pin, const void* buff, size_t len) {
vshymanskyy 0:58b20b438383 89 char mem[8];
vshymanskyy 0:58b20b438383 90 BlynkParam cmd(mem, 0, sizeof(mem));
vshymanskyy 0:58b20b438383 91 cmd.add("vw");
vshymanskyy 0:58b20b438383 92 cmd.add(pin);
vshymanskyy 0:58b20b438383 93 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_HARDWARE, 0, cmd.getBuffer(), cmd.getLength(), buff, len);
vshymanskyy 0:58b20b438383 94 }
vshymanskyy 0:58b20b438383 95
vshymanskyy 0:58b20b438383 96 /**
vshymanskyy 0:58b20b438383 97 * Sends BlynkParam to a Virtual Pin
vshymanskyy 0:58b20b438383 98 *
vshymanskyy 0:58b20b438383 99 * @param pin Virtual Pin number
vshymanskyy 0:58b20b438383 100 * @param param
vshymanskyy 0:58b20b438383 101 */
vshymanskyy 0:58b20b438383 102 void virtualWrite(int pin, const BlynkParam& param) {
vshymanskyy 0:58b20b438383 103 virtualWriteBinary(pin, param.getBuffer(), param.getLength());
vshymanskyy 0:58b20b438383 104 }
vshymanskyy 0:58b20b438383 105
Volodymyr Shymanskyy 9:7369ec77a3ea 106 void virtualWrite(int pin, const BlynkParamAllocated& param) {
Volodymyr Shymanskyy 9:7369ec77a3ea 107 virtualWriteBinary(pin, param.getBuffer(), param.getLength());
Volodymyr Shymanskyy 9:7369ec77a3ea 108 }
Volodymyr Shymanskyy 9:7369ec77a3ea 109
vshymanskyy 0:58b20b438383 110 /**
vshymanskyy 0:58b20b438383 111 * Requests Server to re-send current values for all widgets.
vshymanskyy 0:58b20b438383 112 */
vshymanskyy 0:58b20b438383 113 void syncAll() {
vshymanskyy 0:58b20b438383 114 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_HARDWARE_SYNC);
vshymanskyy 0:58b20b438383 115 }
vshymanskyy 0:58b20b438383 116
vshymanskyy 0:58b20b438383 117 /**
Volodymyr Shymanskyy 10:c241e4227173 118 * Sends internal command
Volodymyr Shymanskyy 10:c241e4227173 119 */
Volodymyr Shymanskyy 10:c241e4227173 120 template <typename... Args>
Volodymyr Shymanskyy 10:c241e4227173 121 void sendInternal(Args... params) {
Volodymyr Shymanskyy 10:c241e4227173 122 char mem[BLYNK_MAX_SENDBYTES];
Volodymyr Shymanskyy 10:c241e4227173 123 BlynkParam cmd(mem, 0, sizeof(mem));
Volodymyr Shymanskyy 10:c241e4227173 124 cmd.add_multi(params...);
Volodymyr Shymanskyy 10:c241e4227173 125 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_INTERNAL, 0, cmd.getBuffer(), cmd.getLength()-1);
Volodymyr Shymanskyy 10:c241e4227173 126 }
Volodymyr Shymanskyy 10:c241e4227173 127
Volodymyr Shymanskyy 10:c241e4227173 128 /**
vshymanskyy 0:58b20b438383 129 * Requests App or Server to re-send current value of a Virtual Pin.
vshymanskyy 0:58b20b438383 130 * This will probably cause user-defined BLYNK_WRITE handler to be called.
vshymanskyy 0:58b20b438383 131 *
vshymanskyy 0:58b20b438383 132 * @param pin Virtual Pin number
vshymanskyy 0:58b20b438383 133 */
Volodymyr Shymanskyy 9:7369ec77a3ea 134 template <typename... Args>
Volodymyr Shymanskyy 9:7369ec77a3ea 135 void syncVirtual(Args... pins) {
Volodymyr Shymanskyy 9:7369ec77a3ea 136 char mem[BLYNK_MAX_SENDBYTES];
vshymanskyy 0:58b20b438383 137 BlynkParam cmd(mem, 0, sizeof(mem));
vshymanskyy 0:58b20b438383 138 cmd.add("vr");
Volodymyr Shymanskyy 9:7369ec77a3ea 139 cmd.add_multi(pins...);
vshymanskyy 0:58b20b438383 140 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_HARDWARE_SYNC, 0, cmd.getBuffer(), cmd.getLength()-1);
vshymanskyy 0:58b20b438383 141 }
vshymanskyy 0:58b20b438383 142
vshymanskyy 0:58b20b438383 143 /**
vshymanskyy 0:58b20b438383 144 * Tweets a message
vshymanskyy 0:58b20b438383 145 *
vshymanskyy 0:58b20b438383 146 * @param msg Text of the message
vshymanskyy 0:58b20b438383 147 */
vshymanskyy 0:58b20b438383 148 template<typename T>
vshymanskyy 0:58b20b438383 149 void tweet(const T& msg) {
vshymanskyy 0:58b20b438383 150 char mem[BLYNK_MAX_SENDBYTES];
vshymanskyy 0:58b20b438383 151 BlynkParam cmd(mem, 0, sizeof(mem));
vshymanskyy 0:58b20b438383 152 cmd.add(msg);
vshymanskyy 0:58b20b438383 153 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_TWEET, 0, cmd.getBuffer(), cmd.getLength()-1);
vshymanskyy 0:58b20b438383 154 }
vshymanskyy 0:58b20b438383 155
vshymanskyy 0:58b20b438383 156 /**
vshymanskyy 0:58b20b438383 157 * Sends a push notification to the App
vshymanskyy 0:58b20b438383 158 *
vshymanskyy 0:58b20b438383 159 * @param msg Text of the message
vshymanskyy 0:58b20b438383 160 */
vshymanskyy 0:58b20b438383 161 template<typename T>
vshymanskyy 0:58b20b438383 162 void notify(const T& msg) {
vshymanskyy 0:58b20b438383 163 char mem[BLYNK_MAX_SENDBYTES];
vshymanskyy 0:58b20b438383 164 BlynkParam cmd(mem, 0, sizeof(mem));
vshymanskyy 0:58b20b438383 165 cmd.add(msg);
vshymanskyy 0:58b20b438383 166 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_NOTIFY, 0, cmd.getBuffer(), cmd.getLength()-1);
vshymanskyy 0:58b20b438383 167 }
vshymanskyy 0:58b20b438383 168
vshymanskyy 0:58b20b438383 169 /**
vshymanskyy 0:58b20b438383 170 * Sends an SMS
vshymanskyy 0:58b20b438383 171 *
vshymanskyy 0:58b20b438383 172 * @param msg Text of the message
vshymanskyy 0:58b20b438383 173 */
vshymanskyy 0:58b20b438383 174 template<typename T>
vshymanskyy 0:58b20b438383 175 void sms(const T& msg) {
vshymanskyy 0:58b20b438383 176 char mem[BLYNK_MAX_SENDBYTES];
vshymanskyy 0:58b20b438383 177 BlynkParam cmd(mem, 0, sizeof(mem));
vshymanskyy 0:58b20b438383 178 cmd.add(msg);
vshymanskyy 0:58b20b438383 179 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_SMS, 0, cmd.getBuffer(), cmd.getLength()-1);
vshymanskyy 0:58b20b438383 180 }
vshymanskyy 0:58b20b438383 181
vshymanskyy 0:58b20b438383 182 /**
vshymanskyy 0:58b20b438383 183 * Sends an email message
vshymanskyy 0:58b20b438383 184 *
vshymanskyy 0:58b20b438383 185 * @param email Email to send to
vshymanskyy 0:58b20b438383 186 * @param subject Subject of message
vshymanskyy 0:58b20b438383 187 * @param msg Text of the message
vshymanskyy 0:58b20b438383 188 */
vshymanskyy 0:58b20b438383 189 template <typename T1, typename T2>
vshymanskyy 0:58b20b438383 190 void email(const char* email, const T1& subject, const T2& msg) {
vshymanskyy 0:58b20b438383 191 char mem[BLYNK_MAX_SENDBYTES];
vshymanskyy 0:58b20b438383 192 BlynkParam cmd(mem, 0, sizeof(mem));
vshymanskyy 0:58b20b438383 193 cmd.add(email);
vshymanskyy 0:58b20b438383 194 cmd.add(subject);
vshymanskyy 0:58b20b438383 195 cmd.add(msg);
vshymanskyy 0:58b20b438383 196 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_EMAIL, 0, cmd.getBuffer(), cmd.getLength()-1);
vshymanskyy 0:58b20b438383 197 }
vshymanskyy 0:58b20b438383 198
Volodymyr Shymanskyy 2:c5b857d4f9f6 199 /**
Volodymyr Shymanskyy 2:c5b857d4f9f6 200 * Sends an email message
Volodymyr Shymanskyy 2:c5b857d4f9f6 201 *
Volodymyr Shymanskyy 2:c5b857d4f9f6 202 * @param subject Subject of message
Volodymyr Shymanskyy 2:c5b857d4f9f6 203 * @param msg Text of the message
Volodymyr Shymanskyy 2:c5b857d4f9f6 204 */
Volodymyr Shymanskyy 2:c5b857d4f9f6 205 template <typename T1, typename T2>
Volodymyr Shymanskyy 2:c5b857d4f9f6 206 void email(const T1& subject, const T2& msg) {
Volodymyr Shymanskyy 2:c5b857d4f9f6 207 char mem[BLYNK_MAX_SENDBYTES];
Volodymyr Shymanskyy 2:c5b857d4f9f6 208 BlynkParam cmd(mem, 0, sizeof(mem));
Volodymyr Shymanskyy 2:c5b857d4f9f6 209 cmd.add(subject);
Volodymyr Shymanskyy 2:c5b857d4f9f6 210 cmd.add(msg);
Volodymyr Shymanskyy 2:c5b857d4f9f6 211 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_EMAIL, 0, cmd.getBuffer(), cmd.getLength()-1);
Volodymyr Shymanskyy 2:c5b857d4f9f6 212 }
Volodymyr Shymanskyy 2:c5b857d4f9f6 213
Volodymyr Shymanskyy 7:8879692d4e6c 214 /**
Volodymyr Shymanskyy 7:8879692d4e6c 215 * Sets property of a Widget
Volodymyr Shymanskyy 7:8879692d4e6c 216 *
Volodymyr Shymanskyy 7:8879692d4e6c 217 * @experimental
Volodymyr Shymanskyy 7:8879692d4e6c 218 *
Volodymyr Shymanskyy 7:8879692d4e6c 219 * @param pin Virtual Pin number
Volodymyr Shymanskyy 7:8879692d4e6c 220 * @param property Property name ("label", "labels", "color", ...)
Volodymyr Shymanskyy 7:8879692d4e6c 221 * @param value Property value
Volodymyr Shymanskyy 7:8879692d4e6c 222 */
Volodymyr Shymanskyy 9:7369ec77a3ea 223 template <typename T, typename... Args>
Volodymyr Shymanskyy 9:7369ec77a3ea 224 void setProperty(int pin, const T& property, Args... values) {
Volodymyr Shymanskyy 7:8879692d4e6c 225 char mem[BLYNK_MAX_SENDBYTES];
Volodymyr Shymanskyy 7:8879692d4e6c 226 BlynkParam cmd(mem, 0, sizeof(mem));
Volodymyr Shymanskyy 7:8879692d4e6c 227 cmd.add(pin);
Volodymyr Shymanskyy 7:8879692d4e6c 228 cmd.add(property);
Volodymyr Shymanskyy 9:7369ec77a3ea 229 cmd.add_multi(values...);
Volodymyr Shymanskyy 7:8879692d4e6c 230 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_PROPERTY, 0, cmd.getBuffer(), cmd.getLength()-1);
Volodymyr Shymanskyy 7:8879692d4e6c 231 }
Volodymyr Shymanskyy 7:8879692d4e6c 232
Volodymyr Shymanskyy 7:8879692d4e6c 233 template <typename T>
Volodymyr Shymanskyy 7:8879692d4e6c 234 void setProperty(int pin, const T& property, const BlynkParam& param) {
Volodymyr Shymanskyy 7:8879692d4e6c 235 char mem[32];
Volodymyr Shymanskyy 7:8879692d4e6c 236 BlynkParam cmd(mem, 0, sizeof(mem));
Volodymyr Shymanskyy 7:8879692d4e6c 237 cmd.add(pin);
Volodymyr Shymanskyy 7:8879692d4e6c 238 cmd.add(property);
Volodymyr Shymanskyy 7:8879692d4e6c 239 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_PROPERTY, 0, cmd.getBuffer(), cmd.getLength(), param.getBuffer(), param.getLength());
Volodymyr Shymanskyy 7:8879692d4e6c 240 }
Volodymyr Shymanskyy 7:8879692d4e6c 241
Volodymyr Shymanskyy 7:8879692d4e6c 242 template <typename T>
Volodymyr Shymanskyy 7:8879692d4e6c 243 void setProperty(int pin, const T& property, const BlynkParamAllocated& param) {
Volodymyr Shymanskyy 7:8879692d4e6c 244 char mem[32];
Volodymyr Shymanskyy 7:8879692d4e6c 245 BlynkParam cmd(mem, 0, sizeof(mem));
Volodymyr Shymanskyy 7:8879692d4e6c 246 cmd.add(pin);
Volodymyr Shymanskyy 7:8879692d4e6c 247 cmd.add(property);
Volodymyr Shymanskyy 7:8879692d4e6c 248 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_PROPERTY, 0, cmd.getBuffer(), cmd.getLength(), param.getBuffer(), param.getLength());
Volodymyr Shymanskyy 7:8879692d4e6c 249 }
Volodymyr Shymanskyy 7:8879692d4e6c 250
vshymanskyy 0:58b20b438383 251 #if defined(BLYNK_EXPERIMENTAL)
vshymanskyy 0:58b20b438383 252 // Attention!
vshymanskyy 0:58b20b438383 253 // Every function in this section may be changed, removed or renamed.
vshymanskyy 0:58b20b438383 254
vshymanskyy 0:58b20b438383 255 /**
vshymanskyy 0:58b20b438383 256 * Refreshes value of a widget by running
vshymanskyy 0:58b20b438383 257 * user-defined BLYNK_READ handler of a pin.
vshymanskyy 0:58b20b438383 258 *
vshymanskyy 0:58b20b438383 259 * @experimental
vshymanskyy 0:58b20b438383 260 *
vshymanskyy 0:58b20b438383 261 * @param pin Virtual Pin number
vshymanskyy 0:58b20b438383 262 */
vshymanskyy 0:58b20b438383 263 void refresh(int pin) {
vshymanskyy 0:58b20b438383 264 if (WidgetReadHandler handler = GetReadHandler(pin)) {
vshymanskyy 0:58b20b438383 265 BlynkReq req = { 0, BLYNK_SUCCESS, (uint8_t)pin };
vshymanskyy 0:58b20b438383 266 handler(req);
vshymanskyy 0:58b20b438383 267 }
vshymanskyy 0:58b20b438383 268 }
vshymanskyy 0:58b20b438383 269
vshymanskyy 0:58b20b438383 270 /**
vshymanskyy 0:58b20b438383 271 * Delays for N milliseconds, handling server communication in background.
vshymanskyy 0:58b20b438383 272 *
vshymanskyy 0:58b20b438383 273 * @experimental
vshymanskyy 0:58b20b438383 274 * @warning Should be used very carefully, especially on platforms with small RAM.
vshymanskyy 0:58b20b438383 275 *
vshymanskyy 0:58b20b438383 276 * @param ms Milliseconds to wait
vshymanskyy 0:58b20b438383 277 */
vshymanskyy 0:58b20b438383 278 void delay(unsigned long ms) {
vshymanskyy 0:58b20b438383 279 uint16_t start = (uint16_t)micros();
vshymanskyy 0:58b20b438383 280 while (ms > 0) {
vshymanskyy 0:58b20b438383 281 static_cast<Proto*>(this)->run();
vshymanskyy 0:58b20b438383 282 #if !defined(BLYNK_NO_YIELD)
vshymanskyy 0:58b20b438383 283 yield();
vshymanskyy 0:58b20b438383 284 #endif
vshymanskyy 0:58b20b438383 285 if (((uint16_t)micros() - start) >= 1000) {
vshymanskyy 0:58b20b438383 286 ms--;
vshymanskyy 0:58b20b438383 287 start += 1000;
vshymanskyy 0:58b20b438383 288 }
vshymanskyy 0:58b20b438383 289 }
vshymanskyy 0:58b20b438383 290 }
vshymanskyy 0:58b20b438383 291
vshymanskyy 0:58b20b438383 292 #endif
vshymanskyy 0:58b20b438383 293
vshymanskyy 0:58b20b438383 294 protected:
vshymanskyy 0:58b20b438383 295 void Init();
vshymanskyy 0:58b20b438383 296 static millis_time_t getMillis();
vshymanskyy 0:58b20b438383 297 void processCmd(const void* buff, size_t len);
vshymanskyy 0:58b20b438383 298 void sendInfo();
vshymanskyy 0:58b20b438383 299 };
vshymanskyy 0:58b20b438383 300
vshymanskyy 0:58b20b438383 301
vshymanskyy 0:58b20b438383 302 #endif