luckyp70/heliot

readme

# Heliot Framework

[![Component Registry](https://img.shields.io/badge/Espressif%20Component%20Registry-heliot-blue)](https://components.espressif.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Heliot** is a powerful, modular IoT application framework for ESP32 devices that provides a complete foundation for building connected devices with web-based management interfaces. Named after Helios, the star at the center of our solar system, Heliot puts your IoT device at the center of its own ecosystem.

## ✨ Features

- **🎯 Domain-Based Architecture**: Organize functionality into logical, reusable domains (WiFi, MQTT, Firmware, Device management)
- **🌐 Built-in Web Server**: Full-featured HTTP server with WebSocket support for real-time bidirectional communication
- **🔌 Hot-Pluggable Domains**: Add custom domains to extend framework functionality for your specific use case
- **📡 Real-Time Event System**: Event-driven architecture for responsive, efficient applications
- **🔐 Security Ready**: Optional authentication, OTA validation, and secure communication
- **📊 Live Logging**: Stream ESP32 logs to web clients in real-time for debugging
- **🎨 Modular UI System**: Automatic discovery and bundling of domain-specific UI components
- **💾 State Management**: Persistent NVS-backed state for all domains
- **⚡ Production-Ready**: Battle-tested in real-world IoT deployments

## 🏗️ Architecture

Heliot adopts a **domain-based architecture** where each functional area (WiFi, MQTT, firmware updates, etc.) is encapsulated as a domain:

```
┌─────────────────────────────────────────┐
│           Your Application              │
│  ┌──────────────────────────────────┐   │
│  │    Custom Domain (e.g., Radar)   │   │
│  └──────────────────────────────────┘   │
└─────────────────────────────────────────┘
         ▲
         │ Domain API
         ▼
┌─────────────────────────────────────────┐
│          Heliot Framework               │
│  ┌──────┐ ┌──────┐ ┌────────┐ ┌─────┐   │
│  │ WiFi │ │ MQTT │ │Firmware│ │ ... │   │
│  │Domain│ │Domain│ │ Domain │ │     │   │
│  └──────┘ └──────┘ └────────┘ └─────┘   │
│  ┌──────────────────────────────────┐   │
│  │      Domain Registry             │   │
│  └──────────────────────────────────┘   │
│  ┌──────────────────────────────────┐   │
│  │  HTTP + WebSocket Server         │   │
│  └──────────────────────────────────┘   │
│  ┌──────────────────────────────────┐   │
│  │  Event System + State Manager    │   │
│  └──────────────────────────────────┘   │
└─────────────────────────────────────────┘
         ▲
         │ ESP-IDF APIs
         ▼
┌─────────────────────────────────────────┐
│            ESP-IDF                      │
└─────────────────────────────────────────┘
```

## 📦 Built-in Domains

Heliot comes with production-ready domains:

| Domain | Description | Features |
|--------|-------------|----------|
| **Device** | Device management & control | Configuration, restart, factory reset, diagnostics |
| **WiFi** | WiFi connectivity | STA/AP modes, network scanning, connection management |
| **MQTT** | MQTT client | Auto-reconnect, message publishing, subscription handling |
| **Firmware** | OTA updates | Encrypted updates, validation, rollback protection |
| **Proto** | WebSocket protocol | Connection handshake, ping/pong, acknowledgments |

## 🚀 Quick Start

### Installation

Add Heliot to your ESP-IDF project using the component manager:

```bash
idf.py add-dependency "heliot"
```

Or manually add to your `idf_component.yml`:

```yaml
dependencies:
  heliot:
    version: "^1.0.0"
```

### Basic Usage

```c
#include "heliot.h"
#include "heliot_domain_registry.h"

void app_main(void) {
    // 1. Initialize Heliot framework
    ESP_ERROR_CHECK(heliot_init());
    
    // 2. Initialize built-in domains (pass NULL for no custom domains)
    ESP_ERROR_CHECK(heliot_domains_init(NULL));
    
    // 3. Start web server
    heliot_web_server_config_t config = HELIOT_WEB_SERVER_DEFAULT_CONFIG();
    ESP_ERROR_CHECK(heliot_web_server_start(&config));
    
    ESP_LOGI("APP", "Heliot framework running!");
}
```

This minimal example gives you:
- Web server on port 80
- WebSocket endpoint at `/ws`
- Built-in domains (WiFi, MQTT, Device, Firmware management)
- Real-time logging streamed to connected clients

### Web Interface

Once running, connect to your ESP32's IP address in a web browser:
- View and configure WiFi networks
- Manage MQTT connections
- Upload firmware updates
- View live logs
- Configure device settings

## 🔧 Creating Custom Domains

Extend Heliot with your own domains for application-specific functionality:

```c
#include "heliot_domain_registry.h"

// Define domain ID (use 0x80-0xFF range for custom domains)
#define DOMAIN_SENSOR_ID 0x80

// Forward declarations
esp_err_t sensor_state_register(void);
esp_err_t sensor_events_register(void);
esp_err_t sensor_state_unregister(void);
esp_err_t sensor_events_unregister(void);
esp_err_t sensor_ws_handler_register(void);
esp_err_t sensor_http_handler_register(httpd_handle_t server);

// Domain registration function
esp_err_t sensor_domain_register(void) {
    return heliot_register_domain(
        DOMAIN_SENSOR_ID,
        "sensor",
        sensor_state_register,
        sensor_events_register,
        sensor_state_unregister,
        sensor_events_unregister,
        sensor_ws_handler_register,    // WebSocket handler
        sensor_http_handler_register   // HTTP handler
    );
}

// Register custom domain with Heliot
void app_main(void) {
    ESP_ERROR_CHECK(heliot_init());
    
    // Array of custom domain registration functions
    const domain_register_fn_t custom_domains[] = {
        sensor_domain_register,
        NULL  // NULL-terminated
    };
    
    ESP_ERROR_CHECK(heliot_domains_init(custom_domains));
    
    heliot_web_server_config_t config = HELIOT_WEB_SERVER_DEFAULT_CONFIG();
    ESP_ERROR_CHECK(heliot_web_server_start(&config));
}
```

## 📚 Documentation

- [Creating Custom Domains](docs/custom_domains.md) - Step-by-step guide
- [WebSocket Protocol](docs/websocket_protocol.md) - Message format and operations
- [State Management](docs/state_management.md) - Persistent configuration
- [Event System](docs/events.md) - Inter-domain communication
- [Security Guide](docs/security.md) - Authentication and encryption
- [API Reference](docs/api_reference.md) - Complete API documentation

## 🎯 Real-World Example

See the [ESP32 Radar project](https://github.com/username/esp_radar) for a complete production example that uses Heliot to:
- Manage mmWave radar sensor integration (custom domain)
- Provide web-based radar visualization
- Handle OTA firmware updates
- MQTT integration for Home Assistant
- WiFi management with fallback AP mode

## 🔐 Security Features

- **Optional Authentication**: Token-based HTTP/WebSocket authentication
- **OTA Validation**: Automatic rollback for failed updates
- **Encrypted Firmware**: AES-256 encrypted OTA updates
- **HMAC Verification**: Firmware integrity validation
- **Secure Defaults**: Configurable security policies per domain

Enable authentication:
```c
heliot_web_server_config_t config = HELIOT_WEB_SERVER_DEFAULT_CONFIG();
config.auth_token = "your-secure-token-here";
ESP_ERROR_CHECK(heliot_web_server_start(&config));
```

## ⚙️ Configuration

Heliot can be configured via menuconfig (future feature):

```bash
idf.py menuconfig
# Navigate to Component config → Heliot Framework
```

Current configuration is done programmatically via the API.

## 📊 Resource Requirements

### Memory Usage (Typical)
- **RAM**: ~60-80 KB (varies with active domains and WebSocket sessions)
- **Flash**: ~200-300 KB (framework + built-in domains)
- **Stack**: 4-8 KB per domain task

### Minimum Requirements
- **ESP-IDF**: v5.0 or later
- **Chip**: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6
- **Flash**: 4 MB minimum (for OTA support)
- **RAM**: 320 KB minimum

## 🛠️ Tools

Heliot includes development tools for UI bundling:

- **`bundle_modular_ui.mjs`**: Bundles domain UI files into compressed C arrays
- **`minify_write.mjs`**: Minifies and gzips web assets

See [tools documentation](tools/README.md) for details.

## 🤝 Contributing

Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Follow ESP-IDF coding standards
4. Add tests if applicable
5. Submit a pull request

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

Copyright (c) 2025 Fortunato Pasqualone

## 🙏 Acknowledgments

Built on top of the excellent [ESP-IDF](https://github.com/espressif/esp-idf) framework by Espressif Systems.

## 💬 Support

- **Documentation**: [Full documentation](docs/)
- **Issues**: [GitHub Issues](https://github.com/username/heliot/issues)
- **Discussions**: [GitHub Discussions](https://github.com/username/heliot/discussions)

## 🗺️ Roadmap

- [ ] Configuration via menuconfig
- [ ] Unit test suite
- [ ] CoAP domain support
- [ ] BLE domain for Bluetooth connectivity
- [ ] More examples (sensors, actuators, displays)
- [ ] Web UI framework/components library

---

**Made with ❤️ for the ESP32 community**