Docs

Appearance

Open console

Devices

Arduino

Connect an Arduino-compatible board to Thinger.io with the Arduino library, from the Arduino IDE or PlatformIO, and update it over the Internet.

Guide7 min read

This guide connects a board to Thinger.io with the Thinger.io Arduino library: you create the device, install the library, upload a sketch and check that the device is online. The steps use an ESP32; for other boards, change the include and the class as shown in Supported boards.

BoardESP32, Arduino, ESP8266…SKETCHthing(USERNAME, DEVICE_ID, DEVICE_CREDENTIAL)thing["led"] << …thing["millis"] >> …thing.handle()1 · Connect over TLSport 252022 · Authenticateuser, device ID, credentials3 · Calls to deviceresources, answeredThinger.ioserverfree Cloud serveror YOUR_SERVERConsoleREST APIthinger CLIAI agent (MCP)The console, the API, the CLI and your agent read and call the device resources through the server.
From the sketch to the console

Before you start ​

  • A Thinger.io account. Your server is YOUR_SERVER: iot.thinger.io on the free Cloud account, or your own domain on a private instance.
  • A supported board and its USB cable.
  • The Arduino IDE, or Visual Studio Code with the PlatformIO extension.

Steps ​

  1. Create the device

    Console

    Go to Devices and click Add Device (Create a Device if you have no devices yet). Fill in the form:

    • Device Type: IOTMP Device (Thinger.io protocol).
    • Device Id: YOUR_DEVICE. Letters, numbers, _ and -.
    • Device Credentials: click Random, or type your own (6 characters or more). Copy them: you need them in the sketch.

    Click Add Device.

    Add Device form with the IOTMP device type, a device ID and credentials
    Add an IOTMP device

    API

    POST/v1/users/{user}/devicesAPI reference
    bash
    curl -X POST "https://YOUR_SERVER/v1/users/YOUR_USER/devices" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"device": "YOUR_DEVICE", "type": "Generic", "credentials": "change-me-123"}'

    YOUR_TOKEN is an access token. Set credentials to the device credentials you choose (6 characters or more). Generic is the IOTMP device type.

    CLI

    bash
    thinger device create YOUR_DEVICE -t Generic

    Without -c, the CLI generates random credentials and prints them. See the CLI reference.

    AI

    Ask your AI agent

    Create an IOTMP device called YOUR_DEVICE in my Thinger.io account and show me its credentials.

  2. Install the library

    Arduino IDE

    1. Install the package of your board. Some packages need an extra URL first: open File > Preferences (Arduino IDE > Settings on macOS) and add it to Additional boards manager URLs. Then open Tools > Board > Boards Manager, search for the package and click Install.

      BoardsBoards manager URLPackage
      ESP32None: the package is in the default list.esp32 by Espressif Systems
      ESP8266https://arduino.esp8266.com/stable/package_esp8266com_index.jsonesp8266 by ESP8266 Community
      Arduino boardsNone.The package named on the family page of your board.

    2. Open Sketch > Include Library > Manage Libraries, search for thinger.io and click Install.

    Arduino IDE 2 with the Library Manager open, the search box set to Thinger.io and the thinger.io library by Alvaro Luis Bustamante installed
    The thinger.io library in the Library Manager

    The library examples are in File > Examples > thinger.io, one per board (see Start from a library example).

    Install from a ZIP file. If you cannot use the Library Manager, for example in an IDE based on the Arduino IDE such as Energia, download the ZIP of the latest release from the Releases page of the library. Then open Sketch > Include Library > Add .ZIP Library and choose the file.

    Sketch menu of the Arduino IDE with the Include Library option, which holds Add .ZIP Library
    Sketch > Include Library holds Add .ZIP Library

    PlatformIO

    1. Install Visual Studio Code. Open the Extensions view (Ctrl+Shift+X, or Cmd+Shift+X on macOS), search for PlatformIO IDE and click Install.

      Visual Studio Code Extensions view with platformio in the search box and the PlatformIO IDE extension page open
      The PlatformIO IDE extension

    2. Open PIO Home (the PlatformIO icon in the activity bar, then Home) and click New Project.

      PIO Home with the Quick Access buttons New Project, Import Arduino Project, Open Project and Project Examples
      New Project in PIO Home

    3. In the Project Wizard, type a Name, choose your Board (Espressif ESP32 Dev Module for a generic ESP32) and the Arduino framework, and click Finish. PlatformIO downloads the tools of the board the first time.

      PlatformIO Project Wizard with the name Thinger.io Example, the board Espressif ESP32 Dev Module and the Arduino framework
      The Project Wizard

    4. Add the library to platformio.ini, in the root of the project. Each [env:…] section is a board you build for:

      platformio.ini
      ini
      [env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
lib_deps = thinger-io/thinger.io
monitor_speed = 115200

    PlatformIO downloads the library on the next build. The sketch goes in src/main.cpp:

    text
    my-project/
├── include/        header files, such as arduino_secrets.h
├── lib/            private libraries
├── src/
│   └── main.cpp    the sketch
├── test/
└── platformio.ini  boards, libraries and build options

    What each version of the library changes is in the Arduino library changelog.

  3. Write the sketch

    Replace the placeholders with your username, the device ID and the device credentials, and set your Wi-Fi network. The three values come from the device you created:

    Thinger.io: Add DeviceYour account usernameDevice IdDevice CredentialsYOUR_USERYOUR_DEVICEYOUR_TOKENSketch#define USERNAME "…"#define DEVICE_ID "…"#define DEVICE_CREDENTIAL "…"Not your emailExactly as in the consoleDevice credentials, not an access token
    From the console to the sketch
    main.cpp
    cpp
    #define THINGER_SERIAL_DEBUG
// #define THINGER_SERVER "YOUR_SERVER"  // only on a private instance

#include <ThingerESP32.h>

#define USERNAME "YOUR_USER"
#define DEVICE_ID "YOUR_DEVICE"
#define DEVICE_CREDENTIAL "YOUR_TOKEN"

#define WIFI_SSID "wifi-network"
#define WIFI_PASSWORD "wifi-password"

#define LED_PIN 2  // change it to the LED pin of your board

ThingerESP32 thing(USERNAME, DEVICE_ID, DEVICE_CREDENTIAL);

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

  thing.add_wifi(WIFI_SSID, WIFI_PASSWORD);

  // input resource: turn the LED on and off
  thing["led"] << digitalPin(LED_PIN);

  // output resource: milliseconds since the board started
  thing["millis"] >> outputValue(millis());
}

