Volodymyr Shymanskyy / Blynk Featured

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

Blynk/BlynkApi.h@9:7369ec77a3ea, 2017-01-05 (annotated)

Committer:
Volodymyr Shymanskyy
Date:
Thu Jan 05 14:55:36 2017 +0200
Revision:
9:7369ec77a3ea
Parent:
7:8879692d4e6c
Child:
10:c241e4227173
Update version

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 /**
vshymanskyy 0:58b20b438383 118 * Requests App or Server to re-send current value of a Virtual Pin.
vshymanskyy 0:58b20b438383 119 * This will probably cause user-defined BLYNK_WRITE handler to be called.
vshymanskyy 0:58b20b438383 120 *
vshymanskyy 0:58b20b438383 121 * @param pin Virtual Pin number
vshymanskyy 0:58b20b438383 122 */
Volodymyr Shymanskyy 9:7369ec77a3ea 123 template <typename... Args>
Volodymyr Shymanskyy 9:7369ec77a3ea 124 void syncVirtual(Args... pins) {
Volodymyr Shymanskyy 9:7369ec77a3ea 125 char mem[BLYNK_MAX_SENDBYTES];
vshymanskyy 0:58b20b438383 126 BlynkParam cmd(mem, 0, sizeof(mem));
vshymanskyy 0:58b20b438383 127 cmd.add("vr");
Volodymyr Shymanskyy 9:7369ec77a3ea 128 cmd.add_multi(pins...);
vshymanskyy 0:58b20b438383 129 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_HARDWARE_SYNC, 0, cmd.getBuffer(), cmd.getLength()-1);
vshymanskyy 0:58b20b438383 130 }
vshymanskyy 0:58b20b438383 131
vshymanskyy 0:58b20b438383 132 /**
vshymanskyy 0:58b20b438383 133 * Tweets a message
vshymanskyy 0:58b20b438383 134 *
vshymanskyy 0:58b20b438383 135 * @param msg Text of the message
vshymanskyy 0:58b20b438383 136 */
vshymanskyy 0:58b20b438383 137 template<typename T>
vshymanskyy 0:58b20b438383 138 void tweet(const T& msg) {
vshymanskyy 0:58b20b438383 139 char mem[BLYNK_MAX_SENDBYTES];
vshymanskyy 0:58b20b438383 140 BlynkParam cmd(mem, 0, sizeof(mem));
vshymanskyy 0:58b20b438383 141 cmd.add(msg);
vshymanskyy 0:58b20b438383 142 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_TWEET, 0, cmd.getBuffer(), cmd.getLength()-1);
vshymanskyy 0:58b20b438383 143 }
vshymanskyy 0:58b20b438383 144
vshymanskyy 0:58b20b438383 145 /**
vshymanskyy 0:58b20b438383 146 * Sends a push notification to the App
vshymanskyy 0:58b20b438383 147 *
vshymanskyy 0:58b20b438383 148 * @param msg Text of the message
vshymanskyy 0:58b20b438383 149 */
vshymanskyy 0:58b20b438383 150 template<typename T>
vshymanskyy 0:58b20b438383 151 void notify(const T& msg) {
vshymanskyy 0:58b20b438383 152 char mem[BLYNK_MAX_SENDBYTES];
vshymanskyy 0:58b20b438383 153 BlynkParam cmd(mem, 0, sizeof(mem));
vshymanskyy 0:58b20b438383 154 cmd.add(msg);
vshymanskyy 0:58b20b438383 155 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_NOTIFY, 0, cmd.getBuffer(), cmd.getLength()-1);
vshymanskyy 0:58b20b438383 156 }
vshymanskyy 0:58b20b438383 157
vshymanskyy 0:58b20b438383 158 /**
vshymanskyy 0:58b20b438383 159 * Sends an SMS
vshymanskyy 0:58b20b438383 160 *
vshymanskyy 0:58b20b438383 161 * @param msg Text of the message
vshymanskyy 0:58b20b438383 162 */
vshymanskyy 0:58b20b438383 163 template<typename T>
vshymanskyy 0:58b20b438383 164 void sms(const T& msg) {
vshymanskyy 0:58b20b438383 165 char mem[BLYNK_MAX_SENDBYTES];
vshymanskyy 0:58b20b438383 166 BlynkParam cmd(mem, 0, sizeof(mem));
vshymanskyy 0:58b20b438383 167 cmd.add(msg);
vshymanskyy 0:58b20b438383 168 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_SMS, 0, cmd.getBuffer(), cmd.getLength()-1);
vshymanskyy 0:58b20b438383 169 }
vshymanskyy 0:58b20b438383 170
vshymanskyy 0:58b20b438383 171 /**
vshymanskyy 0:58b20b438383 172 * Sends an email message
vshymanskyy 0:58b20b438383 173 *
vshymanskyy 0:58b20b438383 174 * @param email Email to send to
vshymanskyy 0:58b20b438383 175 * @param subject Subject of message
vshymanskyy 0:58b20b438383 176 * @param msg Text of the message
vshymanskyy 0:58b20b438383 177 */
vshymanskyy 0:58b20b438383 178 template <typename T1, typename T2>
vshymanskyy 0:58b20b438383 179 void email(const char* email, const T1& subject, const T2& msg) {
vshymanskyy 0:58b20b438383 180 char mem[BLYNK_MAX_SENDBYTES];
vshymanskyy 0:58b20b438383 181 BlynkParam cmd(mem, 0, sizeof(mem));
vshymanskyy 0:58b20b438383 182 cmd.add(email);
vshymanskyy 0:58b20b438383 183 cmd.add(subject);
vshymanskyy 0:58b20b438383 184 cmd.add(msg);
vshymanskyy 0:58b20b438383 185 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_EMAIL, 0, cmd.getBuffer(), cmd.getLength()-1);
vshymanskyy 0:58b20b438383 186 }
vshymanskyy 0:58b20b438383 187
Volodymyr Shymanskyy 2:c5b857d4f9f6 188 /**
Volodymyr Shymanskyy 2:c5b857d4f9f6 189 * Sends an email message
Volodymyr Shymanskyy 2:c5b857d4f9f6 190 *
Volodymyr Shymanskyy 2:c5b857d4f9f6 191 * @param subject Subject of message
Volodymyr Shymanskyy 2:c5b857d4f9f6 192 * @param msg Text of the message
Volodymyr Shymanskyy 2:c5b857d4f9f6 193 */
Volodymyr Shymanskyy 2:c5b857d4f9f6 194 template <typename T1, typename T2>
Volodymyr Shymanskyy 2:c5b857d4f9f6 195 void email(const T1& subject, const T2& msg) {
Volodymyr Shymanskyy 2:c5b857d4f9f6 196 char mem[BLYNK_MAX_SENDBYTES];
Volodymyr Shymanskyy 2:c5b857d4f9f6 197 BlynkParam cmd(mem, 0, sizeof(mem));
Volodymyr Shymanskyy 2:c5b857d4f9f6 198 cmd.add(subject);
Volodymyr Shymanskyy 2:c5b857d4f9f6 199 cmd.add(msg);
Volodymyr Shymanskyy 2:c5b857d4f9f6 200 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_EMAIL, 0, cmd.getBuffer(), cmd.getLength()-1);
Volodymyr Shymanskyy 2:c5b857d4f9f6 201 }
Volodymyr Shymanskyy 2:c5b857d4f9f6 202
Volodymyr Shymanskyy 7:8879692d4e6c 203 /**
Volodymyr Shymanskyy 7:8879692d4e6c 204 * Sets property of a Widget
Volodymyr Shymanskyy 7:8879692d4e6c 205 *
Volodymyr Shymanskyy 7:8879692d4e6c 206 * @experimental
Volodymyr Shymanskyy 7:8879692d4e6c 207 *
Volodymyr Shymanskyy 7:8879692d4e6c 208 * @param pin Virtual Pin number
Volodymyr Shymanskyy 7:8879692d4e6c 209 * @param property Property name ("label", "labels", "color", ...)
Volodymyr Shymanskyy 7:8879692d4e6c 210 * @param value Property value
Volodymyr Shymanskyy 7:8879692d4e6c 211 */
Volodymyr Shymanskyy 9:7369ec77a3ea 212 template <typename T, typename... Args>
Volodymyr Shymanskyy 9:7369ec77a3ea 213 void setProperty(int pin, const T& property, Args... values) {
Volodymyr Shymanskyy 7:8879692d4e6c 214 char mem[BLYNK_MAX_SENDBYTES];
Volodymyr Shymanskyy 7:8879692d4e6c 215 BlynkParam cmd(mem, 0, sizeof(mem));
Volodymyr Shymanskyy 7:8879692d4e6c 216 cmd.add(pin);
Volodymyr Shymanskyy 7:8879692d4e6c 217 cmd.add(property);
Volodymyr Shymanskyy 9:7369ec77a3ea 218 cmd.add_multi(values...);
Volodymyr Shymanskyy 7:8879692d4e6c 219 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_PROPERTY, 0, cmd.getBuffer(), cmd.getLength()-1);
Volodymyr Shymanskyy 7:8879692d4e6c 220 }
Volodymyr Shymanskyy 7:8879692d4e6c 221
Volodymyr Shymanskyy 7:8879692d4e6c 222 template <typename T>
Volodymyr Shymanskyy 7:8879692d4e6c 223 void setProperty(int pin, const T& property, const BlynkParam& param) {
Volodymyr Shymanskyy 7:8879692d4e6c 224 char mem[32];
Volodymyr Shymanskyy 7:8879692d4e6c 225 BlynkParam cmd(mem, 0, sizeof(mem));
Volodymyr Shymanskyy 7:8879692d4e6c 226 cmd.add(pin);
Volodymyr Shymanskyy 7:8879692d4e6c 227 cmd.add(property);
Volodymyr Shymanskyy 7:8879692d4e6c 228 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_PROPERTY, 0, cmd.getBuffer(), cmd.getLength(), param.getBuffer(), param.getLength());
Volodymyr Shymanskyy 7:8879692d4e6c 229 }
Volodymyr Shymanskyy 7:8879692d4e6c 230
Volodymyr Shymanskyy 7:8879692d4e6c 231 template <typename T>
Volodymyr Shymanskyy 7:8879692d4e6c 232 void setProperty(int pin, const T& property, const BlynkParamAllocated& param) {
Volodymyr Shymanskyy 7:8879692d4e6c 233 char mem[32];
Volodymyr Shymanskyy 7:8879692d4e6c 234 BlynkParam cmd(mem, 0, sizeof(mem));
Volodymyr Shymanskyy 7:8879692d4e6c 235 cmd.add(pin);
Volodymyr Shymanskyy 7:8879692d4e6c 236 cmd.add(property);
Volodymyr Shymanskyy 7:8879692d4e6c 237 static_cast<Proto*>(this)->sendCmd(BLYNK_CMD_PROPERTY, 0, cmd.getBuffer(), cmd.getLength(), param.getBuffer(), param.getLength());
Volodymyr Shymanskyy 7:8879692d4e6c 238 }
Volodymyr Shymanskyy 7:8879692d4e6c 239
vshymanskyy 0:58b20b438383 240 #if defined(BLYNK_EXPERIMENTAL)
vshymanskyy 0:58b20b438383 241 // Attention!
vshymanskyy 0:58b20b438383 242 // Every function in this section may be changed, removed or renamed.
vshymanskyy 0:58b20b438383 243
vshymanskyy 0:58b20b438383 244 /**
vshymanskyy 0:58b20b438383 245 * Refreshes value of a widget by running
vshymanskyy 0:58b20b438383 246 * user-defined BLYNK_READ handler of a pin.
vshymanskyy 0:58b20b438383 247 *
vshymanskyy 0:58b20b438383 248 * @experimental
vshymanskyy 0:58b20b438383 249 *
vshymanskyy 0:58b20b438383 250 * @param pin Virtual Pin number
vshymanskyy 0:58b20b438383 251 */
vshymanskyy 0:58b20b438383 252 void refresh(int pin) {
vshymanskyy 0:58b20b438383 253 if (WidgetReadHandler handler = GetReadHandler(pin)) {
vshymanskyy 0:58b20b438383 254 BlynkReq req = { 0, BLYNK_SUCCESS, (uint8_t)pin };
vshymanskyy 0:58b20b438383 255 handler(req);
vshymanskyy 0:58b20b438383 256 }
vshymanskyy 0:58b20b438383 257 }
vshymanskyy 0:58b20b438383 258
vshymanskyy 0:58b20b438383 259 /**
vshymanskyy 0:58b20b438383 260 * Delays for N milliseconds, handling server communication in background.
vshymanskyy 0:58b20b438383 261 *
vshymanskyy 0:58b20b438383 262 * @experimental
vshymanskyy 0:58b20b438383 263 * @warning Should be used very carefully, especially on platforms with small RAM.
vshymanskyy 0:58b20b438383 264 *
vshymanskyy 0:58b20b438383 265 * @param ms Milliseconds to wait
vshymanskyy 0:58b20b438383 266 */
vshymanskyy 0:58b20b438383 267 void delay(unsigned long ms) {
vshymanskyy 0:58b20b438383 268 uint16_t start = (uint16_t)micros();
vshymanskyy 0:58b20b438383 269 while (ms > 0) {
vshymanskyy 0:58b20b438383 270 static_cast<Proto*>(this)->run();
vshymanskyy 0:58b20b438383 271 #if !defined(BLYNK_NO_YIELD)
vshymanskyy 0:58b20b438383 272 yield();
vshymanskyy 0:58b20b438383 273 #endif
vshymanskyy 0:58b20b438383 274 if (((uint16_t)micros() - start) >= 1000) {
vshymanskyy 0:58b20b438383 275 ms--;
vshymanskyy 0:58b20b438383 276 start += 1000;
vshymanskyy 0:58b20b438383 277 }
vshymanskyy 0:58b20b438383 278 }
vshymanskyy 0:58b20b438383 279 }
vshymanskyy 0:58b20b438383 280
vshymanskyy 0:58b20b438383 281 #endif
vshymanskyy 0:58b20b438383 282
vshymanskyy 0:58b20b438383 283 protected:
vshymanskyy 0:58b20b438383 284 void Init();
vshymanskyy 0:58b20b438383 285 static millis_time_t getMillis();
vshymanskyy 0:58b20b438383 286 void processCmd(const void* buff, size_t len);
vshymanskyy 0:58b20b438383 287 void sendInfo();
vshymanskyy 0:58b20b438383 288 };
vshymanskyy 0:58b20b438383 289
vshymanskyy 0:58b20b438383 290
vshymanskyy 0:58b20b438383 291 #endif