Quick Start Guide

This guide walks you through creating a device and sending real data to SiliconWit.io. By the end, you will see live readings on your dashboard.

Prerequisites

• A computer with internet access (Windows, macOS, or Linux)
• A SiliconWit.io account (free)

Step 1: Create Your Account

1. Go to siliconwit.io/register
2. Sign up with email, or use Google or GitHub
3. Check your inbox and click the verification link
4. Log in to your dashboard

Step 2: Add a Device

We will create a test device that simulates temperature and humidity readings.

1. Go to siliconwit.io/login?next=/dashboard/devices (or open your dashboard and click Devices in the sidebar)
2. Click the ”+ Add Device” button

Basic Information

Fill in the following:

Field	Value
Device Name	Temp Humidity Simulator
Device Type	Select Sensor (collects and sends data)
Description	Test device that simulates temperature and humidity readings

Configuration

Set these options:

Setting	Value
Data Direction	Send Only
Connectivity	WiFi + MQTT
Data Interval	10 seconds (click the 10s preset button, or type 10 and select Seconds)
Schema Mode	Strict (only defined fields)
Enable camera snapshots	Leave unchecked

Data Fields

Now define the two fields this device will send:

1. Click Clear to remove any default fields
2. Click Import to open the “Import Data Fields from JSON” dialog
3. Copy and paste this JSON into the import box:

[
  { "name": "temperature", "label": "Temperature", "unit": "°C" },
  { "name": "humidity", "label": "Humidity", "unit": "%" }
]

4. Click Validate - you should see “2 valid fields found”
5. Click Import Fields

Adding fields manually

You can also click + Add to add fields one by one instead of importing JSON. This is useful when you only have a few fields. Each field needs a name (lowercase, e.g., temperature), a label (display name, e.g., Temperature), and an optional unit (e.g., °C).

6. Click Create Device

You will be taken to your new device’s page.

Copy Your Credentials

1. On the device page, click the Settings tab
2. Find your Device ID and copy it (format SWD-XXXXXX, always visible on device page)
3. Find your Access Token below it, click the eye icon to reveal it, and copy it

Credential	Example	Where to find it
Device ID	SWD-XXXXXX	Settings tab, always visible
Access Token	a1b2c3d4e5f6g7h8...	Settings tab, click the eye icon to reveal

Save your access token

You will need both the Device ID and Access Token in the next step. Keep them somewhere safe. If you lose the token, you can regenerate it from the device Settings tab (which will invalidate the old one).

Step 3: Send Your First Data

Choose Python (easiest to test on any computer) or ESP32 (for real hardware).

Option A: Python (recommended for first test)

Python works on any computer and is the fastest way to verify your setup.

Set up your workspace

First, create a folder for this project and install the required Python library:

Windows

1. Download Python from python.org/downloads and install it. Check “Add Python to PATH” during installation.
2. Open Command Prompt (press Win+R, type cmd, press Enter)
3. Create a project folder and install the library:

mkdir %USERPROFILE%\Documents\siliconwit-test
cd %USERPROFILE%\Documents\siliconwit-test
pip install requests

Ubuntu / Debian

Python 3 is usually pre-installed. Open a terminal and run:

mkdir -p ~/Documents/siliconwit-test
cd ~/Documents/siliconwit-test
pip3 install requests

If pip3 is missing: sudo apt install -y python3-pip

macOS

Open Terminal and run:

mkdir -p ~/Documents/siliconwit-test
cd ~/Documents/siliconwit-test
pip3 install requests

If pip3 is not found, install Python from python.org/downloads or via Homebrew: brew install python3.

Send data via HTTP (simplest method)

Create a file called send_data.py in your siliconwit-test folder and paste this code. Replace the two placeholder values with your actual Device ID and Access Token from Step 2:

import requests
import json
import time
import random

# ============ YOUR CREDENTIALS ============
DEVICE_ID = "SWD-XXXXXX"          # Replace with your Device ID
ACCESS_TOKEN = "your-access-token"    # Replace with your Access Token
# ==========================================

URL = "https://siliconwit.io/api/devices/ingest"