void loop() {
  thing.handle();
}
    • DEVICE_CREDENTIAL holds the device credentials, not an access token.
    • On the free Cloud account, leave the THINGER_SERVER line commented: the library connects to the free Cloud server by default. On a private instance, uncomment it and set your domain.
    • THINGER_SERIAL_DEBUG prints the connection steps to the serial monitor. Keep it while you test.

  4. Upload the sketch

    Select your board and port, upload the sketch and open the serial monitor at 115200 baud. When the device connects, the monitor shows [THINGER] Authenticated.

  5. Check that the device is online

    Console

    Go to Devices. The device shows a green status dot (Device Connected). Open it: the Status page shows Device State as Online, with its IP address and the data transmitted.

    Device Status with Device State Online, transmitted and received data and the connection time
    Status of a connected device

    API

    GET/v1/users/{user}/devices/{device}API reference
    bash
    curl "https://YOUR_SERVER/v1/users/YOUR_USER/devices/YOUR_DEVICE" \
  -H "Authorization: Bearer YOUR_TOKEN"

    The response includes the connection state of the device.

    CLI

    bash
    thinger device info YOUR_DEVICE

    AI

    Ask your AI agent

    Is my device YOUR_DEVICE connected to Thinger.io? Tell me since when and its IP address.

  6. Read a device resource

    Console

    Open the device and go to API. Expand the millis device resource and click Run: the output shows the value from the board. Expand led to turn the LED on and off.

    Device API of a device with the led resource as an on/off switch, switched on, and the millis resource with its output after Run
    The led and millis resources after Run

    API

    GET/v3/users/{user}/devices/{device}/resources/{resource}API reference
    bash
    curl "https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/resources/millis" \
  -H "Authorization: Bearer YOUR_TOKEN"

    CLI

    bash
    thinger device resource YOUR_DEVICE millis

    AI

    Ask your AI agent

    Read the millis resource of my device YOUR_DEVICE.

Result ​

The device appears as connected in Devices, and its device resources answer from the console, the API, the CLI and your agent. Continue with the Coding guide to send data to a Data Bucket and react to commands.

Start from a library example ​

The library has a complete sketch for each board in File > Examples > thinger.io of the Arduino IDE. The same sketches are on the family page of each board, to copy into a PlatformIO project.

Arduino IDE File > Examples menu with thinger.io open: the Arduino, EnergiaCC3200, ESP32, ESP8266, LinkItOne and Sonoff folders, and the list of Arduino examples
The thinger.io examples in the Arduino IDE

The examples keep the credentials in a second file, arduino_secrets.h, that the Arduino IDE shows as a tab next to the sketch. Fill it in before you upload:

