QuickStart ~5 min

Connect your first ESP32 device to jettyd and see it appear on your dashboard.

Prerequisites

What	Why
ESP-IDF 5.x	Build toolchain for ESP32
ESP32-S3, ESP32-C3, or ESP32-C6 board (original ESP32 not supported)	Any dev board works
USB cable	Flash & serial monitor
WiFi network	Device connects to your local network

💡 No jettyd account yet?

Steps

Clone the template

git clone https://github.com/jettydiot/jettyd-firmware-template my-device
cd my-device
make setup

This clones the starter project and fetches the jettyd firmware SDK as a submodule.

my-device/
├── device.yaml ← your device config
├── main/
│ ├── main.c ← entry point (usually no changes needed)
│ └── driver_registry.c ← auto-generated from device.yaml
├── jettyd-sdk/ ← SDK submodule (don't edit)
├── build.py ← YAML → C codegen
└── sdkconfig.defaults ← WiFi + fleet token

Configure your device

Edit device.yaml — this is where you declare your sensors and actuators:

# device.yaml
jettyd:
  fleet_token: "ft_your_token_here"
  mqtt_uri: "mqtt://mqtt.jettyd.com:1883"

wifi:
  ssid: "YourNetworkName"
  password: "YourNetworkPassword"

name: "my-device"
version: "1.0.0"
target: "esp32s3"       # esp32s3 | esp32c3 | esp32c6

drivers:
  - name: led
    instance: "status"
    config:
      pin: 8
      active_high: true

  - name: button
    instance: "btn"
    config:
      pin: 0
      active_low: true

Then set your WiFi credentials and fleet token in sdkconfig.defaults:

# sdkconfig.defaults
CONFIG_JETTYD_FLEET_TOKEN="ft_your_token_here"
CONFIG_JETTYD_WIFI_SSID="YourNetworkName"
CONFIG_JETTYD_WIFI_PASSWORD="YourNetworkPassword"

⚠️ Important

After editing sdkconfig.defaults, always delete sdkconfig before building:
rm -f sdkconfig
ESP-IDF caches the config and won't pick up your changes otherwise.

Build and flash

rm -f sdkconfig
idf.py build flash monitor

The build system automatically generates main/driver_registry.c from your device.yaml. No manual C code needed.

On first boot you'll see:

I (3200) jettyd_wifi: Connected — IP: 192.168.1.42
I (4800) jettyd_prov: Provisioning... fleet_token=ft_...
I (5200) jettyd_prov: Provisioned! device_key=dk_abcdef123456
I (5600) jettyd_mqtt: Connected to mqtt.jettyd.com
I (5800) jettyd:   Jettyd running
I (5800) jettyd:   Drivers: 1
I (5800) jettyd:   Rules: 0

✅ Your device is now online

It connected to WiFi, provisioned itself with jettyd, and entered its main loop. Telemetry is publishing on every heartbeat.

See it on the dashboard

Open app.jettyd.com and log in. Your device appears in the device list with a green ● Online indicator.

From the device detail page you can:

View live telemetry (temperature, humidity, etc.)
Inspect the device shadow (reported vs. desired state)
Send commands (reboot, set_interval, etc.)
See command history and delivery status

Control it with AI

jettyd exposes a REST API and an MCP server that any AI agent can use:

# Install the MCP server
npx @jettyd/mcp

# Or use the REST API directly
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.jettyd.com/v1/devices

Your AI agent can now read sensors, send commands, and manage your device fleet — all through a standard API.

Add local rules with JettyScript

JettyScript lets you define rules that run directly on the device — no cloud round-trip needed. Push rules via the platform API or MQTT:

// Blink LED every 5s when online, every 1s when offline
{
  "rules": [
    {
      "id": "status-online",
      "condition": { "sensor": "system.connected", "op": "==", "value": 1 },
      "actions": [{ "action": "blink", "target": "status", "interval_ms": 5000 }]
    },
    {
      "id": "status-offline",
      "condition": { "sensor": "system.connected", "op": "==", "value": 0 },
      "actions": [{ "action": "blink", "target": "status", "interval_ms": 1000 }]
    }
  ]
}

Available system metrics: system.connected, system.rssi, system.chip_temp, system.uptime, system.heap_free

Adding more drivers

Just add entries to device.yaml:

drivers:
  - name: dht22
    instance: "air"
    config:
      pin: 4

  - name: led
    instance: "status"
    config:
      pin: 8
      active_high: true

  - name: button
    instance: "btn"
    config:
      pin: 0
      active_low: true

Run idf.py build flash — the codegen handles the rest.

Available drivers

Driver	Type	Metrics
`dht22`	Sensor	temperature, humidity
`bme280`	Sensor	temperature, humidity, pressure
`ds18b20`	Sensor	temperature
`soil_moisture`	Sensor	moisture (0–100%)
`hcsr04`	Sensor	distance_cm
`ina219`	Sensor	voltage, current, power
`led`	Actuator	on/off, blink, timed
`relay`	Actuator	on/off
`button`	Input	press, long_press, double_press
`pwm_output`	Actuator	duty cycle (0–100%)

Troubleshooting

Device stuck on "Provisioning…"

Check that your fleet token is correct and the device can reach mqtt.jettyd.com:1883. Firewalls sometimes block MQTT.

WiFi won't connect

Make sure you deleted sdkconfig after editing sdkconfig.defaults. The SSID and password are baked in at configure time.

Build fails: "jettyd SDK not found"

Run make setup to clone the SDK, or manually: git clone https://github.com/jettydiot/jettyd-firmware.git jettyd-sdk

Stack overflow / crash on boot

The default stack sizes are tuned for most projects. If you're using many drivers, increase in sdkconfig.defaults:

CONFIG_ESP_MAIN_TASK_STACK_SIZE=8192
CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE=6144

QuickStart ~5 min

Prerequisites

Steps

Clone the template

Configure your device

Build and flash

See it on the dashboard

Control it with AI

Add local rules with JettyScript

Adding more drivers

Available drivers

Troubleshooting

Device stuck on "Provisioning…"

WiFi won't connect

Build fails: "jettyd SDK not found"

Stack overflow / crash on boot

Next steps

📖 API Reference

🔧 Firmware SDK

🤖 MCP Server

📦 Template Repo