Arduino

Every call is made on a HyperwisorIOT instance. This page pairs each method with its signature and a copy-paste example.

#include <hyperwisor-iot.h>
HyperwisorIOT device;

In the examples, targetId is where a message is routed (your dashboard/user). Read it from an incoming command’s from, or from your product configuration.

Core

`begin()`

Initialize everything — Wi-Fi, provisioning, the realtime connection, and command handlers. Call once in setup().

void begin();

void setup() {
  Serial.begin(115200);
  device.begin();
  Serial.println("Device ID: " + device.getDeviceId());
}

`loop()`

Keep the connection alive and process incoming messages. Call every loop().

void loop();

void loop() {
  device.loop();
}

`setApiKeys()`

Set the product’s API key and secret key.

void setApiKeys(const String &apiKey, const String &secretKey);

device.setApiKeys("mk_xxx", "msk_xxx");

Identity

String getDeviceId();
String getUserId();

String id   = device.getDeviceId();
String user = device.getUserId();
Serial.println("Device " + id + " owned by " + user);

Provisioning

Set Wi-Fi and identity. Persisted in Preferences, so you only do this once.

void setCredentials(const String &ssid, const String &password,
                    const String &deviceId, const String &userId = "");
void setWiFiCredentials(const String &ssid, const String &password);
void setDeviceId(const String &deviceId);
void setUserId(const String &userId);
void clearCredentials();
bool hasCredentials();

if (!device.hasCredentials()) {
  device.setCredentials("MySSID", "MyPass", "my-device-id", "my-user-id");
}
// device.clearCredentials();  // wipe and re-provision

See Provisioning for AP-mode setup.

Receiving commands

`setUserCommandHandler()`

void setUserCommandHandler(UserCommandCallback cb);
// typedef std::function<void(JsonObject &msg)> UserCommandCallback;

device.setUserCommandHandler([](JsonObject &msg) {
  JsonObject on = device.findAction(msg, "Operate", "ON");
  if (!on.isNull()) digitalWrite(2, HIGH);

  JsonObject off = device.findAction(msg, "Operate", "OFF");
  if (!off.isNull()) digitalWrite(2, LOW);
});

`sendTo()`

Send a message to another target, building the payload inline.

void sendTo(const String &targetId, std::function<void(JsonObject &)> payloadBuilder);

device.sendTo(targetId, [](JsonObject &p) {
  p["event"] = "door_opened";
  p["at"]    = millis();
});

JSON helpers

Navigate an incoming command payload without parsing by hand.

JsonObject findCommand(JsonObject& payload, const char* commandName);
JsonObject findAction(JsonObject& payload, const char* commandName, const char* actionName);
JsonObject findParams(JsonObject& payload, const char* commandName, const char* actionName);

JsonObject params = device.findParams(msg, "GPIO_MANAGEMENT", "ON");
if (!params.isNull()) {
  int pin = params["gpio"];
  pinMode(pin, OUTPUT);
  digitalWrite(pin, params["status"] == "HIGH" ? HIGH : LOW);
}

Updating widgets

`updateWidget()`

Push a value to a dashboard widget by its widget ID. Overloads cover the common types.

Where do I get the widgetId? Select the widget in the Dashboard Designer and open General → Basic. The Widget ID field holds the value — use the copy button and paste it into your updateWidget / widget.* call. See Binding Data for the full model.

Widget ID in the General tab — Copy a widget's ID from General → Basic — this is the value your update calls reference.

void updateWidget(const String &targetId, const String &widgetId, const String &value);
void updateWidget(const String &targetId, const String &widgetId, float value);
void updateWidget(const String &targetId, const String &widgetId, const std::vector<float> &values);
void updateWidget(const String &targetId, const String &widgetId, const std::vector<int> &values);
void updateWidget(const String &targetId, const String &widgetId, const std::vector<String> &values);

device.updateWidget(targetId, "tempGauge", 27.4f);              // a number
device.updateWidget(targetId, "statusLabel", String("OK"));    // text
device.updateWidget(targetId, "chart", std::vector<float>{ 1.2f, 3.4f, 2.1f });  // a series

void updateFlightAttitude(const String &targetId, const String &widgetId, float roll, float pitch);
void updateWidgetPosition(const String &targetId, const String &widgetId, int x, int y, int w, int h, int r = 0);
void updateCountdown(const String &targetId, const String &widgetId, const String &hours, const String &minutes, const String &seconds);
void updateHeatMap(const String &targetId, const String &widgetId, const std::vector<HeatMapPoint> &dataPoints);
void update3DModel(const String &targetId, const String &widgetId, const String &modelUrl);
void update3DWidget(const String &targetId, const String &widgetId, const std::vector<ThreeDModelUpdate> &models);

