Library examples

The ThingsLinker library comes with ready-to-flash example sketches. Each one is a small, complete program you can upload, watch working, and then change. They are the fastest way to learn the library.

After installing the library (Overview), open them in Arduino IDE under File → Examples → ThingsLinker. The source is also on GitHub: ThingsLinker-Libraries/thingslinker-library/examples.

How to run any example

Every example follows the same five steps.

Open it: File → Examples → ThingsLinker → 02_LED_Control (for example). Arduino IDE opens a copy you can edit and save.
Fill in the credentials. Replace YOUR_DEVICE_AUTH_TOKEN (or YOUR_AUTH_TOKEN) and YOUR_BLUEPRINT_ID with the device's auth token and its blueprint's Blueprint Key. Both are in the Organization Portal: open the blueprint, then Set up hardware on the device.
Create the widgets it uses on the device's dashboard, on the pins listed in the tables below. A widget on the wrong pin shows nothing.
Upload: choose your board and port under Tools, then Upload.
Watch: open the Serial Monitor at 115200 baud. On the first start the device waits for WiFi over Bluetooth; add it in the app (Add a device). Then open its dashboard.

Start with 00_Connection_Test

If anything does not work, flash 00_Connection_Test first. It checks the credentials and the connection, and prints what is wrong in plain words.

All examples

Getting started (WiFi)

Example	What it shows	Widgets to create
`00_Connection_Test`	Checks your credentials, WiFi and the connection to ThingsLinker, and reports problems clearly.	Gauge on V0 (optional)
`01_SimpleExample`	The smallest working sketch: connect and stay connected.	None
`01_BLE_Provisioning`	WiFi setup over Bluetooth, and setting it up again by holding the BOOT button.	Button V0, LED V1
`02_LED_Control`	Turn the board's LED on and off from the app.	Button V0, LED V1
`03_Temperature_Monitor`	Send a reading every few seconds to a gauge.	Gauge V0
`03_Widget_Control_With_Status`	A control and a reading together, with online/offline status.	Button V0, Gauge V1
`04_Advanced_Control`	Several controls and readings in one sketch.	Button V0, Slider V1, Gauges V2, V3
`06_Multiple_Pins`	Using many virtual pins, up to V124.	Buttons and gauges on the pins in the sketch

Dashboards and widgets

Example	What it shows	Widgets to create
`07_All_Widgets_Test`	Every widget type in one sketch: a good way to see them all working.	The pins listed at the top of the sketch
`08_ESP32S3_Full_Dashboard`	A complete dashboard on an ESP32-S3.	The pins listed at the top of the sketch
`10_Full_Feature_Test`	Every library feature together, for testing a new board.	The pins listed at the top of the sketch
`15_Dashboard_Widgets`	Status, Progress Bar, Selector, Number Input, Text Input and Keypad.	The pins listed at the top of the sketch

Storage, WiFi and reliability

Example	What it shows	Widgets to create
`05_Storage_Example`	Save settings in flash so they survive restarts. See Saving settings.	Slider V1, Buttons V2, V3, Gauges V4, V6, LED V5
`09_Clear_WiFi`	Erase the saved WiFi so the device goes back to Bluetooth setup.	None
`02_BLE_Force_Provision`	Start Bluetooth setup on demand.	None
`17_Offline_Storage`	Keep readings while WiFi is down and send them later, at the right times. See Offline storage.	Chart and Value Display (pins in the sketch)

4G (GSM) boards

These use the ThingsLinkerGSM class for Simcom A7672 / SIM7672 modems. See the 4G quick start.

Example	What it shows
`12_GSM_Connection`	Connect over 4G, send a reading and receive a switch.
`13_GSM_Full_Example`	All the main features over 4G.
`14_GSM_GPS_Tracker`	Track position with the modem's built-in GPS, shown on a Map widget.
`16_GSM_Dashboard_Widgets`	The same widgets as `15_Dashboard_Widgets`, over 4G.
`18_GSM_Offline_Storage`	Keep readings while there is no mobile signal.

Firmware updates (OTA)

Example	What it shows
`19_OTA_Auto`	Recommended. Installs updates automatically when you start a shipment in the portal. See OTA firmware updates.
`08_OTA_Update` + `11_OTA_TestFirmware`	A ready-made pair (version 1.0 and 2.0) for trying an update end to end with manual checks.

Walkthrough 1: Turn an LED on from your phone

Example: 02_LED_Control · Widgets: Button on V0, LED on V1

The key part of the sketch:

const int LED_PIN = 2;   // the on-board LED on most ESP32 boards

void setup() {
  pinMode(LED_PIN, OUTPUT);
  iot.begin();

  // Runs every time the Button on V0 is pressed in the app or portal
  iot.onButton("V0", [](bool value) {
    digitalWrite(LED_PIN, value ? HIGH : LOW);
  });
}

