Library reference

This page lists what a sketch can call in the Plynx Arduino library, version 1.0.6, the one the Arduino Library Manager installs today. For a first working sketch, start with Getting started.

Headers

Include the header for your board. #define PLYNX_PRINT Serial above it prints the connection log on the Serial Monitor.

Board	Includes
ESP32 over Wi-Fi	`<WiFi.h>`, `<PlynxSimpleEsp32.h>`
ESP8266	`<ESP8266WiFi.h>`, `<PlynxSimpleEsp8266.h>`
ESP32 over Bluetooth	`<PlynxSimpleEsp32_BLE.h>`, see the Bluetooth guide
Nano 33 IoT, MKR WiFi 1010, UNO WiFi Rev2	`<WiFiNINA.h>`, `<PlynxSimpleWiFiNINA.h>`

Connect

Plynx.begin(auth, ssid, pass);                     // Plynx Cloud
Plynx.begin(auth, ssid, pass, "192.168.1.50", 8080); // your own server
Plynx.begin();                                     // auto setup, ESP32 and ESP8266

begin(auth, ssid, pass) joins the Wi-Fi network, then connects to the public server at yes.plynx.cc, port 8080. It does not return until the board is connected. The last two arguments point it at your own server, as a name or an IPAddress. begin() with no arguments is auto setup: no token and no Wi-Fi password in the sketch.

If setup() must not wait for the server, set the connection up and connect yourself:

Plynx.config(auth);                   // or config(auth, "your.server", 8080)
Plynx.connect();                      // returns false if it could not connect

Call	What it does
`Plynx.run()`	Sends and receives everything. Call it on every pass of `loop()`, with no long `delay()` around it
`Plynx.connected()`	`true` while the board is connected to the server
`Plynx.disconnect()`	Closes the connection

Receive values from the app

A widget that sends, such as a Button or a Slider, writes to a virtual pin. The sketch reacts in a PLYNX_WRITE handler:

PLYNX_WRITE(V1) {
  int on = param.asInt();
  digitalWrite(2, on);
}

On `param`	Returns
`asInt()`, `asLong()`	the value as a whole number
`asFloat()`, `asDouble()`	the value as a decimal number
`asStr()`, `asString()`	the value as text (`const char*`)
`isEmpty()`	`true` when nothing was sent
`param[0]`, `param[1]`, …	each value, for widgets that send several at once, such as the Joystick

PLYNX_WRITE_DEFAULT() catches every virtual pin that has no handler of its own. Inside it, request.pin tells you which pin was written.

Send values to the app

A widget that displays, such as a Gauge or a Chart, shows what the sketch writes to its pin:

Plynx.virtualWrite(V2, temperature);
Plynx.virtualWrite(V3, "door open");
Plynx.virtualWrite(V4, lat, lon);     // several values in one message

Numbers and text both work. Send on a timer, not on every pass of loop(): the server limits how many messages a board can send per second.

PLYNX_READ(Vn) defines a handler that runs when a read request for that pin reaches the board. Most sketches do not need it: they push values with virtualWrite when something changes.

Get the last values after a reconnect

The server keeps the last value of the pins your widgets use. After a restart or a lost connection, ask for them and your PLYNX_WRITE handlers run again with those values:

PLYNX_CONNECTED() {
  Plynx.syncVirtual(V1, V2);          // or Plynx.syncAll();
}

PLYNX_DISCONNECTED() {
  // the connection dropped: Plynx.run() retries every 5 seconds
}

Plynx.setProperty(pin, name, value) changes the widget on that pin while the dashboard is open:

Plynx.setProperty(V1, "color", "#D3435C");
Plynx.setProperty(V1, "label", "Tank");
Plynx.setProperty(V5, "onLabel", "Open");

The app applies these names:

Name	Value
`color`	a colour, as `"#RRGGBB"` or a number such as `0xD3435C`
`onColor`, `offColor`	the text colour of a Styled Button in each state
`onBackColor`, `offBackColor`	the background colour of a Styled Button in each state
`label`	the widget’s title; an empty string removes it
`onLabel`, `offLabel`	the text of a Button or Styled Button in each state
`min`, `max`	the range of a Slider, Gauge or level
`step`	the increment of a Step widget, greater than 0
`maximumFractionDigits`	how many decimals a value shows, 0 to 3
`valueFormatting`, `suffix`	how a value is written, for example `"°C"`
`url`	the stream address of a Video widget

A property only shows on widgets that have that setting. The app ignores labels, urls, isOnPlay, opacity, scale and rotation, and any value it cannot read, instead of guessing.

Notifications and email

Plynx.notify("Water level low");
Plynx.email("you@example.com", "Greenhouse", "Temperature above 35 °C");

notify needs a Notification widget in the project, and push notifications arrive from Plynx Cloud only. email needs an Email widget. If the widget has an address, it wins over the one in the sketch. email(subject, body), with no address, goes to the widget’s address or, when it has none, to your account email.

Timers

PlynxTimer runs functions at intervals without blocking Plynx.run():

PlynxTimer timer;

void sendReading() {
  Plynx.virtualWrite(V2, analogRead(A0));
}

void setup() {
  // Plynx.begin(...) first
  timer.setInterval(5000L, sendReading);
}

void loop() {
  Plynx.run();
  timer.run();
}

Call	What it does
`setInterval(ms, f)`	calls `f` every `ms` milliseconds, returns the timer’s number
`setTimeout(ms, f)`	calls `f` once, after `ms` milliseconds
`setTimer(ms, f, n)`	calls `f` `n` times
`enable(id)`, `disable(id)`, `toggle(id)`, `isEnabled(id)`	pauses and resumes a timer
`changeInterval(id, ms)`, `restartTimer(id)`, `deleteTimer(id)`	changes, restarts or removes it

One PlynxTimer holds up to 16 timers.

Limits by board

	ESP32, ESP8266, SAMD boards	Arduino Uno and other AVR boards
Virtual pins	`V0` to `V127`	`V0` to `V31`

A handler for a pin outside that range compiles and never runs, so on an Uno keep your widgets on V0 to V31.

Coming from a classic sketch

The library speaks the classic Blynk Legacy protocol but carries no legacy names: identifiers are renamed before a classic sketch compiles. The FAQ has the list.