QuickStart — jettyd firmware template

Connect an ESP32 device to jettyd.com in under 10 minutes.

Prerequisites

Requirement	Notes
ESP-IDF v5.2+	Installation guide
Python 3.9+	For `build.py` codegen
Git	To clone this template
jettyd account	Sign up free →

Supported targets: ESP32-S3, ESP32-C3, ESP32-C6

1. Clone the template

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

2. Get your fleet token

Log in to app.jettyd.com
Navigate to Fleet → Tokens → New token
Copy the ft_… token

3. Configure your device

Open device.yaml and fill in the required fields:

jettyd:
  fleet_token: "ft_YOUR_TOKEN_HERE"   # from step 2
  mqtt_uri: "mqtt://mqtt.jettyd.com:1883"

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

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

⚠️ Never commit real tokens. Add device.yaml to .gitignore or use environment variable substitution before committing.

4. Set up the SDK

make setup

This clones jettydiot/jettyd-firmware into jettyd-sdk/ — the SDK that ships your device's telemetry and command handling to jettyd.

5. Build and flash

idf.py build flash monitor

Or use the Makefile shortcuts:

make build           # compile only
make flash           # compile + flash
make flash-monitor   # compile + flash + open serial monitor

On first run, build.py auto-generates:

main/device_config.h — typed device configuration
main/driver_registry.c — driver wiring
main/driver_requires.cmake — build dependencies

6. Verify the connection

Once the device boots you should see in the serial monitor:

I (1234) jettyd: Connected to WiFi
I (1456) jettyd: MQTT connected → mqtt.jettyd.com
I (1460) jettyd: Device registered: my-device
I (1462) jettyd: Telemetry heartbeat sent

Head to app.jettyd.com → Devices — your device should appear online within a few seconds.

7. Add drivers

Edit the drivers: section in device.yaml to map your hardware:

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

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

Re-run idf.py build flash after every device.yaml change — codegen runs automatically.

8. Run checks before committing

make check

Runs codegen validation, format checks, and the SDK unit test suite. All three must pass before pushing.

Telemetry defaults

defaults:
  heartbeat_interval: 60    # seconds between telemetry pushes
  report_metrics:
    - "system.rssi"
    # - "system.chip_temp"
    # - "system.free_heap"

Troubleshooting

Device doesn't appear online

Verify fleet_token is correct and hasn't expired
Check serial output for MQTT errors
Ensure port 1883 is not blocked by your network

Build fails with "sdkconfig mismatch"

device.yaml changed since last build: rm sdkconfig && idf.py build
Or just run make build — the Makefile handles this automatically

make setup fails

Check you have Git and a working internet connection
If jettyd-sdk/ already exists, remove it and re-run: rm -rf jettyd-sdk && make setup