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 web dashboard and mobile app.

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. It will broadcast its MAC address. Go to Devices → Add Device and enter the MAC address to pair it.

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 or mobile app.

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 the dashboard or mobile app, enter the device's MAC address. The backend creates a Django Device record and links it to the Firebase entry.

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, mobile app, 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 real-time power consumption across your device fleet.

Energy data is collected from ESP32 devices via analog pin readings and reported to the backend. The dashboard displays:

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 App

The Giantronic Android app provides full device management on the go.

Features

Authentication Flow

The mobile app uses Firebase Authentication for user sign-in, then exchanges the Firebase ID token for a Django JWT via the /accounts/firebase/exchange-token/ endpoint.

POST /accounts/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.

Mobile app shows "Email not verified"

Check your inbox (and spam folder) for the verification email. You can resend it from the app. Both Django and Firebase send separate verification emails.

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?

Free accounts can pair up to 10 devices. Enterprise accounts have unlimited device support.

Can I use Giantronic without the mobile app?

Yes. The web dashboard provides full functionality. The mobile app is optional for on-the-go management.

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. Both web and mobile write to Firebase with identical field names, and the ESP32 reads directly from Firebase.

Is the API rate-limited?

API requests are rate-limited to 100 requests per minute per user. Device polling to Firebase is not rate-limited.