arduino_secrets.h
cpp
#define USERNAME "YOUR_USER"
#define DEVICE_ID "YOUR_DEVICE"
#define DEVICE_CREDENTIAL "YOUR_TOKEN"

#define SSID "wifi-network"
#define SSID_PASSWORD "wifi-password"
  • DEVICE_CREDENTIAL holds the device credentials, not an access token.
  • Cellular boards replace SSID and SSID_PASSWORD with PIN_NUMBER, GPRS_APN, GPRS_LOGIN and GPRS_PASSWORD; Ethernet boards have no network settings. The three versions are in Credentials file.
  • In PlatformIO, put arduino_secrets.h in include/ and keep #include "arduino_secrets.h" in src/main.cpp.
  • If you share the sketch, keep arduino_secrets.h out of version control.

Update the firmware over the Internet ​

The Thinger.io extension for Visual Studio Code builds a PlatformIO project and sends the firmware to a device, or to every device of a product, over its Thinger.io connection. The device must run a sketch with OTA support: add the OTA include and object of your board (see Supported boards).

Visual Studio CodeThinger.io serverDeviceREST API (HTTPS)IOTMP connection1 · BUILD2 · CHECK3 · UPLOAD4 · RESTARTBuilds the firmware with PlatformIOReads THINGER_OTA_VERSIONAsks you to confirm the uploadRead $ota/optionsVersion, block size, compression, checksum, timeoutSame version, or OTA disabled: this device is skipped$ota/begin: size, MD5 checksum, compression$ota/write: one block per call, until the end$ota/end: the device verifies the checksum$ota/rebootConnects againNew firmware runsProduct as the target: steps 2 to 4 run for each device of the product, one after anotherDevices that are offline fail and the extension moves on; the output lists the result of each device
A firmware update from Visual Studio Code
main.cpp
cpp
#include <ThingerESP32.h>
#include <ThingerESP32OTA.h>

ThingerESP32 thing("YOUR_USER", "YOUR_DEVICE", "YOUR_TOKEN");
ThingerESP32OTA ota(thing);

void setup() {
  thing.add_wifi("wifi-network", "wifi-password");
}

void loop() {
  thing.handle();
}

The extension needs the PlatformIO extension, and it becomes active when you open a PlatformIO project. Set it up in the VS Code settings:

SettingDefaultDescription
thinger-io.hostiot.thinger.ioServer of your account: the free Cloud server by default, or YOUR_SERVER.
thinger-io.port443Server port.
thinger-io.ssltrueUse a TLS connection.
thinger-io.securetrueVerify the TLS certificate.
thinger-io.token(empty)Access token of your account. If it is empty, the extension asks for one.

The access token needs these permissions: ListDevices, ListProducts, AccessDeviceResources and ReadDeviceStatistics. See Access Tokens.

  1. Choose the target

    Click the rocket in the status bar, or run Thinger.io: Switch Target Destination from the command palette. Choose Device and the device, or Product to update every device of a product.

  2. Upload the firmware

    Click the upload button in the status bar, or run Thinger.io: Upload Firmware. If the project has several environments, pick one. The extension builds the firmware, asks you to confirm and uploads it. The device restarts with the new firmware.

To skip devices that already run the same firmware, define THINGER_OTA_VERSION in the build. If the upload is slow, set Application > Proxy > Proxy Support to fallback in the VS Code settings. Thinger.io: Clear Target Destination removes the target. More on firmware updates in OTA updates.

Troubleshooting ​

Keep #define THINGER_SERIAL_DEBUG as the first line and open the serial monitor at 115200 baud: the library prints each step of the connection.

SymptomCauseFix
Stops at [NETWORK] Connecting to networkWrong Wi-Fi name or password, or the network is out of reach.Check WIFI_SSID and WIFI_PASSWORD. Most ESP32 boards only join 2.4 GHz networks.
[_SOCKET] Error while connecting!The server cannot be reached.On a private instance, check THINGER_SERVER. Check that the network allows outgoing connections.
[THINGER] Auth Failed! Check username, device id, or device credentials.The credentials do not match the device.Check USERNAME, DEVICE_ID and DEVICE_CREDENTIAL against the device in Devices.
No output at allThe sketch blocks before thing.handle().Remove long delay() calls and loops from setup() and loop().

More cases in Troubleshooting.

Next steps ​

Coding guideWrite Arduino firmware for Thinger.io - device resources, pins, Data Buckets, properties, endpoints and connection handling.Supported boardsThe boards and network modules the Thinger.io Arduino library supports, with the class, the example sketch and the OTA support of each.WebConfigLet users set the Wi-Fi network and the Thinger.io credentials of an ESP32 or ESP8266 from a phone, without changing the firmware.