Giantronic Docs

Overview

Giantronic is a full-stack IoT platform for managing ESP32 devices at scale. It provides real-time monitoring, remote configuration, automation, and OTA firmware updates through a unified, responsive web dashboard that works on desktop, tablet, and phone browsers.

Features

Giantronic includes everything you need for professional IoT fleet management.

Quick Start

Get up and running with Giantronic in minutes.

1. Create Your Account

   Sign up at the Giantronic dashboard. Verify your email address to activate your account.

2. Flash Your ESP32

   Flash the Giantronic firmware to your ESP32 using the OTA updater or USB. The firmware is available in the Firmware section of the dashboard.

3. Pair Your Device

   Power on your ESP32 and connect it to the same WiFi network. Go to Devices → Pair WiFi Device — the dashboard finds the device on your network. Enter the 6-digit pairing code shown on the device screen (the dashboard can read it from the device automatically) to complete pairing.

4. Configure Pins

   Assign functions to GPIO pins: digital input/output, analog input, relay control, or LED indicators.

5. Automate with Schedules

   Create time-based schedules to turn devices on/off at specific times with optional weekly repeats.

Device Pairing

Pair your ESP32 devices to start managing them through the dashboard.

How Pairing Works

Giantronic uses a deterministic device key based on the ESP32's MAC address. The key format is MAC_{sanitized_mac} where the MAC address colons are replaced with underscores.

// MAC Address: AA:BB:CC:DD:EE:FF
"MAC_AA_BB_CC_DD_EE_FF"

Pairing Flow

1. ESP32 connects to WiFi

   The device boots, connects to WiFi, and registers itself in Firebase with its MAC address and IP.

2. User pairs the device

   From Devices → Pair WiFi Device (or Add Device), pick the discovered device or enter its details. Pairing requires the 6-digit pairing code shown on the device — the dashboard reads it from the device automatically, or you can type it in. Only after the code is verified does the backend create a Django Device record linked to your account.

3. Two-way sync begins

   Pin configurations, schedules, and scenes sync between Django, Firebase, and the ESP32 via HTTP polling.

Pin Configuration

Configure ESP32 GPIO pins with custom functions, names, and modes.

Pin Fields

Schedules

Automate your devices with time-based schedules that trigger at specific times.

Schedule Fields

Scenes

Create one-tap actions that control multiple devices simultaneously.

Scene Structure

Each scene contains an action list with device targets and desired pin states. Scenes can be triggered from the web dashboard or via voice keywords.

{
  "name": "Movie Night",
  "actions": [
    {
      "deviceKey": "MAC_AA_BB_CC_DD_EE_FF",
      "pin": "pin_02",
      "state": true
    },
    {
      "deviceKey": "MAC_11_22_33_44_55_66",
      "pin": "pin_04",
      "state": false
    }
  ]
}

Voice Keywords

Scenes can be assigned custom voice keywords for voice assistant integration. Keywords are stored in the format:

{
  "keyword": "movie night",
  "turnOn": true,
  "deviceType": "scene",
  "language": "en",
  "targets": [...]
}

Fleet Management

Group devices into fleets for organized management and monitoring.

Energy Monitoring

Track power consumption, energy usage, and estimated cost across your devices.

Energy readings are reported by the device firmware (sensor hardware varies by build) and displayed on the Energy Analytics dashboard:

Notifications

Stay informed with email and push notifications for device events.

OTA Updates

Update ESP32 firmware over-the-air without physical access.

Update Sources

• GitHub Releases

  Link your firmware repository. Giantronic fetches releases and makes them available for OTA flashing.

• Custom Binary Upload

  Upload .bin firmware files directly through the dashboard.

• Bulk OTA

  Push firmware updates to an entire fleet simultaneously with rollback support.

API Reference

Giantronic provides a full REST API for programmatic access. All endpoints require JWT authentication.

Authentication

POST /api/token/
// Body
{
  "username": "your_username",
  "password": "your_password"
}

// Response
{
  "access": "eyJhbGci...",
  "refresh": "eyJhbGci..."
}

GET /api/devices/
Authorization: Bearer eyJhbGci...

Core Endpoints

API Documentation

Mobile Access

Giantronic works in any modern browser, so you can manage your devices from a phone or tablet — no app install required.

Client Authentication (Firebase)

Clients that sign in with Firebase Authentication exchange the Firebase ID token for a Django JWT via the /firebase/exchange-token/ endpoint.

POST /firebase/exchange-token/
Content-Type: application/json

{
  "id_token": "firebase_id_token_from_client_sdk"
}

// Response
{
  "access": "jwt_access_token",
  "refresh": "jwt_refresh_token",
  "user": { /* user profile */ }
}

Troubleshooting

Common issues and their solutions.

Device not appearing after pairing

Ensure the ESP32 has successfully connected to WiFi and registered in Firebase. The device must be online before pairing can complete. Check the Firebase console under esp32_devices/ to verify the device is registered.

Pin state not syncing

Pin configurations sync via Firebase. If changes aren't reflecting, check that the ESP32 is polling the Firebase path esp32_devices/{device_key}/pins/ at the expected interval (typically every 2-5 seconds).

Schedule not executing

Verify the schedule format uses the correct field names (deviceKey, triggerTime, turnOn). Check that the device is online at the scheduled time. One-time schedules clear after execution.

Email not verified

Check your inbox (and spam folder) for the verification email from Giantronic. If it hasn't arrived, you can request a resend while signed in by calling POST /api/auth/resend-verification/.

OTA update fails

Ensure the ESP32 has a stable WiFi connection. Large firmware files may take several minutes. Check the flash history in the dashboard for detailed error messages.

FAQ

What ESP32 boards are supported?

Giantronic supports all ESP32 variants (ESP32, ESP32-S2, ESP32-S3, ESP32-C3) running the Giantronic firmware.

Is there a limit to the number of devices?

Yes. The Free plan pairs up to 3 devices and the Starter plan up to 10. Enterprise accounts have unlimited device support — see the pricing page for plan details.

Is there a mobile app?

The web dashboard works on desktop, tablet, and phone browsers, so no app is required. A native Android app is in development and will be announced here when it ships.

How does cross-platform sync work?

All device data flows through Firebase as the real-time sync layer. Django serves as the persistent database and API layer. The web dashboard writes to Firebase with identical field names, and the ESP32 reads directly from Firebase.

Is the API rate-limited?

Yes. API requests are rate-limited to 10,000 requests per hour per user (10,000 per hour for anonymous clients). ESP32 devices poll Firebase directly rather than this API, so device traffic is not affected by this limit.