device.updateFlightAttitude(targetId, "adi", roll, pitch);          // from an IMU
device.updateCountdown(targetId, "timer", "00", "05", "30");        // 5m30s
device.update3DModel(targetId, "viewer", "https://.../model.glb");

Dialogs

Show a dialog on the user’s dashboard. showDialog takes an icon; the named helpers are shortcuts.

void showDialog(const String &targetId, const String &title, const String &description, const String &icon = "info");
void info(const String &targetId, const String &title, const String &description);
void warning(const String &targetId, const String &title, const String &description);
void success(const String &targetId, const String &title, const String &description);
void error(const String &targetId, const String &title, const String &description);
void risk(const String &targetId, const String &title, const String &description);

device.success(targetId, "Watering done", "Soil moisture is back to 45%.");
device.warning(targetId, "Low battery", "Node battery at 12%.");

Database

Insert, read, update, and delete records. Each has a fire-and-forget form and a …WithResponse form that returns the result.

void insertDatainDatabase(const String &productId, const String &deviceId,
                          const String &tableName, std::function<void(JsonObject &)> dataBuilder);
void getDatabaseData(const String &productId, const String &tableName, int limit = 50);
void updateDatabaseData(const String &dataId, std::function<void(JsonObject &)> dataBuilder);
void deleteDatabaseData(const String &dataId);
// + insertDatainDatabaseWithResponse / getDatabaseDataWithResponse / … returning DynamicJsonDocument

// Insert a reading
device.insertDatainDatabase(productId, deviceId, "readings", [](JsonObject &row) {
  row["temperature"] = 27.4;
  row["humidity"]    = 61;
});

// Read the latest, with the response
DynamicJsonDocument res =
  device.getDatabaseDataWithResponse(productId, "readings", 20);

Sensor data logger

void send_Sensor_Data_logger(const String &targetId, const String &configId,
  std::initializer_list<std::pair<const char *, float>> dataList);

device.send_Sensor_Data_logger(targetId, "cfg-123", {
  {"temp", 27.4f}, {"humidity", 61.0f}
});

Onboarding

void onboardDevice(const String &productId, const String &userId,
                   const String &deviceName, const String &deviceIdentifier);
DynamicJsonDocument onboardDeviceWithResponse(...);

device.onboardDevice(productId, userId, "Living Room Sensor", "unique-hw-id");

SMS

void sendSMS(const String &productId, const String &to, const String &message);
DynamicJsonDocument sendSMSWithResponse(...);

device.sendSMS(productId, "+15551234567", "Pump turned on automatically.");

Authentication

void authenticateUser(const String &email, const String &password);
DynamicJsonDocument authenticateUserWithResponse(...);

DynamicJsonDocument r = device.authenticateUserWithResponse("user@x.com", "pass");

Time & date (NTP)

void initNTP();
void setTimezone(const char* timezone);
String getNetworkTime();
String getNetworkDate();
String getNetworkDateTime();

device.initNTP();
device.setTimezone("IST-5:30");
Serial.println(device.getNetworkDateTime());   // e.g. "2026-07-01 14:05:22"

GPIO state persistence

Remember pin states across reboots.

void saveGPIOState(int pin, int state);
int  loadGPIOState(int pin);
void restoreAllGPIOStates();

device.saveGPIOState(2, HIGH);            // persist a relay's state
device.restoreAllGPIOStates();            // on boot, restore everything

Device status

void sendDeviceStatus(const String &targetId);

device.sendDeviceStatus(targetId);        // report online/health to the dashboard

See full sketches

Complete example programs.

Overview

ESP-IDF

Arduino — API Reference

Core

`begin()`

`loop()`

`setApiKeys()`

Identity

Provisioning

Receiving commands

`setUserCommandHandler()`

`sendTo()`

JSON helpers

Updating widgets

`updateWidget()`

Specialized widget helpers

Dialogs

Database

Sensor data logger

Onboarding

SMS

Authentication

Time & date (NTP)

GPIO state persistence

Device status

See full sketches

​Core

​begin()

​loop()

​setApiKeys()

​Identity

​Provisioning

​Receiving commands

​setUserCommandHandler()

​sendTo()

​JSON helpers

​Updating widgets

​updateWidget()

​Specialized widget helpers

​Dialogs

​Database

​Sensor data logger

​Onboarding

​SMS

​Authentication

​Time & date (NTP)

​GPIO state persistence

​Device status

See full sketches

Core

`begin()`

`loop()`

`setApiKeys()`

Identity

Provisioning

Receiving commands

`setUserCommandHandler()`

`sendTo()`

JSON helpers

Updating widgets

`updateWidget()`

Specialized widget helpers

Dialogs

Database

Sensor data logger

Onboarding

SMS

Authentication

Time & date (NTP)

GPIO state persistence

Device status