print("Sending data to SiliconWit.io...")
print("Press Ctrl+C to stop.\n")

while True:
    payload = {
        "device_id": DEVICE_ID,
        "access_token": ACCESS_TOKEN,
        "data": {
            "temperature": round(random.uniform(20.0, 35.0), 1),
            "humidity": round(random.uniform(30.0, 80.0), 1)
        }
    }

    try:
        response = requests.post(URL, json=payload, timeout=10)
        result = response.json()

        if result.get("success"):
            print(f"Sent: temp={payload['data']['temperature']}, humidity={payload['data']['humidity']}")
        else:
            print(f"Error: {result.get('error', 'Unknown error')}")
    except Exception as e:
        print(f"Request failed: {e}")

    time.sleep(10)  # Send every 10 seconds (matches device interval)

Run it:

Windows

python send_data.py

Ubuntu / Debian

python3 send_data.py

macOS

python3 send_data.py

In your terminal, you should see successful sends:

Sending data to SiliconWit.io...
Press Ctrl+C to stop.

Sent: temp=24.3, humidity=55.7
Sent: temp=28.1, humidity=42.9
Sent: temp=22.6, humidity=67.3

Now go to your devices page and click on your device (the same one where you copied the Device ID and Access Token from the Settings tab). Click the Data tab. You will see your data streaming in across several cards: Latest Reading showing current values, Insights with min/max/average stats, Historical Data with interactive charts, and a Telemetry Data table with all received data points.

HTTP vs MQTT

The HTTP method above is the simplest way to test. For production devices that send data frequently, use MQTT instead (shown below) - it keeps a persistent connection and uses less bandwidth.

Send data via MQTT (persistent connection)

MQTT is the recommended protocol for devices that stream data continuously. It keeps a persistent connection open, so data arrives faster and uses less bandwidth than HTTP.

Install the MQTT library (run this in your siliconwit-test folder):

Windows

pip install paho-mqtt

Ubuntu / Debian

pip3 install paho-mqtt

macOS

pip3 install paho-mqtt

Create a file called mqtt_client.py in your siliconwit-test folder. Replace the two placeholder values with your credentials from Step 2:

import ssl
import json
import time
import random
import paho.mqtt.client as mqtt

# ============ YOUR CREDENTIALS ============
DEVICE_ID = "SWD-XXXXXX"          # Replace with your Device ID
ACCESS_TOKEN = "your-access-token"    # Replace with your Access Token
# ==========================================

BROKER = "mqtt.siliconwit.io"
PORT = 8883
TOPIC = f"d/{DEVICE_ID}/t"

def on_connect(client, userdata, flags, reason_code, properties):
    if reason_code == 0:
        print("Connected to SiliconWit.io MQTT broker")
    else:
        print(f"Connection failed: {reason_code}")

def on_publish(client, userdata, mid, reason_code, properties):
    print(f"  Message {mid} delivered")

# Create client
client = mqtt.Client(
    callback_api_version=mqtt.CallbackAPIVersion.VERSION2,
    client_id=DEVICE_ID,
    protocol=mqtt.MQTTv311,
)
client.username_pw_set(DEVICE_ID, ACCESS_TOKEN)
client.tls_set(tls_version=ssl.PROTOCOL_TLS_CLIENT)
client.on_connect = on_connect
client.on_publish = on_publish

# Connect
print(f"Connecting to {BROKER}:{PORT}...")
client.connect(BROKER, PORT, keepalive=60)
client.loop_start()

print("Sending data to SiliconWit.io...")
print("Press Ctrl+C to stop.\n")

try:
    while True:
        if client.is_connected():
            data = {
                "temperature": round(random.uniform(20.0, 35.0), 1),
                "humidity": round(random.uniform(30.0, 80.0), 1),
            }
            client.publish(TOPIC, json.dumps(data), qos=1)
            print(f"Sent: {json.dumps(data)}")
        else:
            print("Waiting for connection...")
        time.sleep(10)  # Send every 10 seconds (matches device interval)
except KeyboardInterrupt:
    print("\nStopping...")
    client.loop_stop()
    client.disconnect()