void loop() {
  iot.run();
}

On the device's dashboard add a Button on V0 (label LED), and an LED widget on V1 (label LED state).
Fill in the credentials and upload.
Press the button in the app. The board's LED lights within a second.

Try next: connect a relay module to pin 4 instead of the LED to switch a lamp or a pump (use a relay rated for the load, and take care with mains voltage).

Walkthrough 2: Send a sensor reading

Example: 03_Temperature_Monitor · Widget: Gauge on V0 (unit °C, MIN 0, MAX 50)

void loop() {
  iot.run();

  static unsigned long lastRead = 0;
  if (millis() - lastRead > 5000) {           // every 5 seconds, without blocking
    lastRead = millis();
    float temperature = random(200, 350) / 10.0;   // replace with your sensor
    iot.gauge("V0", temperature);
  }
}

The example sends a made-up value so it works with no sensor attached. To use a real sensor, for example a DHT22 on pin 15 with the DHT sensor library:

#include <ThingsLinker.h>
#include <DHT.h>

ThingsLinker iot("YOUR_DEVICE_AUTH_TOKEN", "YOUR_BLUEPRINT_KEY");
DHT dht(15, DHT22);

void setup() {
  Serial.begin(115200);
  dht.begin();
  iot.begin();
}

void loop() {
  iot.run();

  static unsigned long last = 0;
  if (millis() - last >= 10000) {
    last = millis();
    float t = dht.readTemperature();
    float h = dht.readHumidity();
    if (!isnan(t)) iot.gauge("V0", t);   // Gauge "Temperature" on V0
    if (!isnan(h)) iot.gauge("V1", h);   // Gauge "Humidity" on V1
  }
}

Try next: add a Chart on the same pin V0 and call iot.chart("V0", t) too. The dashboard then shows the current value and its history.

Never use long delay() calls

iot.run() keeps the connection alive. Use the millis() pattern above instead of delay(10000), or the device misses commands and may show offline.

Walkthrough 3: Status, selector and keypad

Example: 15_Dashboard_Widgets

This example shows the widgets that turn values into something friendlier:

Status turns a number into a named state with a colour, for example soil moisture 46 → Good.
Progress Bar shows a value between MIN and MAX as a bar.
Selector lets the customer pick an option, for example Manual / Auto / Night; iot.onSelectorText() gives your code the chosen value.
Number Input and Keypad send numbers and one-off commands.

Create the widgets listed at the top of the sketch, then open the dashboard and try each one while watching the Serial Monitor.

Walkthrough 4: Automatic firmware updates

Example: 19_OTA_Auto

void setup() {
  Serial.begin(115200);
  iot.begin();
  iot.enableOTA();   // install updates when a shipment starts
}

void loop() {
  iot.run();         // also installs an update when one is waiting
}

In Tools → Partition Scheme choose Minimal SPIFFS (1.9MB APP with OTA) and upload version 1.0 over USB.
Change FIRMWARE_VERSION to "1.1" and choose Sketch → Export Compiled Binary.
In the Organization Portal start a shipment with that .bin (Firmware updates). The device installs it within moments and restarts printing v1.1.

The full explanation is in OTA firmware updates.

Sending and receiving at a glance

To…	Call	Widget
Show a number	`iot.gauge("V0", value)`, `iot.chart(…)`, `iot.progress(…)`	Gauge, Chart, Progress Bar
Show text or a number	`iot.display("V2", value)`, `iot.label(…)`	Value Display, Label
Show a named state	`iot.status("V3", value)`	Status
Show on/off	`iot.led("V4", true)`	LED
Show a position	`iot.map("V5", lat, lng)`	Map
Write a line to a console	`iot.terminal("V6", "Pump started")`	Terminal
React to a button or switch	`iot.onButton("V0", fn)`, `iot.onSwitch(…)`	Button, Switch
React to a slider or number	`iot.onSlider("V1", fn)`, `iot.onNumberInput(…)`	Slider, Number Input
React to a choice or text	`iot.onSelectorText(…)`, `iot.onTextInput(…)`, `iot.onTerminal(…)`	Selector, Text Input, Terminal
React to a key or joystick	`iot.onKeypad(…)`, `iot.onJoystick("V7", fn(x, y))`	Keypad, Joystick

Full details are in Sending and receiving.

How to run any example​

All examples​

Getting started (WiFi)​

Dashboards and widgets​

Storage, WiFi and reliability​

4G (GSM) boards​

Firmware updates (OTA)​

Walkthrough 1: Turn an LED on from your phone​

Walkthrough 2: Send a sensor reading​

Walkthrough 3: Status, selector and keypad​

Walkthrough 4: Automatic firmware updates​

Sending and receiving at a glance​