Devices

A device is a named MQTT endpoint — one piece of hardware, bound to one broker, described by the topics it talks on. It's a pure data source; the controls that drive it live on a Dashboard.

What a device is

In IoT Parrot a device groups the MQTT topics that one piece of hardware — an ESP32, an Arduino, a Raspberry Pi, anything that speaks MQTT — publishes to or subscribes to. It's bound to exactly one broker, and it does nothing on its own: it's a pure data source. The buttons, sliders, gauges, and toggles that actually send and read messages live on a Dashboard, where each widget points back at a device's topic.

That separation is deliberate. You describe your hardware once as a device, then build any number of dashboards on top of it without redefining the connection each time.

Device fields

When you add or edit a device on the web, you fill in these fields:

name

A human-friendly label for the device, e.g. Garage door or Greenhouse sensor. This is what you'll see when picking a device for a widget or automation.

broker

Which broker this device lives on. A device belongs to exactly one broker; every topic below is resolved against that broker's connection.

topics

The MQTT topics this device publishes and subscribes to, entered comma-separated in the form — for example home/garage/door, sensors/greenhouse/temp. These are the topics your dashboard widgets bind to.

confirmationTopic

Optional. A topic the device publishes to after it finishes an action, so the dashboard can show a confirmation popup. See Action confirmation below.

confirmationDuration

How long the confirmation popup stays on screen, in seconds (default 5s).

color

A color used to distinguish this device's widgets on a cross-device dashboard, so you can tell at a glance which hardware each control belongs to.

orientation

The device's default layout orientation, used as a starting point when you build dashboards around it.

Choosing topics

Topics are the addresses your messages flow through. IoT Parrot uses concrete topics for device actions — pick clear, hierarchical names and keep one topic per distinct function. A tidy convention pays off when you have several devices:

• home/garage/door — publish OPEN / CLOSE to actuate the door.
• home/livingroom/light — publish ON / OFF to switch a lamp.
• sensors/greenhouse/temp — the device publishes readings like 24.6 for a gauge to display.
• devices/greenhouse-1/status — a quiet status topic separate from high-frequency telemetry.

New to any of this? The MQTT basics page explains topics, payloads, and the publish/subscribe model.

Action confirmation

Confirmation gives a widget tap a visible "it worked" acknowledgement that comes from the device itself, not just from the app. When the device finishes an action it publishes to the confirmationTopic, and the dashboard shows a confirmation popup for confirmationDuration seconds.

Managed-broker devices & firmware

If your device lives on the IoT Parrot managed broker (see Brokers), the app does the connection wiring for you. Each managed device is issued its own per-device MQTT username and password, and its topics are namespaced under your account so they can't collide with anyone else's.

When you create a managed device, the app shows a copy-paste ESP32 firmware snippet already filled in with that device's TLS credentials and the managed endpoint mqtt.iotparrot.com:8883. Flash it and the board connects on first boot — no hand-typing hosts or secrets. The snippet looks like this:

#include <WiFi.h>
#include <WiFiClientSecure.h>
#include <PubSubClient.h>

const char* WIFI_SSID     = "your-wifi-ssid";
const char* WIFI_PASSWORD = "your-wifi-password";

// Managed broker endpoint + this device's per-device credentials,
// preloaded by the app when you add a managed device.
const char* MQTT_HOST = "mqtt.iotparrot.com";
const int   MQTT_PORT = 8883;                     // TLS is required — no plain 1883
const char* MQTT_USERNAME = "dev-ab12cd34-greenhouse-1"; // this device only
const char* MQTT_PASSWORD = "••••••••••••••••";   // filled in for you

// Root CA the managed broker's Let's Encrypt certificate chains to (ISRG
// Root X1). The app pastes the full PEM here; embedding it lets the ESP32
// verify the server so the per-device password can't be captured by a
// man-in-the-middle.
const char* ISRG_ROOT_X1 = R"EOF(-----BEGIN CERTIFICATE-----
... the app fills in the full certificate here ...
-----END CERTIFICATE-----)EOF";

WiFiClientSecure net;
PubSubClient mqtt(net);

void connectWifi() {
  WiFi.begin(WIFI_SSID, WIFI_PASSWORD);
  while (WiFi.status() != WL_CONNECTED) delay(250);
}

void connectMqtt() {
  while (!mqtt.connected()) {
    mqtt.connect("greenhouse-1", MQTT_USERNAME, MQTT_PASSWORD);
    if (!mqtt.connected()) delay(1000);
  }
}

void setup() {
  connectWifi();
  net.setCACert(ISRG_ROOT_X1); // verify the broker's certificate (secure default)
  // net.setInsecure();        // PROTOTYPING ONLY — skips verification; never ship this
  mqtt.setServer(MQTT_HOST, MQTT_PORT);
  connectMqtt();
}

void loop() {
  if (!mqtt.connected()) connectMqtt();
  mqtt.loop();
  // publish readings / subscribe to your device's namespaced topics here
}

Device limits

How many devices you can create depends on your tier:

See Account & billing for how the tiers compare. With a device in place, head to Dashboards & widgets to build the controls that actually drive it.