Run it:

Windows

python mqtt_client.py

Ubuntu / Debian

python3 mqtt_client.py

macOS

python3 mqtt_client.py

In your terminal, you should see a successful connection and message deliveries:

Connecting to mqtt.siliconwit.io:8883...
Connected to SiliconWit.io MQTT broker
Sending data to SiliconWit.io...
Press Ctrl+C to stop.

Sent: {"temperature": 24.3, "humidity": 55.7}
  Message 1 delivered
Sent: {"temperature": 28.1, "humidity": 42.9}
  Message 2 delivered

Now go to your devices page, click on your device, then click the Data tab. Just like with the HTTP method, you will see data streaming in across the Latest Reading, Insights, Historical Data, and Telemetry Data cards.

Option B: ESP32 (Arduino IDE)

For real hardware projects, the ESP32 is the most popular choice. This example uses MQTT over TLS.

Install Arduino IDE and libraries

1. Download Arduino IDE and install it
2. Add ESP32 board support:
   • Go to File > Preferences
   • In “Additional Board Manager URLs”, add:

     https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

   • Go to Tools > Board > Boards Manager, search esp32, and install esp32 by Espressif Systems
3. Install the MQTT library:
   • Go to Sketch > Include Library > Manage Libraries
   • Search PubSubClient and install PubSubClient by Nick O’Leary
4. Select your board: Tools > Board > ESP32 Dev Module (or your specific board)

Upload the sketch

Create a new sketch and paste this code. Replace the four placeholder values:

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

// ============ YOUR SETTINGS ============
const char* WIFI_SSID     = "YOUR_WIFI_NAME";       // Your WiFi network name
const char* WIFI_PASSWORD = "YOUR_WIFI_PASSWORD";    // Your WiFi password
const char* DEVICE_ID     = "SWD-XXXXXX";        // From SiliconWit.io dashboard
const char* ACCESS_TOKEN  = "your-access-token";     // From SiliconWit.io dashboard
// =======================================

const char* MQTT_BROKER = "mqtt.siliconwit.io";
const int   MQTT_PORT   = 8883;

WiFiClientSecure espClient;
PubSubClient mqtt(espClient);

unsigned long lastSend = 0;
const unsigned long SEND_INTERVAL = 10000; // 10 seconds (matches device interval)

void connectWifi() {
  Serial.print("Connecting to WiFi");
  WiFi.begin(WIFI_SSID, WIFI_PASSWORD);
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  Serial.println(" connected!");
  Serial.print("IP: ");
  Serial.println(WiFi.localIP());
}

void connectMqtt() {
  while (!mqtt.connected()) {
    Serial.print("Connecting to MQTT...");
    if (mqtt.connect(DEVICE_ID, DEVICE_ID, ACCESS_TOKEN)) {
      Serial.println(" connected!");
    } else {
      Serial.print(" failed (");
      Serial.print(mqtt.state());
      Serial.println("). Retrying in 5s...");
      delay(5000);
    }
  }
}

void setup() {
  Serial.begin(115200);
  Serial.println("\n=== SiliconWit.io ESP32 Quick Start ===\n");

  connectWifi();

  espClient.setInsecure(); // Skip certificate verification (OK for testing)
  mqtt.setServer(MQTT_BROKER, MQTT_PORT);
}

void loop() {
  if (!mqtt.connected()) {
    connectMqtt();
  }
  mqtt.loop();

  if (millis() - lastSend >= SEND_INTERVAL) {
    lastSend = millis();

    // Simulated sensor readings - replace with your actual sensor code
    float temperature = 20.0 + (float)(random(0, 150)) / 10.0;
    float humidity    = 30.0 + (float)(random(0, 500)) / 10.0;

    // Build JSON payload
    String payload = "{\"temperature\":" + String(temperature, 1)
                   + ",\"humidity\":" + String(humidity, 1) + "}";

    // Build topic: d/{device_id}/t
    String topic = "d/" + String(DEVICE_ID) + "/t";

    // Publish
    if (mqtt.publish(topic.c_str(), payload.c_str())) {
      Serial.println("Sent: " + payload);
    } else {
      Serial.println("Publish failed!");
    }
  }
}

Click Upload. Open Tools > Serial Monitor (baud rate: 115200) to see the ESP32 output:

=== SiliconWit.io ESP32 Quick Start ===

Connecting to WiFi... connected!
IP: 192.168.1.42
Connecting to MQTT... connected!
Sent: {"temperature":24.3,"humidity":55.7}
Sent: {"temperature":28.1,"humidity":42.9}

Now go to your devices page, click on your device, then click the Data tab. You will see data streaming in across the Latest Reading, Insights, Historical Data, and Telemetry Data cards.

Step 4: View Your Data

1. Go to your devices page and click on your device (it has a Data tab and a Settings tab)
2. On the Data tab, you will see your temperature and humidity readings streaming in across several cards:
   • Latest Reading - current values for each field
   • Insights - min, max, and average statistics
   • Historical Data - interactive charts that plot readings over time
   • Telemetry Data - a table with all received data points and timestamps

Real-time updates

If you see data in the table but not the chart, wait for 2-3 data points - the chart needs at least two points to draw a line.

JSON Payload Reference

Your device sends a JSON object with key-value pairs. Your payload must match your device’s configured field schema. See the Field Schema guide for details.

Simple readings:

{
  "temperature": 25.5,
  "humidity": 60
}

GPS tracker:

{
  "lat": -1.2921,
  "lon": 36.8219,
  "speed": 45.2,
  "battery": 87
}

Mixed types (numbers, booleans, text):

{
  "temperature": 25.5,
  "door_open": true,
  "status": "normal"
}

Nested data (max 2 levels deep):

{
  "indoor": { "temp": 22, "humidity": 45 },
  "outdoor": { "temp": 18, "humidity": 70 }
}

Payload limits

Limit	Value
Maximum payload size	10 KB
Maximum fields	50 per message
Maximum nesting depth	2 levels
Minimum send interval	1 second

Connection Reference

Setting	Value
MQTT Broker	mqtt.siliconwit.io
MQTT Port	8883 (TLS required)
MQTT Username	Your Device ID
MQTT Password	Your Access Token
MQTT Client ID	Your Device ID
MQTT Topic	d/{device_id}/t
HTTP Endpoint	POST https://siliconwit.io/api/devices/ingest
WebSocket	wss://mqtt.siliconwit.io:8084/mqtt

Troubleshooting

Python HTTP errors

Error	Cause	Fix
{"error": "Invalid device_id or access_token"}	Wrong credentials	Double-check Device ID and Access Token from your dashboard
{"error": "Device is not active"}	Device is paused	Go to dashboard and resume the device
Connection refused	No internet or firewall	Check your internet connection
ModuleNotFoundError: requests	Library not installed	Run pip install requests

Python MQTT errors

Error	Cause	Fix
Connection failed: 5	Wrong credentials	Verify Device ID and Access Token
SSL: CERTIFICATE_VERIFY_FAILED	Missing CA certificates	Run pip install certifi and update your OS
Connection timed out	Port 8883 blocked	Check firewall allows outbound port 8883
ModuleNotFoundError: paho	Library not installed	Run pip install paho-mqtt
AttributeError: CallbackAPIVersion	Old paho-mqtt version	Run pip install --upgrade paho-mqtt (need v2.0+)

ESP32 errors

Error	Cause	Fix
WiFi won’t connect	Wrong SSID/password	Check credentials, ensure 2.4 GHz network (not 5 GHz)
MQTT state -2	Network unreachable	Check WiFi is connected first
MQTT state 5	Auth failed	Verify Device ID and Access Token
Data not appearing	Wrong topic	Topic must be exactly d/{your_device_id}/t

Next Steps

• Set up alerts to get notified when readings cross a threshold
• ESP32 Setup Guide for connecting real sensors (DHT22, deep sleep, etc.)
• Python MQTT Tutorial for a more detailed Python walkthrough
• HTTP Ingestion for MicroPython, Node.js, and cURL examples
• Topics and Payloads for advanced payload formats and commands
• Explore the Public API for reading data programmatically